wechat_wc/docs/team-collaboration-guide.md

智绘微刻小程序团队协作总文档

本文档是四人团队的协作单一入口，定义仓库、分工、Git 规范、契约管理和推荐开发节奏。 四个路线的具体开发内容见 docs/routes/，后端接口契约见 wxmp_backend/docs/api-contract-v1.md 与 wxmp_backend/docs/wordcloud-contract.md。

1. 仓库与主干

仓库	角色	主干分支	说明
wechat_wc	小程序前端（Taro）	master	已连接 Gitee，页面与前端协作文档都在这里
wxmp_backend	小程序后端（NestJS）	main	已连接 GitHub，接口契约与迁移在这边
wordcloud	词云生成外部服务（FastAPI）	独立演进	只通过冻结契约复用，不参与前后端分支同步

注意：早期文档里写“合并到 main”时，一律按本表执行：前端合 master，后端合 main。

2. 分工模型

团队由 4 人组成，每人独立拥有一条端到端路线，前端和后端改动都归本人：

成员	路线	分支	仓库
成员 1	R1 商品目录	feat/r1-catalog	wechat_wc + wxmp_backend
成员 2	R2 地址 + 设计清单	feat/r2-address-design	wechat_wc + wxmp_backend
成员 3	R3 订单 + 支付占位	feat/r3-order-pay	wechat_wc + wxmp_backend
成员 4	R4 上传 + 词云 + 线稿	feat/r4-upload-wordcloud	wechat_wc + wxmp_backend

四人互不等待：各自在两条仓库做自己的切片，不拆前端/后端小组，也不跨路线改别人的文件。 路线之间只通过契约、主干和合并顺序衔接。

2.1 四条路线

路线	分支	目标	wordcloud
R1 商品目录	feat/r1-catalog	商品/分类 API + 前端四个页面切 API	不用
R2 地址 + 设计清单	feat/r2-address-design	地址 CRUD、清单 CRUD、状态映射	不用
R3 订单 + 支付占位	feat/r3-order-pay	服务端下单、订单状态机、支付未配置占位	不用
R4 上传 + 词云 + 线稿	feat/r4-upload-wordcloud	COS 上传、词云任务、sketch、队列	唯一使用

2.2 文件所有权

前端公共文件只由 R0 维护：

文件	归属
src/utils/store/index.ts、src/utils/api/index.ts	R0 聚合入口，只加 re-export，不堆业务
src/utils/store/design.ts、address.ts	R2
src/utils/store/order.ts	R3
src/utils/api/product.ts	R1
src/utils/api/address.ts、design.ts	R2
src/utils/api/order.ts	R3
src/utils/api/upload.ts	R4

页面所有权：

页面	归属
index、shop、shop/detail、product	R1
address、designList	R2
checkout、orders、orderDetail	R3
wordcloud、diy/stickerEdit	R4
profile	只读统计消费者，R2/R3 合入后统一收尾

后端按 NestJS 模块自然划分，不跨路线修改其他模块。

3. Git 规范

3.1 分支

• 每条路线在前端与后端仓库使用同名分支：feat/r1-catalog、feat/r2-address-design、feat/r3-order-pay、feat/r4-upload-wordcloud。
• 主干只允许合入，不允许直接开发；面向发布的小改动可以走 fix/... 短分支。
• 分支从各自仓库主干创建：前端 git checkout master，后端 git checkout main。

# 前端示例
git checkout master && git pull
git checkout -b feat/r1-catalog

# 后端示例
git checkout main && git pull
git checkout -b feat/r1-catalog

3.2 提交

• 使用 Conventional Commits：feat(scope): message、fix(scope): message、docs(scope): message、refactor(scope): message。
• scope 建议：catalog、address、design、order、pay、upload、wordcloud、store、api、contract。
• 一个提交只做一件事；文件级原子提交，不把无关改动混进同一个 commit。
• 不提交 .env、密钥、证书、临时日志；已跟踪的 dist/ 产物按各自仓库现有约定处理。
• 遇到他人未提交的工作区改动，不重置、不覆盖，需要时先沟通。

3.3 评审与合并

• 禁止直接推主干，统一走 Gitee/GitHub Pull Request。
• 同一路线的前端 PR 与后端 PR 由同一成员维护，其他成员评审；后端先定契约，前端按契约实现。
• 合并前先 rebase 主干，保持提交历史线性：

git fetch origin
git rebase origin/master   # 前端
git rebase origin/main     # 后端

• 合入使用 --no-ff，保留路线合并痕迹。
• 合入顺序：R1 最先（R3 依赖商品表），R2/R4 随后，R3 最后。
• 合入动作由路线负责人执行，其余成员只看评审，不代推主干。

3.4 冲突处理

• R0 聚合入口冲突由维护者协调，其他人只提交自己域内文件。
• 共享页面（如 checkout）按所有权表归属，冲突时由该页负责人解决。
• 出现跨路线耦合需求时，先在契约文档升版本，再开新任务，不临时改别人文件。

4. 契约管理

文档	位置	作用
API 契约 v1	wxmp_backend/docs/api-contract-v1.md	前后端接口的唯一依据
wordcloud 契约 v1	wxmp_backend/docs/wordcloud-contract.md	隔离 wordcloud 大量变更
路线文档	wechat_wc/docs/routes/	每条路线要开发什么、DO/DON'T、验收

规则：

• 接口先冻结，前端再开发；同一版本内禁止改字段名/类型/语义。
• 字段只能新增 optional 字段，否则升版本并同步更新前端 types。
• wordcloud 契约变更由 R4 单独升级适配器，不阻塞其他路线。

5. 推荐开发节奏

5.1 单个路线的生命周期

1. 契约对齐：后端写 DTO/Swagger + 更新契约文档，前端同步类型。
2. 独立实现：本人同时处理前端页面/数据层与后端 service/事务/权限。
3. 本地联调：用 Swagger + 微信开发者工具走通主流程。
4. 验收：构建、接口 smoke、手测清单逐项打勾。
5. 合并：rebase 主干，前端与后端 PR 一起提交，通知其他成员 git pull。

5.2 建议的两周迭代

阶段	建议安排
第 1-3 天	R0 收尾；R1-R4 四轨独立开工；R3/R4 先冻结各自契约
第 4-8 天	R1 合入；R2 持续开发；R3 基于 R1 契约开工；R4 开发上传与适配层
第 9-12 天	R2 合入；R3 联调；R4 与 wordcloud 联调
第 13-14 天	R3/R4 验收与合入；整理遗留问题和下一迭代计划

路线的粗略工时（一人独立完成）：

路线	预计
R1	3-5 天
R2	3-4 天
R3	5-7 天
R4	5-7 天（含外部联调）

5.3 每日节奏

• 早晨 15 分钟同步：昨天的进度、blocker、今天的契约/联调事项。
• 每人每天开工前 git pull + rebase 主干；长期分支不隔夜不管。
• 小步提交，一天至少推到远端一次，避免本地大爆炸式改动。
• PR 当天评审，评审人 24h 内反馈；遇到阻塞先降级方案再继续。

6. 验收红线（Definition of Done）

每路线合入前必须满足：

• 前端 npm run build:weapp 通过；后端 npm run build 通过。
• Swagger 与 api-contract-v1.md 一致，前端类型与契约一致。
• 涉及金额：金额只能服务端重算，客户端金额永不生效。
• 涉及私有数据：所有按 id 查询都校验本人，越权返回 403。
• 涉及支付：密钥未配置时返回结构化“未配置”，不做假成功。
• 涉及词云：小程序不直连 wordcloud，任务结果有用户归属。
• 路线文档中的 DO/DON'T 与验收清单逐项确认。

7. 高风险警示

• 不要在仓库里提交微信支付密钥、COS 密钥、JWT_SECRET。
• 不要把 wxfile:// 临时路径当作持久化图片地址入库。
• 不要模拟词云进度或模拟支付成功。
• 不要随意扩大路线边界；超出范围的需求先更新契约或新建任务。

8. 文档索引

• 并行开发指南
• R1 商品目录动态化
• R2 收货地址 + 设计清单
• R3 订单闭环 + 支付占位
• R4 上传 + 词云 + 线稿
• wxmp_backend/docs/api-contract-v1.md
• wxmp_backend/docs/wordcloud-contract.md