6.5 KiB
6.5 KiB
多线程联调协作方式
文档版本：v1.0 最后更新：2026-04-02 08:28:05
目标
当前项目已经进入前后端联调阶段，并且存在多条并行工作线程：
- 前端线程
- 后端线程
- 总控线程
这份文档用于明确三条线程如何协作、各自负责什么，以及如何通过共享文档同步事实，而不是靠口头记忆维持项目状态。
1. 当前协作模型
当前采用的是：
- 一个代码仓库
- 多条并行线程
- 两份根目录协作文档
- 一名全局维护者负责总览和收口
对应关系：
- 前端线程：推进小程序页面、状态链、模拟器接入、地图与体验层
- 后端线程：推进接口、配置发布、会话生命周期、业务数据模型
- 总控线程：负责全局判断、主线推进、交叉影响评估、文档索引与阶段总结
2. 两份协作文档的职责
当前跨线程沟通只走两份文件：
2.1 f2b.md
由前端线程维护，用于记录：
- 前端当前联调状态
- 前端已经按什么契约实现
- 需要后端确认什么
- 当前前端阻塞点是什么
它不是后端说明文档，也不是讨论区。
2.2 b2f.md
由后端线程维护，用于记录：
- 后端已经具备什么能力
- 前端应如何接入
- 哪些地方不允许前端自行假设
- 哪些接口和字段已经定版
它不是前端反馈文档，也不是需求池。
2.3 当前固定模板
为了避免两份协作文档再次变成长讨论稿，当前约定两边都采用统一结构：
待确认已确认阻塞已完成下一步
并且每条尽量固定包含：
- 时间
- 提出方
- 当前事实
- 需要对方确认什么
- 当前状态
这样做的目的不是增加格式负担，而是保证：
- 三条线程都能快速扫描
- 总控线程能快速识别优先级
- 已确认事项不会反复讨论
3. 总控线程的职责
总控线程不替代前后端线程，而是负责：
- 维护全局主线
- 判断当前阶段的优先级
- 识别跨层影响
- 把重要结论收进正式文档
- 在代码、文档、配置之间建立一致性
3.1 总控线程要看的信息源
总控线程至少持续关注：
以及当前代码事实：
miniprogram/backend/tools/mock-gps-sim/
3.2 总控线程不应该做的事
总控线程不应该：
- 抢写前端线程的
f2b.md - 抢写后端线程的
b2f.md - 把临时讨论直接当作正式契约
- 在两边尚未确认时擅自“替双方拍板”
总控线程只维护：
- 全局状态
- 正式设计文档
- 阶段结论
3.3 当前总控线程的附加约束
总控线程需要持续做两件事：
也就是说，总控线程不是“第三份协作文档”，而是：
- 主线维护者
- 正式知识沉淀者
- 交叉影响判断者
4. 推荐协作顺序
当前建议三条线程按下面这条链协作：
前端/后端各自推进
-> 遇到跨边界事项时写入 f2b / b2f
-> 总控线程读取两份协作文档
-> 判断是否需要：
- 调整主线优先级
- 更新正式方案文档
- 修正索引与阶段总结
-> 再继续推进代码
也就是说：
f2b / b2f是协作事实层doc/是正式知识层- 代码是最终实现层
5. 文档分层原则
为了避免信息再次散掉，建议始终遵守下面的分层：
5.1 协作文档
位于仓库根目录：
特点：
- 强时效
- 以联调事实为主
- 可频繁修改
- 不要求体系化
- 采用统一固定结构
- 不承担正式设计说明职责
5.2 正式文档
位于 doc/：
- 配置
- 玩法
- 动画
- 体验
- 渲染
- 调试
- 网关
特点：
- 结构化
- 可长期维护
- 只收已经收敛的结论
5.3 代码与配置
最终行为以代码和线上配置为准。
如果出现：
- 协作文档和正式文档不一致
- 正式文档和代码不一致
优先级应该是：
代码 / 运行结果
> 正式文档
> 协作文档
然后由总控线程负责把文档补齐。
6. 当前适合这种方式的原因
这个项目已经同时存在多条主线：
- 小程序前台
- 后端业务接口
- 配置发布链
- 模拟器
- H5 详情页
- 规则和运行时
如果所有讨论都只堆在一个线程里，会出现：
- 信息丢失
- 职责不清
- 已确认结论反复讨论
- 线程之间互相覆盖
采用当前这种方式的好处是：
- 前端线程可以只关心前端接入和用户体验
- 后端线程可以只关心接口和业务语义
- 总控线程能持续维护全局一致性
7. 当前项目的推荐工作法
7.1 前端线程
优先维护：
- 页面
- 宿主层
- 模拟器接入
- 交互和体验
并把需要后端确认的事项写入 f2b.md。
7.2 后端线程
优先维护：
- API
- 会话语义
- release / manifest / config 发布链
- workbench / dev tools
并把前端需要知道的契约写入 b2f.md。
7.3 总控线程
优先维护：
- 全局文档索引
- 阶段总结
- 主线优先级
- 正式架构文档
- 跨层决策
8. 一句话约定
当前项目的协作方式正式定为：
前后端线程分别维护自己的协作文档， 总控线程负责读取两份协作文档并维护全局主线、正式文档和阶段结论。
这样做的目标不是增加文书工作，而是：
- 让并行开发不串线
- 让重要结论沉淀下来
- 让总控线程始终知道项目全貌
9. 当前执行状态
截至当前阶段，这套方式已经进入实际执行状态：
后续如果线程数量增加，或者联调链变复杂，优先仍然是：
- 先扩展协作文档约定
- 再决定是否引入更重的流程工具
而不是先把协作体系做复杂。