Add message queue documentation

docs/dev/mq.zh.md

@@ -0,0 +1,53 @@
+# 消息队列
+
+技术选型：`Redis Stream`
+
+## Web to Worker
+
+Startup:
+
+```bash
+# 若相应的 stream 不存在，会自动创建
+XGROUP CREATE build worker_group 0 MKSTREAM
+XGROUP CREATE manual_match worker_group 0 MKSTREAM
+XGROUP CREATE auto_match worker_group 0 MKSTREAM
+```
+
+Send message:
+
+```bash
+# 若相应的 stream 不存在，会自动创建
+# type: game_logic / ai
+XADD build * type <type> id <id>
+XADD manual_match * id <match_id>
+XADD auto_match * id <match_id>
+```
+
+Read message:
+
+```bash
+# 若相应名字的 consumer 不存在，会自动在 group 中创建
+# BLOCK 0 表示永久阻塞，直到有消息到达
+XREADGROUP GROUP worker_group <consumer_name> COUNT 1 BLOCK 0 STREAMS build manual_match auto_match >
+```
+
+Ack message:
+
+```bash
+# stream: build / manual_match / auto_match
+XACK <stream> worker_group <message_id>
+```
+
+## Worker to Web
+
+Send message:
+
+```bash
+XADD match_result * id <match_id> replay <replay>
+```
+
+Read message:
+
+```bash
+XREAD BLOCK 0 STREAMS match_result >
+```

docs/dev/web.zh.md

@@ -193,20 +193,7 @@ var/hiper/
 - 消息队列：Redis Stream
 - client: [github.com/go-redis/redis/v9](https://github.com/go-redis/redis/v9) 
 
-发送的方式为：
-
-```mqsend
-model.Rdb.XAdd(ctx, &redis.XAddArgs{
-	Stream: msg.Topic,
-	MaxLen: 0,
-	Approx: true,
-	ID:     "*",
-	Values: []interface{}{"body", msg.Body, "type", msg.Type},
-})
-```
-
-
-<!-- TODO -->
+消息队列接口见 [消息队列](mq.md)。
 
 ### 其他 Service
 

docs/dev/worker.zh.md

@@ -10,14 +10,16 @@ worker 的工作流程：
 2. 修改状态信息，表示正在执行
 3. 获取任务所需信息
 4. 起容器，执行任务
-5. 等待任务完成，获取任务输出，保存与修改相关信息（含 在 `match_finished` 消息队列中发送消息，如果是 公开对局 的话）
+5. 等待任务完成，获取任务输出，保存与修改相关信息（含 在 `match_result` 消息队列中发送消息，如果是 公开对局 的话）
 6. 修改状态信息，表示执行完成
 7. ACK 消息，准备获取下一个任务
 
 ## 获取任务
 
 Worker 从消息队列中获取任务。
 
+<!-- TODO -->
+
 ### 任务调度
 
 ??? note "问题分析"
@@ -65,7 +67,7 @@ Worker 从消息队列中获取任务。
 
     不过，问题1 和 问题2 在每个任务都执行得足够快的情况其实都不是问题。
 
-分为 3 个优先级：用户触发的构建 > 用户触发的对局 > 赛事脚本触发的对局。它们分别对应 3 个消息队列：``
+分为 3 个优先级：用户触发的构建 > 用户触发的对局 > 赛事脚本触发的对局。它们分别对应 1 个消息队列。
 
 ## Docker in Docker
 
@@ -99,6 +101,7 @@ Worker 从消息队列中获取任务。
 TODO: 之后改用单独启动一个 Docker 供所有 worker 实例共用的方案。
 
 > [Introductory demo for the Sysbox container runtime](https://asciinema.org/a/kkTmOxl8DhEZiM2fLZNFlYzbo)
+>
 > [Sysbox Quick Start Guide](https://github.com/nestybox/sysbox/blob/master/docs/quickstart/README.md)
 
 ## docker build
@@ -109,7 +112,7 @@ TODO: 之后改用单独启动一个 Docker 供所有 worker 实例共用的方
 
 `<hash>` 为构建镜像时使用的 Dockerfile 的 hash，用于判断是否需要重新构建镜像。
 
-例：`game-1-build-df1c930f5d049d445487b15d16c9763e`、`ai-3-run-aeceee35bfe1fa755fac895403db4da4`。
+例：`game-1-build-df1c930f5d049d445487b15d16c9763e`, `ai-3-run-aeceee35bfe1fa755fac895403db4da4`。
 
 ## docker run
 

mkdocs.yml

@@ -9,6 +9,7 @@ nav:
   - 开发环境搭建: dev/dev-env-setup.zh.md
   - 架构: dev/arch.zh.md
   - 后端 - Web: dev/web.zh.md
+  - 消息队列: dev/mq.zh.md
   - 后端 - Worker: dev/worker.zh.md
 - 用户文档:
   - 局部管理员:
@@ -50,6 +51,7 @@ plugins:
         开发环境搭建: Dev Env Setup
         架构: Architecture
         后端 - Web: Backend - Web
+        消息队列: Message Queue
         后端 - Worker: Backend - Worker
         用户文档: User Docs
         局部管理员: Local Admin