# R2 收货地址 + 设计清单（feat/r2-address-design）

**Goal:** 把收货地址和设计清单从本地 Storage 切换到后端 CRUD，完成字段契约、接口权限、
默认地址事务、设计数据 JSON 与状态映射，让 R3 的订单闭环可以直接消费这两组能力。

**Architecture:** 前端 `api/address.ts`、`api/design.ts` 负责 HTTP 契约，本地
`store/address.ts`、`store/design.ts` 在联调期保留为兜底；后端补齐 addresses 与 design-list
的完整 CRUD、事务与本人数据校验；`checkout` 页归 R3 所有，R2 只定义接口不修改该页面。

**Tech Stack:** Taro 3.6 + React 18 + TypeScript；NestJS 11 + Prisma/PostgreSQL。

## 1. 本分支要开发的内容

### 前端 `wechat_wc`

| 文件 | 职责 |
|---|---|
| `src/utils/api/address.ts` | `fetchAddresses/createAddress/updateAddress/deleteAddress/setDefaultAddress`，负责 `region[]` 与 `province/city/district` 双向转换 |
| `src/utils/api/design.ts` | `fetchDesignList/createDesign/updateDesign/deleteDesigns` |
| `src/pages/address/index.tsx` | 列表、新增、编辑、删除、设为默认全部走 API；保留表单校验与区域 Picker |
| `src/pages/designList/index.tsx` | 列表、状态筛选、批量删除走 API；保留 LoginGuard |
| `src/types/index.ts` | AddressItem/DesignItem 与后端结构对齐，新增服务端 id、状态码、时间字段 |
| `src/utils/store/address.ts`、`design.ts` | 降级为“本地缓存/离线兜底”，API 调用成功后同步刷新 |

### 后端 `wxmp_backend`

| 模块 | 内容 |
|---|---|
| `addresses` | `GET/POST /api/addresses`、`PATCH /api/addresses/:id`、`PATCH /api/addresses/:id/default`、`DELETE /api/addresses/:id`；全部带 userId 归属校验 |
| `addresses` 事务 | 设置默认时事务内先清旧默认再设新默认；删除默认地址后自动指定最新一条为默认 |
| `design-list` | `GET/POST /api/design-list`、`PATCH /api/design-list/:id`、`DELETE /api/design-list/:id`、批量删除 |
| `design-list` 校验 | `items` JSON 结构与大小校验、状态机转换、本人专属查询 |
| `docs/api-contract-v1.md` | 地址字段映射、设计清单状态枚举、错误码 |

### 词云项目 `wordcloud`

不参与本分支，但 `designData` 中的本地贴纸图片路径问题会影响后续 R4，见风险一节。

## 2. 状态映射（必须先定死）

后端 `DesignListStatus` 目前是 `DRAFT/SUBMITTED/PROCESSING/DONE`，前端是
`undesigned/designing/ordered`。R2 不要在两边各造一套值，建议按显示语义映射：

| 前端显示 | 后端状态 | 前端状态码 |
|---|---|---|
| 待设计 | DRAFT | `undesigned` |
| 设计中 | SUBMITTED | `designing` |
| 生产中 | PROCESSING | `processing` |
| 已下单 | DONE | `ordered` |

“已下单”不要用独立状态表达，改为 `orderId != null` 派生；前端只显示，不提交这个状态。
状态码收口到 `docs/api-contract-v1.md`，后端校验状态迁移，前端不传自由字符串。

## 3. 字段契约

### 地址

后端 `province/city/district/detail` 对应前端 `region: [province, city, district] + detail`。
转换只放在 `api/address.ts`，页面和 store 不得散落第二次转换。

### 设计数据

`DesignList.items` 是服务端 JSON，前端提交结构建议与当前 `DesignItem.designData` 对齐：

```ts
interface DesignData {
  stickers?: StickerItem[]
  category?: ProductCategory
  imageSrc?: string
  imagePos?: { x: number; y: number; scale: number }
}
```

服务端只做白名单字段校验，不修改业务 JSON 内容；单条设计数据建议限制在 1MB 以内。

## 4. 设计注意事项

### DO

- DO 地址的增删改查和默认切换全部要求登录态，401 时引导去个人中心登录。
- DO 所有按 id 操作的服务端路由同时带 `userId` 条件，404 与 403 区分清楚。
- DO 默认地址切换与删除补偿放在同一个 Prisma transaction 里。
- DO 前端继续沿用户已熟悉的表单校验，但最终校验提示以后端返回为准。
- DO 设计清单状态通过后端枚举返回，前端状态筛选基于返回的 `status` 计算。
- DO 批量删除设计条目提供单个接口或循环调用时保证部分失败可恢复；推荐后端一次批量删除。
- DO 本地 store 只在 API 失败时做降级读取，成功写回后以服务端数据为准。

### DON'T

- DON'T 把前端 `region` 数组原样 POST 给后端，后端契约是四个独立地址字段。
- DON'T 让前端直接写 `isDefault` 的两条规则，默认地址唯一性由后端事务保证。
- DON'T 在路由/service 层漏掉归属校验；这是本分支最容易出的越权洞。
- DON'T 新增前端自造状态 `ordered` 之外的字符串，状态值必须在契约文档里可枚举。
- DON'T 在本分支修改 `checkout/index.tsx`，地址选择器与下单集成留给 R3。
- DON'T 把 `wxfile://` 临时贴纸路径当作可持久化 URL 直接入库，R4 之前它只是本地预览。
- DON'T 用设计清单字段承载订单状态，`orderId` 派生展示即可。

## 5. 补充内容

### 验收标准

- 地址页与设计清单页在登录态下增删改查、默认切换、批量删除全部走真实后端并刷新。
- 后端所有变更接口带本人校验，越权访问返回 403，不存在资源返回 404。
- 默认地址永远唯一；删除默认地址后列表自动产生新的默认地址。
- 前端构建与后端构建通过；Swagger 涵盖地址与设计清单全部接口。
- 状态映射表在 `docs/api-contract-v1.md` 中落地，前端页面不再出现魔法字符串状态。

### 合并与依赖

- 分支名：前端与后端均为 `feat/r2-address-design`。
- R2 依赖已有登录体系（已完成），不依赖 R1；可与 R1 并行开发。
- checkout 对地址 API 的调用在 R3 接入，R2 只需保证接口稳定即可。

### 风险

- 设计数据中的贴纸是本地临时路径，一旦真机重启或清理缓存，旧设计预览会裂图；在 R4 上传能力完成前，文档明确这是已知限制。
- 旧版本本地 `smart_design_list_<openid>` 数据与后端数据可能并存，首次切换登录时避免双写冲突；可做一次性“导入本地清单”或直接忽略旧数据。
- 批量删除接口若后端未实现，前端循环删除会遇到部分失败，联调时先约定失败语义。

### 测试要求

- 后端：地址 CRUD、默认地址唯一性事务、越权访问、设计清单状态迁移、超大 JSON 拒绝。
- 前端：地址新增/编辑/删除/默认切换、设计清单筛选/批量删除、断网降级提示、401 引导登录。