191 lines
8.3 KiB
Markdown
191 lines
8.3 KiB
Markdown
# 智绘微刻小程序团队协作总文档
|
||
|
||
本文档是四人团队的协作单一入口，定义仓库、分工、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`
|