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的存储、验证、刷新

存储方式:

// 存储Token
uni.setStorageSync('auth_token', token)

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

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

1.3.3 权限验证

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

权限控制:

// 获取用户角色
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 数据结构

// 登录凭证
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 数据结构

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 场地切换

交互方式: 横向滚动选择

实现方式:

<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 数据结构

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 项目切换

交互方式: 横向滚动选择

实现方式:

<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 数据结构

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 数据结构

// 普通评委<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

实现方式:

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项

交互方式:

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 数据结构

// 评分提交
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

实现方式:

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 数据结构

// 修改提交
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 数据结构

// 扣分项
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 数据结构

// 比赛统计
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连接

// 连接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 数据结构

// 新评分推送
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接口和数据结构。建议按照开发优先级进行分阶段开发，确保核心功能先完成，再逐步添加增强功能。