From b109451e29aab17291e71443e5ada0e7a23c4de6 Mon Sep 17 00:00:00 2001 From: lhmin0604 Date: Sat, 12 Sep 2026 20:10:18 +0800 Subject: [PATCH] =?UTF-8?q?docs(r2):=20=E4=BA=A4=E6=8E=A5=E6=96=87?= =?UTF-8?q?=E6=A1=A3=E5=A4=8D=E6=A0=B8=E6=9B=B4=E6=96=B0=E2=80=94=E2=80=94?= =?UTF-8?q?DIY=20=E4=BF=AE=E6=AD=A3=E6=89=B9=E6=AC=A1=E6=96=B0=E4=BA=8B?= =?UTF-8?q?=E5=AE=9E=20+=20=E5=A5=91=E7=BA=A6=E6=A0=B8=E5=AF=B9=E7=BB=93?= =?UTF-8?q?=E8=AE=BA?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - README：新增修正批次落地事实（草稿随时 PATCH、SUBMITTED 触发点、 edits 落库与消费、width/height 语义、x/y 允许超界、onShow 同步通病）、 契约核对结论与已知偏差（wxfile:// 以冻结决策为准） - r2-workflow：决策#6 注记 SUBMITTED 触发点提前 - design-data-contract：实现注记明确 x/y 允许超出画布边界（钳制已撤销） Co-Authored-By: Claude --- docs/design-data-contract-v1.md | 4 +++- docs/r2-workflow.md | 4 +++- docs/routes/R2/README.md | 29 ++++++++++++++++++++++++++++- 3 files changed, 34 insertions(+), 3 deletions(-) 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（商品目录）