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 打包器同时兜底读旧字段。
|
WCD 打包器同时兜底读旧字段。
|
||||||
|
|
||||||
> **实现注记(2026-09-12,DIY 修正,非版本升级)**:`stickers[].width/height` 的语义为
|
> **实现注记(2026-09-12,DIY 修正,非版本升级)**:`stickers[].width/height` 的语义为
|
||||||
> **画布显示像素**(坐标空间 = `category.mask` 的宽高),`x/y` 同为画布内坐标。
|
> **画布显示像素**(坐标空间 = `category.mask` 的宽高),`x/y` 使用画布坐标空间
|
||||||
|
> (原点 = mask 左上角;**允许超出画布边界**——2026-09-12 需求确认:贴纸可拖出画布
|
||||||
|
> 自由摆放,渲染端裁切显示,WCD 打包按原值还原,不做钳制)。
|
||||||
> 渲染、碰撞检测、WCD 打包三方按同一语义消费,打包时不再做像素换算。
|
> 渲染、碰撞检测、WCD 打包三方按同一语义消费,打包时不再做像素换算。
|
||||||
> 历史数据中按「图片原始像素」写入的值(width > mask 宽高)由读取端按 mask 等比归一化兼容,
|
> 历史数据中按「图片原始像素」写入的值(width > mask 宽高)由读取端按 mask 等比归一化兼容,
|
||||||
> 不做存量迁移。`addSticker` 时即归一化到画布空间(建议初始占 mask 短边 60%)。
|
> 不做存量迁移。`addSticker` 时即归一化到画布空间(建议初始占 mask 短边 60%)。
|
||||||
|
|||||||
+3
-1
@@ -35,7 +35,9 @@
|
|||||||
`PRODUCT_ICON_MAP[productId]` 兜底推导(`designList/index.tsx:168` 逻辑已存在)。
|
`PRODUCT_ICON_MAP[productId]` 兜底推导(`designList/index.tsx:168` 逻辑已存在)。
|
||||||
4. **title 前端传 productName**:后端 `title` 保持必填不动,创建时填商品名。
|
4. **title 前端传 productName**:后端 `title` 保持必填不动,创建时填商品名。
|
||||||
5. **GET 两个列表接口不分页**:返回纯数组(地址、清单均为小数据量)。
|
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` 派生,
|
`PROCESSING`/`DONE` 由 R3 订单流程驱动,前端不提交;`ordered` 由 `orderId != null` 派生,
|
||||||
前端只读。状态机单向推进,禁止回退。
|
前端只读。状态机单向推进,禁止回退。
|
||||||
7. **其他默认**:批量删除用单接口 `POST /api/design-list/batch-delete`;
|
7. **其他默认**:批量删除用单接口 `POST /api/design-list/batch-delete`;
|
||||||
|
|||||||
@@ -21,6 +21,27 @@
|
|||||||
6. 环境坑:前端 `.env`(`OSS_BASE_URL`)不入库。新机器 clone 后必须手动创建,否则
|
6. 环境坑:前端 `.env`(`OSS_BASE_URL`)不入库。新机器 clone 后必须手动创建,否则
|
||||||
`assetUrl('/img/...')` 退化为找包内本地文件 → **首页大图全空白**(大图 8 月已迁 OSS,
|
`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(订单 + 支付)
|
## 给 R3(订单 + 支付)
|
||||||
|
|
||||||
@@ -30,6 +51,9 @@
|
|||||||
2. **状态触发权归 R3**:`PROCESSING`/`DONE` 由订单流程驱动(前端从不提交);
|
2. **状态触发权归 R3**:`PROCESSING`/`DONE` 由订单流程驱动(前端从不提交);
|
||||||
`ordered` 由 `orderId != null` 派生,只读。R2 已实现单向状态机
|
`ordered` 由 `orderId != null` 派生,只读。R2 已实现单向状态机
|
||||||
`DRAFT→SUBMITTED→PROCESSING→DONE`(后端校验,回退 400)。
|
`DRAFT→SUBMITTED→PROCESSING→DONE`(后端校验,回退 400)。
|
||||||
|
**注意(2026-09-12 变更)**:`SUBMITTED`(designing)现在由 R2 前端在「进入 DIY
|
||||||
|
工作台」时即提交(不再等确认完成)——R3 不要假设 DRAFT 表示"用户还没动过设计",
|
||||||
|
DRAFT 仅表示条目创建后从未打开过工作台。
|
||||||
3. **删除保护(R3 落地项)**:R2 的 DELETE/batch-delete **没有**做"有订单关联的清单
|
3. **删除保护(R3 落地项)**:R2 的 DELETE/batch-delete **没有**做"有订单关联的清单
|
||||||
禁止删除"的守卫。R3 建 Order→DesignList 关联时必须同步加 delete-guard 或明确外键行为
|
禁止删除"的守卫。R3 建 Order→DesignList 关联时必须同步加 delete-guard 或明确外键行为
|
||||||
(SetNull),否则用户可删掉订单引用的设计快照。
|
(SetNull),否则用户可删掉订单引用的设计快照。
|
||||||
@@ -40,7 +64,7 @@
|
|||||||
mount + onShow 双时机读取(详见 `docs/diy-fix-workflow.md` 问题 6)。
|
mount + onShow 双时机读取(详见 `docs/diy-fix-workflow.md` 问题 6)。
|
||||||
6. **checkout 预览不消费贴纸 `edits`**(亮度/色相/对比度):DIY 渲染端套 CSS filter
|
6. **checkout 预览不消费贴纸 `edits`**(亮度/色相/对比度):DIY 渲染端套 CSS filter
|
||||||
呈现编辑效果,checkout 预览接入时需同样消费(R3 待办,见 diy-fix-workflow 问题 5)。
|
呈现编辑效果,checkout 预览接入时需同样消费(R3 待办,见 diy-fix-workflow 问题 5)。
|
||||||
5. 金额重算:按契约用服务端 Product 真实价格 + `designList.items[0]` 快照,
|
7. 金额重算:按契约用服务端 Product 真实价格 + `designList.items[0]` 快照,
|
||||||
忽略客户端金额;下单带 `requestId` 幂等。
|
忽略客户端金额;下单带 `requestId` 幂等。
|
||||||
|
|
||||||
## 给 R4(上传 / 词云 / 派单)
|
## 给 R4(上传 / 词云 / 派单)
|
||||||
@@ -55,6 +79,9 @@
|
|||||||
R4 不要往该字段塞完整 ProductCategory。
|
R4 不要往该字段塞完整 ProductCategory。
|
||||||
4. DIY 贴纸目前不产生 `rotation`(无旋转手势)、`zIndex` 仅渲染层使用——两字段类型已
|
4. DIY 贴纸目前不产生 `rotation`(无旋转手势)、`zIndex` 仅渲染层使用——两字段类型已
|
||||||
备好但值可能缺席,WCD 打包按 optional 处理(契约决策#2)。
|
备好但值可能缺席,WCD 打包按 optional 处理(契约决策#2)。
|
||||||
|
5. **(2026-09-12 起)`width/height` = 画布显示像素**(mask 短边 60% 归一化起步),
|
||||||
|
`x/y` 为画布坐标空间且**允许超界(含负值,不钳制)**——打包按原值还原布局即可,
|
||||||
|
不要按「图片原始像素」换算,也不要对坐标做边界裁剪(契约实现注记)。
|
||||||
|
|
||||||
## 给 R1(商品目录)
|
## 给 R1(商品目录)
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user