wechat_wc/docs/parallel-development-guide.md

并行开发指南（R0）

团队的仓库、分工、Git 规范与开发节奏以 团队协作总文档 为准；本页专注代码修改约定。

本文档是四名成员并行开发时的代码修改约定。目标是：每个人在自己路线的文件里改动， 不与其他人发生文件级冲突；共享文件只由 R0 聚合入口维护，平时不再堆业务代码。

1. 目录约定

页面不得直接读写 Storage 或跨过聚合入口调用底层模块，统一从下面两个入口导入：

import { getAddressList, addAddress } from '../../utils/store'
import { fetchProducts, createOrder } from '../../utils/api'

src/utils/store/：DA 层，按域拆分：

文件	归属	内容
store/keys.ts	R0，尽量不改	openid 作用域 key 与 mock 判断
store/user.ts	R0/R3	用户信息、账号切换、注册表
store/design.ts	R2	设计清单本地数据
store/address.ts	R2	收货地址本地数据
store/order.ts	R3	订单本地数据与 designToOrder
store/theme.ts	R0	主题模式读写
store/index.ts	R0	聚合 re-export，只加不删

src/utils/api/：HTTP 接口层，按域拆分：

文件	归属	内容
api/auth.ts	R0	登录、登出、token
api/user.ts	R0	用户资料
api/product.ts	R1	商品、分类
api/address.ts	R2	收货地址（待补）
api/design.ts	R2	设计清单（待补）
api/order.ts	R3	订单、支付（待补）
api/upload.ts	R4	上传、词云、线稿（待补）
api/index.ts	R0	聚合 re-export

类型统一放在 src/types/index.ts，或按域新增 src/types/<domain>.ts， 不要把页面私有类型散落在各个页面里。

2. 路线归属

每条路线的完整开发内容、设计 DO/DON'T 与验收标准见 docs/routes/：

文档	分支
R1 商品目录动态化	feat/r1-catalog
R2 地址 + 设计清单	feat/r2-address-design
R3 订单 + 支付占位	feat/r3-order-pay
R4 上传 + 词云 + 线稿	feat/r4-upload-wordcloud

路线	页面	后端	词云项目
R1 商品目录	index、shop、product	products/categories、schema 扩展、seed	不用
R2 地址 + 设计清单	address、designList	addresses CRUD、design-list CRUD、状态映射	不用
R3 订单 + 支付占位	checkout、orders、orderDetail、付款按钮	orders 重算/事务、payments 占位	不用
R4 上传 + 词云 + 线稿	wordcloud、diy/stickerEdit	upload、词云适配器、sketch、队列	复用，需冻结最小契约

文件所有权约定：

• checkout 页归 R3，R2 只做 address 和 designList 页。
• profile 页是只读统计消费者，等 R2/R3 合入后再统一收尾。
• wordcloud 项目只有 R4 会碰，其余路线不依赖它。

3. 新增接口怎么改

1. 后端先把 Swagger/DTO 定下来，确认字段与状态枚举。
2. 在对应的 api/<domain>.ts 里写函数，返回类型对齐 src/types。
3. 不需要改页面里的导入路径：聚合入口已 re-export 所有域文件， 新函数会自动从 ../../utils/api 导出。
4. 页面只调用 api 层的函数，不在页面里直接写 http.get。

4. 新增本地业务怎么改

1. 判断属于哪个域，写进 store/<domain>.ts。
2. 若该域已有文件，直接在文件内追加函数；不要新建 xxx2.ts。
3. 新域需在 store/index.ts 增加一行显式 re-export。
4. 页面通过 ../../utils/store 导入，不直接 import 内部模块路径。

5. Git 协作

每路线在 wechat_wc 与 wxmp_backend 使用同名分支：

路线	分支名
R1	feat/r1-catalog
R2	feat/r2-address-design
R3	feat/r3-order-pay
R4	feat/r4-upload-wordcloud

日常循环：

git checkout main && git pull
git checkout -b feat/r1-catalog

# 提交并推送自己的分支
git add -A
git commit -m "feat(catalog): xxx"
git push -u origin feat/r1-catalog

# 主干有更新时，变基到最新
git fetch origin
git rebase origin/main

# 合入：只有合入负责人执行
git checkout main && git pull
git merge --no-ff feat/r1-catalog
git push origin main

规则：

• 主干 main 保持可运行，禁止直接 push，合入走 Pull Request。
• 后端与前端同名分支是一对，评审时成对看，后端 Swagger 先定契约。
• 不跨路线互相拉分支；主干更新只通过 rebase origin/main 获取。
• 合入顺序：R1 先合（R3 服务端金额重算依赖商品表），R2/R4 随后，R3 最后。

6. 验证

每次提交前至少保证：

npm run build:weapp

R1 合入前额外跑后端接口 smoke；R2/R3 合入前跑对应页面在微信开发者工具里的手测； R4 合入前跑一次词云契约 smoke。