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