diff --git a/docs/design-data-contract-v1.md b/docs/design-data-contract-v1.md index 0bbdf66..cb013fe 100644 --- a/docs/design-data-contract-v1.md +++ b/docs/design-data-contract-v1.md @@ -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%)。 diff --git a/docs/r2-workflow.md b/docs/r2-workflow.md index b677702..ba6f62e 100644 --- a/docs/r2-workflow.md +++ b/docs/r2-workflow.md @@ -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`; diff --git a/docs/routes/R2/README.md b/docs/routes/R2/README.md index 45286c3..e6de8b3 100644 --- a/docs/routes/R2/README.md +++ b/docs/routes/R2/README.md @@ -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(商品目录)