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