# 赛程编排系统后端部署指南

## 📋 部署步骤

### 1. 数据库初始化

执行数据库表创建脚本:

```bash
mysql -u root -p martial_competition < database/martial-db/create_schedule_tables.sql
```

或者在MySQL客户端中直接执行 `database/martial-db/create_schedule_tables.sql`

### 2. 导入测试数据(可选)

如果需要测试编排功能,可以导入测试数据:

```bash
# 在前端项目的test-data目录下
mysql -u root -p martial_competition < test-data/create_100_team_participants.sql
```

这将创建:
- 100个集体项目队伍(500人)
- 5个集体项目类型
- 配合原有个人项目,总计1500人

### 3. 编译后端项目

```bash
cd martial-master
mvn clean package -DskipTests
```

### 4. 启动后端服务

```bash
java -jar target/martial-master.jar
```

### 5. 配置PowerJob定时任务

#### 5.1 访问PowerJob控制台

默认地址: `http://localhost:7700`

#### 5.2 创建定时任务

在PowerJob控制台中配置:

- **任务名称**: 赛程自动编排
- **任务描述**: 每10分钟自动编排未锁定的赛事
- **执行类型**: BASIC
- **处理器**: `org.springblade.job.processor.ScheduleAutoArrangeProcessor`
- **Cron表达式**: `0 */10 * * * ?` (每10分钟执行一次)
- **最大实例数**: 1 (避免并发)
- **运行超时时间**: 600000 (10分钟)

#### 5.3 启动任务

在PowerJob控制台中启动该任务

---

## 🔧 API接口说明

### 1. 获取编排结果

```http
GET /api/martial/schedule/result?competitionId={id}
```

**响应示例**:

```json
{
  "code": 200,
  "success": true,
  "data": {
    "scheduleStatus": 1,
    "lastAutoScheduleTime": "2025-12-08 10:00:00",
    "totalGroups": 45,
    "totalParticipants": 1500,
    "scheduleGroups": [
      {
        "id": 1,
        "groupName": "太极拳集体 成年组",
        "projectType": 2,
        "displayOrder": 1,
        "totalParticipants": 10,
        "totalTeams": 2,
        "organizationGroups": [
          {
            "organization": "少林寺武校",
            "participants": [
              {"playerName": "张三"},
              {"playerName": "李四"}
            ],
            "scheduleDetails": [
              {
                "venueId": 1,
                "venueName": "一号场地",
                "scheduleDate": "2025-11-06",
                "timeSlot": "08:30",
                "timePeriod": "morning"
              }
            ]
          }
        ]
      }
    ]
  }
}
```

### 2. 保存并锁定编排

```http
POST /api/martial/schedule/save-and-lock
Content-Type: application/json

{
  "competitionId": 200
}
```

**响应示例**:

```json
{
  "code": 200,
  "success": true,
  "msg": "编排已保存并锁定"
}
```

### 3. 手动触发自动编排(测试用)

```http
POST /api/martial/schedule/auto-arrange
Content-Type: application/json

{
  "competitionId": 200
}
```

---

## 📊 数据库表说明

### 1. martial_schedule_group (编排分组表)

存储自动分组结果,包括集体项目和个人项目的分组信息。

### 2. martial_schedule_detail (编排明细表)

存储场地时间段分配结果,记录每个分组被分配到哪个场地和时间段。

### 3. martial_schedule_participant (参赛者关联表)

存储参赛者与编排的关联关系,记录每个参赛者的出场顺序。

### 4. martial_schedule_status (编排状态表)

存储每个赛事的编排状态:
- 0: 未编排
- 1: 编排中
- 2: 已保存锁定

---

## 🧪 测试流程

### 1. 准备测试数据

```bash
# 执行测试数据脚本
mysql -u root -p martial_competition < test-data/create_100_team_participants.sql
```

### 2. 手动触发编排

使用API测试工具(Postman/Apifox)调用:

```http
POST http://localhost/api/martial/schedule/auto-arrange
Content-Type: application/json

{
  "competitionId": 200
}
```

### 3. 查看编排结果

```http
GET http://localhost/api/martial/schedule/result?competitionId=200
```

### 4. 前端测试

访问前端页面:

```
http://localhost:3000/martial/schedule?competitionId=200
```

应该能看到:
- 竞赛分组Tab: 按时间段显示分组
- 场地Tab: 按场地显示分组
- 集体项目按单位分组显示
- 个人项目直接列出参赛者

### 5. 保存并锁定

在前端页面点击"保存编排"按钮,或调用API:

```http
POST http://localhost/api/martial/schedule/save-and-lock
Content-Type: application/json

{
  "competitionId": 200
}
```

锁定后,定时任务将不再自动编排该赛事。

---

## 🔍 故障排查

### 问题1: 编排结果为空

**原因**:
- 赛事没有参赛者
- 赛事没有配置场地
- 赛事时间未设置

**解决**:
- 检查 `martial_athlete` 表是否有该赛事的参赛者
- 检查 `martial_venue` 表是否有该赛事的场地
- 检查 `martial_competition` 表的 `competition_start_time` 和 `competition_end_time`

### 问题2: 定时任务未执行

**原因**:
- PowerJob服务未启动
- 任务未启动
- Worker未连接

**解决**:
- 检查PowerJob控制台任务状态
- 查看Worker日志
- 确认Cron表达式正确

### 问题3: 场地容量不足

**原因**:
- 参赛人数过多
- 时间段容量不够

**解决**:
- 增加比赛天数
- 增加场地数量
- 调整时间段容量配置

---

## 📝 注意事项

1. **定时任务执行频率**: 默认每10分钟执行一次,可以根据需要调整Cron表达式

2. **锁定机制**: 一旦保存并锁定,定时任务将不再自动编排该赛事

3. **容量检查**: 编排算法会自动检查时间段容量,超出容量的分组会报警

4. **项目类型**:
   - type=1: 个人项目
   - type=2: 双人项目
   - type=3: 集体项目

5. **时间段容量**:
   - 上午(08:30-11:30): 150分钟
   - 下午(13:30-17:30): 210分钟

---

## 🚀 性能优化建议

1. **数据库索引**: 已自动创建必要索引,无需额外优化

2. **批量插入**: Service层使用批量插入,提升性能

3. **缓存**: 可以考虑使用Redis缓存编排结果(可选)

4. **并发控制**: PowerJob任务设置最大实例数为1,避免并发冲突

---

**版本**: v1.0
**创建时间**: 2025-12-08
**维护人**: 开发团队