# 并行开发指南（R0）

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

## 1. 目录约定

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

```ts
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 商品目录动态化](routes/route-r1-product-catalog.md) | `feat/r1-catalog` |
| [R2 地址 + 设计清单](routes/route-r2-address-design.md) | `feat/r2-address-design` |
| [R3 订单 + 支付占位](routes/route-r3-order-pay.md) | `feat/r3-order-pay` |
| [R4 上传 + 词云 + 线稿](routes/route-r4-upload-wordcloud.md) | `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` |

日常循环：

```bash
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. 验证

每次提交前至少保证：

```bash
npm run build:weapp
```

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