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:
@@ -83,7 +83,9 @@ interface DesignDataV1 {
|
||||
WCD 打包器同时兜底读旧字段。
|
||||
|
||||
> **实现注记(2026-09-12,DIY 修正,非版本升级)**:`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
@@ -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`;
|
||||
|
||||
@@ -21,6 +21,27 @@
|
||||
6. 环境坑:前端 `.env`(`OSS_BASE_URL`)不入库。新机器 clone 后必须手动创建,否则
|
||||
`assetUrl('/img/...')` 退化为找包内本地文件 → **首页大图全空白**(大图 8 月已迁 OSS,
|
||||
包内不再携带)。
|
||||
7. **DIY 修正批次已全部落地**(2026-09-12,commits 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-12,route 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(商品目录)
|
||||
|
||||
|
||||
Reference in New Issue
Block a user