205 lines
5.9 KiB
Markdown
205 lines
5.9 KiB
Markdown
# 赛程编排后端API数据格式规范
|
||
|
||
## 1. 获取赛程编排结果 - getScheduleResult
|
||
|
||
**接口地址**: `GET /api/martial/schedule/result`
|
||
|
||
**请求参数**:
|
||
```javascript
|
||
{
|
||
competitionId: Number // 赛事ID
|
||
}
|
||
```
|
||
|
||
**返回数据格式**:
|
||
```javascript
|
||
{
|
||
"code": 200,
|
||
"msg": "success",
|
||
"data": {
|
||
"isDraft": true, // 是否为草稿状态
|
||
"isCompleted": false, // 是否已完成编排
|
||
"competitionGroups": [ // 竞赛分组列表
|
||
{
|
||
"id": 1, // 分组ID
|
||
"title": "1. 小学组小组赛男女类", // 分组标题
|
||
"type": "集体", // 类型：集体/单人/双人
|
||
"count": "2队", // 队伍数量
|
||
"code": "1101", // 分组编号
|
||
"venueId": 1, // 当前所属场地ID
|
||
"venueName": "一号场地", // 场地名称
|
||
"timeSlot": "2025年11月6日 上午8:30", // 时间段
|
||
"timeSlotIndex": 0, // 时间段索引
|
||
"participants": [ // 参赛人员列表
|
||
{
|
||
"id": 101, // 参赛人员ID
|
||
"schoolUnit": "清河小学", // 学校/单位
|
||
"status": "未签到", // 状态：未签到/已签到/异常
|
||
"sortOrder": 1 // 排序
|
||
},
|
||
{
|
||
"id": 102,
|
||
"schoolUnit": "访河社区",
|
||
"status": "未签到",
|
||
"sortOrder": 2
|
||
}
|
||
]
|
||
},
|
||
{
|
||
"id": 2,
|
||
"title": "1. 小学组小组赛男女类",
|
||
"type": "单人",
|
||
"count": "3队",
|
||
"code": "1组",
|
||
"venueId": 2,
|
||
"venueName": "二号场地",
|
||
"timeSlot": "2025年11月6日 上午8:30",
|
||
"timeSlotIndex": 0,
|
||
"participants": [
|
||
{
|
||
"id": 103,
|
||
"schoolUnit": "少林寺武校",
|
||
"status": "未签到",
|
||
"sortOrder": 1
|
||
},
|
||
{
|
||
"id": 104,
|
||
"schoolUnit": "访河社区",
|
||
"status": "已签到",
|
||
"sortOrder": 2
|
||
},
|
||
{
|
||
"id": 105,
|
||
"schoolUnit": "武当派",
|
||
"status": "异常",
|
||
"sortOrder": 3
|
||
}
|
||
]
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
**重要说明**:
|
||
1. **首次分配规则**: 系统后台需要按照"先集体，后个人"的顺序进行第一次场地分配
|
||
2. **状态字段**:
|
||
- `未签到`: 默认状态
|
||
- `已签到`: 参赛人员已签到
|
||
- `异常`: 被标记为异常的参赛人员
|
||
3. **timeSlotIndex**: 对应前端动态生成的时间段数组索引，从0开始
|
||
4. **sortOrder**: 参赛人员在分组内的排序，用于上移/下移功能
|
||
|
||
## 2. 保存编排草稿 - saveDraftSchedule
|
||
|
||
**接口地址**: `POST /api/martial/schedule/save-draft`
|
||
|
||
**请求数据格式**:
|
||
```javascript
|
||
{
|
||
"competitionId": 1, // 赛事ID
|
||
"isDraft": true, // 是否为草稿
|
||
"competitionGroups": [ // 竞赛分组数据
|
||
{
|
||
"id": 1, // 分组ID（如果是新建则为null）
|
||
"title": "1. 小学组小组赛男女类",
|
||
"type": "集体",
|
||
"count": "2队",
|
||
"code": "1101",
|
||
"venueId": 1, // 场地ID
|
||
"venueName": "一号场地",
|
||
"timeSlot": "2025年11月6日 上午8:30",
|
||
"timeSlotIndex": 0,
|
||
"participants": [
|
||
{
|
||
"id": 101,
|
||
"schoolUnit": "清河小学",
|
||
"status": "未签到",
|
||
"sortOrder": 1
|
||
},
|
||
{
|
||
"id": 102,
|
||
"schoolUnit": "访河社区",
|
||
"status": "异常",
|
||
"sortOrder": 2
|
||
}
|
||
]
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
**返回数据格式**:
|
||
```javascript
|
||
{
|
||
"code": 200,
|
||
"msg": "草稿保存成功",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
**重要说明**:
|
||
1. 草稿可以被多次保存和更新
|
||
2. 保存草稿不会锁定数据，用户可以继续编辑
|
||
3. 下次打开页面时，如果`isCompleted`为false，则加载草稿数据
|
||
|
||
## 3. 完成编排并锁定 - saveAndLockSchedule
|
||
|
||
**接口地址**: `POST /api/martial/schedule/save-and-lock`
|
||
|
||
**请求数据格式**:
|
||
```javascript
|
||
{
|
||
"competitionId": 1 // 赛事ID
|
||
}
|
||
```
|
||
|
||
**返回数据格式**:
|
||
```javascript
|
||
{
|
||
"code": 200,
|
||
"msg": "编排已完成并锁定",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
**重要说明**:
|
||
1. 完成编排后，`isCompleted`标记为true
|
||
2. 编排完成后，前端将禁用所有编辑功能（上移、下移、标记异常、移动分组等）
|
||
3. 只有在`isCompleted`为true时，才显示"导出"按钮
|
||
|
||
## 4. 前端页面功能说明
|
||
|
||
### 4.1 移动分组功能
|
||
- 用户可以将整个竞赛分组移动到不同的场地和时间段
|
||
- 移动后需要更新分组的`venueId`、`venueName`、`timeSlot`、`timeSlotIndex`字段
|
||
- 移动操作在保存草稿时提交到后端
|
||
|
||
### 4.2 异常组功能
|
||
- 只有状态为"未签到"的参赛人员才显示"异常"按钮
|
||
- 点击"异常"按钮后，参赛人员状态变为"异常"
|
||
- 异常参赛人员会在"异常组"弹窗中显示
|
||
- 可以从异常组移除，状态恢复为"未签到"
|
||
|
||
### 4.3 上移/下移功能
|
||
- 调整参赛人员在分组内的顺序
|
||
- 修改后会更新`sortOrder`字段
|
||
- 在保存草稿时提交到后端
|
||
|
||
### 4.4 保存草稿与完成编排
|
||
- **保存草稿**: 保存当前编排状态，不锁定，可继续编辑
|
||
- **完成编排**: 锁定编排，禁用所有编辑功能，显示导出按钮
|
||
|
||
## 5. 字段映射说明
|
||
|
||
| 前端字段 | 后端字段（可能的命名） | 说明 |
|
||
|---------|---------------------|------|
|
||
| schoolUnit | school_unit / schoolUnit | 学校/单位名称 |
|
||
| venueName | venue_name / venueName | 场地名称 |
|
||
| venueId | venue_id / venueId | 场地ID |
|
||
| timeSlot | time_slot / timeSlot | 时间段文本 |
|
||
| timeSlotIndex | time_slot_index / timeSlotIndex | 时间段索引 |
|
||
| sortOrder | sort_order / sortOrder | 排序 |
|
||
|
||
**提示**: 后端可以使用下划线命名（snake_case）或驼峰命名（camelCase），前端已做兼容处理。
|