# 评委邀请码管理功能说明

## 功能概述

评委邀请码管理功能用于管理武术比赛中的评委邀请流程，包括发送邀请、跟踪邀请状态、管理评委回复等。

## 数据库升级

### 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
- ✅ 创建评委邀请码管理页面
- ✅ 实现邀请码展示和复制功能
- ✅ 添加邀请状态管理
- ✅ 实现统计卡片
- ✅ 支持搜索和筛选
- ✅ 创建数据库升级脚本
- ✅ 实现后端关联查询
- ✅ 添加邀请统计接口