From f7393907ec9d10ed0dac5c097035ec86011a3027 Mon Sep 17 00:00:00 2001
From: zhangyan <zy6000@gmail.com>
Date: Wed, 1 Apr 2026 18:59:30 +0800
Subject: [PATCH] =?UTF-8?q?=E8=A1=A5=E5=85=85=E5=A4=9A=E7=BA=BF=E7=A8=8B?=
 =?UTF-8?q?=E8=81=94=E8=B0=83=E5=8D=8F=E4=BD=9C=E6=96=87=E6=A1=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 doc/gameplay/多线程联调协作方式.md | 257 +++++++++++++++++++++++++++++
 doc/文档索引.md                    |   1 +
 2 files changed, 258 insertions(+)
 create mode 100644 doc/gameplay/多线程联调协作方式.md

diff --git a/doc/gameplay/多线程联调协作方式.md b/doc/gameplay/多线程联调协作方式.md
new file mode 100644
index 0000000..ca2845f
--- /dev/null
+++ b/doc/gameplay/多线程联调协作方式.md
@@ -0,0 +1,257 @@
+# 多线程联调协作方式
+
+## 目标
+
+当前项目已经进入前后端联调阶段，并且存在多条并行工作线程：
+
+- 前端线程
+- 后端线程
+- 总控线程
+
+这份文档用于明确三条线程如何协作、各自负责什么，以及如何通过共享文档同步事实，而不是靠口头记忆维持项目状态。
+
+---
+
+## 1. 当前协作模型
+
+当前采用的是：
+
+- 一个代码仓库
+- 多条并行线程
+- 两份根目录协作文档
+- 一名全局维护者负责总览和收口
+
+对应关系：
+
+- 前端线程：推进小程序页面、状态链、模拟器接入、地图与体验层
+- 后端线程：推进接口、配置发布、会话生命周期、业务数据模型
+- 总控线程：负责全局判断、主线推进、交叉影响评估、文档索引与阶段总结
+
+---
+
+## 2. 两份协作文档的职责
+
+当前跨线程沟通只走两份文件：
+
+- [f2b.md](D:/dev/cmr-mini/f2b.md)
+- [b2f.md](D:/dev/cmr-mini/b2f.md)
+
+### 2.1 `f2b.md`
+
+由前端线程维护，用于记录：
+
+- 前端当前联调状态
+- 前端已经按什么契约实现
+- 需要后端确认什么
+- 当前前端阻塞点是什么
+
+它不是后端说明文档，也不是讨论区。
+
+### 2.2 `b2f.md`
+
+由后端线程维护，用于记录：
+
+- 后端已经具备什么能力
+- 前端应如何接入
+- 哪些地方不允许前端自行假设
+- 哪些接口和字段已经定版
+
+它不是前端反馈文档，也不是需求池。
+
+---
+
+## 3. 总控线程的职责
+
+总控线程不替代前后端线程，而是负责：
+
+- 维护全局主线
+- 判断当前阶段的优先级
+- 识别跨层影响
+- 把重要结论收进正式文档
+- 在代码、文档、配置之间建立一致性
+
+### 3.1 总控线程要看的信息源
+
+总控线程至少持续关注：
+
+- [readme-develop.md](D:/dev/cmr-mini/readme-develop.md)
+- [文档索引.md](D:/dev/cmr-mini/doc/文档索引.md)
+- [f2b.md](D:/dev/cmr-mini/f2b.md)
+- [b2f.md](D:/dev/cmr-mini/b2f.md)
+
+以及当前代码事实：
+
+- `miniprogram/`
+- `backend/`
+- `tools/mock-gps-sim/`
+
+### 3.2 总控线程不应该做的事
+
+总控线程不应该：
+
+- 抢写前端线程的 `f2b.md`
+- 抢写后端线程的 `b2f.md`
+- 把临时讨论直接当作正式契约
+- 在两边尚未确认时擅自“替双方拍板”
+
+总控线程只维护：
+
+- 全局状态
+- 正式设计文档
+- 阶段结论
+
+---
+
+## 4. 推荐协作顺序
+
+当前建议三条线程按下面这条链协作：
+
+```text
+前端/后端各自推进
+-> 遇到跨边界事项时写入 f2b / b2f
+-> 总控线程读取两份协作文档
+-> 判断是否需要：
+   - 调整主线优先级
+   - 更新正式方案文档
+   - 修正索引与阶段总结
+-> 再继续推进代码
+```
+
+也就是说：
+
+- `f2b / b2f` 是协作事实层
+- `doc/` 是正式知识层
+- 代码是最终实现层
+
+---
+
+## 5. 文档分层原则
+
+为了避免信息再次散掉，建议始终遵守下面的分层：
+
+### 5.1 协作文档
+
+位于仓库根目录：
+
+- [f2b.md](D:/dev/cmr-mini/f2b.md)
+- [b2f.md](D:/dev/cmr-mini/b2f.md)
+
+特点：
+
+- 强时效
+- 以联调事实为主
+- 可频繁修改
+- 不要求体系化
+
+### 5.2 正式文档
+
+位于 `doc/`：
+
+- 配置
+- 玩法
+- 动画
+- 体验
+- 渲染
+- 调试
+- 网关
+
+特点：
+
+- 结构化
+- 可长期维护
+- 只收已经收敛的结论
+
+### 5.3 代码与配置
+
+最终行为以代码和线上配置为准。
+
+如果出现：
+
+- 协作文档和正式文档不一致
+- 正式文档和代码不一致
+
+优先级应该是：
+
+```text
+代码 / 运行结果
+> 正式文档
+> 协作文档
+```
+
+然后由总控线程负责把文档补齐。
+
+---
+
+## 6. 当前适合这种方式的原因
+
+这个项目已经同时存在多条主线：
+
+- 小程序前台
+- 后端业务接口
+- 配置发布链
+- 模拟器
+- H5 详情页
+- 规则和运行时
+
+如果所有讨论都只堆在一个线程里，会出现：
+
+- 信息丢失
+- 职责不清
+- 已确认结论反复讨论
+- 线程之间互相覆盖
+
+采用当前这种方式的好处是：
+
+- 前端线程可以只关心前端接入和用户体验
+- 后端线程可以只关心接口和业务语义
+- 总控线程能持续维护全局一致性
+
+---
+
+## 7. 当前项目的推荐工作法
+
+### 7.1 前端线程
+
+优先维护：
+
+- 页面
+- 宿主层
+- 模拟器接入
+- 交互和体验
+
+并把需要后端确认的事项写入 [f2b.md](D:/dev/cmr-mini/f2b.md)。
+
+### 7.2 后端线程
+
+优先维护：
+
+- API
+- 会话语义
+- release / manifest / config 发布链
+- workbench / dev tools
+
+并把前端需要知道的契约写入 [b2f.md](D:/dev/cmr-mini/b2f.md)。
+
+### 7.3 总控线程
+
+优先维护：
+
+- 全局文档索引
+- 阶段总结
+- 主线优先级
+- 正式架构文档
+- 跨层决策
+
+---
+
+## 8. 一句话约定
+
+当前项目的协作方式正式定为：
+
+> 前后端线程分别维护自己的协作文档， 总控线程负责读取两份协作文档并维护全局主线、正式文档和阶段结论。
+
+这样做的目标不是增加文书工作，而是：
+
+- 让并行开发不串线
+- 让重要结论沉淀下来
+- 让总控线程始终知道项目全貌
diff --git a/doc/文档索引.md b/doc/文档索引.md
index 7292d73..0f2e48a 100644
--- a/doc/文档索引.md
+++ b/doc/文档索引.md
@@ -33,6 +33,7 @@
 - [玩法构想方案](/D:/dev/cmr-mini/doc/gameplay/玩法构想方案.md)
 - [程序默认规则基线](/D:/dev/cmr-mini/doc/gameplay/程序默认规则基线.md)
 - [游戏规则架构](/D:/dev/cmr-mini/doc/gameplay/游戏规则架构.md)
+- [多线程联调协作方式](/D:/dev/cmr-mini/doc/gameplay/多线程联调协作方式.md)
 - [故障恢复机制](/D:/dev/cmr-mini/doc/gameplay/故障恢复机制.md)
 - [运行时编译层总表](/D:/dev/cmr-mini/doc/gameplay/运行时编译层总表.md)
 - [玩法设计文档模板](/D:/dev/cmr-mini/doc/gameplay/玩法设计文档模板.md)