This commit is contained in:
277
docs/judge-invite-feature.md
Normal file
277
docs/judge-invite-feature.md
Normal file
@@ -0,0 +1,277 @@
|
||||
# 评委邀请码管理功能说明
|
||||
|
||||
## 功能概述
|
||||
|
||||
评委邀请码管理功能用于管理武术比赛中的评委邀请流程，包括发送邀请、跟踪邀请状态、管理评委回复等。
|
||||
|
||||
## 数据库升级
|
||||
|
||||
### 1. 执行升级脚本
|
||||
|
||||
在执行新功能之前，需要先升级数据库表结构：
|
||||
|
||||
```bash
|
||||
mysql -h localhost -P 3306 -u root -p blade < database/martial-db/upgrade_judge_invite_table.sql
|
||||
```
|
||||
|
||||
### 2. 插入测试数据（可选）
|
||||
|
||||
如果需要测试数据，可以执行：
|
||||
|
||||
```bash
|
||||
mysql -h localhost -P 3306 -u root -p blade < database/martial-db/insert_test_judge_invite_data.sql
|
||||
```
|
||||
|
||||
## 新增字段说明
|
||||
|
||||
| 字段名 | 类型 | 说明 |
|
||||
|--------|------|------|
|
||||
| invite_status | INT | 邀请状态(0-待回复,1-已接受,2-已拒绝,3-已取消) |
|
||||
| invite_time | DATETIME | 邀请时间 |
|
||||
| reply_time | DATETIME | 回复时间 |
|
||||
| reply_note | VARCHAR(500) | 回复备注 |
|
||||
| contact_phone | VARCHAR(20) | 联系电话 |
|
||||
| contact_email | VARCHAR(100) | 联系邮箱 |
|
||||
| invite_message | VARCHAR(1000) | 邀请消息 |
|
||||
| cancel_reason | VARCHAR(500) | 取消原因 |
|
||||
|
||||
## 后端接口
|
||||
|
||||
### 1. 分页查询邀请列表
|
||||
|
||||
**接口地址**: `GET /api/blade-martial/judgeInvite/list`
|
||||
|
||||
**请求参数**:
|
||||
- `current`: 当前页码（默认1）
|
||||
- `size`: 每页条数（默认10）
|
||||
- `competitionId`: 赛事ID（必填）
|
||||
- `judgeName`: 裁判姓名（可选，模糊查询）
|
||||
- `judgeLevel`: 裁判等级（可选）
|
||||
- `inviteStatus`: 邀请状态（可选）
|
||||
|
||||
**响应示例**:
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"success": true,
|
||||
"data": {
|
||||
"records": [
|
||||
{
|
||||
"id": 1,
|
||||
"competitionId": 1,
|
||||
"judgeId": 1,
|
||||
"judgeName": "张三",
|
||||
"judgeLevel": "国家级",
|
||||
"inviteCode": "INV2025001",
|
||||
"contactPhone": "13800138001",
|
||||
"contactEmail": "zhangsan@example.com",
|
||||
"inviteStatus": 0,
|
||||
"inviteTime": "2025-12-12 00:00:00",
|
||||
"replyTime": null,
|
||||
"replyNote": null
|
||||
}
|
||||
],
|
||||
"total": 5,
|
||||
"size": 10,
|
||||
"current": 1
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. 获取邀请统计
|
||||
|
||||
**接口地址**: `GET /api/blade-martial/judgeInvite/statistics`
|
||||
|
||||
**请求参数**:
|
||||
- `competitionId`: 赛事ID（必填）
|
||||
|
||||
**响应示例**:
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"success": true,
|
||||
"data": {
|
||||
"totalInvites": 5,
|
||||
"pendingCount": 2,
|
||||
"acceptedCount": 2,
|
||||
"rejectedCount": 1
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3. 新增或修改邀请
|
||||
|
||||
**接口地址**: `POST /api/blade-martial/judgeInvite/submit`
|
||||
|
||||
**请求体**:
|
||||
```json
|
||||
{
|
||||
"competitionId": 1,
|
||||
"judgeId": 1,
|
||||
"inviteCode": "INV2025001",
|
||||
"role": "judge",
|
||||
"contactPhone": "13800138001",
|
||||
"contactEmail": "zhangsan@example.com",
|
||||
"inviteMessage": "诚邀您担任本次武术比赛的裁判",
|
||||
"inviteStatus": 0,
|
||||
"inviteTime": "2025-12-12 00:00:00",
|
||||
"expireTime": "2025-01-12 00:00:00"
|
||||
}
|
||||
```
|
||||
|
||||
## 前端页面
|
||||
|
||||
### 页面路径
|
||||
`src/views/martial/judgeInvite/index.vue`
|
||||
|
||||
### 主要功能
|
||||
|
||||
#### 1. 搜索和筛选
|
||||
- 选择赛事
|
||||
- 按评委姓名搜索
|
||||
- 按评委等级筛选
|
||||
- 按邀请状态筛选
|
||||
|
||||
#### 2. 统计卡片
|
||||
显示以下统计信息：
|
||||
- 总邀请数
|
||||
- 待回复数量
|
||||
- 已接受数量
|
||||
- 已拒绝数量
|
||||
|
||||
#### 3. 数据表格
|
||||
显示以下信息：
|
||||
- 评委姓名
|
||||
- 评委等级（彩色标签）
|
||||
- **邀请码**（橙色标签，点击可复制）
|
||||
- 联系电话
|
||||
- 联系邮箱
|
||||
- 邀请状态（彩色标签）
|
||||
- 邀请时间
|
||||
- 回复时间
|
||||
- 回复备注
|
||||
|
||||
#### 4. 操作按钮
|
||||
- **重发**: 重新发送邀请（仅待回复状态）
|
||||
- **提醒**: 发送提醒消息（仅待回复状态）
|
||||
- **取消**: 取消邀请（仅待回复状态）
|
||||
- **查看**: 查看详情
|
||||
- **确认**: 确认接受（仅已接受状态）
|
||||
|
||||
#### 5. 工具栏
|
||||
- 发送邀请
|
||||
- 批量邀请
|
||||
- 从评委库导入
|
||||
- 导出数据
|
||||
- 刷新
|
||||
|
||||
### 邀请码复制功能
|
||||
|
||||
点击表格中的邀请码（橙色标签），会自动复制到剪贴板，并显示成功提示。
|
||||
|
||||
支持两种复制方式：
|
||||
1. 现代浏览器：使用 Clipboard API
|
||||
2. 旧浏览器：使用 document.execCommand('copy') 降级方案
|
||||
|
||||
## 使用流程
|
||||
|
||||
### 1. 发送邀请
|
||||
1. 进入评委邀请码管理页面
|
||||
2. 选择赛事
|
||||
3. 点击"发送邀请"或"批量邀请"
|
||||
4. 填写评委信息和邀请消息
|
||||
5. 系统自动生成邀请码
|
||||
6. 发送邀请给评委
|
||||
|
||||
### 2. 评委回复
|
||||
评委收到邀请后，使用邀请码登录小程序：
|
||||
1. 输入邀请码
|
||||
2. 查看邀请详情
|
||||
3. 选择接受或拒绝
|
||||
4. 填写回复备注（可选）
|
||||
|
||||
### 3. 管理邀请
|
||||
1. 查看邀请列表和统计
|
||||
2. 对待回复的邀请进行重发或提醒
|
||||
3. 确认已接受的邀请
|
||||
4. 取消不需要的邀请
|
||||
|
||||
## 状态说明
|
||||
|
||||
| 状态值 | 状态名称 | 标签颜色 | 说明 |
|
||||
|--------|---------|---------|------|
|
||||
| 0 | 待回复 | 橙色 | 邀请已发送，等待评委回复 |
|
||||
| 1 | 已接受 | 绿色 | 评委已接受邀请 |
|
||||
| 2 | 已拒绝 | 红色 | 评委已拒绝邀请 |
|
||||
| 3 | 已取消 | 灰色 | 主办方已取消邀请 |
|
||||
|
||||
## 注意事项
|
||||
|
||||
1. **邀请码唯一性**: 每个邀请码必须唯一，建议使用格式：`INV + 年份 + 序号`
|
||||
2. **过期时间**: 邀请码应设置合理的过期时间，建议30天
|
||||
3. **联系方式**: 确保填写正确的联系电话和邮箱，便于后续沟通
|
||||
4. **状态流转**:
|
||||
- 待回复 → 已接受/已拒绝（评委操作）
|
||||
- 待回复 → 已取消（主办方操作）
|
||||
- 已接受 → 已取消（主办方操作）
|
||||
|
||||
## 技术实现
|
||||
|
||||
### 后端
|
||||
- **实体类**: `MartialJudgeInvite`
|
||||
- **VO类**: `MartialJudgeInviteVO`（包含关联的裁判信息）
|
||||
- **Mapper**: `MartialJudgeInviteMapper`（支持关联查询）
|
||||
- **Service**: `IMartialJudgeInviteService`
|
||||
- **Controller**: `MartialJudgeInviteController`
|
||||
|
||||
### 前端
|
||||
- **框架**: Vue 3 + Element Plus
|
||||
- **API**: `src/api/martial/judgeInvite.js`
|
||||
- **页面**: `src/views/martial/judgeInvite/index.vue`
|
||||
|
||||
### 数据库
|
||||
- **主表**: `martial_judge_invite`
|
||||
- **关联表**:
|
||||
- `martial_judge`（裁判信息）
|
||||
- `martial_competition`（赛事信息）
|
||||
|
||||
## 待完善功能
|
||||
|
||||
以下功能目前显示"开发中"提示，可以后续添加：
|
||||
|
||||
1. **发送邀请对话框**: 完整的邀请发送表单
|
||||
2. **批量邀请对话框**: 批量选择评委并发送邀请
|
||||
3. **从评委库导入**: 从裁判库中选择评委并自动生成邀请
|
||||
4. **取消邀请对话框**: 填写取消原因
|
||||
5. **查看详情对话框**: 显示邀请的完整信息
|
||||
6. **导出功能**: 导出邀请名单为Excel文件
|
||||
|
||||
## 测试建议
|
||||
|
||||
1. **单元测试**: 测试Service层的业务逻辑
|
||||
2. **集成测试**: 测试Controller层的接口
|
||||
3. **前端测试**: 测试页面交互和数据展示
|
||||
4. **端到端测试**: 测试完整的邀请流程
|
||||
|
||||
## 常见问题
|
||||
|
||||
### Q1: 邀请码复制失败？
|
||||
A: 检查浏览器是否支持Clipboard API，或者是否在HTTPS环境下。如果都不满足，会自动使用降级方案。
|
||||
|
||||
### Q2: 统计数据不准确？
|
||||
A: 确保数据库中的invite_status字段值正确，并且is_deleted字段为0。
|
||||
|
||||
### Q3: 关联查询性能问题？
|
||||
A: 已为competition_id和invite_status字段添加索引，如果数据量很大，可以考虑添加更多索引或使用缓存。
|
||||
|
||||
## 更新日志
|
||||
|
||||
### 2025-12-12
|
||||
- ✅ 创建评委邀请码管理页面
|
||||
- ✅ 实现邀请码展示和复制功能
|
||||
- ✅ 添加邀请状态管理
|
||||
- ✅ 实现统计卡片
|
||||
- ✅ 支持搜索和筛选
|
||||
- ✅ 创建数据库升级脚本
|
||||
- ✅ 实现后端关联查询
|
||||
- ✅ 添加邀请统计接口
|
||||
Reference in New Issue
Block a user