library-picturebook-activity/docs/legacy/CONTEST_MANAGEMENT_PLAN.md

# 赛事管理模块产品方案与实现计划

## 📋 目录
1. [产品交互方案](#产品交互方案)
2. [数据库设计分析](#数据库设计分析)
3. [功能模块划分](#功能模块划分)
4. [实现计划](#实现计划)
5. [技术实现要点](#技术实现要点)

---

## 产品交互方案

### 1. 赛事创建

#### 1.1 功能概述
管理员创建赛事，填写赛事基本信息、时间安排、参赛范围等。

#### 1.2 交互流程
```
管理员进入"赛事管理" → 点击"创建赛事" → 填写表单 → 保存草稿/提交审核
```

#### 1.3 表单字段（基于 t_contest 表）
- **基本信息**
  - 赛事名称（必填，唯一性校验）
  - 赛事类型（字典：individual/team）
  - 赛事状态（默认：unpublished）
  - 封面图（上传）
  - 海报图（上传）
  - 赛事详情（富文本编辑器）

- **时间安排**
  - 赛事开始时间
  - 赛事结束时间
  - 报名开始时间
  - 报名结束时间
  - 作品提交开始时间
  - 作品提交结束时间
  - 评审开始时间
  - 评审结束时间
  - 结果发布时间（可选）

- **参赛范围**
  - 授权租户（多选，支持租户列表选择）
  - 提交规则（once/resubmit）

- **联系信息**
  - 联系人姓名
  - 联系电话
  - 联系人二维码（上传）

- **组织信息**
  - 主办单位（数组）
  - 协办单位（数组）
  - 赞助单位（数组）

- **线下信息**
  - 线下地址（可选）

- **评审规则**
  - 评审规则ID（关联评审规则配置）

#### 1.4 业务规则
- 时间顺序校验：报名开始 < 报名结束 < 提交开始 < 提交结束 < 评审开始 < 评审结束 < 结果发布
- 赛事名称在系统内唯一
- 创建后状态为 `unpublished`，需要发布后才能被租户看到
- 支持保存草稿（可多次编辑）

---

### 2. 赛事发布

#### 2.1 功能概述
管理员将已创建的赛事发布，使其对授权租户可见。

#### 2.2 交互流程
```
赛事列表 → 选择赛事 → 点击"发布" → 确认发布 → 更新状态为 published
```

#### 2.3 业务规则
- 只有状态为 `unpublished` 的赛事可以发布
- 发布前校验必填字段完整性
- 发布后，授权租户可以看到该赛事
- 已发布的赛事可以撤回（状态改回 `unpublished`），但需要检查是否有报名记录

---

### 3. 赛事公告

#### 3.1 功能概述
管理员发布赛事相关公告，通知参赛者重要信息。

#### 3.2 交互流程
```
赛事详情页 → "公告管理" → 创建公告 → 编辑内容 → 发布公告
```

#### 3.3 功能设计
**注意**：当前 SQL 中没有公告表，需要新增：
- `t_contest_notice` 表
  - id, contest_id, title, content, notice_type, priority, publish_time, creator, create_time, modify_time, valid_state

#### 3.4 公告类型
- 系统公告（系统自动生成）
- 人工公告（管理员发布）
- 紧急通知（高优先级）

---

### 4. 赛事报名

#### 4.1 功能概述
授权租户的用户（学生/老师）报名参加赛事，支持个人赛和团队赛。

#### 4.2 交互流程

**个人赛报名：**
```
租户用户登录 → 浏览已发布赛事 → 选择赛事 → 点击"立即报名" → 填写信息 → 提交报名
```

**团队赛报名：**
```
队长创建团队 → 邀请成员 → 成员确认加入 → 队长提交团队报名 → 等待审核
```

#### 4.3 报名流程详细设计

**4.3.1 个人赛报名**
1. 用户选择赛事
2. 检查报名时间是否在有效期内
3. 检查用户是否已报名（防止重复报名）
4. 填写报名信息（账号信息自动填充）
5. 提交报名（状态：pending）
6. 管理员审核（可选，根据赛事配置）
7. 审核通过（状态：passed）或拒绝（状态：rejected）

**4.3.2 团队赛报名**
1. 队长创建团队
   - 填写团队名称（租户内唯一）
   - 设置最大成员数
   - 邀请成员（通过账号搜索）
2. 成员确认加入
   - 收到邀请通知
   - 确认/拒绝加入
3. 队长提交团队报名
   - 检查团队成员数量是否符合要求
   - 提交报名（所有成员状态：pending）
4. 管理员审核团队报名
   - 审核通过：所有成员状态改为 passed
   - 审核拒绝：所有成员状态改为 rejected

#### 4.4 数据表关系
- `t_contest_registration`：报名记录表
  - 个人赛：registration_type = 'individual'，team_id = null
  - 团队赛：registration_type = 'team'，team_id 关联 t_contest_team
- `t_contest_team`：团队表
- `t_contest_team_member`：团队成员表

#### 4.5 业务规则
- 报名时间限制：必须在 `register_start_time` 和 `register_end_time` 之间
- 报名状态流转：pending → passed/rejected/withdrawn
- 已通过的报名可以撤回（withdrawn），但需要检查是否已提交作品
- 团队名称在同一赛事、同一租户内唯一
- 团队成员角色：leader（队长）、member（队员）、mentor（指导教师）

---

### 5. 赛事作品提交

#### 5.1 功能概述
已报名的用户提交参赛作品，支持单次提交和多次提交（根据赛事配置）。

#### 5.2 交互流程
```
已报名用户 → 进入"我的赛事" → 选择赛事 → 点击"提交作品" → 上传作品文件 → 填写作品信息 → 提交
```

#### 5.3 作品提交表单
- 作品标题（必填）
- 作品说明（可选）
- 作品文件（支持多文件上传）
  - 图片、视频、3D模型等
  - 文件类型和大小限制
- 作品预览URL（可选，用于3D/视频预览）
- AI建模元数据（可选，JSON格式）

#### 5.4 提交规则

**单次提交（submit_rule = 'once'）：**
- 只能提交一次作品
- 提交后状态为 `submitted`，不可修改

**多次提交（submit_rule = 'resubmit'）：**
- 可以多次提交作品
- 每次提交创建新版本（version 递增）
- 旧版本 `is_latest = 0`，新版本 `is_latest = 1`
- 只有最新版本参与评审

#### 5.5 数据表关系
- `t_contest_work`：作品主表
  - entry_id 关联 t_contest_registration.id
  - files 字段存储简易文件列表（JSON）
- `t_contest_work_attachment`：作品附件表（详细文件信息）

#### 5.6 业务规则
- 提交时间限制：必须在 `submit_start_time` 和 `submit_end_time` 之间
- 必须已通过报名审核（registration_state = 'passed'）
- 作品编号（work_no）自动生成，格式：CONTEST-{contest_id}-{序号}
- 作品状态流转：
  - submitted（已提交）
  - locked（已锁定，不可修改）
  - reviewing（评审中）
  - rejected（已拒绝）
  - accepted（已接受）

---

### 6. 赛事作品评审

#### 6.1 功能概述
评委对提交的作品进行评分，支持多维度评分和评语。

#### 6.2 交互流程
```
评委登录 → 进入"评审管理" → 选择赛事 → 查看分配的作品列表 → 点击作品 → 查看作品详情 → 评分 → 提交评分
```

#### 6.3 评审流程设计

**6.3.1 作品分配**
- 需要新增表：`t_contest_work_judge_assignment`（作品分配表）
  - id, contest_id, work_id, judge_id, assignment_time, status
- 管理员或系统自动分配作品给评委
- 支持手动分配和自动分配（轮询、随机等）

**6.3.2 评分界面**
- 显示作品信息（标题、说明、文件、预览等）
- 显示评审规则（review_rule_id 关联的评审规则）
- 多维度评分表单
  - 根据评审规则动态生成评分维度
  - 每个维度设置分数范围
  - 总分自动计算（根据评审规则配置的权重）
- 评语输入框
- 提交评分按钮

**6.3.3 评分数据**
- `t_contest_work_score`：评分表
  - dimension_scores：JSON格式，存储各维度分数
  - total_score：总分（根据规则计算）
  - comments：评语

#### 6.4 评审规则设计
需要新增表：`t_contest_review_rule`（评审规则表）
- id, contest_id, rule_name, dimensions（JSON，存储评分维度配置）
- 示例维度配置：
  ```json
  {
    "dimension1": {
      "name": "创意性",
      "weight": 0.3,
      "maxScore": 100
    },
    "dimension2": {
      "name": "技术性",
      "weight": 0.4,
      "maxScore": 100
    },
    "dimension3": {
      "name": "完成度",
      "weight": 0.3,
      "maxScore": 100
    }
  }
  ```

#### 6.5 业务规则
- 评审时间限制：必须在 `review_start_time` 和 `review_end_time` 之间
- 作品状态更新：评审开始时，作品状态改为 `reviewing`
- 每个作品可以被多个评委评审
- 最终得分计算：取所有评委的平均分，或根据评审规则计算
- 评审完成后，作品状态改为 `accepted` 或 `rejected`

---

### 7. 赛事结果公布

#### 7.1 功能概述
管理员公布赛事评审结果，包括获奖名单、排名等。

#### 7.2 交互流程
```
管理员 → 进入"赛事管理" → 选择赛事 → 点击"公布结果" → 确认公布 → 结果发布
```

#### 7.3 结果公布内容
- 获奖名单（按奖项分类）
- 作品排名（按总分排序）
- 各维度平均分统计
- 评审统计信息（参与评审人数、作品数量等）

#### 7.4 业务规则
- 只有评审已完成的赛事可以公布结果
- 公布后，`result_publish_time` 设置为当前时间
- 结果公布后，所有用户可以看到排名和获奖信息
- 支持导出结果（Excel/PDF）

---

## 数据库设计分析

### 现有表结构

#### 1. t_contest（赛事表）
✅ **优点：**
- 字段设计完整，覆盖赛事全生命周期
- 支持多租户（contest_tenant 字段）
- 时间字段齐全

⚠️ **注意事项：**
- `contest_tenant` 使用 text 类型存储租户列表，建议考虑 JSON 类型或关联表
- `organizers`、`co_organizers`、`sponsors` 使用 text 存储数组，建议使用 JSON

#### 2. t_contest_attachment（赛事附件表）
✅ 设计合理，支持多种文件类型

#### 3. t_contest_work（作品表）
✅ **优点：**
- 支持版本控制（version、is_latest）
- 支持多种提交来源（teacher/student/team_leader）
- 支持 AI 建模元数据

⚠️ **问题：**
- 索引 `idx_submit_filter` 引用了不存在的字段 `review_status`，应删除或修正

#### 4. t_contest_work_attachment（作品附件表）
⚠️ **问题：**
- 第102行末尾有多余的逗号，需要删除

#### 5. t_contest_work_score（评分表）
⚠️ **问题：**
- 表定义重复（104-123行和125-144行），需要删除重复定义

#### 6. t_contest_registration（报名表）
✅ 设计合理，支持个人和团队报名

#### 7. t_contest_team（团队表）
⚠️ **问题：**
- 唯一索引 `uk_team_name` 引用了不存在的字段 `name`，应改为 `team_name`

#### 8. t_contest_team_member（团队成员表）
✅ 设计合理

### 缺失的表结构

#### 1. t_contest_notice（赛事公告表）
```sql
CREATE TABLE `t_contest_notice` (
  `id` varchar(63) NOT NULL COMMENT '主键id',
  `contest_id` varchar(63) NOT NULL COMMENT '赛事id',
  `title` varchar(255) NOT NULL COMMENT '公告标题',
  `content` text NOT NULL COMMENT '公告内容',
  `notice_type` varchar(31) NOT NULL DEFAULT 'manual' COMMENT '公告类型：system/manual/urgent',
  `priority` int DEFAULT 0 COMMENT '优先级（数字越大优先级越高）',
  `publish_time` datetime DEFAULT NULL COMMENT '发布时间',
  `creator` varchar(63) NOT NULL DEFAULT '' COMMENT '创建人',
  `modifier` varchar(63) NOT NULL DEFAULT '' COMMENT '修改人',
  `create_time` datetime DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
  `modify_time` datetime DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
  `valid_state` varchar(1) NOT NULL DEFAULT '1' COMMENT '有效状态（1-有效，2-失效）',
  PRIMARY KEY (`id`),
  KEY `idx_contest` (`contest_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='赛事公告表';
```

#### 2. t_contest_review_rule（评审规则表）
```sql
CREATE TABLE `t_contest_review_rule` (
  `id` varchar(63) NOT NULL COMMENT '主键id',
  `contest_id` varchar(63) NOT NULL COMMENT '赛事id',
  `rule_name` varchar(127) NOT NULL COMMENT '规则名称',
  `dimensions` json NOT NULL COMMENT '评分维度配置JSON',
  `calculation_rule` varchar(31) DEFAULT 'average' COMMENT '计算规则：average/max/min/weighted',
  `creator` varchar(63) NOT NULL DEFAULT '' COMMENT '创建人',
  `modifier` varchar(63) NOT NULL DEFAULT '' COMMENT '修改人',
  `create_time` datetime DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
  `modify_time` datetime DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
  `valid_state` varchar(1) NOT NULL DEFAULT '1' COMMENT '有效状态（1-有效，2-失效）',
  PRIMARY KEY (`id`),
  KEY `idx_contest` (`contest_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='评审规则表';
```

#### 3. t_contest_work_judge_assignment（作品分配表）
```sql
CREATE TABLE `t_contest_work_judge_assignment` (
  `id` varchar(63) NOT NULL COMMENT '主键id',
  `contest_id` varchar(63) NOT NULL COMMENT '赛事id',
  `work_id` varchar(63) NOT NULL COMMENT '作品id',
  `judge_id` varchar(63) NOT NULL COMMENT '评委用户id',
  `assignment_time` datetime DEFAULT CURRENT_TIMESTAMP COMMENT '分配时间',
  `status` varchar(31) NOT NULL DEFAULT 'assigned' COMMENT '分配状态：assigned/reviewing/completed',
  `creator` varchar(63) NOT NULL DEFAULT '' COMMENT '创建人',
  `modifier` varchar(63) NOT NULL DEFAULT '' COMMENT '修改人',
  `create_time` datetime DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
  `modify_time` datetime DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
  PRIMARY KEY (`id`),
  UNIQUE KEY `uk_work_judge` (`work_id`, `judge_id`),
  KEY `idx_contest_judge` (`contest_id`, `judge_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='作品分配表';
```

---

## 功能模块划分

### 后端模块结构

```
backend/src/contests/
├── contests.module.ts          # 赛事主模块
├── contests.controller.ts       # 赛事控制器
├── contests.service.ts         # 赛事服务
├── dto/
│   ├── create-contest.dto.ts
│   ├── update-contest.dto.ts
│   ├── query-contest.dto.ts
│   └── publish-contest.dto.ts
├── works/
│   ├── works.module.ts
│   ├── works.controller.ts
│   ├── works.service.ts
│   └── dto/
│       ├── create-work.dto.ts
│       ├── update-work.dto.ts
│       └── submit-work.dto.ts
├── registrations/
│   ├── registrations.module.ts
│   ├── registrations.controller.ts
│   ├── registrations.service.ts
│   └── dto/
│       ├── create-registration.dto.ts
│       ├── review-registration.dto.ts
│       └── create-team.dto.ts
├── teams/
│   ├── teams.module.ts
│   ├── teams.controller.ts
│   ├── teams.service.ts
│   └── dto/
│       ├── create-team.dto.ts
│       └── invite-member.dto.ts
├── reviews/
│   ├── reviews.module.ts
│   ├── reviews.controller.ts
│   ├── reviews.service.ts
│   └── dto/
│       ├── create-score.dto.ts
│       ├── assign-work.dto.ts
│       └── create-review-rule.dto.ts
└── notices/
    ├── notices.module.ts
    ├── notices.controller.ts
    ├── notices.service.ts
    └── dto/
        ├── create-notice.dto.ts
        └── update-notice.dto.ts
```

### 前端模块结构

```
frontend/src/views/contests/
├── Index.vue                    # 赛事列表页
├── Create.vue                   # 创建赛事页
├── Detail.vue                   # 赛事详情页
├── Edit.vue                     # 编辑赛事页
├── works/
│   ├── Index.vue                # 作品列表页
│   ├── Submit.vue               # 提交作品页
│   └── Detail.vue               # 作品详情页
├── registrations/
│   ├── Index.vue                # 报名列表页
│   ├── Register.vue            # 报名页
│   └── Review.vue              # 审核报名页
├── teams/
│   ├── Index.vue                # 团队列表页
│   ├── Create.vue               # 创建团队页
│   └── Detail.vue               # 团队详情页
├── reviews/
│   ├── Index.vue                # 评审列表页
│   ├── Score.vue                # 评分页
│   └── Results.vue              # 结果公布页
└── notices/
    ├── Index.vue                # 公告列表页
    └── Create.vue                # 创建公告页
```

---

## 实现计划

### 阶段一：基础功能（2-3周）

#### 1.1 数据库迁移
- [ ] 修复 SQL 文件中的错误
  - 删除 `t_contest_work_score` 重复定义
  - 修复 `t_contest_work_attachment` 的逗号错误
  - 修复 `t_contest_team` 索引字段名错误
  - 修复 `t_contest_work` 索引字段错误
- [ ] 创建缺失的表（公告表、评审规则表、作品分配表）
- [ ] 更新 Prisma schema
- [ ] 执行数据库迁移

#### 1.2 后端基础模块
- [ ] 创建 contests 模块（Controller、Service、DTO）
- [ ] 实现赛事 CRUD 接口
- [ ] 实现赛事发布/撤回接口
- [ ] 实现租户权限控制
- [ ] 编写单元测试

#### 1.3 前端基础页面
- [ ] 创建赛事列表页
- [ ] 创建赛事创建/编辑页
- [ ] 创建赛事详情页
- [ ] 集成权限控制
- [ ] 实现路由配置

### 阶段二：报名功能（2周）

#### 2.1 后端实现
- [ ] 创建 registrations 模块
- [ ] 实现个人报名接口
- [ ] 实现团队报名接口
- [ ] 实现报名审核接口
- [ ] 实现报名状态流转逻辑

#### 2.2 前端实现
- [ ] 创建报名页面
- [ ] 创建团队管理页面
- [ ] 创建报名审核页面
- [ ] 实现报名状态展示

### 阶段三：作品提交功能（2周）

#### 3.1 后端实现
- [ ] 创建 works 模块
- [ ] 实现作品提交接口
- [ ] 实现文件上传功能
- [ ] 实现作品版本控制逻辑
- [ ] 实现作品状态管理

#### 3.2 前端实现
- [ ] 创建作品提交页面
- [ ] 实现文件上传组件
- [ ] 创建作品列表页
- [ ] 创建作品详情页

### 阶段四：评审功能（2-3周）

#### 4.1 后端实现
- [ ] 创建 reviews 模块
- [ ] 实现评审规则管理接口
- [ ] 实现作品分配接口
- [ ] 实现评分接口
- [ ] 实现评分计算逻辑

#### 4.2 前端实现
- [ ] 创建评审规则配置页
- [ ] 创建作品分配页
- [ ] 创建评分页面
- [ ] 实现多维度评分表单

### 阶段五：结果公布与公告（1周）

#### 5.1 后端实现
- [ ] 创建 notices 模块
- [ ] 实现公告 CRUD 接口
- [ ] 实现结果公布接口
- [ ] 实现结果统计接口

#### 5.2 前端实现
- [ ] 创建公告管理页面
- [ ] 创建结果公布页面
- [ ] 实现结果展示页面

### 阶段六：优化与测试（1-2周）

#### 6.1 功能优化
- [ ] 性能优化（数据库查询优化、缓存）
- [ ] 用户体验优化
- [ ] 错误处理完善

#### 6.2 测试
- [ ] 单元测试
- [ ] 集成测试
- [ ] 端到端测试
- [ ] 压力测试

---

## 技术实现要点

### 1. 权限设计

#### 1.1 权限编码规划
```
contest:create      # 创建赛事
contest:read        # 查看赛事
contest:update      # 更新赛事
contest:delete      # 删除赛事
contest:publish     # 发布赛事
contest:register    # 报名赛事
work:submit         # 提交作品
work:read           # 查看作品
work:update         # 更新作品
review:assign       # 分配作品
review:score        # 评分
review:read         # 查看评审
result:publish      # 公布结果
notice:create       # 创建公告
notice:read         # 查看公告
```

#### 1.2 角色规划
- **超级管理员**：所有权限
- **赛事管理员**：contest:*、notice:*、result:publish
- **评委**：review:assign、review:score、review:read、work:read
- **参赛者**：contest:read、contest:register、work:submit、work:read

### 2. 租户隔离

#### 2.1 数据隔离策略
- 赛事创建：超级租户创建，通过 `contest_tenant` 字段控制可见范围
- 报名数据：通过 `tenant_key` 字段隔离
- 作品数据：通过 `tenant_key` 字段隔离
- 评审数据：通过 `tenant_key` 字段隔离

#### 2.2 接口权限控制
- 使用 `@TenantId()` 装饰器获取租户信息
- Service 层自动过滤租户数据
- Controller 层验证租户权限

### 3. 时间状态管理

#### 3.1 赛事状态机
```
unpublished → published → (可撤回) → unpublished
```

#### 3.2 报名状态机
```
pending → passed/rejected/withdrawn
```

#### 3.3 作品状态机
```
submitted → locked → reviewing → accepted/rejected
```

#### 3.4 定时任务
- 自动更新报名状态（根据时间）
- 自动更新作品提交状态
- 自动更新评审状态
- 自动发送通知（可选）

### 4. 文件上传

#### 4.1 文件存储
- 使用对象存储（OSS/S3）或本地存储
- 文件类型限制：图片、视频、3D模型、文档等
- 文件大小限制：根据文件类型设置

#### 4.2 文件管理
- 文件上传接口
- 文件删除接口
- 文件预览接口
- 文件下载接口

### 5. 通知系统

#### 5.1 通知类型
- 报名成功通知
- 报名审核结果通知
- 作品提交成功通知
- 评审结果通知
- 结果公布通知

#### 5.2 通知方式（可选）
- 站内消息
- 邮件通知
- 短信通知（可选）

### 6. 数据统计

#### 6.1 赛事统计
- 报名人数统计
- 作品提交数量统计
- 评审进度统计
- 结果统计

#### 6.2 报表导出
- 报名名单导出（Excel）
- 作品列表导出（Excel）
- 评审结果导出（Excel）
- 结果报告导出（PDF）

---

## 注意事项

### 1. SQL 文件问题修复
在开始开发前，必须先修复 SQL 文件中的错误：
- 删除重复的 `t_contest_work_score` 表定义
- 修复 `t_contest_work_attachment` 表的语法错误
- 修复 `t_contest_team` 表的索引错误
- 修复 `t_contest_work` 表的索引错误

### 2. 数据一致性
- 报名和作品的关系：一个报名可以对应多个作品版本
- 团队和报名的关系：一个团队对应多个报名记录（每个成员一条）
- 作品和评分的关系：一个作品可以有多条评分记录（多个评委）

### 3. 性能考虑
- 赛事列表查询需要分页
- 作品列表查询需要分页和筛选
- 评分计算需要缓存
- 文件上传需要异步处理

### 4. 安全性
- 文件上传需要验证文件类型和大小
- 接口需要权限验证
- 敏感操作需要日志记录
- 防止 SQL 注入和 XSS 攻击

---

## 总结

本方案基于现有的多租户 RBAC 系统架构，设计了完整的赛事管理功能模块。主要特点：

1. **完整的生命周期管理**：从赛事创建到结果公布的全流程
2. **灵活的参赛方式**：支持个人赛和团队赛
3. **强大的评审系统**：支持多维度评分和自定义评审规则
4. **良好的扩展性**：模块化设计，易于扩展新功能

建议按照阶段逐步实现，每个阶段完成后进行测试和优化，确保系统稳定可靠。