chore(docs): add crash status to room & force stop container (#1769)

* add crash status to room & force stop container * Update contest.md "Finished" --------- Co-authored-by: xiangmy21 <[email protected]>
eesast · Apr 28, 2024 · 0098a3d · 0098a3d
1 parent 8bbe726
commit 0098a3d
Showing 1 changed file with 9 additions and 7 deletions.
diff --git a/docs/contest.md b/docs/contest.md
@@ -1,4 +1,4 @@
----
+aaqaqqqqqqqqqqqqqqqqqqqqAqw   a---
 title: 天梯和比赛逻辑
 description: 网站开发接口文档
 permalink: /contest
@@ -30,9 +30,10 @@ permalink: /contest
    - 比赛期间，用户可通过特定端口观看直播。后端在上面所述启动比赛的【第二步】时分配好一个端口。如果端口数量不足，则不启动比赛。如果成功分配端口并启动比赛，则应同时更新数据库`contest_room`表中的`port`字段。
    - 前端应当使用`subscription`实时更新比赛状态和直播观看端口。
 6. `docker` 服务器结束比赛后请求后端`/arena/finish`路由。
-   - 后端更新数据库，更新`contest_room`表中的`status`为`Finished`、更新`port`为`NULL`；更新`contest_room_team`表中的`score`字段，为这场比赛的每个队伍记录分数
+   - 后端更新数据库，更新`contest_room`表中的`status`为`Finished` 或 `Crashed` 、更新`port`为`NULL`；更新`contest_room_team`表中的`score`字段，为这场比赛的每个队伍记录分数
    - 后端将比赛回放文件以及日志文件（如有）上传至 `cos`，具体路径参考[COS存储桶访问路径](https://eesast.github.io/web/cos)。
    - 后端向参与这场比赛的队伍队员发送`Web Push`订阅通知（暂不急于实现）。
+   - 后端会设置最大运行时间（位于数据库内，每届比赛有不同的运行时间），若超过最大运行时间，则后端会强制停止所有相关容器的运行，并更新 `room` 状态为 `Crashed`，释放 `port`。
 7. 比赛结束后，前端提供下载和在线观看回放的功能，直接按照[COS存储桶访问路径](https://eesast.github.io/web/cos)中约定的路径从`cos`下载对应的文件即可。
 
 ### 接口描述
@@ -70,7 +71,7 @@ permalink: /contest
   - 错误：`500`：`undefined`，返回报错信息
 - `/arena/finish`：`docker`服务器比赛结束的`hook`。更新比赛结果，更新天梯分数，将比赛回放和日志文件上传至`COS`。
   - 请求方法：`POST`
-  - 请求：`{result: ContestResult[]}`，类型定义见下方附录。同时在`headers`里传回创建`docker`时设置的`TOKEN`。
+  - 请求：`{result: ContestResult}`，类型定义见下方附录。同时在`headers`里传回创建`docker`时设置的`TOKEN`。如果 `docker` 未能正常运行比赛，`ContestResult.status` 设置为 `Crashed`，不会更新分数；否则 `ContestResult.status` 设置为 `Finished`，正常更新分数。
   - 响应：`200`：`Update OK!`
   - 错误：`500`：`undefined`，返回报错信息
 - `注意`：除此之外，后端需要在`docker_cron`中更新数据库比赛状态和端口信息（异步、非请求内）。
@@ -128,9 +129,9 @@ permalink: /contest
   - 请求：在`headers`里传回创建`docker`时设置的`TOKEN`（内部包含`round_id`）。
   - 响应：`{result: ContestResult[]}`。顺序与 `TOKEN.team_label_binds` 中的顺序一致。
   - 错误：`500`：`undefined`，返回报错信息
-- `/competition/finish-one`：`docker`服务器比赛结束的`hook`。更新比赛结果，更新比赛分数，将比赛回放和日志文件上传至`COS`。
+- `/competition/finish-one`：`docker`服务器比赛结束的`hook`。更新比赛结果，更新比赛分数，将比赛回放和日志文件上传至`COS`。如果 `docker` 未能正常运行比赛，`ContestResult.status` 设置为 `Crashed`，不会更新分数；否则 `ContestResult.status` 设置为 `Finished`，正常更新分数。
   - 请求方法：`POST`
-  - 请求：`{result: ContestResult[]}` ，类型定义见下方附录。同时在`headers`里传回创建`docker`时设置的`TOKEN`。
+  - 请求：`{result: ContestResult}` ，类型定义见下方附录。同时在`headers`里传回创建`docker`时设置的`TOKEN`。
   - 响应：`200`：`Update OK!`
   - 错误：`500`：`undefined`，返回报错信息
 
@@ -158,7 +159,7 @@ permalink: /contest
   - `MODE`: 判断当前比赛是天梯还是最终比赛。取值为 `ARENA` （天梯）或者 `COMPETITION`（决赛）。
   - `TOKEN`: 服务端验证身份的 token。发送请求时需带上。
   - `TEAM_LABELS`: 全局信息。本场比赛的所有队伍标签。用 `:` 分隔，其中的每个元素对应 `TeamLabelBind` 中的 `label` 字段，位序对应客户端 `TEAM_SEQ_ID` 的顺序，也对应 `SCORE_URL` 和 `FINISH_URL` 的分数信息 `ContestResult[]` 的顺序。
-  - `TIME`: 比赛持续的时间，单位为秒。
+  - `GAME_TIME`: 比赛持续的时间，单位为秒。若超过这个时间，后端会强制停止所有相关容器。
   - `MAP_ID`: 地图 id。
   - `SCORE_URL`: 获取当前天梯分数的 url 路径。请求时需带上 `TOKEN`。
   - `FINISH_URL`: 结束比赛时更新分数的 url 路径。请求时需带上 `TOKEN`。
@@ -175,7 +176,8 @@ permalink: /contest
 
 ```javascript
 interface ContestResult {
-  score: number; // 最新的 score
+  status: string; // `Crashed` 或 `Finished`。
+  scores: number[]; // 每个队伍的分数，顺序与 TEAM_LABELS 一致。
 };
 
 interface TeamLabelBind {