docs(r2): 交接文档复核更新——DIY 修正批次新事实 + 契约核对结论

- README:新增修正批次落地事实(草稿随时 PATCH、SUBMITTED 触发点、
  edits 落库与消费、width/height 语义、x/y 允许超界、onShow 同步通病)、
  契约核对结论与已知偏差(wxfile:// 以冻结决策为准)
- r2-workflow:决策#6 注记 SUBMITTED 触发点提前
- design-data-contract:实现注记明确 x/y 允许超出画布边界(钳制已撤销)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
2026-09-12 20:10:18 +08:00
co-authored by Claude
parent 190e59af94
commit b109451e29
3 changed files with 34 additions and 3 deletions
+3 -1
View File
@@ -83,7 +83,9 @@ interface DesignDataV1 {
WCD 打包器同时兜底读旧字段。
> **实现注记(2026-09-12DIY 修正,非版本升级)**`stickers[].width/height` 的语义为
> **画布显示像素**(坐标空间 = `category.mask` 的宽高),`x/y` 同为画布坐标
> **画布显示像素**(坐标空间 = `category.mask` 的宽高),`x/y` 使用画布坐标空间
> (原点 = mask 左上角;**允许超出画布边界**——2026-09-12 需求确认:贴纸可拖出画布
> 自由摆放,渲染端裁切显示,WCD 打包按原值还原,不做钳制)。
> 渲染、碰撞检测、WCD 打包三方按同一语义消费,打包时不再做像素换算。
> 历史数据中按「图片原始像素」写入的值(width > mask 宽高)由读取端按 mask 等比归一化兼容,
> 不做存量迁移。`addSticker` 时即归一化到画布空间(建议初始占 mask 短边 60%)。
+3 -1
View File
@@ -35,7 +35,9 @@
`PRODUCT_ICON_MAP[productId]` 兜底推导(`designList/index.tsx:168` 逻辑已存在)。
4. **title 前端传 productName**:后端 `title` 保持必填不动,创建时填商品名。
5. **GET 两个列表接口不分页**:返回纯数组(地址、清单均为小数据量)。
6. **状态迁移触发点**:创建默认 `DRAFT`product 加入清单);DIY 保存设计 → `SUBMITTED`
6. **状态迁移触发点**:创建默认 `DRAFT`product 加入清单);~~DIY 保存设计 → `SUBMITTED`~~
**注记 2026-09-12**SUBMITTED 触发点提前到「进入 DIY 工作台」——新建条目创建后立即
PATCH `designing`,继续设计同样推进;见 `docs/diy-fix-workflow.md` 问题3);
`PROCESSING`/`DONE` 由 R3 订单流程驱动,前端不提交;`ordered``orderId != null` 派生,
前端只读。状态机单向推进,禁止回退。
7. **其他默认**:批量删除用单接口 `POST /api/design-list/batch-delete`
+28 -1
View File
@@ -21,6 +21,27 @@
6. 环境坑:前端 `.env``OSS_BASE_URL`)不入库。新机器 clone 后必须手动创建,否则
`assetUrl('/img/...')` 退化为找包内本地文件 → **首页大图全空白**(大图 8 月已迁 OSS
包内不再携带)。
7. **DIY 修正批次已全部落地**2026-09-12commits eea6c3f → 190e59a,详见
`docs/diy-fix-workflow.md`),新增事实:
- **清单条目会随时被 PATCH**:DIY 工作台贴纸变化防抖 800ms 静默同步服务端
(含 DRAFT 状态条目,designData 白名单/1MB 校验与状态无关),切后台/跳转前强制
flush。**R4 读改写 designData 时必须整包合并**(红线已在下方给 R4 第 1 条)。
- **SUBMITTED 触发点 = 进入 DIY 工作台**(新建创建后立即 PATCH `designing`
继续设计同样推进),不再是「确认完成」。状态机方向不变(r2-workflow 决策#6 已注记)。
- **贴纸 `edits` 现在会真实落库并被 DIY 渲染端消费**(CSS filter:亮度/色相/对比度);
贴纸 `src` 在纯滤镜编辑下保持不变(裁剪/线稿才替换 src)。
- **`stickers[].width/height` = 画布显示像素**addSticker 按 mask 短边 60% 归一化;
旧数据(原始像素语义)由读取端按 mask 等比归一化兼容,**不做存量迁移**。
- **`x/y` 允许超出画布边界**(2026-09-12 需求确认撤销了坐标钳制):负坐标/超界是
合法状态,渲染端 `overflow: hidden` 裁切显示,WCD 打包按原值还原,不要钳制。
- **页面栈返回不刷新是通病**:DIY 已加 `useDidShow` 从缓存同步贴纸;其他页面若
存在「子页面修改数据 → navigateBack 后不更新」,同样要用 onShow 双时机读取。
8. 契约核对(2026-09-12route DO/DON'T + 双契约):checkout 未改动(本分支 0 diff);
`region[]` 转换只在 `api/address.ts`;前端只提交契约内状态码(designing);
`isDefault` 唯一性由后端事务保证(本地 store 仅离线镜像);设计数据 7 键白名单
/1MB/wordcloud 保留全部遵守。**已知且已被契约接受的偏差**:贴纸 `src` 暂存
`wxfile://`route 文档 DON'T 写于冻结决策之前,以 design-data-contract
约束#1/决策#4 为准,R4 派单前必须上传 COS)。
## 给 R3(订单 + 支付)
@@ -30,6 +51,9 @@
2. **状态触发权归 R3**`PROCESSING`/`DONE` 由订单流程驱动(前端从不提交);
`ordered``orderId != null` 派生,只读。R2 已实现单向状态机
`DRAFT→SUBMITTED→PROCESSING→DONE`(后端校验,回退 400)。
**注意(2026-09-12 变更)**`SUBMITTED`designing)现在由 R2 前端在「进入 DIY
工作台」时即提交(不再等确认完成)——R3 不要假设 DRAFT 表示"用户还没动过设计",
DRAFT 仅表示条目创建后从未打开过工作台。
3. **删除保护(R3 落地项)**R2 的 DELETE/batch-delete **没有**做"有订单关联的清单
禁止删除"的守卫。R3 建 Order→DesignList 关联时必须同步加 delete-guard 或明确外键行为
(SetNull),否则用户可删掉订单引用的设计快照。
@@ -40,7 +64,7 @@
mount + onShow 双时机读取(详见 `docs/diy-fix-workflow.md` 问题 6)。
6. **checkout 预览不消费贴纸 `edits`**(亮度/色相/对比度):DIY 渲染端套 CSS filter
呈现编辑效果,checkout 预览接入时需同样消费(R3 待办,见 diy-fix-workflow 问题 5)。
5. 金额重算:按契约用服务端 Product 真实价格 + `designList.items[0]` 快照,
7. 金额重算:按契约用服务端 Product 真实价格 + `designList.items[0]` 快照,
忽略客户端金额;下单带 `requestId` 幂等。
## 给 R4(上传 / 词云 / 派单)
@@ -55,6 +79,9 @@
R4 不要往该字段塞完整 ProductCategory。
4. DIY 贴纸目前不产生 `rotation`(无旋转手势)、`zIndex` 仅渲染层使用——两字段类型已
备好但值可能缺席,WCD 打包按 optional 处理(契约决策#2)。
5. **2026-09-12 起)`width/height` = 画布显示像素**(mask 短边 60% 归一化起步),
`x/y` 为画布坐标空间且**允许超界(含负值,不钳制)**——打包按原值还原布局即可,
不要按「图片原始像素」换算,也不要对坐标做边界裁剪(契约实现注记)。
## 给 R1(商品目录)