martial-admin-mini/doc/功能模块划分.md

# 功能模块划分文档

## 文档说明

本文档按照功能模块对武术评分系统进行清晰的划分，便于开发和维护。每个模块包含功能说明、涉及页面、API接口、数据结构等信息。

---

## 模块总览

```
武术评分系统
├── 1. 用户认证模块
├── 2. 比赛信息模块
├── 3. 场地管理模块
├── 4. 项目管理模块
├── 5. 选手管理模块
├── 6. 评分管理模块
├── 7. 评分修改模块（裁判长）
├── 8. 扣分项管理模块
├── 9. 统计分析模块
└── 10. 实时推送模块
```

---

## 一、用户认证模块

### 1.1 模块概述

负责用户登录、权限验证、Token管理等功能。

### 1.2 涉及页面

- **登录页** (`pages/login/login.vue`)

### 1.3 核心功能

#### 1.3.1 登录认证

**功能描述**: 用户通过比赛编码和邀请码进行登录

**涉及字段**:
- `matchCode`: 比赛编码
- `inviteCode`: 邀请码 (pub/admin)

**业务流程**:
```
用户输入 → 验证非空 → 调用登录API → 保存Token和用户信息 → 根据角色跳转
```

**角色跳转规则**:
- `pub` (普通评委) → 评分列表页
- `admin` (裁判长) → 多场地列表页

#### 1.3.2 Token管理

**功能描述**: 管理JWT Token的存储、验证、刷新

**存储方式**:
```javascript
// 存储Token
uni.setStorageSync('auth_token', token)

// 获取Token
const token = uni.getStorageSync('auth_token')

// 清除Token
uni.removeStorageSync('auth_token')
```

#### 1.3.3 权限验证

**功能描述**: 验证用户角色和访问权限

**权限控制**:
```javascript
// 获取用户角色
const userRole = getApp().globalData.userRole

// 权限检查
if (userRole !== 'admin') {
  uni.showToast({ title: '权限不足', icon: 'none' })
  uni.navigateBack()
}
```

### 1.4 API接口

- `POST /api/auth/login` - 用户登录
- `POST /api/auth/logout` - 退出登录
- `GET /api/auth/verify` - Token验证

### 1.5 数据结构

```typescript
// 登录凭证
interface LoginCredentials {
  matchCode: string
  inviteCode: string
}

// 认证响应
interface AuthResponse {
  token: string
  userRole: 'pub' | 'admin'
  matchId: string
  matchName: string
  judgeId: string
  judgeName: string
  // ...
}

// 全局数据
getApp().globalData = {
  userRole: 'pub' | 'admin',
  matchCode: string,
  token: string
}
```

### 1.6 待开发功能

- [ ] 找回密码
- [ ] 修改密码
- [ ] Token自动刷新
- [ ] 登录日志记录

---

## 二、比赛信息模块

### 2.1 模块概述

管理比赛的基本信息、时间、地点等。

### 2.2 涉及页面

- **评分列表页** (`pages/score-list/score-list.vue`)
- **多场地列表页** (`pages/score-list-multi/score-list-multi.vue`)

### 2.3 核心功能

#### 2.3.1 比赛信息展示

**显示内容**:
- 比赛名称
- 比赛时间
- 比赛地点
- 场地数量
- 项目数量

**示例**:
```
2025年全国武术散打锦标赛暨第十七届世界武术锦标赛选拔赛
比赛时间：2025年6月25日 9:00
```

#### 2.3.2 比赛状态管理

**状态类型**:
- `upcoming`: 未开始
- `ongoing`: 进行中
- `finished`: 已结束

### 2.4 API接口

- `GET /api/matches/{matchId}` - 获取比赛详情

### 2.5 数据结构

```typescript
interface Match {
  matchId: string
  matchName: string
  matchTime: string
  matchEndTime: string
  location: string
  status: 'upcoming' | 'ongoing' | 'finished'
  venueCount: number
  projectCount: number
  athleteCount: number
}
```

### 2.6 待开发功能

- [ ] 比赛日程管理
- [ ] 比赛公告
- [ ] 比赛规则说明

---

## 三、场地管理模块

### 3.1 模块概述

管理比赛的各个场地信息，支持多场地切换（裁判长专用）。

### 3.2 涉及页面

- **多场地列表页** (`pages/score-list-multi/score-list-multi.vue`)

### 3.3 核心功能

#### 3.3.1 场地列表展示

**功能描述**: 显示所有场地，支持横向滚动切换

**场地数量**: 5个场地
- 第一场地
- 第二场地
- 第三场地
- 第四场地
- 第五场地

**展示信息**:
- 场地名称
- 选手数量
- 已评分数量
- 评分进度

#### 3.3.2 场地切换

**交互方式**: 横向滚动选择

**实现方式**:
```vue
<scroll-view class="venue-scroll" scroll-x="true">
  <view
    v-for="venue in venues"
    :key="venue.id"
    :class="['venue-tab', currentVenue === venue.id ? 'active' : '']"
    @click="switchVenue(venue.id)"
  >
    {{ venue.name }}
  </view>
</scroll-view>
```

**切换效果**:
- 当前场地高亮显示
- 底部绿色下划线
- 自动加载对应选手列表

### 3.4 API接口

- `GET /api/venues` - 获取场地列表

### 3.5 数据结构

```typescript
interface Venue {
  venueId: string
  venueName: string
  order: number
  athleteCount: number
  scoredCount: number
  status: 'active' | 'completed' | 'paused'
}

// 前端数据
data() {
  return {
    currentVenue: 1,
    venues: [
      { id: 1, name: '第一场地' },
      { id: 2, name: '第二场地' },
      { id: 3, name: '第三场地' },
      { id: 4, name: '第四场地' },
      { id: 5, name: '第五场地' }
    ]
  }
}
```

### 3.6 权限说明

- **普通评委**: 只能查看分配的场地
- **裁判长**: 可以查看所有场地

---

## 四、项目管理模块

### 4.1 模块概述

管理比赛的各个项目类型，支持多项目切换。

### 4.2 涉及页面

- **评分列表页** (`pages/score-list/score-list.vue`)
- **多场地列表页** (`pages/score-list-multi/score-list-multi.vue`)

### 4.3 核心功能

#### 4.3.1 项目列表展示

**功能描述**: 显示所有项目，支持横向滚动切换

**项目数量**: 8个项目
1. 女子组长拳
2. 男子组陈氏太极拳
3. 女子组双剑（含长穗双剑）
4. 男子组杨氏太极拳
5. 女子组刀术
6. 男子组棍术
7. 女子组枪术
8. 男子组剑术

**展示信息**:
- 项目名称
- 参赛选手数
- 评分范围

#### 4.3.2 项目切换

**交互方式**: 横向滚动选择

**实现方式**:
```vue
<scroll-view class="project-scroll" scroll-x="true">
  <view
    v-for="(project, index) in projects"
    :key="index"
    :class="['project-btn', currentProject === index ? 'active' : '']"
    @click="switchProject(index)"
  >
    {{ project }}
  </view>
</scroll-view>
```

**切换效果**:
- 当前项目背景变绿
- 文字变白
- 自动加载对应选手列表

### 4.4 API接口

- `GET /api/projects` - 获取项目列表
- `GET /api/projects/{projectId}` - 获取项目详情

### 4.5 数据结构

```typescript
interface Project {
  projectId: string
  projectName: string
  category: string
  order: number
  athleteCount: number
  minScore: 5.0
  maxScore: 10.0
  scoreStep: 0.001
}

// 前端数据
data() {
  return {
    currentProject: 0,
    projects: [
      '女子组长拳',
      '男子组陈氏太极拳',
      // ...
    ]
  }
}
```

---

## 五、选手管理模块

### 5.1 模块概述

管理参赛选手信息，展示选手列表，支持查询和筛选。

### 5.2 涉及页面

- **评分列表页** (`pages/score-list/score-list.vue`)
- **评分详情页** (`pages/score-detail/score-detail.vue`)
- **多场地列表页** (`pages/score-list-multi/score-list-multi.vue`)
- **修改评分页** (`pages/modify-score/modify-score.vue`)

### 5.3 核心功能

#### 5.3.1 选手列表展示

**普通评委视图**:
- 选手姓名
- 身份证号
- 队伍名称
- 比赛编号
- 我的评分（已评分）
- 总分（已评分）
- 评分按钮（未评分）

**裁判长视图**:
- 选手姓名
- 身份证号
- 队伍名称
- 比赛编号
- 总分
- 修改按钮

#### 5.3.2 选手详情展示

**显示内容**:
```
姓名：张三
身份证：123456789000000000
队伍：少林寺武术大学院
编号：123-4567898275
```

#### 5.3.3 选手状态管理

**状态类型**:
- `waiting`: 等待表演
- `performing`: 正在表演
- `finished`: 已完成

### 5.4 API接口

- `GET /api/athletes` - 获取选手列表（普通评委）
- `GET /api/athletes/all` - 获取选手列表（裁判长）
- `GET /api/athletes/{athleteId}` - 获取选手详情

### 5.5 数据结构

```typescript
// 普通评委<E8AF84><E5A794><EFBFBD>图
interface AthleteListItem {
  athleteId: string
  name: string
  idCard: string
  team: string
  number: string
  myScore?: number
  totalScore?: number
  scored: boolean
}

// 裁判长视图
interface AthleteListItemAdmin {
  athleteId: string
  name: string
  idCard: string
  team: string
  number: string
  totalScore?: number
  judgeCount: number
  totalJudges: number
  canModify: boolean
}
```

### 5.6 待开发功能

- [ ] 选手照片展示
- [ ] 选手历史成绩
- [ ] 选手搜索功能
- [ ] 选手分组管理

---

## 六、评分管理模块（普通评委）

### 6.1 模块概述

普通评委对选手进行评分的核心功能模块。

### 6.2 涉及页面

- **评分列表页** (`pages/score-list/score-list.vue`)
- **评分详情页** (`pages/score-detail/score-detail.vue`)

### 6.3 核心功能

#### 6.3.1 评分界面

**评分控制**:
- 当前分数显示（精度0.001，3位小数）
- 减分按钮（-0.001）
- 加分按钮（+0.001）
- 分数范围：5.000 - 10.000

**实现方式**:
```javascript
decreaseScore() {
  if (this.currentScore > this.minScore) {
    this.currentScore = parseFloat((this.currentScore - 0.001).toFixed(3))
  }
}

increaseScore() {
  if (this.currentScore < this.maxScore) {
    this.currentScore = parseFloat((this.currentScore + 0.001).toFixed(3))
  }
}
```

#### 6.3.2 扣分项选择

**功能描述**: 多选扣分项

**扣分项数量**: 8项

**交互方式**:
```javascript
toggleDeduction(index) {
  this.deductions[index].checked = !this.deductions[index].checked
}
```

**显示方式**:
- 2列网格布局
- 圆形复选框
- 选中变绿

#### 6.3.3 备注填写

**功能描述**: 填写评分备注（选填）

**限制**:
- 最大200字
- 多行文本输入

#### 6.3.4 提交评分

**提交流程**:
```
验证分数范围 → 收集扣分项 → 调用API → 显示成功提示 → 返回列表页
```

**验证规则**:
- 分数必须在5.000-10.000之间
- 精度必须为0.001
- 不可重复提交

### 6.4 API接口

- `POST /api/scores` - 提交评分
- `GET /api/scores/my-records` - 获取我的评分记录

### 6.5 数据结构

```typescript
// 评分提交
interface ScoreSubmit {
  matchId: string
  athleteId: string
  judgeId: string
  projectId: string
  venueId: string
  score: number
  deductions: string[]
  note?: string
}

// 页面数据
data() {
  return {
    currentScore: 8.907,
    note: '',
    minScore: 5.0,
    maxScore: 10.0,
    deductions: [
      { text: '扣分项描述', checked: false },
      // ...
    ]
  }
}
```

### 6.6 业务规则

1. **评分范围**: 5.000 - 10.000
2. **评分精度**: 0.001（3位小数）
3. **重复提交**: 不允许重复提交
4. **备注长度**: 最多200字
5. **扣分项**: 支持多选

---

## 七、评分修改模块（裁判长）

### 7.1 模块概述

裁判长查看所有评分并进行修改的功能模块。

### 7.2 涉及页面

- **多场地列表页** (`pages/score-list-multi/score-list-multi.vue`)
- **修改评分页** (`pages/modify-score/modify-score.vue`)

### 7.3 核心功能

#### 7.3.1 评分详情查看

**显示内容**:
- 选手基本信息
- 当前总分
- 各评委评分明细

**评委评分明细**:
```
共有6位评委完成评分

欧阳丽娜：8.907
张三：8.901
裁判姓名：8.902
裁判姓名：8.907
裁判姓名：8.905
裁判姓名：8.904
```

#### 7.3.2 修改总分

**修改控制**:
- 原始总分显示
- 修改后分数（可调整）
- "可不改"提示
- 分数范围：5.000 - 10.000

**实现方式**:
```javascript
decreaseScore() {
  if (this.currentScore > this.minScore) {
    this.currentScore = parseFloat((this.currentScore - 0.001).toFixed(3))
  }
}

increaseScore() {
  if (this.currentScore < this.maxScore) {
    this.currentScore = parseFloat((this.currentScore + 0.001).toFixed(3))
  }
}
```

#### 7.3.3 修改备注

**功能描述**: 填写修改原因（可选填）

**限制**:
- 最大200字
- 多行文本输入
- "可不填"提示

#### 7.3.4 提交修改

**提交流程**:
```
验证权限 → 验证分数 → 调用API → 记录修改日志 → 返回列表页
```

### 7.4 API接口

- `GET /api/scores/{athleteId}` - 获取评分详情
- `PUT /api/scores/{athleteId}/modify` - 修改评分

### 7.5 数据结构

```typescript
// 修改提交
interface ScoreModifySubmit {
  athleteId: string
  modifierId: string
  originalScore: number
  modifiedScore: number
  note: string
}

// 评委评分
interface JudgeScore {
  scoreId: string
  judgeId: string
  judgeName: string
  score: number
  deductions: Deduction[]
  note?: string
  scoreTime: string
}

// 修改记录
interface ScoreModification {
  modifyId: string
  modifierId: string
  modifierName: string
  originalScore: number
  modifiedScore: number
  note: string
  modifyTime: string
}
```

### 7.6 权限控制

- 只有裁判长可以修改评分
- 修改前验证用户角色
- 记录修改人和修改时间

### 7.7 业务规则

1. **权限**: 只有admin角色可以修改
2. **修改范围**: 5.000 - 10.000
3. **修改精度**: 0.001
4. **修改记录**: 保留完整的修改历史
5. **备注**: 建议填写修改原因

---

## 八、扣分项管理模块

### 8.1 模块概述

管理各项目的扣分项，用于评分时选择。

### 8.2 涉及页面

- **评分详情页** (`pages/score-detail/score-detail.vue`)

### 8.3 核心功能

#### 8.3.1 扣分项展示

**显示方式**:
- 2列网格布局
- 圆形复选框
- 扣分项描述

**扣分项数量**: 8项（当前为Mock数据）

#### 8.3.2 扣分项选择

**功能描述**: 支持多选

**交互方式**:
- 点击切换选中状态
- 选中后复选框变绿
- 显示白色对勾

### 8.4 API接口

- `GET /api/deductions` - 获取扣分项列表

### 8.5 数据结构

```typescript
// 扣分项
interface Deduction {
  deductionId: string
  projectId: string
  text: string
  score: number        // 扣分值（负数）
  category?: string
  order: number
}

// 前端选择项
interface DeductionItem {
  deductionId?: string
  text: string
  checked: boolean
}

// 前端数据
data() {
  return {
    deductions: [
      { text: '扣分项描述', checked: false },
      { text: '扣分项描述', checked: false },
      { text: '扣分项描述', checked: true },
      // ... 共8项
    ]
  }
}
```

### 8.6 待开发功能

- [ ] 动态加载扣分项
- [ ] 扣分项分类
- [ ] 扣分值显示
- [ ] 扣分项说明

---

## 九、统计分析模块

### 9.1 模块概述

提供比赛的统计数据和分析报表（裁判长专用）。

### 9.2 当前状态

**状态**: 待开发

### 9.3 规划功能

#### 9.3.1 比赛总览

**统计内容**:
- 总选手数
- 已完成评分数
- 评分进度
- 平均分
- 最高分/最低分

#### 9.3.2 场地统计

**统计内容**:
- 各场地选手数
- 各场地完成度
- 各场地平均分

#### 9.3.3 项目统计

**统计内容**:
- 各项目选手数
- 各项目完成度
- 各项目平均分
- 各项目最高分/最低分

#### 9.3.4 评委统计

**统计内容**:
- 评委评分数量
- 评委平均给分
- 评委评分分布
- 评委评分时间统计

#### 9.3.5 数据导出

**导出功能**:
- 导出Excel报表
- 导出PDF报告
- 导出选手成绩单

### 9.4 API接口

- `GET /api/statistics/match/{matchId}` - 比赛统计
- `GET /api/statistics/judges` - 评委统计
- `POST /api/export/excel` - 导出Excel
- `POST /api/export/pdf` - 导出PDF

### 9.5 数据结构

```typescript
// 比赛统计
interface MatchStatistics {
  matchId: string
  totalAthletes: number
  finishedAthletes: number
  totalJudges: number
  activeJudges: number
  totalScores: number
  averageScore: number
  highestScore: number
  lowestScore: number
  venueStats: VenueStatistics[]
  projectStats: ProjectStatistics[]
}
```

---

## 十、实时推送模块

### 10.1 模块概述

通过WebSocket实现评分数据的实时推送和更新。

### 10.2 当前状态

**状态**: 待开发

### 10.3 规划功能

#### 10.3.1 评分实时更新

**功能描述**: 其他评委评分后实时推送

**推送内容**:
- 选手ID
- 评委姓名
- 评分
- 当前总分

#### 10.3.2 评分修改通知

**功能描述**: 裁判长修改评分后推送通知

**推送内容**:
- 选手ID
- 原始分数
- 修改后分数
- 修改原因

#### 10.3.3 选手状态更新

**功能描述**: 选手表演状态实时更新

**推送内容**:
- 选手ID
- 状态变化（等待→表演中→完成）

### 10.4 WebSocket连接

```javascript
// 连接WebSocket
const connectWebSocket = () => {
  const token = uni.getStorageSync('auth_token')

  uni.connectSocket({
    url: `wss://api.example.com/ws?token=${token}`,
    success: () => {
      console.log('WebSocket连接成功')
    }
  })

  // 监听消息
  uni.onSocketMessage((res) => {
    const message = JSON.parse(res.data)
    handleWebSocketMessage(message)
  })
}

// 处理推送消息
const handleWebSocketMessage = (message) => {
  switch (message.type) {
    case 'new_score':
      // 处理新评分
      break
    case 'score_modified':
      // 处理评分修改
      break
    case 'athlete_status':
      // 处理选手状态更新
      break
  }
}
```

### 10.5 数据结构

```typescript
// 新评分推送
interface NewScoreMessage {
  type: 'new_score'
  data: {
    athleteId: string
    athleteName: string
    judgeId: string
    judgeName: string
    score: number
    totalScore: number
    judgeCount: number
    timestamp: string
  }
}

// 评分修改推送
interface ScoreModifiedMessage {
  type: 'score_modified'
  data: {
    athleteId: string
    athleteName: string
    modifierId: string
    modifierName: string
    originalScore: number
    modifiedScore: number
    note: string
    timestamp: string
  }
}

// 选手状态推送
interface AthleteStatusMessage {
  type: 'athlete_status'
  data: {
    athleteId: string
    athleteName: string
    status: 'waiting' | 'performing' | 'finished'
    timestamp: string
  }
}
```

---

## 模块依赖关系

```
用户认证模块
  ↓
  ├─→ 比赛信息模块
  │     ↓
  │     ├─→ 场地管理模块
  │     │     ↓
  │     │     └─→ 选手管理模块
  │     │           ↓
  │     │           ├─→ 评分管理模块
  │     │           │     ↓
  │     │           │     └─→ 扣分项管理模块
  │     │           │
  │     │           └─→ 评分修改模块
  │     │
  │     └─→ 项目管理模块
  │           ↓
  │           └─→ 选手管理模块
  │
  └─→ 统计分析模块
        ↓
        └─→ 实时推送模块
```

---

## 开发优先级建议

### 第一阶段（核心功能）

1. **用户认证模块** - 必须先完成
2. **比赛信息模块** - 基础数据
3. **选手管理模块** - 核心业务
4. **评分管理模块** - 核心业务
5. **扣分项管理模块** - 配合评分

**预计时间**: 2-3周

### 第二阶段（管理功能）

1. **场地管理模块** - 裁判长功能
2. **项目管理模块** - 裁判长功能
3. **评分修改模块** - 裁判长功能

**预计时间**: 1-2周

### 第三阶段（增强功能）

1. **统计分析模块** - 数据分析
2. **实时推送模块** - 实时更新

**预计时间**: 2-3周

---

## 模块测试要点

### 用户认证模块

- [ ] 登录成功/失败
- [ ] Token存储和获取
- [ ] 角色判断和跳转
- [ ] Token过期处理

### 评分管理模块

- [ ] 评分范围验证
- [ ] 评分精度验证
- [ ] 扣分项多选
- [ ] 重复提交防止
- [ ] 备注长度限制

### 评分修改模块

- [ ] 权限验证
- [ ] 修改记录保存
- [ ] 修改通知推送
- [ ] 修改历史查询

### 选手管理模块

- [ ] 列表分页加载
- [ ] 选手详情展示
- [ ] 状态实时更新
- [ ] 搜索和筛选

---

## 附录：模块接口对应表

| 模块 | 主要接口 | 涉及页面 |
|------|---------|---------|
| 用户认证 | POST /api/auth/login | login.vue |
| 比赛信息 | GET /api/matches/{matchId} | score-list.vue, score-list-multi.vue |
| 场地管理 | GET /api/venues | score-list-multi.vue |
| 项目管理 | GET /api/projects | score-list.vue, score-list-multi.vue |
| 选手管理 | GET /api/athletes | score-list.vue |
| 评分管理 | POST /api/scores | score-detail.vue |
| 评分修改 | PUT /api/scores/{athleteId}/modify | modify-score.vue |
| 扣分项管理 | GET /api/deductions | score-detail.vue |
| 统计分析 | GET /api/statistics/match/{matchId} | 待开发 |
| 实时推送 | WebSocket连接 | 所有页面 |

---

## 总结

本文档按功能模块清晰地划分了武术评分系统的所有功能，每个模块都包含了详细的功能说明、涉及页面、API接口和数据结构。建议按照开发优先级进行分阶段开发，确保核心功能先完成，再逐步添加增强功能。