docs(design): 设计真相源分层治理落地（原型漂移拍板）

- CLAUDE.md 新增「设计真相源分层」强制规则：L1 设计系统层原型单源不变； L2 屏级三态（同步/快照/代码先行）；L3 新屏仍 design-first；漂移改定期体检 - CONTRACT 块 4 加「真相源」列（14 屏同步 / register 快照），新增代码先行屏小节（授权管理面板/购买卡/官网 checkout 等，不反向补原型） - screens.mjs 注释明确只登记「同步」态屏，与 CONTRACT 互为镜像 - 附带体检：golden 84 用例全绿（failures 264 张陈留物已清）； fidelity 36 屏×主题全部阈内（≤8%）；check-ds 12 道闸全过 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JJ1g8XV1YhhmHRzhwWEW7o
2026-07-04 06:56:17 +08:00
parent e022494f63
commit e0fdb8c12f
3 changed files with 53 additions and 20 deletions
@@ -254,6 +254,18 @@ cd client && flutter test
 - 使用 `dart:io` 的 `Platform` 类前，必须先检查 `kIsWeb`（`import 'package:flutter/foundation.dart'`）
 - Web 平台不支持 `dart:io`，直接使用会在 Web 构建时崩溃

+### 设计真相源分层（原型漂移治理，2026-07-04 拍板）
+
+原型（`.superpowers/prototype/`）与真实页面**不追求全量永久同步**，按层分治：
+
+- **L1 设计系统层**（`tokens.css` / `atoms.css` / `mobile-atoms.css` / `icons.js` + `index.html` 登记）：原型是**单一真源**。新增颜色/组件/图标必须**先登记原型再同步**代码与官网（如 `web/_includes/icons.njk`）。闸：pre-commit `check-ds.mjs` 12 道（本地钩子，新机器先跑 `sh scripts/hooks/install.sh`）+ 代码侧 `client/tool/check_ds_code.mjs`。
+- **L2 屏级三态**（台账 = `design/CONTRACT.md` 块 4「真相源」列）：
+  - `同步`：注册于 `tools/screens.mjs`，fidelity 像素闸生效。整屏改版须原型先行；小迭代改后跑 fidelity 确认阈内，超阈则同步原型或降级快照。
+  - `快照`：原型退役为历史参考，**golden + CONTRACT 文字规格为准**；小迭代只更 golden，**不回填原型**。
+  - `代码先行`：无原型屏，golden 为唯一像素基准。
+- **L3 新屏/整屏改版**：design-first 不变（原型 → CONTRACT → 实现 → fidelity 验收），建成后入 `同步` 态。
+- **漂移体检**：不逐提交强制同步；大版本/整屏改版前跑 `node tools/fidelity.mjs`，按报告逐屏决定「重新对齐原型」或「降级快照」，结果回填 CONTRACT。
+
 ### 表格与列头筛选（ds 真相源）
 - 列表屏统一 `DsTable`（`widgets/ds/ds_table.dart`：toolbar+表格+pager 连成一卡），列定义 `DsColumn`，可筛选列走其列头漏斗（`filtered` 态高亮），可隐藏列走列设置菜单
 - 不要在 toolbar 放独立筛选按钮，筛选入口内嵌列头或工具栏 `DsChip`
@@ -1,8 +1,11 @@
 # 设计契约 — 岩美酒库 Flutter 还原（Phase 1 起：库存列表）

-> design-distill 阶段 1 产物。像素以 `.superpowers/prototype/` 原型为**唯一基准**；
-> token 走 codegen 单源（已在 P0 落地）；还原由截图 diff 验收，不靠目测。
+> design-distill 阶段 1 产物。token 走 codegen 单源（已在 P0 落地）；还原由截图 diff 验收，不靠目测。
 > 本文件是**执行真相源**（与 plan `.md` 同性质，机器/diff 引用），随逐屏推进增补。
+>
+> **真相源分层（2026-07-04 拍板，全文见 CLAUDE.md「设计真相源分层」）**：原型仅对
+> 设计系统层（tokens/atoms/icons）与「真相源=同步」态屏是唯一基准；`快照`/`代码先行`
+> 态屏以 **golden + 本文件文字规格**为准，小迭代不回填原型。屏的状态登记在块 4「真相源」列。

 ## 阶段 0 · 归一化产物（已就位）

@@ -87,23 +90,38 @@ AppTokens 目前**仅颜色**。原型还驱动：

 ## 块 4 · 逐屏验收清单（每屏 × 主题；diff 闸）

-| 屏 | 原型 | Flutter | a(基准) | b | c |
-|---|---|---|---|---|---|
-| 库存列表(桌面) | `inventory.html` | `inventory_list_screen.dart` | ✅ KPI/徽章/列/副标/toolbar 已还原 | ✅ golden 自比 | ✅ golden 自比 |
-| 库存列表(移动) | `m-inventory.html` | 同上窄屏(卡片流) | ✅ golden 自比 | ✅ golden 自比 | ✅ golden 自比 |
-| 往来单位(桌面) | `partners.html` | `partners_screen.dart` | ✅ **Phase2 重建**：单表+类型 chips/应收应付列(finance summary)/详情抽屉/frow 弹窗；fidelity 2.5–3.5%≤8% | ✅ fidelity | ✅ fidelity |
-| 往来单位(移动) | `m-partners.html` | 同上窄屏(卡片流) | ✅ golden 自比 | ✅ golden 自比 | ✅ golden 自比 |
-| 基础数据(桌面) | `products.html` | `products_screen.dart` | ✅ **Phase2 重建**：.seg 5 tab(档案/介绍/系列/规格/仓库)+三套视图+编辑抽屉复用；fidelity 2.4–3.5%≤8%（已知差异见下） | ✅ fidelity | ✅ fidelity |
-| 基础数据(移动) | `m-products.html` | 同上窄屏(卡片流) | ✅ golden 自比 | ✅ golden 自比 | ✅ golden 自比 |
-| 入库列表(桌/移) | `stock-in-list.html` | `stock_in_list_screen.dart` | ✅ 副标 + 共享 StatusPill(草稿/待审/已审/已拒) | ✅ golden | ✅ golden |
-| 出库列表(桌/移) | `stock-out-list.html` | `stock_out_list_screen.dart` | ✅ 副标 + 共享 StatusPill | ✅ golden | ✅ golden |
-| 财务(桌/移) | `finance.html` | `finance_screen.dart` | ✅ **Phase2 重建**：时间范围 chips(真实过滤)+KPI 4 卡(stock summary 环比)+收支趋势柱状图(DsBarChart, /finance/trend)+应收应付汇总(/finance/summary)+流水表+往来抽屉+登记收支(补往来单位)；fidelity 3.0–4.2%≤8% | ✅ fidelity | ✅ fidelity |
-| 设备管理(桌/移) | `devices.html` | `device_management_screen.dart` | ✅ **Phase2 重建**：会话表(DsTable)+外设卡网格(custom_fields.peripherals 本地存档)+打印模板；fidelity 2.4–3.0%≤8% | ✅ fidelity | ✅ fidelity |
-| 系统设置(桌/移) | `settings.html` | `settings_screen.dart` | ✅ **Phase2 重建**：subnav 5 面板(门店/用户预览/编号规则/授权兑换券/偏好)；假「系统参数」已删；fidelity 1.7–2.3%≤8% | ✅ fidelity | ✅ fidelity |
-| 用户管理(桌/移) | `users.html` | `users_screen.dart`（`/settings/users`） | ✅ **Phase2 新独立页**：KPI 4 卡+搜索/角色筛选+rcard 弹窗，角色四级拉平；fidelity 1.3–2.1%≤8% | ✅ fidelity | ✅ fidelity |
-| 关于我们(桌/移) | `about.html` | `about_screen.dart` | ✅ **Phase2 重建**：Hero/产品信息/授权信息/更新日志 timeline(/public/release 同源)；fidelity 2.2–2.7%≤8% | ✅ fidelity | ✅ fidelity |
-| 登录 | `login.html` | `login_screen.dart` | ✅ **Phase2 重建（2026-07-03）**：两栏卡片(品牌渐变面板+表单)+右上主题切换器+记住我/忘记密码+lg 主按钮；fidelity 1.4–2.1%≤8%（已知差异见下） | ✅ fidelity | ✅ fidelity |
-| 注册新门店 | `register.html` | `register_screen.dart` | ✅ **Phase2 重建（2026-07-03）**：品牌面板三步时间线+grid2 表单+协议勾选；**暂不入 fidelity 闸**（少 门店编号/兑换券 两字段致结构错位，用户拍板先不加，见下） | ✅ golden ×3 | ✅ golden ×3 |
+**「真相源」列三态**（治理规则见 CLAUDE.md「设计真相源分层」）：
+`同步` = 注册于 `tools/screens.mjs`，桌面走 fidelity 像素闸（移动走 golden），整屏改版须原型先行；
+`快照` = 原型退役为历史参考，golden + 本表文字规格为准，小迭代不回填原型；
+`代码先行` = 无原型屏，golden 为唯一像素基准（清单见块 4 末尾小节）。
+
+| 屏 | 原型 | Flutter | 真相源 | a(基准) | b | c |
+|---|---|---|---|---|---|---|
+| 库存列表(桌面) | `inventory.html` | `inventory_list_screen.dart` | 同步 | ✅ KPI/徽章/列/副标/toolbar 已还原 | ✅ golden 自比 | ✅ golden 自比 |
+| 库存列表(移动) | `m-inventory.html` | 同上窄屏(卡片流) | 同步 | ✅ golden 自比 | ✅ golden 自比 | ✅ golden 自比 |
+| 往来单位(桌面) | `partners.html` | `partners_screen.dart` | 同步 | ✅ **Phase2 重建**：单表+类型 chips/应收应付列(finance summary)/详情抽屉/frow 弹窗；fidelity 2.5–3.5%≤8% | ✅ fidelity | ✅ fidelity |
+| 往来单位(移动) | `m-partners.html` | 同上窄屏(卡片流) | 同步 | ✅ golden 自比 | ✅ golden 自比 | ✅ golden 自比 |
+| 基础数据(桌面) | `products.html` | `products_screen.dart` | 同步 | ✅ **Phase2 重建**：.seg 5 tab(档案/介绍/系列/规格/仓库)+三套视图+编辑抽屉复用；fidelity 2.4–3.5%≤8%（已知差异见下） | ✅ fidelity | ✅ fidelity |
+| 基础数据(移动) | `m-products.html` | 同上窄屏(卡片流) | 同步 | ✅ golden 自比 | ✅ golden 自比 | ✅ golden 自比 |
+| 入库列表(桌/移) | `stock-in-list.html` | `stock_in_list_screen.dart` | 同步 | ✅ 副标 + 共享 StatusPill(草稿/待审/已审/已拒) | ✅ golden | ✅ golden |
+| 出库列表(桌/移) | `stock-out-list.html` | `stock_out_list_screen.dart` | 同步 | ✅ 副标 + 共享 StatusPill | ✅ golden | ✅ golden |
+| 财务(桌/移) | `finance.html` | `finance_screen.dart` | 同步 | ✅ **Phase2 重建**：时间范围 chips(真实过滤)+KPI 4 卡(stock summary 环比)+收支趋势柱状图(DsBarChart, /finance/trend)+应收应付汇总(/finance/summary)+流水表+往来抽屉+登记收支(补往来单位)；fidelity 3.0–4.2%≤8% | ✅ fidelity | ✅ fidelity |
+| 设备管理(桌/移) | `devices.html` | `device_management_screen.dart` | 同步 | ✅ **Phase2 重建**：会话表(DsTable)+外设卡网格(custom_fields.peripherals 本地存档)+打印模板；fidelity 2.4–3.0%≤8% | ✅ fidelity | ✅ fidelity |
+| 系统设置(桌/移) | `settings.html` | `settings_screen.dart` | 同步 | ✅ **Phase2 重建**：subnav 5 面板(门店/用户预览/编号规则/授权管理/偏好)；假「系统参数」已删；fidelity 1.7–2.3%≤8%；**授权管理面板为代码先行区**（见下小节） | ✅ fidelity | ✅ fidelity |
+| 用户管理(桌/移) | `users.html` | `users_screen.dart`（`/settings/users`） | 同步 | ✅ **Phase2 新独立页**：KPI 4 卡+搜索/角色筛选+rcard 弹窗，角色四级拉平；fidelity 1.3–2.1%≤8% | ✅ fidelity | ✅ fidelity |
+| 关于我们(桌/移) | `about.html` | `about_screen.dart` | 同步 | ✅ **Phase2 重建**：Hero/产品信息/更新日志 timeline(/public/release 同源)；fidelity 2.2–2.7%≤8%；授权信息卡 2026-07-04 迁至 设置→授权管理 | ✅ fidelity | ✅ fidelity |
+| 登录 | `login.html` | `login_screen.dart` | 同步 | ✅ **Phase2 重建（2026-07-03）**：两栏卡片(品牌渐变面板+表单)+右上主题切换器+记住我/忘记密码+lg 主按钮；fidelity 1.4–2.1%≤8%（已知差异见下） | ✅ fidelity | ✅ fidelity |
+| 注册新门店 | `register.html` | `register_screen.dart` | 快照 | ✅ **Phase2 重建（2026-07-03）**：品牌面板三步时间线+grid2 表单+协议勾选；**不入 fidelity 闸**（少 门店编号/兑换券 两字段致结构错位，用户拍板先不加，见下） | ✅ golden ×3 | ✅ golden ×3 |
+
+### 代码先行屏/面板（无原型，golden 为唯一像素基准）
+
+2026-07-04 用户拍板：以下功能为代码先行交付，**不反向补建原型**；后续小迭代只更 golden 与本表规格。
+
+| 屏/面板 | Flutter | 像素基准 | 说明 |
+|---|---|---|---|
+| 设置→授权管理面板（授权信息/在线购买续费/兑换券/降级规则 四卡） | `settings_screen.dart` `_LicensePanel` | settings golden ×3（仅锁面板 0 门店信息；子导航文字变更会入镜） | 2026-07 授权/购买迭代产物；原型 `settings.html` 仍是旧「授权兑换券」面板，视为历史快照 |
+| 购买卡（首月特惠/标准/高级 tab + 年付月付 + 支付轮询三态） | `purchase_card.dart` | 无独立 golden；改动后人工目检 + `flutter test` 回归 | 价格展示以 `license_plans.dart` 为源，实付以 pay 侧为准 |
+| 官网 定价区/checkout/license-result/profile/logout | `web/index.njk` `checkout.njk` 等 | 人工验收（web 无 golden 体系） | 原型 `pricing.html`/`checkout.html` 为当初设计参考，已漂移，视为历史快照 |

 > **共享组件杠杆**：`StatusBadge`（入/出库单据状态）一处升级两屏受益；`StatusPill`/`KpiCard` 现已被库存/往来/入出库/财务/设备/设置/关于复用——新屏直接套，无需重做徽章/卡片。

@@ -118,7 +136,7 @@ AppTokens 目前**仅颜色**。原型还驱动：
 | Web 营销站 | ✅ **已对齐品牌**：`web/assets/color.css` 的 `--brand-500:#2563AC` / `--accent` 酒红 / 灰阶 与原型令牌一致，roadmap「Web 镜像品牌」已满足 |

 ### 仍属「新建功能」（Phase 6，非重建既有屏）
-应用内注册 / 购买·套餐·下单（设计+前端壳，**支付不接**）——这是 net-new 功能开发，需各自 spec→设计→实现，不在「既有屏设计语言升级」范围内。
+~~应用内注册 / 购买·套餐·下单~~ → **2026-07 已交付**（支付宝支付打通，App 内购买卡 + 官网 checkout），按「代码先行」登记于块 4 末尾小节，不再走 design-first 补票。后续 net-new 功能仍各自 spec→设计→实现。

 > **Phase 2 已解决（2026-07-02）**：
 > - **往来单位**：应收/应付列改由 `GET /finance/summary`（按 partner 聚合未结清）供给，两 Tab 改回原型的类型 chips 单表；详情抽屉近期单据走 `finance/records?partner_id=`。
@@ -3,6 +3,9 @@
 // fidelity.mjs（自动 diff 闸）与 ds-compare.mjs（人工 montage 目检）共用此表，
 // 保证「每一屏 + 外壳都跟原型比」（规则 2）。屏随 Phase 1/2 照原型重建后逐个入册。
 //
+// 本表只登记 design/CONTRACT.md 块 4 中「真相源 = 同步」的屏，两处互为镜像；
+// 快照 / 代码先行 态屏不入册（分层规则见 CLAUDE.md「设计真相源分层」）。
+//
 // 字段：
 //   html      原型 html（仓库根相对路径）
 //   prefix    Flutter golden 文件前缀 → client/test/golden/goldens/<prefix>_<theme>.png