martial/martial-admin-mini
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

✅ Mock版本完成 - UI冻结版本

Browse Source 
完成内容:
- 5个完整的UI页面（登录、评分列表、评分详情、多场地列表、修改评分）
- 完整的Mock数据展示
- 完整的业务逻辑实现
- 文档体系建立（2000+行文档）

文档包含:
- 项目概述.md
- 页面功能说明.md
- API接口设计.md (17个接口)
- 数据结构设计.md (17个接口定义)
- 功能模块划分.md
- 后端实现对比报告.md
- 数据可行性分析报告.md (95分评估)
- 保护Mock版本的实施方案.md (4层保护机制)
- API对接完成度检查报告.md

此版本为Mock原型版本，所有UI功能完整，数据为硬编码Mock数据。
This commit is contained in:
宅房
2025-12-11 13:22:19 +08:00
parent c2f3313c7c
commit 7bd197f4ac
13 changed files with 8457 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
.claude/settings.local.json
View File

@@ -2,7 +2,8 @@
"permissions": {
"allow": [
"Bash(tree:*)",
"Bash(find:*)"
"Bash(find:*)",
"Bash(git add:*)"
],
"deny": [],
"ask": []

375
doc/API对接完成度检查报告.md Normal file
View File

@@ -0,0 +1,375 @@
# API对接完成度检查报告
**检查时间**: 2025-12-11
**项目路径**: `D:\workspace\31.比赛项目\project\martial-admin-mini`
---
## 📊 完成度总览
```
总体进度: ██░░░░░░░░ 20%
✅ 已完成:
- 数据可行性分析 (100%)
- 保护方案设计 (100%)
- 后端能力评估 (100%)
- 文档编写 (100%)
❌ 未开始:
- 前端API对接代码 (0%)
- 后端小程序接口 (0%)
- 联调测试 (0%)
```
---
## ✅ 已完成的工作
### 1. 文档编写（100%）
| 文档 | 状态 | 内容 |
|------|------|------|
| 数据可行性分析报告.md | ✅ 完成 | 600+行，详细分析前后端数据能力 |
| 保护Mock版本的实施方案.md | ✅ 完成 | 700+行，4层保护机制 + 完整代码 |
| 后端实现对比报告.md | ✅ 完成 | 后端API和Entity对比 |
| API接口设计.md | ✅ 完成 | 17个API接口定义 |
| 数据结构设计.md | ✅ 完成 | 17个TypeScript接口 |
### 2. 分析评估（100%）
- ✅ 5个页面的Mock数据需求分析
- ✅ 后端Entity字段能力评估
- ✅ 后端Controller接口能力评估
- ✅ 数据可行性评分：95/100
- ✅ 缺失接口清单（5个）
- ✅ SQL查询示例编写
- ✅ VO类设计
### 3. 方案设计（100%）
- ✅ Git分支隔离方案
- ✅ 配置开关控制方案
- ✅ 数据适配器架构设计
- ✅ Mock数据整理方案
- ✅ API目录结构设计
- ✅ 实施步骤规划
---
## ❌ 未完成的工作
### 1. 前端代码实现（0%）
#### 缺失文件清单
```
martial-admin-mini/
├── ❌ config/
│ ├── ❌ env.config.js # 环境配置
│ └── ❌ api.config.js # API配置
│
├── ❌ mock/ # Mock数据目录
│ ├── ❌ index.js # Mock入口
│ ├── ❌ login.js # 登录Mock
│ ├── ❌ athlete.js # 选手Mock
│ └── ❌ score.js # 评分Mock
│
├── ❌ api/ # API调用目录
│ ├── ❌ index.js # API入口
│ ├── ❌ auth.js # 认证API
│ ├── ❌ athlete.js # 选手API
│ └── ❌ score.js # 评分API
│
└── utils/
├── ❌ request.js # 网络请求封装
└── ❌ dataAdapter.js # 数据适配器
```
#### 需要修改的页面
```
pages/
├── login/
│ └── ⚠️ login.vue # 需要接入dataAdapter
├── score-list/
│ └── ⚠️ score-list.vue # 需要接入dataAdapter
├── score-detail/
│ └── ⚠️ score-detail.vue # 需要接入dataAdapter
├── score-list-multi/
│ └── ⚠️ score-list-multi.vue # 需要接入dataAdapter
└── modify-score/
└── ⚠️ modify-score.vue # 需要接入dataAdapter
```
### 2. 后端代码实现（0%）
#### 缺失的后端文件
```
martial-master/src/main/java/org/springblade/modules/martial/
├── controller/
│ └── ❌ MartialMiniController.java # 小程序专用Controller
│
├── service/
│ ├── ❌ IMartialMiniService.java # 接口
│ └── impl/
│ └── ❌ MartialMiniServiceImpl.java # 实现类
│
├── mapper/
│ └── ❌ (需要添加自定义SQL方法)
│
└── pojo/
└── vo/
├── ❌ LoginVO.java # 登录响应VO
├── ❌ AthleteWithScoreVO.java # 带评分的选手VO
├── ❌ AthleteAdminVO.java # 裁判长选手VO
├── ❌ AthleteScoreDetailVO.java # 评分详情VO
└── ❌ JudgeScoreVO.java # 评委评分VO
```
#### 缺失的接口（5个）
```java
❌ POST /api/mini/login # 登录验证
❌ GET /api/mini/athletes # 普通评委选手列表
❌ GET /api/mini/athletes/admin # 裁判长选手列表
❌ GET /api/mini/score/detail/{athleteId} # 评分详情
❌ PUT /api/mini/score/modify # 修改评分
```
### 3. 保护机制实施（0%）
```
❌ Git分支创建
- 未创建 v1.0-mock 标签
- 未创建 feature/api-integration 分支
❌ Mock版本备份
- 未创建代码压缩包
- 未导出Git存档
❌ 配置文件部署
- 未部署 env.config.js
- 未设置 dataMode 开关
```
### 4. 测试验证（0%）
```
❌ 单元测试
❌ 接口测试
❌ 联调测试
❌ UI功能测试
❌ 数据格式验证
❌ Token验证测试
❌ 权限验证测试
```
---
## 📋 待办事项清单
### 第一阶段：保护现有代码（1小时）
- [ ] 提交当前代码到Git
- [ ] 创建 v1.0-mock 标签
- [ ] 创建 feature/api-integration 分支
- [ ] 创建代码备份压缩包
### 第二阶段：前端基础架构（2-3小时）
- [ ] 创建 `config/env.config.js`
- [ ] 创建 `utils/request.js`
- [ ] 创建 `utils/dataAdapter.js`
- [ ] 创建 `mock/` 目录结构
- [ ] 创建 `api/` 目录结构
### 第三阶段：Mock数据整理（2小时）
- [ ] 从页面中提取Mock数据到 `mock/login.js`
- [ ] 提取到 `mock/athlete.js`
- [ ] 提取到 `mock/score.js`
- [ ] 编写 `mock/index.js` 入口
### 第四阶段：API接口定义（1-2小时）
- [ ] 编写 `api/auth.js`
- [ ] 编写 `api/athlete.js`
- [ ] 编写 `api/score.js`
- [ ] 编写 `api/index.js` 入口
### 第五阶段：页面改造（2-3小时）
- [ ] 修改 `login.vue` 使用 dataAdapter
- [ ] 修改 `score-list.vue` 使用 dataAdapter
- [ ] 修改 `score-detail.vue` 使用 dataAdapter
- [ ] 修改 `score-list-multi.vue` 使用 dataAdapter
- [ ] 修改 `modify-score.vue` 使用 dataAdapter
### 第六阶段：后端开发（3-5天）
- [ ] 创建 `MartialMiniController.java`
- [ ] 实现登录接口
- [ ] 实现选手列表接口（普通评委）
- [ ] 实现选手列表接口（裁判长）
- [ ] 实现评分详情接口
- [ ] 实现修改评分接口
- [ ] 编写自定义SQL
- [ ] 创建VO类
### 第七阶段：联调测试（2-3天）
- [ ] Mock模式测试
- [ ] API模式测试
- [ ] 模式切换测试
- [ ] 完整业务流程测试
- [ ] 错误处理测试
- [ ] 性能测试
---
## 🎯 当前状态总结
### ✅ 优势
1. **分析充分**: 数据可行性已全面评估（95分）
2. **方案完整**: 保护机制、架构设计全部完成
3. **文档齐全**: 600+700行的详细实施文档
4. **可行性高**: 后端数据能力完全支持前端需求
### ⚠️ 差距
1. **无实际代码**: 所有API对接代码均未创建
2. **无保护措施**: Git分支、标签、备份均未实施
3. **无后端接口**: 5个小程序专用接口需要开发
4. **页面未改造**: 5个页面仍使用硬编码Mock数据
### 📊 完成度评估
```
理论准备: ████████████████████ 100%
实际开发: ████░░░░░░░░░░░░░░░░ 20%
↑
仅有文档
```
---
## 🚀 下一步建议
### 方案A：立即开始前端API对接（推荐）
**优势**:
- 快速验证方案可行性
- 前端可独立开发（Mock模式）
- 为后端开发提供明确的接口规范
**步骤**:
1. 保护当前代码（Git分支 + 标签）
2. 创建前端基础架构文件
3. 整理Mock数据
4. 改造5个页面
5. 测试Mock模式
**预计时间**: 1-2天
### 方案B：先开发后端接口
**优势**:
- 先有真实数据
- 前端直接对接真实API
**步骤**:
1. 创建 `MartialMiniController`
2. 实现5个接口
3. 测试接口
4. 前端对接
**预计时间**: 3-5天
### 方案C：前后端并行开发
**优势**:
- 最快完成
- 前端Mock模式开发，后端实现接口
- 最后联调
**步骤**:
1. 前端：创建架构 + Mock数据
2. 后端：实现5个接口
3. 联调：切换到API模式测试
**预计时间**: 1周
---
## ⚡ 快速启动建议
**如果要立即开始，我建议按以下顺序进行**:
### Step 1: 保护现有代码（10分钟）
```bash
git add .
git commit -m "✅ Mock版本完成"
git tag -a v1.0-mock -m "Mock原型版本"
git checkout -b feature/api-integration
```
### Step 2: 创建基础文件（30分钟）
我可以帮您创建：
- ✅ `config/env.config.js`
- ✅ `utils/request.js`
- ✅ `utils/dataAdapter.js`
- ✅ `mock/index.js`
- ✅ `api/index.js`
### Step 3: 改造一个页面（1小时）
先改造登录页作为示例：
- ✅ 提取Mock数据
- ✅ 接入dataAdapter
- ✅ 测试Mock模式
### Step 4: 完成其他页面（2-3小时）
按照登录页的模式改造其他4个页面
---
## 🤔 需要您的决策
**请告诉我您希望如何进行**:
1. ❓ **是否立即开始前端API对接代码开发？**
- 如果是，我将开始创建所有必要的文件
2. ❓ **是否需要先保护Mock版本？**
- 创建Git分支和标签
3. ❓ **是否需要先开发后端接口？**
- 创建 `MartialMiniController` 和相关代码
4. ❓ **选择哪种方案？**
- 方案A: 前端先行
- 方案B: 后端先行
- 方案C: 前后端并行
---
## 📞 总结
**当前状态**:
- ✅ 完成了所有的分析、设计和文档工作
- ❌ 尚未开始实际的代码开发工作
**完成度**: 20%（仅理论准备）
**下一步**: 等待您的决策，选择实施方案后开始开发
---
**报告生成时间**: 2025-12-11
**检查范围**: 前端代码 + 文档
**检查结果**: ❌ API对接尚未开始

1107
doc/API接口设计.md Normal file
View File

File diff suppressed because it is too large Load Diff

375
doc/README.md Normal file
View File

@@ -0,0 +1,375 @@
# 武术评分系统 - 项目文档
## 📚 文档目录
本目录包含武术评分系统的完整项目文档，帮助开发者快速了解项目结构、功能设计和API接口。
---
## 📖 文档列表
### 1. [项目概述](./项目概述.md)
**内容概要**:
- 项目基本信息
- 核心功能介绍
- 技术架构
- 项目结构
- 页面流程
- 色彩系统
- 运行和部署说明
- 后续扩展建议
**适合人群**: 项目管理者、新加入的开发者、产品经理
---
### 2. [页面功能说明](./页面功能说明.md)
**内容概要**:
- 所有页面总览
- 登录页详细说明
- 评分列表页详细说明
- 评分详情页详细说明
- 多场地列表页详细说明
- 修改评分页详细说明
- 页面间跳转关系
- 页面共同特性
**适合人群**: 前端开发者、UI设计师、测试工程师
**关键信息**:
- 5个页面的完整功能说明
- 每个页面需要对接的API接口
- 页面数据结构
- 交互逻辑说明
---
### 3. [API接口设计](./API接口设计.md)
**内容概要**:
- 接口规范和通用格式
- 9大功能模块的完整API接口
- 认证模块（3个接口）
- 比赛信息模块（1个接口）
- 场地管理模块（1个接口）
- 项目管理模块（2个接口）
- 选手管理模块（3个接口）
- 评分管理模块（4个接口）
- 扣分项管理模块（1个接口）
- 统计分析模块（2个接口）
- 实时推送模块（WebSocket）
- 接口调用示例（JavaScript）
- 接口安全建议
- 性能优化建议
- 环境配置
**适合人群**: 后端开发者、前端开发者、接口对接人员
**关键信息**:
- 共计17个REST API接口
- 完整的请求参数和响应格式
- 错误处理规范
- WebSocket推送协议
---
### 4. [数据结构设计](./数据结构设计.md)
**内容概要**:
- 17个核心数据结构定义（TypeScript）
- 用户角色相关（3个）
- 比赛相关（1个）
- 场地相关（2个）
- 项目相关（2个）
- 选手相关（3个）
- 评分相关（4个）
- 评分修改相关（2个）
- 扣分项相关（2个）
- 统计分析相关（3个）
- 前端页面数据结构（5个）
- 全局数据结构（1个）
- WebSocket推送数据结构（3个）
- 分页数据结构（2个）
- 数据验证规则
- 枚举类型汇总
- 数据关系图
- 数据存储建议
**适合人群**: 前端开发者、后端开发者、数据库设计人员
**关键信息**:
- 完整的TypeScript类型定义
- 数据关系说明
- 数据验证规则
- 前后端数据格式统一
---
### 5. [功能模块划分](./功能模块划分.md)
**内容概要**:
- 10大功能模块详细说明
1. 用户认证模块
2. 比赛信息模块
3. 场地管理模块
4. 项目管理模块
5. 选手管理模块
6. 评分管理模块（普通评委）
7. 评分修改模块（裁判长）
8. 扣分项管理模块
9. 统计分析模块
10. 实时推送模块
- 每个模块的核心功能
- 涉及的页面和API接口
- 数据结构
- 业务规则
- 权限说明
- 模块依赖关系
- 开发优先级建议
- 模块测试要点
**适合人群**: 项目经理、开发团队、测试团队
**关键信息**:
- 模块化的功能设计
- 开发优先级（3个阶段）
- 模块依赖关系图
- 完整的测试要点
---
## 🎯 快速导航
### 我是项目管理者
**推荐阅读顺序**:
1. [项目概述](./项目概述.md) - 了解项目整体情况
2. [功能模块划分](./功能模块划分.md) - 了解功能模块和开发计划
3. [页面功能说明](./页面功能说明.md) - 了解页面功能需求
### 我是前端开发者
**推荐阅读顺序**:
1. [项目概述](./项目概述.md) - 了解技术栈
2. [页面功能说明](./页面功能说明.md) - 了解页面需求
3. [数据结构设计](./数据结构设计.md) - 了解数据格式
4. [API接口设计](./API接口设计.md) - 了解如何对接API
### 我是后端开发者
**推荐阅读顺序**:
1. [项目概述](./项目概述.md) - 了解项目背景
2. [功能模块划分](./功能模块划分.md) - 了解业务逻辑
3. [API接口设计](./API接口设计.md) - 实现API接口
4. [数据结构设计](./数据结构设计.md) - 设计数据库
### 我是UI/UX设计师
**推荐阅读顺序**:
1. [项目概述](./项目概述.md) - 了解色彩系统和设计规范
2. [页面功能说明](./页面功能说明.md) - 了解页面需求和交互
### 我是测试工程师
**推荐阅读顺序**:
1. [页面功能说明](./页面功能说明.md) - 了解功能需求
2. [功能模块划分](./功能模块划分.md) - 了解测试要点
3. [API接口设计](./API接口设计.md) - 了解接口规范
---
## 📊 项目数据统计
### 页面统计
- **总页面数**: 5个
- **普通评委页面**: 3个（登录页、评分列表页、评分详情页）
- **裁判长页面**: 3个（登录页、多场地列表页、修改评分页）
### 功能模块统计
- **功能模块数**: 10个
- **已完成模块**: 8个
- **待开发模块**: 2个（统计分析、实时推送）
### API接口统计
- **REST API接口数**: 17个
- **WebSocket接口**: 1个
- **认证相关**: 3个
- **业务相关**: 14个
### 数据结构统计
- **核心数据结构**: 17个
- **页面数据结构**: 5个
- **推送数据结构**: 3个
- **枚举类型**: 6个
### 代码统计
- **总代码行数**: 约3000行
- **Vue页面**: 5个
- **配置文件**: 7个
- **文档文件**: 5个
---
## 🔧 技术栈
### 前端技术
- **框架**: UniApp + Vue.js 2.x
- **样式**: CSS3 + SCSS
- **UI**: UniApp原生组件
- **状态管理**: getApp().globalData
- **路由**: UniApp内置路由
### 支持平台
- 微信小程序
- H5
### 开发工具
- HBuilderX（推荐）
- VS Code + uni-cli
---
## 📝 版本历史
### v1.0.0 (2025-06-25)
- ✅ 完成5个页面的UI开发
- ✅ 完成角色区分（pub/admin）
- ✅ 完成评分功能（精度0.001）
- ✅ 完成扣分项多选
- ✅ 完成场地和项目切换
- ✅ 完成评分修改功能
- ✅ 完成项目文档
### 待开发功能
- ❌ 后端API对接
- ❌ 真实数据存储
- ❌ 用户身份持久化
- ❌ 实时数据同步
- ❌ 离线支持
- ❌ 数据统计和导出
---
## 👥 团队协作
### 前端开发
**工作内容**:
1. 阅读[页面功能说明](./页面功能说明.md)
2. 阅读[数据结构设计](./数据结构设计.md)
3. 根据现有页面进行功能完善
4. 对接后端API接口
**需要对接**:
- 与后端确认API接口格式
- 与UI设计师确认页面样式
### 后端开发
**工作内容**:
1. 阅读[API接口设计](./API接口设计.md)
2. 阅读[数据结构设计](./数据结构设计.md)
3. 设计数据库表结构
4. 实现API接口
**需要对接**:
- 与前端确认数据格式
- 与测试确认接口规范
### 测试工程师
**工作内容**:
1. 阅读[功能模块划分](./功能模块划分.md)中的测试要点
2. 编写测试用例
3. 进行功能测试和接口测试
**需要对接**:
- 与开发确认测试环境
- 与产品确认验收标准
---
## 🚀 开发建议
### 第一阶段（核心功能） - 2-3周
**任务**:
1. 搭建后端框架
2. 实现用户认证API
3. 实现评分相关API
4. 前端对接API
5. 完成基础功能测试
**产出**:
- 可用的登录功能
- 可用的评分功能
- 可用的评分修改功能
### 第二阶段（管理功能） - 1-2周
**任务**:
1. 实现场地和项目管理API
2. 实现选手管理API
3. 完善权限控制
4. 前端对接API
5. 完成功能测试
**产出**:
- 完整的裁判长功能
- 完整的权限控制
### 第三阶段（增强功能） - 2-3周
**任务**:
1. 实现统计分析功能
2. 实现WebSocket实时推送
3. 实现数据导出功能
4. 性能优化
5. 完成全面测试
**产出**:
- 完整的统计分析
- 实时数据更新
- 数据导出功能
---
## 📞 联系方式
如有疑问，请联系项目负责人。
---
## 📄 文档维护
**文档版本**: v1.0.0
**最后更新**: 2025-06-25
**维护人员**: 开发团队
**更新记录**:
- 2025-06-25: 创建初始文档
---
## ⚠️ 注意事项
1. 所有文档中的示例数据均为Mock数据
2. 实际开发时请根据后端返回的真实数据进行调整
3. API接口地址需要根据实际环境配置
4. 所有涉及安全的功能（登录、Token等）需要严格测试
5. 评分精度必须保证为0.001，不可有误差
---
## 📚 相关资源
- [UniApp官方文档](https://uniapp.dcloud.io/)
- [Vue.js官方文档](https://cn.vuejs.org/)
- [项目GitHub地址]() - 待添加
- [设计原型](../image/) - 查看设计图
---
**祝开发顺利！** 🎉

1040
doc/保护Mock版本的实施方案.md Normal file
View File

File diff suppressed because it is too large Load Diff

1102
doc/功能模块划分.md Normal file
View File

File diff suppressed because it is too large Load Diff

0
功能说明.md → doc/功能说明.md
View File

1073
doc/后端实现对比报告.md Normal file
View File

File diff suppressed because it is too large Load Diff

0
如何运行.md → doc/如何运行.md
View File

1290
doc/数据可行性分析报告.md Normal file
View File

File diff suppressed because it is too large Load Diff

1136
doc/数据结构设计.md Normal file
View File

File diff suppressed because it is too large Load Diff

751
doc/页面功能说明.md Normal file
View File

@@ -0,0 +1,751 @@
# 页面功能说明
## 页面总览
| 页面 | 路径 | 权限 | 功能描述 |
|------|------|------|----------|
| 登录页 | pages/login/login.vue | 所有用户 | 用户登录认证 |
| 评分列表页 | pages/score-list/score-list.vue | 普通评委(pub) | 查看选手列表并进行评分 |
| 评分详情页 | pages/score-detail/score-detail.vue | 普通评委(pub) | 对选手进行详细评分 |
| 多场地列表页 | pages/score-list-multi/score-list-multi.vue | 裁判长(admin) | 查看所有场地和项目 |
| 修改评分页 | pages/modify-score/modify-score.vue | 裁判长(admin) | 修改已有评分 |
---
## 1. 登录页 (login.vue)
### 页面路径
`pages/login/login.vue`
### 访问权限
所有用户
### 页面功能
#### 核心功能
- 用户通过比赛编码和邀请码进行登录认证
- 根据邀请码类型（pub/admin）自动跳转到对应页面
#### 页面元素
1. **自定义导航栏**
- 标题: "评分系统"
- 右侧图标: 菜单按钮、关闭按钮
2. **输入区域**
- 比赛编码输入框
- 评委邀请码输入框
3. **操作按钮**
- "立即评分" 提交按钮
### 数据结构
```javascript
data() {
return {
matchCode: '', // 比赛编码
inviteCode: '' // 邀请码 (pub/admin)
}
}
```
### 业务逻辑
#### 提交流程
1. 验证比赛编码不为空
2. 验证邀请码不为空
3. 判断邀请码类型（pub 或 admin）
4. 保存用户信息到全局数据
5. 根据角色跳转页面
```javascript
// 全局数据存储
getApp().globalData = {
userRole: 'pub' | 'admin', // 用户角色
matchCode: string // 比赛编码
}
```
#### 角色跳转规则
- **admin (裁判长)**: 跳转到多场地列表页 (score-list-multi)
- **pub (普通评委)**: 跳转到评分列表页 (score-list)
### 需要对接的API
#### 1. 登录认证接口
**接口**: `POST /api/auth/login`
**请求参数**:
```json
{
"matchCode": "string", // 比赛编码
"inviteCode": "string" // 邀请码
}
```
**返回数据**:
```json
{
"code": 200,
"message": "登录成功",
"data": {
"token": "string", // JWT Token
"userRole": "pub|admin", // 用户角色
"matchId": "string", // 比赛ID
"matchName": "string", // 比赛名称
"judgeName": "string", // 评委姓名
"judgeId": "string" // 评委ID
}
}
```
### 样式特点
- 使用渐变背景（深绿到浅绿）
- 输入框带阴影和圆角
- 提交按钮带渐变和悬停效果
---
## 2. 评分列表页 (score-list.vue)
### 页面路径
`pages/score-list/score-list.vue`
### 访问权限
普通评委 (pub)
### 页面功能
#### 核心功能
- 显示当前比赛信息
- 显示选手列表
- 查看已评分/未评分状态
- 跳转到评分详情页进行评分
#### 页面元素
1. **自定义导航栏**
- 标题: "评分系统"
2. **比赛信息区域**
- 比赛标题
- 比赛时间
3. **场地和项目区域**
- 当前场地显示（第一场地）
- 当前项目显示（男子组陈氏太极拳）
4. **评分统计**
- 已评分数量/总数 (如: 2/30)
5. **选手列表**
- 选手姓名
- 身份证号
- 队伍名称
- 编号
- 我的评分（已评分时显示）
- 总分（已评分时显示）
- "评分"按钮（未评分时显示）
### 数据结构
```javascript
// 当前为静态Mock数据，需要从API获取
data() {
return {
matchInfo: {
title: '2025年全国武术散打锦标赛暨第十七届世界武术锦标赛选拔赛',
time: '2025年6月25日 9:00'
},
venue: '第一场地',
project: '男子组陈氏太极拳',
scoreStats: {
scored: 2, // 已评分数
total: 30 // 总数
},
players: [] // 选手列表
}
}
```
### 需要对接的API
#### 1. 获取比赛信息
**接口**: `GET /api/match/{matchId}`
**返回数据**:
```json
{
"code": 200,
"data": {
"matchId": "string",
"matchName": "string",
"matchTime": "2025-06-25T09:00:00",
"venue": "第一场地",
"project": "男子组陈氏太极拳"
}
}
```
#### 2. 获取选手列表
**接口**: `GET /api/athletes`
**请求参数**:
```
matchId: string
venueId: string
projectId: string
judgeId: string
```
**返回数据**:
```json
{
"code": 200,
"data": {
"total": 30,
"scored": 2,
"athletes": [
{
"athleteId": "string",
"name": "张三",
"idCard": "123456789000000000",
"team": "少林寺武术大学院",
"number": "123-4567898275",
"myScore": 8.906, // 我的评分（已评分）
"totalScore": 8.907, // 总分（已评分）
"scored": true // 是否已评分
}
]
}
}
```
### 交互逻辑
1. 点击"评分"按钮跳转到评分详情页
2. 页面显示时自动刷新选手列表
3. 已评分的选手显示分数，未评分显示评分按钮
---
## 3. 评分详情页 (score-detail.vue)
### 页面路径
`pages/score-detail/score-detail.vue`
### 访问权限
普通评委 (pub)
### 页面功能
#### 核心功能
- 对选手进行精确评分（精度0.001）
- 选择扣分项（多选）
- 填写评分备注
- 提交评分
#### 页面元素
1. **自定义导航栏**
- 返回按钮
- 标题: "评分详情"
2. **选手信息区域**
- 选手姓名
- 身份证号
- 队伍名称
- 编号
3. **评分提示**
- "点击分数填写或拖动滑块打分（5-10分）"
4. **分数控制区域**
- 减少按钮（-0.001）
- 当前分数显示（3位小数）
- 增加按钮（+0.001）
5. **扣分项区域**
- 8个扣分项（多选）
- 圆形复选框
6. **备注区域**
- 多行文本输入框
- 最大200字
7. **提交按钮**
### 数据结构
```javascript
data() {
return {
athleteId: '', // 选手ID（从路由参数获取）
currentScore: 8.907, // 当前评分
note: '', // 备注
minScore: 5.0, // 最低分
maxScore: 10.0, // 最高分
deductions: [ // 扣分项列表
{ id: 1, text: '扣分项描述', checked: false },
{ id: 2, text: '扣分项描述', checked: false },
// ... 共8项
]
}
}
```
### 业务逻辑
#### 评分控制
- 每次点击增加/减少0.001分
- 分数范围: 5.000 - 10.000
- 超出范围时按钮置灰（需实现）
#### 扣分项选择
- 支持多选
- 点击切换选中状态
#### 提交评分
1. 验证分数范围
2. 收集扣分项
3. 提交数据到后端
4. 显示成功提示
5. 返回列表页
### 需要对接的API
#### 1. 获取选手详情
**接口**: `GET /api/athletes/{athleteId}`
**返回数据**:
```json
{
"code": 200,
"data": {
"athleteId": "string",
"name": "张三",
"idCard": "123456789000000000",
"team": "少林寺武术大学院",
"number": "123-4567898275",
"defaultScore": 8.907 // 默认分数
}
}
```
#### 2. 获取扣分项列表
**接口**: `GET /api/deductions`
**请求参数**:
```
projectId: string
```
**返回数据**:
```json
{
"code": 200,
"data": [
{
"deductionId": "string",
"text": "扣分项描述",
"score": -0.1 // 扣分值
}
]
}
```
#### 3. 提交评分
**接口**: `POST /api/scores`
**请求参数**:
```json
{
"matchId": "string",
"athleteId": "string",
"judgeId": "string",
"score": 8.907,
"deductions": ["deductionId1", "deductionId2"],
"note": "string"
}
```
**返回数据**:
```json
{
"code": 200,
"message": "评分提交成功",
"data": {
"scoreId": "string",
"createTime": "2025-06-25T09:15:00"
}
}
```
---
## 4. 多场地列表页 (score-list-multi.vue)
### 页面路径
`pages/score-list-multi/score-list-multi.vue`
### 访问权限
裁判长 (admin)
### 页面功能
#### 核心功能
- 查看所有场地和项目
- 切换场地（横向滚动）
- 切换项目（横向滚动）
- 查看各场地选手列表
- 修改已有评分
#### 页面元素
1. **自定义导航栏**
- 标题: "评分系统"
2. **比赛信息区域**
- 比赛标题
- 比赛时间
3. **场地切换区域**
- 5个场地横向滚动切换
- 当前场地高亮显示
4. **项目切换区域**
- 8个项目横向滚动切换
- 当前项目高亮显示
5. **评分统计**
- 当前场地已评分数/总数
6. **选手列表**
- 选手信息
- 总分显示
- "修改"按钮
### 数据结构
```javascript
data() {
return {
currentVenue: 1, // 当前场地ID
currentProject: 0, // 当前项目索引
venues: [ // 场地列表
{ id: 1, name: '第一场地' },
{ id: 2, name: '第二场地' },
{ id: 3, name: '第三场地' },
{ id: 4, name: '第四场地' },
{ id: 5, name: '第五场地' }
],
projects: [ // 项目列表
'女子组长拳',
'男子组陈氏太极拳',
'女子组双剑（含长穗双剑）',
'男子组杨氏太极拳',
'女子组刀术',
'男子组棍术',
'女子组枪术',
'男子组剑术'
],
players: [] // 选手列表
}
}
```
### 需要对接的API
#### 1. 获取场地列表
**接口**: `GET /api/venues`
**请求参数**:
```
matchId: string
```
**返回数据**:
```json
{
"code": 200,
"data": [
{
"venueId": "string",
"venueName": "第一场地",
"order": 1
}
]
}
```
#### 2. 获取项目列表
**接口**: `GET /api/projects`
**请求参数**:
```
matchId: string
```
**返回数据**:
```json
{
"code": 200,
"data": [
{
"projectId": "string",
"projectName": "女子组长拳",
"order": 1
}
]
}
```
#### 3. 获取选手列表（带总分）
**接口**: `GET /api/athletes/scored`
**请求参数**:
```
matchId: string
venueId: string
projectId: string
```
**返回数据**:
```json
{
"code": 200,
"data": {
"total": 30,
"scored": 25,
"athletes": [
{
"athleteId": "string",
"name": "张三",
"idCard": "123456789000000000",
"team": "少林寺武术大学院",
"number": "123-4567898275",
"totalScore": 8.907, // 总分
"judgeCount": 6, // 评委数量
"canModify": true // 是否可修改
}
]
}
}
```
### 交互逻辑
1. 横向滚动切换场地
2. 横向滚动切换项目
3. 切换场地/项目时自动加载对应选手列表
4. 点击"修改"按钮跳转到修改评分页
---
## 5. 修改评分页 (modify-score.vue)
### 页面路径
`pages/modify-score/modify-score.vue`
### 访问权限
裁判长 (admin)
### 页面功能
#### 核心功能
- 查看选手信息和当前总分
- 查看所有评委的评分详情
- 修改总分（精度0.001）
- 填写修改备注
- 提交修改
#### 页面元素
1. **自定义导航栏**
- 返回按钮
- 标题: "修改评分"
2. **选手信息区域**
- 选手姓名
- 当前总分
- 身份证号
- 队伍名称
- 编号
3. **评委评分统计区域**
- 标题: "共有X位评委完成评分"
- 各评委的评分列表
4. **修改总分区域**
- 说明: "修改总分（+-0.005分）"
- 减少按钮（-0.001）
- 当前分数显示
- "可不改"提示
- 增加按钮（+0.001）
5. **备注区域**
- 多行文本输入框
- "可不填"提示
- 最大200字
6. **修改按钮**
### 数据结构
```javascript
data() {
return {
athleteId: '', // 选手ID
originalScore: 8.907, // 原始总分
currentScore: 8.907, // 修改后的分数
note: '', // 修改备注
minScore: 5.0, // 最低分
maxScore: 10.0, // 最高分
judgeScores: [] // 评委评分列表
}
}
```
### 需要对接的API
#### 1. 获取选手评分详情
**接口**: `GET /api/scores/{athleteId}/detail`
**返回数据**:
```json
{
"code": 200,
"data": {
"athleteId": "string",
"name": "张三",
"idCard": "123456789000000000",
"team": "少林寺武术大学院",
"number": "123-4567898275",
"totalScore": 8.907,
"judgeCount": 6,
"judgeScores": [
{
"judgeId": "string",
"judgeName": "欧阳丽娜",
"score": 8.907,
"deductions": ["扣分项1", "扣分项2"],
"note": "备注内容",
"scoreTime": "2025-06-25T09:15:00"
}
],
"modifications": [
{
"modifyId": "string",
"modifier": "裁判长姓名",
"originalScore": 8.907,
"modifiedScore": 8.910,
"note": "修改原因",
"modifyTime": "2025-06-25T10:00:00"
}
]
}
}
```
#### 2. 修改评分
**接口**: `PUT /api/scores/{athleteId}/modify`
**请求参数**:
```json
{
"athleteId": "string",
"originalScore": 8.907,
"modifiedScore": 8.910,
"note": "修改原因",
"modifier": "裁判长ID"
}
```
**返回数据**:
```json
{
"code": 200,
"message": "修改成功",
"data": {
"modifyId": "string",
"modifiedScore": 8.910,
"modifyTime": "2025-06-25T10:00:00"
}
}
```
### 业务逻辑
#### 修改总分
- 每次点击增加/减少0.001分
- 分数范围: 5.000 - 10.000
- "可不改"表示可以不修改分数
#### 提交修改
1. 验证分数范围
2. 检查是否有实际修改
3. 提交数据到后端
4. 显示成功提示
5. 返回多场地列表页
### 交互逻辑
1. 显示所有评委的评分明细
2. 裁判长可以调整总分
3. 必须填写修改备注（可选）
4. 提交后返回列表页
---
## 页面间跳转关系
```
登录页 (login.vue)
├─→ [pub角色] → 评分列表页 (score-list.vue)
│ └─→ 评分详情页 (score-detail.vue)
│ └─→ [提交后返回] → 评分列表页
│
└─→ [admin角色] → 多场地列表页 (score-list-multi.vue)
└─→ 修改评分页 (modify-score.vue)
└─→ [修改后返回] → 多场地列表页
```
## 页面共同特性
### 1. 自定义导航栏
所有页面都使用自定义导航栏（`navigationStyle: "custom"`）
- 高度: 90rpx
- 背景: 渐变绿色 (#1B7C5E → #2A9D7E)
- 标题居中
- 右侧固定菜单和关闭按钮
### 2. 响应式设计
使用rpx单位实现跨设备适配
### 3. 色彩系统统一
- 主色: #1B7C5E（深绿）
- 次色: #2A9D7E（浅绿）
- 强调色: #FF4D6A（红色）
### 4. 交互反馈
- 按钮点击有透明度变化
- 表单验证有toast提示
- 加载状态需要添加loading（待实现）
### 5. 错误处理
- 网络请求失败提示（待实现）
- 表单验证提示
- 权限验证提示

206
doc/项目概述.md Normal file
View File

@@ -0,0 +1,206 @@
# 武术评分系统 - 项目概述
## 项目基本信息
- **项目名称**: 武术评分系统 (martial-admin-mini)
- **项目类型**: UniApp 跨端小程序
- **技术框架**: Vue.js 2.x + UniApp
- **支持平台**: 微信小程序 + H5
- **版本**: v1.0.0
## 项目简介
武术评分系统是一个专为武术比赛评委打分设计的移动端应用。系统支持多角色权限管理，区分普通评委和裁判长两种角色，提供精确的评分功能（精度到0.001分）。
## 核心功能
### 1. 用户角色
- **普通评委 (pub)**: 对选手进行评分
- **裁判长 (admin)**: 查看所有场地和项目，修改评分
### 2. 主要功能模块
1. **登录认证**: 通过比赛编码和邀请码登录
2. **评分管理**: 精确评分（5.0-10.0分，精度0.001）
3. **场地管理**: 支持多场地切换（5个场地）
4. **项目管理**: 支持多项目切换（8个项目类型）
5. **扣分项管理**: 支持多选扣分项
6. **评分修改**: 裁判长可修改总分
## 技术架构
### 技术栈
| 技术 | 版本/说明 |
|------|----------|
| 框架 | UniApp |
| 前端框架 | Vue.js 2.x |
| 样式 | CSS3 + SCSS |
| UI组件 | UniApp原生组件 |
| 状态管理 | getApp().globalData |
| 路由 | UniApp内置路由 |
### 项目特点
1. **跨平台**: 一套代码，同时支持微信小程序和H5
2. **无三方依赖**: 完全使用UniApp原生API和组件
3. **自定义导航栏**: 所有页面使用自定义导航栏设计
4. **响应式设计**: 使用rpx单位适配不同屏幕
5. **精确控制**: 评分精度达0.001分
## 项目结构
```
martial-admin-mini/
├── pages/ # 页面文件
│ ├── login/ # 登录页
│ ├── score-list/ # 评分列表页（普通评委）
│ ├── score-detail/ # 评分详情页
│ ├── score-list-multi/ # 多场地列表页（裁判长）
│ └── modify-score/ # 修改评分页（裁判长）
├── common/ # 公共资源
│ └── common.css # 全局样式
├── static/ # 静态资源
├── doc/ # 项目文档
├── image/ # 设计图
├── pages.json # 页面配置
├── manifest.json # 应用配置
├── App.vue # 根组件
├── main.js # 入口文件
└── uni.scss # 全局样式变量
```
## 页面流程
```
┌─────────────────┐
│ 登录页面 │ (login.vue)
│ 输入比赛编码 │
│ 输入邀请码 │
└────────┬────────┘
│
验证邀请码
│
┌────┴────┐
│ │
pub admin
│ │
▼ ▼
┌────────┐ ┌────────────────┐
│评分列表│ │多场地列表页 │
│(普通评委)│ │(裁判长) │
└───┬────┘ └────┬───────────┘
│ │
▼ ▼
┌────────┐ ┌──────────┐
│评分详情│ │修改评分 │
│页面 │ │页面 │
└────────┘ └──────────┘
```
## 色彩系统
| 颜色类型 | 色值 | 说明 |
|---------|------|------|
| 主色调 | #1B7C5E | 深绿色（导航栏、按钮） |
| 次要色 | #2A9D7E | 浅绿色（渐变） |
| 强调色 | #FF4D6A | 红色（提示、警告） |
| 文字主色 | #333333 | 深灰色 |
| 文字次色 | #666666 | 中灰色 |
| 占位符 | #CCCCCC | 浅灰色 |
| 页面背景 | #F5F5F5 | 浅灰色背景 |
## 当前开发状态
### 已完成功能
- ✅ 登录权限验证
- ✅ 角色区分（pub/admin）
- ✅ 评分界面（精度0.001）
- ✅ 扣分项多选
- ✅ 场地切换（5个场地）
- ✅ 项目切换（8个项目）
- ✅ 评分修改功能
- ✅ 自定义导航栏
- ✅ 响应式布局
### 待开发功能
- ❌ 后端API对接
- ❌ 真实数据存储
- ❌ 用户身份持久化
- ❌ 实时数据同步
- ❌ 离线支持
- ❌ 数据统计和导出
## 运行说明
### 使用 HBuilderX（推荐）
1. 打开 HBuilderX
2. 文件 → 打开目录 → 选择项目根目录
3. 右键点击项目名称 → 运行 → 运行到浏览器 → Chrome
4. 首次编译需要1-2分钟
### 使用命令行
```bash
# H5开发
npm run dev:h5
# 微信小程序开发
npm run dev:mp-weixin
# 构建H5生产环境
npm run build:h5
# 构建微信小程序
npm run build:mp-weixin
```
## 部署说明
### H5部署
1. 运行 `npm run build:h5`
2. 将 `dist/build/h5` 目录部署到服务器
3. 配置nginx静态资源服务
### 微信小程序部署
1. 运行 `npm run build:mp-weixin`
2. 使用微信开发者工具打开 `dist/build/mp-weixin` 目录
3. 配置 `manifest.json` 中的 `appid`
4. 上传审核
## 后续扩展建议
### 短期优化（1-2周）
1. 对接后端API
2. 实现JWT认证
3. 添加loading状态
4. 完善错误处理
### 中期功能（1-2月）
1. WebSocket实时同步
2. 评分历史记录
3. 数据统计分析
4. 导出Excel报表
5. 离线缓存支持
### 长期架构（2-3月）
1. 引入Vuex/Pinia状态管理
2. 组件化拆分
3. 单元测试覆盖
4. CI/CD自动化部署
5. 性能优化
## 联系方式
- 项目仓库: [项目地址]
- 技术文档: [文档地址]
- 问题反馈: [Issues地址]