ADR 结论摘要与实现偏差

原文在 docs/decisions/（原文才是决策记录，这里只是索引）。四篇状态都是 accepted（2026-09-30）。

ADR-0001 2D 编辑器引擎：自研 Fabric.js 内核

原文：docs/decisions/ADR-0001-editor-engine.md

• 结论：Fabric.js（MIT）作交互 canvas 内核，自研 Layer/Command/History 与对象模型；Konva + react-konva（MIT）为备选。 切换引擎的前提是 Design JSON schema 不变（schema 才是资产）。
• 不引入 Polotno SDK（AGENTS.md 红线 5）：其许可明确限制"使用 SDK 构建或协助构建 competing editor / SDK / design platform"，而本产品本体就是设计平台 → 未取得书面豁免前属于明显的商业许可违约风险。 这里记录 Polotno 只为说明"为什么不用"，它不是本项目的采用方案。
• 后果：编辑器工作量真实落在我们自己身上（P2-01~P2-09）；对象模型必须写成纯 TS、不绑 React。
• 实现现状：验证工作台用 Fabric.js 做交互与场景渲染（docs/demo/scene.mjs、docs/demo/app.mjs）； Design JSON、几何、业务状态由项目代码掌管。packages/editor-core/ 的正式内核已落地并验收（P1-03 done）： packages/editor-core/src/geom.ts、packages/editor-core/src/style.ts、packages/editor-core/src/stage.ts、 packages/editor-core/src/scene.ts、packages/editor-core/src/layers.ts 已是纯 TS、DOM-free、mm 单位实现， packages/editor-core/src/index.ts 已把五个模块 export 出去（packages/editor-core/test/fixtures.ts 刚起步）。 它由 packages/editor-core/test/stage.test.ts 与内联刀模 fixture 做跨包对账（逐面板 + 线集合）验收， registry 中 P1-03 已 done；正式命令系统与图层树 UI 属 P2-01/P2-02。

ADR-0002 Design JSON 是唯一真源；图片只是渲染结果

原文：docs/decisions/ADR-0002-design-json-source-of-truth.md · 细则见 Design JSON 真源约定

• 结论：Design JSON = Canvas JSON + Assets + Fonts + Dieline + Brand Tokens + 3D Mapping； 所有导出都是投影；AI 修改必须改写 JSON。几何一律 mm（PX_PER_MM 可配，默认 4）； 颜色语义分离；图层六类；每次 AI 改动产生可回滚版本；AI 图内文字只作参考； 加工层（上光/白墨/烫金/UV）对应 GWG Packaging（其基础是 PDF/X-4）与 ISO 19593-1 语义 —— 这只是 JSON 侧语义，真正导出映射属未实现的 P3-09。
• 偏差：
  • 原文写 meta.schemaVersion + 迁移器；实现是顶层 schemaVersion（字面量 1），迁移器未实现（P1-10/P2-13）。
  • 原文要求"改 schema 的 PR 必须带 round-trip 与黄金样例测试"；当前只有 schema 单测 + 本站点示例检查， 黄金图基线尚未建立（P2-14 方向）。
  • 加工层 → OCG 的导出映射属 P3-09，未实现。

ADR-0003 Dieline Geometry 与 2D→3D UV 映射

原文：docs/decisions/ADR-0003-dieline-3d-uv.md · 细则见 刀模规范

• 结论：不用整块 BoxGeometry 贴图，而是每面板一个 mesh face，自带 UV 子矩形； Dieline / UVLayout / ArtworkMapping / Material 四件套；不让模型猜展开位置； 材质只影响预览；先固定盒型族，任意尺寸/纸厚/动态折叠属 PX-01。
• 偏差：
  • 线语义原文写 cut | crease | glue | bleed，实现是 cut | crease | glue | perf （packages/dieline/src/types.ts）；出血在实现里是 design.bleed 数值 + auxKind: "bleed"，不是线型。
  • "每面板不同染色 + 3D 截图比对"的文字方向不变量测试（P1-02 原设想）改成了 折叠链 + UV 方向断言（packages/dieline/test/uv.test.ts）：当时还没有 3D 渲染层可比对截图。 现在渲染层已落在 apps/web/src/three/PackPreview.ts 并验收（P1-04 done）， 折叠链断言仍是主防线，tools/verify-3d-preview.mjs 的像素核对是它的二次复验。
  • perf（齿孔线）目前只在枚举里，生成器不产出。

ADR-0004 生图与分割技术栈（Apple Silicon 约束）

原文：docs/decisions/ADR-0004-ai-segmentation-stack.md · 细则见 生图通道

• 当前生图：Seedream 5.0 Pro，通过持久化作业队列提交和恢复结果；OpenAI 适配器作为备选，离线回放用于零费用功能验收。
• 开发替代方案：2026-10-05 按用户要求移除项目内本地生图替代链，不再作为生产或开发依赖。
• 分割：当前使用 OpenCV GrabCut 与人工修边；SAM 2 的本机 MPS/CoreML 路线尚未部署或实测。
• 成本与回执：Seedream 估算费用使用人民币字段，厂商真实扣费以账单为准；后台与作业回执保留来源和调用标识。

决策 → 代码对照

决策	代码落点
真源与单位	packages/design-json/src/units.ts、geometry.ts、color.ts
图层与红线护栏	packages/design-json/src/layers.ts（source 三态、条码 superRefine、AUX_LAYER_KINDS）
版本可回滚	packages/design-json/src/versioning.ts
几何与 UV	packages/dieline/src/rectangular.mjs、uv.ts、types.ts
引擎与导出投影	docs/demo/scene.mjs、tools/render-document.mjs、tools/fix-pdf-page.py
AI 栈与埋点	workers/ai/src/providers.py、selection.py、segment.py、openai_image.py