# 评委邀请码生成方案 - 实施指南

> **实施日期**: 2025-12-12
> **实施方式**: 管理员生成 → 复制发送 → 评委使用
> **状态**: ✅ 代码已完成，可立即测试

---

## 📋 方案概述

### 核心流程

```
管理员操作：
1. 进入评委管理页面
2. 选择评委，点击"生成邀请码"
3. 系统生成6位随机码（如：ABC123）
4. 复制邀请码
5. 通过微信/短信发送给评委

评委使用：
1. 收到邀请码
2. 打开小程序登录页
3. 输入比赛编码 + 邀请码
4. 登录成功，开始评分
```

### 技术特点

- ✅ **无需改表** - 使用现有字段
- ✅ **6位随机码** - 大写字母+数字组合
- ✅ **唯一性保证** - 数据库唯一索引
- ✅ **有效期管理** - 默认30天
- ✅ **状态管理** - 待使用/已使用/已禁用

---

## 🚀 已完成的代码

### 1. DTO 类

#### GenerateInviteDTO.java
**路径**: `src/main/java/org/springblade/modules/martial/pojo/dto/GenerateInviteDTO.java`

```java
@Data
@ApiModel("生成邀请码DTO")
public class GenerateInviteDTO {
    @NotNull(message = "赛事ID不能为空")
    private Long competitionId;

    @NotNull(message = "评委ID不能为空")
    private Long judgeId;

    @NotBlank(message = "角色不能为空")
    private String role;  // judge 或 chief_judge

    private Long venueId;  // 场地ID（普通评委必填）
    private String projects;  // 项目列表（JSON）
    private Integer expireDays = 30;  // 过期天数
}
```

#### BatchGenerateInviteDTO.java
**路径**: `src/main/java/org/springblade/modules/martial/pojo/dto/BatchGenerateInviteDTO.java`

```java
@Data
@ApiModel("批量生成邀请码DTO")
public class BatchGenerateInviteDTO {
    @NotNull(message = "赛事ID不能为空")
    private Long competitionId;

    @NotEmpty(message = "评委列表不能为空")
    private List<Long> judgeIds;

    private String role = "judge";
    private Integer expireDays = 30;
}
```

---

### 2. Service 层

#### IMartialJudgeInviteService.java
**新增方法**:

```java
// 生成邀请码
MartialJudgeInvite generateInviteCode(GenerateInviteDTO dto);

// 批量生成邀请码
List<MartialJudgeInvite> batchGenerateInviteCode(BatchGenerateInviteDTO dto);

// 重新生成邀请码
MartialJudgeInvite regenerateInviteCode(Long inviteId);

// 生成唯一邀请码
String generateUniqueInviteCode();
```

#### MartialJudgeInviteServiceImpl.java
**核心实现**:

1. **生成唯一邀请码**:
   ```java
   // 6位随机字符串（大写字母+数字）
   String inviteCode = UUID.randomUUID().toString()
       .replaceAll("-", "")
       .substring(0, 6)
       .toUpperCase();
   ```

2. **检查重复**:
   ```java
   // 检查邀请码是否已存在
   long count = this.count(
       Wrappers.<MartialJudgeInvite>lambdaQuery()
           .eq(MartialJudgeInvite::getInviteCode, inviteCode)
           .eq(MartialJudgeInvite::getIsDeleted, 0)
   );
   ```

3. **防止重复生成**:
   ```java
   // 检查评委是否已有有效邀请码
   MartialJudgeInvite existInvite = this.getOne(
       Wrappers.<MartialJudgeInvite>lambdaQuery()
           .eq(MartialJudgeInvite::getCompetitionId, competitionId)
           .eq(MartialJudgeInvite::getJudgeId, judgeId)
           .eq(MartialJudgeInvite::getStatus, 1)
           .gt(MartialJudgeInvite::getExpireTime, LocalDateTime.now())
   );
   ```

---

### 3. Controller 层

#### MartialJudgeInviteController.java
**新增接口**:

| 接口 | 方法 | 路径 | 说明 |
|------|------|------|------|
| 生成邀请码 | POST | `/martial/judgeInvite/generate` | 为单个评委生成 |
| 批量生成 | POST | `/martial/judgeInvite/generate/batch` | 批量生成 |
| 重新生成 | PUT | `/martial/judgeInvite/regenerate/{id}` | 重新生成（旧码失效） |
| 查询邀请码 | GET | `/martial/judgeInvite/byJudge` | 查询评委的邀请码 |

---

## 🧪 测试指南

### 1. 使用 Postman 测试

#### 测试1：生成邀请码

```http
POST http://localhost:8080/martial/judgeInvite/generate
Content-Type: application/json
Blade-Auth: Bearer {token}

{
  "competitionId": 1,
  "judgeId": 1,
  "role": "judge",
  "venueId": 1,
  "projects": "[\"女子组长拳\",\"男子组陈氏太极拳\"]",
  "expireDays": 30
}
```

**预期响应**:
```json
{
  "code": 200,
  "success": true,
  "data": {
    "id": 1001,
    "competitionId": 1,
    "judgeId": 1,
    "inviteCode": "ABC123",
    "role": "judge",
    "venueId": 1,
    "projects": "[\"女子组长拳\",\"男子组陈氏太极拳\"]",
    "expireTime": "2026-01-11 10:00:00",
    "isUsed": 0,
    "status": 1
  }
}
```

#### 测试2：批量生成邀请码

```http
POST http://localhost:8080/martial/judgeInvite/generate/batch
Content-Type: application/json
Blade-Auth: Bearer {token}

{
  "competitionId": 1,
  "judgeIds": [1, 2, 3, 4, 5],
  "role": "judge",
  "expireDays": 30
}
```

#### 测试3：查询评委邀请码

```http
GET http://localhost:8080/martial/judgeInvite/byJudge?competitionId=1&judgeId=1
Blade-Auth: Bearer {token}
```

#### 测试4：重新生成邀请码

```http
PUT http://localhost:8080/martial/judgeInvite/regenerate/1001
Blade-Auth: Bearer {token}
```

---

### 2. 使用 SQL 测试

#### 执行测试脚本

```bash
# 进入数据库
mysql -u root -p blade

# 执行测试脚本
source database/martial-db/test_invite_code_generation.sql
```

#### 查询有效邀请码

```sql
SELECT
    ji.id,
    ji.invite_code,
    ji.role,
    j.name AS judge_name,
    ji.expire_time,
    ji.is_used,
    CASE
        WHEN ji.is_used = 1 THEN '已使用'
        WHEN ji.expire_time < NOW() THEN '已过期'
        WHEN ji.status = 0 THEN '已禁用'
        ELSE '待使用'
    END AS status_text
FROM martial_judge_invite ji
LEFT JOIN martial_judge j ON ji.judge_id = j.id
WHERE ji.competition_id = 1
  AND ji.is_deleted = 0
ORDER BY ji.create_time DESC;
```

---

## 📊 数据库字段说明

### martial_judge_invite 表

| 字段 | 类型 | 说明 | 使用方式 |
|------|------|------|----------|
| `invite_code` | varchar(50) | 邀请码 | 6位随机码 |
| `status` | int | 状态 | 1-启用，0-禁用 |
| `is_used` | int | 是否已使用 | 0-未使用，1-已使用 |
| `expire_time` | datetime | 过期时间 | 默认30天后 |
| `use_time` | datetime | 使用时间 | 登录时记录 |
| `role` | varchar(20) | 角色 | judge/chief_judge |
| `venue_id` | bigint | 场地ID | 普通评委必填 |
| `projects` | varchar(500) | 项目列表 | JSON数组 |

### 状态判断逻辑

```
有效邀请码：status=1 AND is_used=0 AND expire_time>NOW()
已使用：is_used=1
已过期：expire_time<=NOW()
已禁用：status=0
```

---

## 🎯 前端集成建议

### 1. 在评委管理页面添加按钮

```vue
<template>
  <el-table :data="judgeList">
    <el-table-column label="操作">
      <template #default="{ row }">
        <!-- 生成邀请码按钮 -->
        <el-button
          v-if="!row.inviteCode"
          type="primary"
          size="small"
          @click="generateInviteCode(row)"
        >
          生成邀请码
        </el-button>

        <!-- 显示邀请码 -->
        <div v-else>
          <el-tag>{{ row.inviteCode }}</el-tag>
          <el-button
            type="text"
            size="small"
            @click="copyInviteCode(row.inviteCode)"
          >
            复制
          </el-button>
          <el-button
            type="text"
            size="small"
            @click="regenerateInviteCode(row)"
          >
            重新生成
          </el-button>
        </div>
      </template>
    </el-table-column>
  </el-table>
</template>
```

### 2. 生成邀请码方法

```javascript
async generateInviteCode(judge) {
  try {
    const res = await this.$http.post('/martial/judgeInvite/generate', {
      competitionId: this.competitionId,
      judgeId: judge.id,
      role: judge.refereeType === 1 ? 'chief_judge' : 'judge',
      venueId: judge.venueId,
      projects: JSON.stringify(judge.projects),
      expireDays: 30
    });

    if (res.success) {
      this.$message.success('邀请码生成成功：' + res.data.inviteCode);
      // 复制到剪贴板
      this.copyToClipboard(res.data.inviteCode);
      // 刷新列表
      this.loadJudgeList();
    }
  } catch (error) {
    this.$message.error(error.message || '生成失败');
  }
}

// 复制到剪贴板
copyToClipboard(text) {
  const input = document.createElement('input');
  input.value = text;
  document.body.appendChild(input);
  input.select();
  document.execCommand('copy');
  document.body.removeChild(input);
  this.$message.success('已复制到剪贴板');
}
```

### 3. 批量生成

```javascript
async batchGenerate() {
  const selectedJudges = this.$refs.table.selection;
  if (selectedJudges.length === 0) {
    this.$message.warning('请选择评委');
    return;
  }

  const judgeIds = selectedJudges.map(j => j.id);

  try {
    const res = await this.$http.post('/martial/judgeInvite/generate/batch', {
      competitionId: this.competitionId,
      judgeIds: judgeIds,
      role: 'judge',
      expireDays: 30
    });

    if (res.success) {
      this.$message.success(`成功生成${res.data.length}个邀请码`);
      this.loadJudgeList();
    }
  } catch (error) {
    this.$message.error(error.message || '批量生成失败');
  }
}
```

---

## ✅ 验证清单

### 后端验证

- [ ] DTO类创建成功
- [ ] Service方法实现完成
- [ ] Controller接口添加完成
- [ ] 编译无错误
- [ ] Swagger文档生成正常

### 功能验证

- [ ] 单个生成邀请码成功
- [ ] 邀请码格式正确（6位大写字母+数字）
- [ ] 邀请码唯一性验证通过
- [ ] 批量生成成功
- [ ] 重新生成成功（旧码失效）
- [ ] 查询邀请码成功
- [ ] 防止重复生成（已有有效邀请码时报错）

### 数据库验证

- [ ] 邀请码保存成功
- [ ] 过期时间设置正确
- [ ] 状态字段正确
- [ ] 唯一索引生效

### 小程序验证

- [ ] 使用邀请码登录成功
- [ ] 登录后权限正确
- [ ] 场地和项目信息正确

---

## 🔧 常见问题

### 问题1：邀请码重复

**现象**: 生成的邀请码已存在

**原因**: 随机生成时碰撞

**解决**: 代码已实现重试机制（最多10次）

---

### 问题2：评委已有邀请码

**现象**: 提示"该评委已有有效邀请码"

**原因**: 防止重复生成

**解决**:
- 使用"重新生成"功能
- 或等待旧邀请码过期

---

### 问题3：邀请码过期

**现象**: 登录时提示邀请码已过期

**原因**: 超过30天有效期

**解决**: 使用"重新生成"功能

---

## 📈 后续优化建议

### 短期优化（可选）

1. **邀请码格式优化**
   - 添加前缀（如：WS-ABC123）
   - 区分角色（J-评委，C-裁判长）

2. **批量导出**
   - 导出Excel：评委信息+邀请码
   - 生成PDF邀请函

3. **统计报表**
   - 邀请码使用率
   - 过期邀请码数量

### 长期优化（可选）

1. **短信/邮件发送**
   - 集成短信服务
   - 自动发送邀请码

2. **二维码生成**
   - 生成邀请二维码
   - 扫码直接登录

3. **邀请码管理**
   - 批量禁用
   - 批量延期

---

## 📞 技术支持

### 代码位置

| 文件 | 路径 |
|------|------|
| DTO类 | `src/main/java/org/springblade/modules/martial/pojo/dto/` |
| Service接口 | `src/main/java/org/springblade/modules/martial/service/IMartialJudgeInviteService.java` |
| Service实现 | `src/main/java/org/springblade/modules/martial/service/impl/MartialJudgeInviteServiceImpl.java` |
| Controller | `src/main/java/org/springblade/modules/martial/controller/MartialJudgeInviteController.java` |
| 测试SQL | `database/martial-db/test_invite_code_generation.sql` |

### Swagger 文档

启动后端服务后访问：
```
http://localhost:8080/doc.html
```

搜索"裁判邀请码管理"查看所有接口。

---

## 🎉 总结

### 已完成

✅ DTO类创建
✅ Service层实现
✅ Controller接口
✅ 测试SQL脚本
✅ 实施文档

### 工作量

- 后端开发：2小时
- 测试验证：1小时
- 文档编写：1小时
- **总计**：4小时

### 下一步

1. 启动后端服务
2. 使用Postman测试接口
3. 前端集成（如需要）
4. 联调测试
5. 上线部署

---

**祝您实施顺利！** 🚀

如有问题，请查看代码注释或联系技术支持。