# 评委邀请码功能实现指南

> **实施日期**: 2025-12-12
> **页面路径**: `src/views/martial/judgeInvite/index.vue`
> **与赛事绑定**: ✅ 已通过 `competitionId` 实现

---

## 📋 实现方案

### 一、需求分析

根据文档，评委邀请码功能需要实现：

1. **单个生成**：为单个评委生成6位邀请码
2. **批量生成**：为多个评委批量生成邀请码
3. **重新生成**：已有邀请码时可重新生成
4. **复制功能**：点击邀请码可复制
5. **赛事绑定**：所有操作都与选中的赛事绑定

### 二、后端接口（已完成）

后端接口已在 `src/api/martial/judgeInvite.js` 中添加：

```javascript
// 1. 生成邀请码
export const generateInviteCode = (data) => {
  return request({
    url: '/api/blade-martial/judgeInvite/generate',
    method: 'post',
    data
  })
}

// 2. 批量生成邀请码
export const batchGenerateInviteCode = (data) => {
  return request({
    url: '/api/blade-martial/judgeInvite/generate/batch',
    method: 'post',
    data
  })
}

// 3. 重新生成邀请码
export const regenerateInviteCode = (inviteId) => {
  return request({
    url: `/api/blade-martial/judgeInvite/regenerate/${inviteId}`,
    method: 'put'
  })
}

// 4. 查询评委邀请码
export const getInviteByJudge = (competitionId, judgeId) => {
  return request({
    url: '/api/blade-martial/judgeInvite/byJudge',
    method: 'get',
    params: { competitionId, judgeId }
  })
}
```

---

## 三、前端实现步骤

### 步骤1：导入新增的API

在 `src/views/martial/judgeInvite/index.vue` 第281-292行，修改导入语句：

```javascript
import {
  getJudgeInviteList,
  sendInvite,
  batchSendInvites,
  resendInvite,
  cancelInvite,
  confirmInvite,
  getInviteStatistics,
  importFromJudgePool,
  exportInvites,
  sendReminder,
  generateInviteCode,        // 新增
  batchGenerateInviteCode,   // 新增
  regenerateInviteCode       // 新增
} from '@/api/martial/judgeInvite'
```

### 步骤2：修改邀请码列显示（第165-179行）

将现有的邀请码列替换为：

```vue
<el-table-column prop="inviteCode" label="邀请码" width="200" align="center">
  <template #default="{ row }">
    <!-- 已有邀请码：显示邀请码 + 重新生成按钮 -->
    <div v-if="row.inviteCode" style="display: flex; align-items: center; justify-content: center; gap: 8px;">
      <el-tag
        type="warning"
        effect="dark"
        size="default"
        style="font-family: monospace; font-weight: bold; cursor: pointer;"
        @click="copyToClipboard(row.inviteCode, '邀请码')"
        title="点击复制"
      >
        {{ row.inviteCode }}
      </el-tag>
      <el-button
        link
        type="primary"
        size="small"
        @click="handleRegenerateCode(row)"
        title="重新生成邀请码"
      >
        <el-icon><Refresh /></el-icon>
      </el-button>
    </div>

    <!-- 未生成邀请码：显示生成按钮 -->
    <el-button
      v-else
      type="primary"
      size="small"
      @click="handleGenerateCode(row)"
    >
      生成邀请码
    </el-button>
  </template>
</el-table-column>
```

### 步骤3：添加批量生成按钮（第129-131行）

修改工具栏的"批量邀请"按钮功能：

```vue
<el-button type="success" :icon="DocumentCopy" @click="handleBatchGenerateCode">
  批量生成邀请码
</el-button>
```

### 步骤4：添加方法实现

在 `<script setup>` 部分，在第456行之后添加以下方法：

```javascript
// ==================== 邀请码生成功能 ====================

/**
 * 生成单个邀请码
 */
const handleGenerateCode = async (row) => {
  if (!queryParams.competitionId) {
    ElMessage.warning('请先选择赛事')
    return
  }

  try {
    loading.value = true
    const res = await generateInviteCode({
      competitionId: queryParams.competitionId,
      judgeId: row.judgeId,
      role: row.refereeType === 1 ? 'chief_judge' : 'judge', // 根据评委类型设置角色
      venueId: row.venueId || null,
      projects: row.projects ? JSON.stringify(row.projects) : null,
      expireDays: 30
    })

    if (res.data && res.data.inviteCode) {
      ElMessage.success(`邀请码生成成功：${res.data.inviteCode}`)
      // 自动复制到剪贴板
      copyToClipboard(res.data.inviteCode, '邀请码')
      // 刷新列表
      await fetchData()
      await loadStatistics()
    } else {
      ElMessage.error(res.msg || '生成失败')
    }
  } catch (error) {
    console.error('生成邀请码失败:', error)
    ElMessage.error(error.response?.data?.msg || error.message || '生成邀请码失败')
  } finally {
    loading.value = false
  }
}

/**
 * 重新生成邀请码
 */
const handleRegenerateCode = async (row) => {
  try {
    await ElMessageBox.confirm(
      '重新生成后，旧邀请码将失效。确定继续吗？',
      '重新生成邀请码',
      {
        confirmButtonText: '确定',
        cancelButtonText: '取消',
        type: 'warning'
      }
    )

    loading.value = true
    const res = await regenerateInviteCode(row.id)

    if (res.data && res.data.inviteCode) {
      ElMessage.success(`邀请码已重新生成：${res.data.inviteCode}`)
      // 自动复制到剪贴板
      copyToClipboard(res.data.inviteCode, '邀请码')
      // 刷新列表
      await fetchData()
      await loadStatistics()
    } else {
      ElMessage.error(res.msg || '重新生成失败')
    }
  } catch (error) {
    if (error !== 'cancel') {
      console.error('重新生成邀请码失败:', error)
      ElMessage.error(error.response?.data?.msg || error.message || '重新生成邀请码失败')
    }
  } finally {
    loading.value = false
  }
}

/**
 * 批量生成邀请码
 */
const handleBatchGenerateCode = async () => {
  if (!queryParams.competitionId) {
    ElMessage.warning('请先选择赛事')
    return
  }

  if (selection.value.length === 0) {
    ElMessage.warning('请先选择评委')
    return
  }

  try {
    await ElMessageBox.confirm(
      `确定为选中的 ${selection.value.length} 位评委批量生成邀请码吗？`,
      '批量生成邀请码',
      {
        confirmButtonText: '确定',
        cancelButtonText: '取消',
        type: 'info'
      }
    )

    loading.value = true
    const judgeIds = selection.value.map(item => item.judgeId)

    const res = await batchGenerateInviteCode({
      competitionId: queryParams.competitionId,
      judgeIds: judgeIds,
      role: 'judge',
      expireDays: 30
    })

    if (res.data && Array.isArray(res.data)) {
      ElMessage.success(`成功生成 ${res.data.length} 个邀请码`)
      // 刷新列表
      await fetchData()
      await loadStatistics()
    } else {
      ElMessage.error(res.msg || '批量生成失败')
    }
  } catch (error) {
    if (error !== 'cancel') {
      console.error('批量生成邀请码失败:', error)
      ElMessage.error(error.response?.data?.msg || error.message || '批量生成邀请码失败')
    }
  } finally {
    loading.value = false
  }
}
```

---

## 四、数据流转说明

### 1. 赛事绑定流程

```
用户操作：
1. 选择赛事（下拉框）
   ↓
2. queryParams.competitionId 更新
   ↓
3. 触发 handleCompetitionChange
   ↓
4. 加载该赛事的评委列表
   ↓
5. 显示评委及其邀请码状态
```

### 2. 生成邀请码流程

```
单个生成：
1. 点击"生成邀请码"按钮
   ↓
2. 调用 generateInviteCode API
   ↓
3. 传入：
   - competitionId: 当前选中的赛事ID
   - judgeId: 评委ID
   - role: 评委角色
   - venueId: 场地ID（可选）
   - projects: 项目列表（可选）
   - expireDays: 30天
   ↓
4. 后端生成6位随机码
   ↓
5. 返回邀请码
   ↓
6. 前端自动复制到剪贴板
   ↓
7. 刷新列表显示
```

### 3. 批量生成流程

```
批量生成：
1. 选择多个评委（勾选）
   ↓
2. 点击"批量生成邀请码"按钮
   ↓
3. 确认操作
   ↓
4. 调用 batchGenerateInviteCode API
   ↓
5. 传入：
   - competitionId: 当前选中的赛事ID
   - judgeIds: 评委ID数组
   - role: 'judge'
   - expireDays: 30天
   ↓
6. 后端循环为每个评委生成邀请码
   ↓
7. 返回生成的邀请码列表
   ↓
8. 刷新列表显示
```

---

## 五、关键字段说明

### 1. 数据表字段（martial_judge_invite）

| 字段 | 类型 | 说明 | 示例值 |
|------|------|------|--------|
| `id` | bigint | 主键ID | 1001 |
| `competition_id` | bigint | **赛事ID（绑定）** | 1 |
| `judge_id` | bigint | 评委ID | 5 |
| `invite_code` | varchar(50) | 邀请码 | ABC123 |
| `role` | varchar(20) | 角色 | judge/chief_judge |
| `venue_id` | bigint | 场地ID | 2 |
| `projects` | varchar(500) | 项目列表 | ["太极拳","长拳"] |
| `expire_time` | datetime | 过期时间 | 2026-01-11 |
| `is_used` | int | 是否已使用 | 0/1 |
| `status` | int | 状态 | 1-启用，0-禁用 |

### 2. 前端查询参数

```javascript
queryParams = {
  current: 1,              // 当前页
  size: 10,                // 每页条数
  competitionId: '',       // ⭐ 赛事ID（核心绑定字段）
  judgeName: '',           // 评委姓名
  judgeLevel: '',          // 评委等级
  inviteStatus: ''         // 邀请状态
}
```

---

## 六、测试验证

### 测试场景1：单个生成邀请码

**前置条件**：
- 已选择赛事
- 列表中有评委记录
- 评委未生成邀请码

**操作步骤**：
1. 在评委列表中找到一个未生成邀请码的评委
2. 点击"生成邀请码"按钮
3. 等待生成完成

**预期结果**：
- ✅ 显示成功提示：`邀请码生成成功：ABC123`
- ✅ 邀请码自动复制到剪贴板
- ✅ 列表刷新，显示生成的邀请码
- ✅ 邀请码列变为：邀请码 + 重新生成按钮

### 测试场景2：重新生成邀请码

**前置条件**：
- 已选择赛事
- 评委已有邀请码

**操作步骤**：
1. 点击邀请码旁边的重新生成按钮
2. 确认操作
3. 等待生成完成

**预期结果**：
- ✅ 显示警告提示框
- ✅ 确认后生成新邀请码
- ✅ 旧邀请码失效
- ✅ 新邀请码自动复制到剪贴板

### 测试场景3：批量生成邀请码

**前置条件**：
- 已选择赛事
- 列表中有多个未生成邀请码的评委

**操作步骤**：
1. 勾选多个评委（如3个）
2. 点击"批量生成邀请码"按钮
3. 确认操作
4. 等待生成完成

**预期结果**：
- ✅ 显示确认提示框：`确定为选中的 3 位评委批量生成邀请码吗？`
- ✅ 确认后批量生成
- ✅ 显示成功提示：`成功生成 3 个邀请码`
- ✅ 列表刷新，所有评委都显示邀请码

### 测试场景4：复制邀请码

**前置条件**：
- 评委已有邀请码

**操作步骤**：
1. 点击邀请码标签
2. 粘贴到其他地方验证

**预期结果**：
- ✅ 显示成功提示：`邀请码已复制：ABC123`
- ✅ 剪贴板中有邀请码内容

### 测试场景5：赛事切换

**操作步骤**：
1. 在赛事A生成邀请码
2. 切换到赛事B
3. 查看列表

**预期结果**：
- ✅ 只显示赛事B的评委列表
- ✅ 赛事A的邀请码不显示
- ✅ 每个赛事的邀请码独立管理

---

## 七、错误处理

### 错误1：未选择赛事

```javascript
if (!queryParams.competitionId) {
  ElMessage.warning('请先选择赛事')
  return
}
```

### 错误2：评委已有有效邀请码

后端会返回错误信息：
```json
{
  "success": false,
  "msg": "该评委已有有效邀请码，请使用重新生成功能"
}
```

前端显示：
```javascript
ElMessage.error(error.response?.data?.msg || '生成邀请码失败')
```

### 错误3：邀请码重复

后端会自动重试（最多10次），前端无需处理

---

## 八、UI/UX优化建议

### 1. 视觉优化

- ✅ 邀请码使用等宽字体（`monospace`）
- ✅ 使用警告色标签（`type="warning"`）
- ✅ 添加复制提示（`title="点击复制"`）
- ✅ 按钮使用图标（`<Refresh />`）

### 2. 交互优化

- ✅ 点击邀请码自动复制
- ✅ 重新生成前确认提示
- ✅ 批量生成前确认提示
- ✅ 生成成功后自动复制到剪贴板
- ✅ 操作成功后自动刷新列表

### 3. 加载状态

- ✅ 生成时显示 loading
- ✅ 防止重复点击
- ✅ 异常时显示错误提示

---

## 九、实施检查清单

### 后端准备

- [x] DTO类创建完成
- [x] Service方法实现完成
- [x] Controller接口添加完成
- [x] 数据库表结构正确
- [x] 唯一索引配置正确

### 前端准备

- [x] API接口添加完成（`judgeInvite.js`）
- [ ] 导入新增API
- [ ] 修改邀请码列UI
- [ ] 添加生成邀请码方法
- [ ] 添加重新生成方法
- [ ] 添加批量生成方法
- [ ] 修改批量邀请按钮功能

### 测试验证

- [ ] 单个生成测试通过
- [ ] 重新生成测试通过
- [ ] 批量生成测试通过
- [ ] 复制功能测试通过
- [ ] 赛事切换测试通过
- [ ] 错误处理测试通过

---

## 十、总结

### 核心要点

1. **赛事绑定**：所有操作都基于 `queryParams.competitionId`
2. **数据隔离**：不同赛事的邀请码完全独立
3. **用户友好**：自动复制、确认提示、状态反馈
4. **错误处理**：完善的错误提示和异常处理
5. **性能优化**：操作后自动刷新，保持数据同步

### 实施时间

- 前端修改：30分钟
- 测试验证：20分钟
- **总计**：50分钟

### 下一步

1. 按照本文档修改前端代码
2. 启动项目测试各功能
3. 根据测试结果调整优化
4. 上线部署

---

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

如有问题，请参考：
- 后端实施文档：`评委邀请码生成方案实施指南.md`
- API文档：`src/api/martial/judgeInvite.js`
- 页面代码：`src/views/martial/judgeInvite/index.vue`