jiu/design/CONTRACT.md

# 设计契约 — 岩美酒库 Flutter 还原（Phase 1 起：库存列表）

> design-distill 阶段 1 产物。像素以 `.superpowers/prototype/` 原型为**唯一基准**；
> token 走 codegen 单源（已在 P0 落地）；还原由截图 diff 验收，不靠目测。
> 本文件是**执行真相源**（与 plan `.md` 同性质，机器/diff 引用），随逐屏推进增补。

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

| 项 | 位置 | 说明 |
|---|---|---|
| token 单源 | `.superpowers/prototype/tokens.css` | 三主题 `[data-theme=a/b/c]`，已 snapshot 到 `client/lib/core/theme/token_source/tokens.css` |
| token codegen | `client/lib/core/theme/tool/gen_tokens.mjs` → `app_tokens.g.dart` | 单源生成，**禁手改**；`kTokensA/B/C` + `appTokensOf(key)` |
| 实现层 | `themes.dart`（buildTheme）+ `context_tokens.dart`（`context.tokens`） | AppTokens ThemeExtension 挂三 ThemeData |
| 原型清单 | `.superpowers/prototype/screens/*.html` | 桌面 + `m-*` 移动；viewport 桌面 1280×860 / 移动 390×844 |
| 设计铁律 | `.superpowers/prototype/index.html`（atoms 注册）+ `tools/check-ds.mjs` 闸 | 颜色只走 token；组件出自已登记 atoms |
| 验收工具 | `~/.claude/skills/design-distill/tools/{shoot-prototype,diff}.mjs` | prototype shoot 已验证三主题可出图 |

### 主题
- **a 经典蓝**（浅，**diff 基准**） · **b 琥珀**（深） · **c 酒窖**（暖浅）。结构/密度/字阶三套统一，只换颜色。

---

## 块 1 · token 映射表（prototype CSS var → Flutter AppTokens）

颜色字段 P0 已 1:1 落地（同名）。下表为 a 主题取值（来源 `tokens.css`，b/c 见 `app_tokens.g.dart`）：

| 原型 var | a 值 | AppTokens 字段 | 用途 |
|---|---|---|---|
| `--page` | `#E7EBF1` | `page` | 最外层底 |
| `--bg` | `#F5F7FA` | `bg` | 内容区底 |
| `--surface` | `#FFFFFF` | `surface` | 卡片/工具条/表格面 |
| `--border` / `--border-subtle` | `#DCE2EB` / `#ECEFF4` | `border` / `borderSubtle` | 描边 |
| `--text` / `--heading` / `--title` | `#232934` / `#1B2430` / `#1B2430` | `text` / `heading` / `title` | 正文/小标题/大标题 |
| `--muted` / `--faint` | `#6E7888` / `#99A3B3` | `muted` / `faint` | 次要/极弱文字 |
| `--primary` / `--primary-dark` / `--on-primary` | `#2563AC` / `#154072` / `#FFFFFF` | `primary` / `primaryDark` / `onPrimary` | 主操作 |
| `--brand400` / `--brand50` / `--accent` | `#4F86C6` / `#EEF4FB` / `#8B2331` | `brand400` / `brand50` / `accent` | 品牌/强调 |
| `--th-bg` / `--row-hover` / `--shadow` | `#F7F9FC` / `#EEF4FB` | `thBg` / `rowHover` / `shadow` | 表头/悬停/投影 |
| 顶栏 `--top-*` / 侧栏 `--side-*` / 用户菜单 `--menu-user-*` | — | `topBg…/sideBg…/menuUser*` | 外壳 chrome（P0 已迁移） |
| 状态徽章 `.badge.b-在售/预警/缺货` | success/warn/danger 系 | `success`+`okSoft` / `warn`+`warnBg` / `danger`+`dangerBg` | 状态色 |

### ⚠️ 缺口（鲁棒还原前需补）
AppTokens 目前**仅颜色**。原型还驱动：
- **字阶** `--fs-display 28 / h1 21 / h2 17 / title 15 / body 13 / sm 12 / xs 11`
- **圆角** `--r-sm 4 / md 6 / lg 10 / xl 14 / pill 999`
- **间距** kpis gap 14、toolbar pad 12/14、head mb 18、searchbox 240/180 等

→ 还原前需把字阶/圆角（必要时间距）补进 token 单源 + codegen（P1 第一步，**禁页面里写死 px**）。

---

## 块 2 · 组件清单（原型 atom → Flutter widget）

| 原型 atom | Flutter | props / 状态 | 现状 |
|---|---|---|---|
| `.top`（顶栏，品牌+门店+主题+通知+用户） | `shell/app_shell.dart` 顶栏 | active 项、主题选择器、通知红点、用户菜单 | 已有，需对齐新视觉 |
| `.side`（分组导航 单据/经营/系统 + 用户页脚） | `shell/app_shell.dart` 侧栏/Drawer | 分组、active、窄屏 Drawer | 已有，需分组化 |
| `.kpi` / `.kpi.alert.click`（KPI 卡 + 图标 + 同比） | **新** `widgets/kpi_card.dart` | icon/title/value/delta(up/down)/onTap/alert | **缺**，需新建 |
| `.toolbar` + `.searchbox` + `.chip`（筛选条） | `widgets/` 复用 + 列头 chip | 搜索/编码/状态 chip/重置 | 部分有 |
| `.table` + `.fh.filtered`（列头漏斗筛选） | `widgets/data_table_card.dart` + `FilterableColumnHeader` | 列头内嵌筛选、可隐藏列、`thBg` 表头 | 已有 |
| `.badge.b-*`（状态徽章 圆点+色） | `widgets/status_badge.dart` | 在售/预警/缺货 → ok/warn/danger | 已有，校色 |
| `.qty.low`（低库存染色 qty≤10） | data row 单元 | qty≤min_stock 染 danger | 需补 |
| `.pager` + `.pgsize-btn`（分页 + 每页条数） | `widgets/` 分页 | 页码/每页 10/20/50/100 | 需对齐 |
| `.ds-fab`（设计期返回球） | — | 仅原型，不还原 | 不实现 |

---

## 块 3 · 页面像素规格 — 库存列表（`screens/inventory.html`，桌面 1280×860）

数值取自原型源码（`inventory.html` 内联 + `atoms.css`/`tokens.css`），非目测。

- **head**：`align-items:flex-end; gap:14; margin-bottom:18`。`h1` `fs-h1(21)/700/title/letter .3px`；`.sub` `fs-sm(12)/muted`。`.actions` 右对齐 gap 10：`列设置`(ghost) `导出`(ghost) `新增入库`(primary)。
- **kpis**：`grid 4×1fr gap:14 margin-bottom:20`。每卡：左 `.ic`（圆角 `r-xl` 色块 info/ok/blue/alert）+ `.t`(fs-sm muted) + `.v`(大数值) + `.d`(同比 up=success▲ / down=danger▼)。第 4 卡 `alert.click` → 点击筛状态=缺货；第 1 卡 click → 清筛选。
- **toolbar**：`surface` 面、`border` 无下边、上圆角 `r-lg`、`pad 12/14 gap 10`。`searchbox` 240（商品名/拼音）；`searchbox.code` 180（商品编码）；`chip` 状态（`.on` 高亮 + 选中值）；右侧 `重置`(ghost sm)。
- **table**（`flush-top` 接 toolbar）：表头 `thBg`；列见块 4。行 `click` 进商品抽屉；`qty≤10` 染 `low`(danger)；`生产日期` 等宽 `text`、`入库时间` 等宽 `muted`；`status` → `.badge.b-{在售|预警|缺货}`；`act` 列 眼睛图标查看。空态 `.empty「没有匹配的商品 · 试试调整筛选或搜索」`。
- **pager**：`每页 [10▾] 条`（10/20/50/100 菜单） + `显示 a–b，共 N` + 页码 `‹ 1 2 … ›`，当前页 `.cur`。
- **移动**（`m-inventory.html`，390×844）：表格 → `MobileListCard` 卡片流（复用 `mobile_list_card.dart`）；筛选 pill 换行不横滚（原型已修）。

### 列定义（顺序 = 还原顺序）
`商品`(name+code 两行，fixed) · `规格` · `系列` · `批次号` · `库存`(num,≤10染色) · `成本价`(num) · `单价`(num) · `生产日期`(mono) · `入库时间`(mono,muted) · `供应商` · `状态`(filter) · `操作`(fixed)
> 真实后端字段对齐：name=品牌 / series=型号 / spec=版本 / code=商品编号 / batch_no / production_date；状态派生 qty vs `products.min_stock`（在售 / 预警 / 缺货）。快照列回退 `COALESCE(p.*, 快照)`。

---

## 块 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` | ✅ 副标/状态徽章/两行名称/响应式 toolbar | ✅ golden 自比 | ✅ golden 自比 |
| 往来单位(移动) | `m-partners.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` | ✅ KpiCard + 类型/结清 StatusPill + 离线条 token | ✅ golden | ✅ golden |
| 设备管理(桌/移) | `devices.html` | `device_management_screen.dart` | ✅ 在线/离线 StatusPill | ✅ golden | ✅ golden |
| 系统设置·参数 | `settings.html` | `settings_screen.dart` | ✅ 主题选择器三色板 + 角色 StatusPill | ✅ golden | ✅ golden |
| 关于我们(桌/移) | `about.html` | `about_screen.dart` | ✅ 正文已 token 化（golden 锁定） | ✅ golden | ✅ golden |

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

### 全量清扫收尾（其余屏状态）
| 屏 | 状态 |
|---|---|
| 登录 | ✅ 离线条 token 化 + 整屏 golden ×3 |
| 盘点 | ✅ 斑马行 token 化（表单屏，0 残留，无 golden：静态态不含明细） |
| 商品列表(基础数据) | ✅ 已 token 净（仅 default 金星 FFB300 为有意 accent）；原型 商品档案/香型/介绍 富数据重排**待后端** |
| 商品详情 | ✅ 主数据/价格/描述区 token 净；原型 3 KPI/仓库分布/流水 **待后端聚合** |
| 公开商品/门店页 | ✅ **有意独立设计**（warm-paper/酒红 bespoke 调色板 `_kPaper/_kBurgundy…`），顾客扫码固定品牌页，不参与 A/B/C 主题——保持现状 |
| Web 营销站 | ✅ **已对齐品牌**：`web/assets/color.css` 的 `--brand-500:#2563AC` / `--accent` 酒红 / 灰阶 与原型令牌一致，roadmap「Web 镜像品牌」已满足 |

### 仍属「新建功能」（Phase 6，非重建既有屏）
应用内注册 / 购买·套餐·下单（设计+前端壳，**支付不接**）——这是 net-new 功能开发，需各自 spec→设计→实现，不在「既有屏设计语言升级」范围内。

> **重要发现（原型 vs 现有数据）**：原型是「理想态富数据重设计」，多数屏的富数据区**当前后端不供给**，无法一次完整还原：
> - **商品列表**：8 tab vs 原型 5 tab；香型字典 / 商品介绍 缺后端 → 暂缓。
> - **商品详情**：原型 3 KPI（库存/货值/出库）+ 仓库分布 + 流水，`getDetail` 仅返回商品主数据 → 需聚合接口，暂缓。
> - **往来单位**：原型 应收/应付 列，Partner 模型无该字段 → 暂缓；类型 chips 暂保留为两 Tab。
>
> 故本阶段策略 = **「设计语言升级」**：把每屏视觉升到新 token/组件系（副标 / StatusPill / KpiCard〔数据够时〕/ 两行名称 / 响应式 toolbar / token 间距）+ 接 golden 闸；富数据区（应收应付 / 富 KPI / 仓库分布 / 流水 / tab 重排）等后端聚合就绪再做二期。库存屏因 KPI 可由已加载数据现算，是少数能一次到位的。

**验收法（HTML→Flutter 特例）**：HTML(Chromium) 与 Flutter 渲染器不同，**严格 0.1% pixelmatch 不适用跨渲染器**（见 design-distill `references/flutter-golden.md`）。本项目双闸：
1. **保真闸（人工目检）**：`node tools/ds-compare.mjs --html .superpowers/prototype/screens/<screen>.html --prefix <prefix>` → 截原型基准 + 与 Flutter golden 用 montage 并排 → `design/_compare/`。
2. **回归闸（自动）**：`test/golden/<screen>_golden_test.dart` 走 `pumpGolden`/`goldenAcrossThemes`（`test/support/golden_harness.dart`）出 A/B/C 三主题 golden，入库随 `flutter test` 同渲染器自比，抓串色/漏 token。
3. token 残留闸：`grep 0xFF…` 该屏为 0（颜色全走 `context.tokens`）。

> **基建就位**（本轮）：golden 骨架 + 整屏还原闸（库存列表已接）+ ds-compare 目检编排 + design-distill skill 补全（montage/flutter-golden/跨渲染器分流/多主题 codegen）。
> 后续屏（商品/单据/往来/财务/系统域）逐个追加块 3 规格 + 块 4 行 + 一份 `*_golden_test.dart`，一屏一闭环，禁积压。