From 395fa4116c3a8f03079bb9317a8869756c47968b Mon Sep 17 00:00:00 2001 From: lhmin0604 Date: Sat, 12 Sep 2026 18:53:07 +0800 Subject: [PATCH] =?UTF-8?q?docs(r2):=20=E5=A5=91=E7=BA=A6=E6=A0=B8?= =?UTF-8?q?=E5=AF=B9=E8=A1=A5=E5=85=85=20+=20design-data-contract=20?= =?UTF-8?q?=E5=A2=9E=E5=8A=A0=20width/height=20=E8=AF=AD=E4=B9=89=E6=B3=A8?= =?UTF-8?q?=E8=AE=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - diy-fix-workflow：新增两份契约逐项核对总表 - design-data-contract-v1：stickers[].width/height/x/y 语义 = 画布显示像素 （实现注记，非版本升级），历史数据读端按 mask 归一化兼容 Co-Authored-By: Claude --- docs/design-data-contract-v1.md | 6 ++++++ docs/diy-fix-workflow.md | 18 ++++++++++++++++++ 2 files changed, 24 insertions(+) diff --git a/docs/design-data-contract-v1.md b/docs/design-data-contract-v1.md index 63a8a9a..0bbdf66 100644 --- a/docs/design-data-contract-v1.md +++ b/docs/design-data-contract-v1.md @@ -82,6 +82,12 @@ interface DesignDataV1 { - `imageSrc/imagePos` 保留为兼容旧版字段；新写入统一走 `background.src/pos`， WCD 打包器同时兜底读旧字段。 +> **实现注记（2026-09-12，DIY 修正，非版本升级）**：`stickers[].width/height` 的语义为 +> **画布显示像素**（坐标空间 = `category.mask` 的宽高），`x/y` 同为画布内坐标。 +> 渲染、碰撞检测、WCD 打包三方按同一语义消费，打包时不再做像素换算。 +> 历史数据中按「图片原始像素」写入的值（width > mask 宽高）由读取端按 mask 等比归一化兼容， +> 不做存量迁移。`addSticker` 时即归一化到画布空间（建议初始占 mask 短边 60%）。 + ## 3. 冻结约束（R2 需落地） | # | 约束 | 说明 | diff --git a/docs/diy-fix-workflow.md b/docs/diy-fix-workflow.md index ebdd073..992fa85 100644 --- a/docs/diy-fix-workflow.md +++ b/docs/diy-fix-workflow.md @@ -190,6 +190,24 @@ R2 侧职责（API 保存 + 缓存回写）已正确完成并经真机验证。 --- +## 契约核对总表（api-contract-v1.md + design-data-contract-v1.md） + +2026-09-12 对两份契约逐项核对后的结论： + +| # | api-contract-v1.md | design-data-contract-v1.md | +|---|---|---| +| 1 | 无需改（stickers 为 `unknown[]`，语义由子契约承载）；§5 已加实现补充注记指引 | **加实现注记**：width/height/x/y 语义 = 画布显示像素，历史数据读端兼容（已完成） | +| 2 | PATCH 部分更新语义后端已实现，1MB 按次校验不受高频影响；无契约文字改动 | 无 | +| 3 | 状态映射表未写死 SUBMITTED 触发点，DRAFT→SUBMITTED 合法；无契约改动（触发点调整记录在 r2-workflow 决策#6 注记） | 无 | +| 4 | 无 | 无 | +| 5 | stickers 透传 edits、§8 sketch 不变；无契约改动 | edits 边界（不进 document.json）不变 | +| 6 | §4 地址接口不变，读时机为客户端行为 | 无 | + +**核对中发现并已修正的矛盾**：api-contract §5 引用块原写「贴纸图 src 必须为 COS 持久 URL +（禁止 `wxfile://`/`tmp`）」，与 design-data-contract 约束#1/决策#4（R2 允许暂存本地图、 +R4 派单前持久化回写）直接矛盾，且真机落库数据即为 wxfile://。已按冻结决策修正措辞 +（非字段/语义变更，不升版本）。 + ## 修复顺序与依赖 ```