From e0fdb8c12f46d6e423e5e9e862705129d92e53f0 Mon Sep 17 00:00:00 2001 From: wangjia <809946525@qq.com> Date: Sat, 4 Jul 2026 06:56:17 +0800 Subject: [PATCH] =?UTF-8?q?docs(design):=20=E8=AE=BE=E8=AE=A1=E7=9C=9F?= =?UTF-8?q?=E7=9B=B8=E6=BA=90=E5=88=86=E5=B1=82=E6=B2=BB=E7=90=86=E8=90=BD?= =?UTF-8?q?=E5=9C=B0=EF=BC=88=E5=8E=9F=E5=9E=8B=E6=BC=82=E7=A7=BB=E6=8B=8D?= =?UTF-8?q?=E6=9D=BF=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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 Claude-Session: https://claude.ai/code/session_01JJ1g8XV1YhhmHRzhwWEW7o --- CLAUDE.md | 12 ++++++++++ design/CONTRACT.md | 58 ++++++++++++++++++++++++++++++---------------- tools/screens.mjs | 3 +++ 3 files changed, 53 insertions(+), 20 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 6bea0d4..c1157f5 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -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` diff --git a/design/CONTRACT.md b/design/CONTRACT.md index d7423ae..304c4f3 100644 --- a/design/CONTRACT.md +++ b/design/CONTRACT.md @@ -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=`。 diff --git a/tools/screens.mjs b/tools/screens.mjs index d852e3a..afefae8 100644 --- a/tools/screens.mjs +++ b/tools/screens.mjs @@ -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/_.png