docs: fix team collaboration as four independent slices

docs/parallel-development-guide.md

@@ -1,5 +1,8 @@
 # 并行开发指南（R0）
 
+团队的仓库、分工、Git 规范与开发节奏以
+[团队协作总文档](team-collaboration-guide.md) 为准；本页专注代码修改约定。
+
 本文档是四名成员并行开发时的代码修改约定。目标是：每个人在自己路线的文件里改动，
 不与其他人发生文件级冲突；共享文件只由 R0 聚合入口维护，平时不再堆业务代码。
 

docs/team-collaboration-guide.md

@@ -0,0 +1,190 @@
+# 智绘微刻小程序团队协作总文档
+
+本文档是四人团队的协作单一入口，定义仓库、分工、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`。
+
+```bash
+# 前端示例
+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 主干，保持提交历史线性：
+
+```bash
+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. 文档索引
+
+- [并行开发指南](parallel-development-guide.md)
+- [R1 商品目录动态化](routes/route-r1-product-catalog.md)
+- [R2 收货地址 + 设计清单](routes/route-r2-address-design.md)
+- [R3 订单闭环 + 支付占位](routes/route-r3-order-pay.md)
+- [R4 上传 + 词云 + 线稿](routes/route-r4-upload-wordcloud.md)
+- `wxmp_backend/docs/api-contract-v1.md`
+- `wxmp_backend/docs/wordcloud-contract.md`