martial-web/doc/schedule/archive/schedule-backend-api-spec.md

赛程编排后端API数据格式规范

1. 获取赛程编排结果 - getScheduleResult

接口地址: GET /api/martial/schedule/result

请求参数:

{
  competitionId: Number  // 赛事ID
}

返回数据格式:

{
  "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

请求数据格式:

{
  "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
        }
      ]
    }
  ]
}

返回数据格式:

{
  "code": 200,
  "msg": "草稿保存成功",
  "data": null
}

重要说明:

1. 草稿可以被多次保存和更新
2. 保存草稿不会锁定数据，用户可以继续编辑
3. 下次打开页面时，如果isCompleted为false，则加载草稿数据

3. 完成编排并锁定 - saveAndLockSchedule

接口地址: POST /api/martial/schedule/save-and-lock

请求数据格式:

{
  "competitionId": 1  // 赛事ID
}

返回数据格式:

{
  "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），前端已做兼容处理。