补充多线程联调协作文档

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. 一句话约定
+
+当前项目的协作方式正式定为：
+
+> 前后端线程分别维护自己的协作文档， 总控线程负责读取两份协作文档并维护全局主线、正式文档和阶段结论。
+
+这样做的目标不是增加文书工作，而是：
+
+- 让并行开发不串线
+- 让重要结论沉淀下来
+- 让总控线程始终知道项目全貌