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

> design-distill 阶段 1 产物。token 走 codegen 单源（已在 P0 落地）；还原由截图 diff 验收，不靠目测。
> 本文件是**执行真相源**（与 plan `.md` 同性质，机器/diff 引用），随逐屏推进增补。
>
> **真相源铁律（2026-07-10 升级，全文见 CLAUDE.md「设计真相源分层」）**：原型与真实
> 页面必须 **100% 一致**；任何前端改动**必须先改原型再改真实页面**，同一提交两者同落。
> `快照`/`代码先行` 仅为历史遗留标记——凡改到该屏须先回填原型（升级回 `同步`）再动代码，
> 「小迭代不回填原型」旧口径作废。屏的状态登记在块 4「真相源」列。

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

| 项 | 位置 | 说明 |
|---|---|---|
| token 单源 | `design/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 |
| 原型清单 | `design/prototype/screens/*.html` | 桌面 + `m-*` 移动；viewport 桌面 1280×860 / 移动 390×844 |
| 设计铁律 | `design/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`（设计期返回球） | — | 仅原型，不还原 | 不实现 |
| `.btn.lg`（登录/注册主按钮 h44/pad22/fs14） | `DsButton(large:true)` | 全宽居中 | 已有 |
| `.check` / `.agree`（自绘复选 18px+勾） | `DsCheck`（ds_atoms） | value/onChanged/Widget label/alignTop | 已有 |
| `.theme-switch`（auth 页右上 A/B/C 圆钮） | `ThemePickerPill(onSurface:true)`（表单面板右上） | 2026-07-03 用户拍板：不用原型 A/B/C，复用主界面小衣服 pill 浅色变体 | 已有 |
| `.auth` + `.brand`（两栏卡片+品牌渐变面板） | `AuthPageScaffold`/`AuthBrandPanel` | 栏宽/窄屏折叠 | 已有 |

---

## 块 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 闸）

**「真相源」列**（2026-07-10 铁律升级，治理规则见 CLAUDE.md「设计真相源分层」）：
`同步` = 唯一目标态：原型=真实 100% 一致，注册于 `tools/screens.mjs`，桌面走 fidelity 像素闸（移动走 golden），**一切改动原型先行、同提交落地**；
`快照` / `代码先行` = 历史遗留标记（旧三态治理已废除）：**凡改到该屏，必须先把原型补齐到当前真实形态、升级回 `同步`，再做新改动**；不再允许只更 golden 不回填原型。

| 屏 | 原型 | Flutter | 真相源 | a(基准) | b | c |
|---|---|---|---|---|---|---|
| 库存列表(桌面) | `inventory.html` | `inventory_list_screen.dart` | 同步 | ✅ KPI/徽章/列/副标/toolbar 已还原；**2026-07-14 六项优化**：商品抽屉补供应商+批次号行、列表批次号↔生产日期列位对调（原型同步）；fidelity a 4.325% / b 3.313% / c 4.724%（均 ≤ 阈值 7%） | ✅ golden 自比 | ✅ golden 自比 |
| 库存列表(移动) | `m-inventory.html` | 同上窄屏(卡片流) | 同步 | ✅ golden 自比（同上抽屉+列位改动，`inventory_list_mobile_golden_test.dart` 全绿） | ✅ 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(草稿/待审/已审/已拒)；**2026-07-14 六项优化**：详情抽屉明细增加生产日期+批次号两列（抽屉加宽 660）、状态筛选改多选 chip 且默认勾选「草稿+待审核」、新建单默认填充默认仓库（原型 stock-in-list.html/stock-in.js 同步）；fidelity a 3.323% / b 2.319% / c 3.633%（均 ≤ 阈值 6%），移动 golden 自比全绿 | ✅ golden | ✅ golden |
| 出库列表(桌/移) | `stock-out-list.html` | `stock_out_list_screen.dart` | 同步 | ✅ 副标 + 共享 StatusPill；**2026-07-14 六项优化**：详情抽屉明细同增生产日期+批次号两列（抽屉 660）、状态筛选改多选 chip 且默认「草稿+待审核」、新建单默认填充默认仓库（原型 stock-out-list.html 同步）；fidelity a 3.228% / b 2.217% / c 3.538%（均 ≤ 阈值 6%），移动 golden 自比全绿 | ✅ golden | ✅ golden |
| 财务(桌/移) | `finance.html` | `finance_screen.dart` | 同步 | ✅ **Phase2 重建**：时间范围 chips(真实过滤)+KPI 4 卡(stock summary 环比)+收支趋势柱状图(DsBarChart, /finance/trend)+应收应付汇总(/finance/summary)+流水表+往来抽屉+登记收支(补往来单位)；**2026-07-14 六项优化**：流水表筛选新增「往来单位」下拉、时间范围统一改用通用自定义时间组件（原型 finance.html/m-finance.html 同步）；fidelity a 4.036% / b 3.131% / c 4.340%（均 ≤ 阈值 6%），移动 golden 自比全绿；**2026-07-14 追加**：应收/应付汇总卡头部新增「往来单位」搜索——本地即时过滤（`/finance/summary` 全量非分页，搜索口径=显示口径），桌面 `DsSearchBox`（`_secHead` trailing）/移动 应收·应付 分段头 `MSearchRow`（流水分段沿用既有 chip→sheet 单选，不重复），原型 finance.html `.sum-search` / m-finance.html 应收应付分段 `.m-search` 同步，finance 相关 6 个整屏 golden + m_finance 3 个 golden 已按新布局 `--update-goldens`；**2026-07-14 验收反馈调整**：桌面「往来单位」搜索由卡标题行 `DsSearchBox` 挪进汇总表表头「往来单位」列头右侧，改为下拉单选 `ComboSearchField`（同 `_flowTable` 往来单位筛选控件，选中精确匹配一行/× 清除恢复全量，候选=当前汇总行往来单位）；原型 `.sec-head .sum-search` 移除，改 `.th-party-wrap` 内嵌 `.combo` + `openSearchMenu` 弹层；移动端未动。desktop `finance` golden 3 主题已 `--update-goldens`（3.11% 差异，目检确认新版式），`finance_mobile`/`m_finance` 无变化、原样通过；**2026-07-14 验收反馈2**（实机截图 3 处细节）：①下拉候选由「仅当前汇总行往来单位」改为「全量往来单位」（`allPartnersProvider`，与 `_flowTable` toolbar 同源），选中一个汇总没有余额行的单位时走既有「没有匹配的往来单位」空态；②占位符叠词修复——`ComboSearchField.hint` 由 `'搜索往来单位'` 改 `'往来单位'`（内部会自动拼「搜索」前缀），弹层内搜索框恢复正常显示「搜索往来单位…」，收起态触发器文案对齐 `_flowTable` 写法同为「往来单位」；③表头行下拉垂直位置——`header` 外包 `SizedBox(height: 34)` 显式钉住 Row 高度消除潜在字体行高偏差，不改表头行 pad 11/14 既有行高口径。原型 finance.html 同步：`ALL_PARTNERS`（`SUMMARY` 全部单位 + 1 个无余额行的「鼎丰超市」演示空态）替换 `sumPartyId`/`SUMMARY` 候选、`#sumPartyInput` 收起态 placeholder 改「往来单位」；`.th-party-wrap{align-items:center}` + 浏览器 `th` 默认 `vertical-align:middle` 本就居中，未改 CSS。desktop `finance` golden 3 主题已 `--update-goldens`（0.04% 差异，目检确认新候选/占位文案，表头对齐无回归），`finance_mobile`/`m_finance` 无变化、原样通过 | ✅ 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 重建**；假「系统参数」已删；fidelity 1.7–2.3%≤8%；**2026-07-10 授权管理面板迁出**（提升为独立一级屏 `license.html`），subnav 剩 门店信息/用户管理/偏好——**真实端已同步完成**（`settings_screen.dart` 子导航同步摘除授权管理项，golden 已按新态重生成，见授权管理两行） | ✅ 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 |
| 移动壳 | `mobile-shell.js`（m-top/m-tabbar） | `app_shell.dart` 窄屏 + `m_tab_bar.dart` | 同步 | ✅ **2026-07-04 移动壳落地**：底部 5 tab(库存/入库/出库/财务/我的)+顶栏(标题/主题/铃/头像)+二级屏返回箭头；golden `app_shell_mobile` ×3 | ✅ golden 自比 | ✅ golden 自比 |
| 我的(移动) | `m-me.html` | `me_screen.dart`（`/me`） | 同步 | ✅ 用户头卡+经营管理/系统 hub+退出登录确认 sheet；golden `me` ×3 | ✅ golden 自比 | ✅ golden 自比 |
| 授权管理(桌面) | `license.html` | `screens/license/license_screen.dart`（`/license`，侧边栏「系统」组） | 同步 | ✅ 2026-07-10 独立一级屏三 tab 落地：tab1=授权三格+兑换券+降级规则+iOS 客服卡（`LicensePanel`）；tab2=`PurchaseCard`（iOS 合规态/非管理员分别隐藏 tab、降级为联系管理员提示）；tab3=`LicenseOrdersTab`（KPI 4 卡+套餐/状态/时间筛选+DsTable+详情抽屉，仅管理员可见）；fidelity 2.2–4.0%≤8% | ✅ fidelity | — |
| 授权管理(移动) | `m-license.html` | 同上 Widget（`/me/license`，「我的」系统组） | 同步 | ✅ 同桌面三 tab 化（通栏 DsSeg + MCard 订单流 + 详情 sheet），与桌面共用 `LicenseScreen`；golden `license_mobile` ×3 | ✅ golden 自比 | ✅ 同左 |
| 库存盘点(移动) | `m-inventory-check.html` | `inventory_check_screen.dart` 窄屏 | 同步 | ✅ 卡片流+详情 sheet+底部操作条（原型为桩，按桩粒度）；golden `m_inventory_check` ×3 | ✅ golden 自比 | ✅ golden 自比 |
| 通知/通知详情(移动) | `m-notifications.html` `m-notification.html` | —（二期未落地） | 二期 | 后端无通知模块；铃铛保持「暂无通知」 | — | — |
| 建单表单(移动) | `m-stock-in.html` `m-stock-out.html` | —（拍板不落地） | 不落地 | 2026-07-04 拍板：移动端无建单入口（列表无 +/FAB），录单仅桌面 | — | — |

### 代码先行屏/面板（历史遗留清单，2026-07-10 铁律后逐步清零）

~~2026-07-04「不反向补建原型」旧口径~~ **已被 2026-07-10 铁律取代**（原型=代码 100% 一致，改到即回填）。清单只剩未回填项：

| 屏/面板 | Flutter | 像素基准 | 状态 |
|---|---|---|---|
| ~~设置→授权管理面板~~ | `settings/license_panel.dart` | settings golden ×3 | ✅ **2026-07-10 已回填原型**（`settings.html` 授权面板重建 + `m-license.html`），移出本清单 |
| ~~购买卡~~ | `purchase_card.dart` | 无独立 golden；人工目检 + `flutter test` | ✅ **2026-07-10 已回填原型**（settings.html/m-license.html buyCard 三阶段同构）；pay v2 改造按铁律原型先行 |
| 官网 定价区/checkout/license-result/profile/logout | `web/index.njk` `checkout.njk` 等 | 人工验收（web 无 golden 体系） | 🟡 未回填：原型 `pricing.html`/`checkout.html` 仍为历史快照，改到时先对齐原型 |

### 移动愿景原型（m-*，2026-07-04 对齐轮 → **同日 Flutter 落地**）

`m-*` 屏是移动端目标设计（底部 tab + 「我的」hub 导航）。**2026-07-04 Flutter 已整体落地**：窄屏 Drawer 汉堡导航退役，改为底部 5 tab（库存/入库/出库/财务/我的）+ 「我的」hub 聚合二级屏（往来/基础数据/盘点/用户/授权/设备/设置/关于），二级屏隐藏 tabbar + 顶栏返回；一切弹层（详情/筛选/详搜/退单/确认定价/表单）窄屏统一走底部 sheet（`showMSheet`）；列表 = 2×2 可点 KPI（`MKpiGrid`）+ 搜索行（`MSearchRow`）+ 图标徽章卡片流（`status_icon_map` 转录原型 BADGE_ICON 28 词）。移动屏验收 = 各自 `*_mobile`/`m_*` golden ×3 主题（390×844@2x），**不入 fidelity 像素闸**（跨渲染器移动字体度量漂移大）；桌面形态全程零改动。移动端**不提供建单入口**（无 + / FAB）、**无打印动作**。

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

### 全量清扫收尾（其余屏状态）
| 屏 | 状态 |
|---|---|
| 登录/注册 | ✅ **Phase2 已照原型重建**（login.html/register.html，见上验收表） |
| 盘点 | ✅ 斑马行 token 化（表单屏，0 残留，无 golden：静态态不含明细） |
| 商品列表(基础数据) | ✅ **Phase2 已照原型重建**（.seg 5 tab，见上验收表）；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，非重建既有屏）
~~应用内注册 / 购买·套餐·下单~~ → **2026-07 已交付**（支付宝支付打通，App 内购买卡 + 官网 checkout）；~~按「代码先行」登记不补票~~ → **2026-07-10 已按新铁律回填原型**（settings.html/m-license.html 购买卡；官网 checkout 原型仍待回填）。后续 net-new 功能一律 design-first（spec→原型→实现）。

> **Phase 2 已解决（2026-07-02）**：
> - **往来单位**：应收/应付列改由 `GET /finance/summary`（按 partner 聚合未结清）供给，两 Tab 改回原型的类型 chips 单表；详情抽屉近期单据走 `finance/records?partner_id=`。
> - **基础数据**：tab 集合按用户口径收敛为 5 个 **档案/介绍/系列/规格/仓库**（商品名称并入档案；产地/保质期/储存/香型撤管理入口，后端字典保留）。
> - **商品详情**：`getDetail` 聚合已就绪（3 KPI/仓库分布/流水，见 product_detail golden）。
>
> **基础数据屏已知差异（数据/模型驱动，fidelity 残差包含它们）**：
> - 档案无「分类」列、无香型筛选 chips（香型弃用）；无「状态(在售/停用)」列（products 无 status 字段，用户拍板不加）。
> - 档案无「新增商品」按钮（product=序列号铁律：入库每行自动建档）。
> - 字典视图无「关联商品」计数列（无后端计数源）；seg 第 5 tab 香型→仓库。
> - 档案 pager 用带控件分页（真实数据量大）；介绍/字典/仓库 pager 仅文案（对齐原型）。
>
> **库存屏已知差异（2026-07-02 用户口径调整）**：
> - 搜索合一：原型 名称/拼音(240)+编码(180) 两框 → 一框「商品名 / 拼音 / 编码」（后端 keyword 本就四列 LIKE），回车触发（原型 oninput 即搜）。
> - 工具栏「状态」筛选 chip 删除（用户裁定无用）；状态列 + 列头漏斗 + KPI 缺货点击筛选保留。
> - reload 不再白屏：skipLoadingOnReload + DsLoadingScrim 半透明遮罩（与入库/出库屏一致）。
>
> **商品编辑抽屉（2026-07-03 用户增强）**：
> - 「从介绍库选择」由原型 .pe-pick 普通菜单升级为**搜索下拉**（GridComboCell 表单形态，供应商选择器同款：弹层搜索 + ✓ 选中 + 计数）；收起态外观与原型一致。
>
> **出入库列表补闸 + 单元格对齐（2026-07-03）**：
> - stock-in/stock-out 此前**漏注册 fidelity**（偏差长期未被闸住）→ 桌面 golden 改外壳挂载并入册（阈值 9%，实测 3.0–5.2%）。
> - 单元格对齐原型：单号 = .pcode（faint+mono，弃蓝色链接样式）；金额 = ¥+千分位无小数（td.num mono）；审核员空值 = faint「—」。
> - 全局 InputDecorationTheme 渗漏修复：内嵌裸 TextField 的组合控件显式屏蔽主题边框（搜索框双层框根因）。旧 DataTableCard 组件已无引用，删除。
>
> **登录/注册屏重建（2026-07-03）**：
> - **主题切换（用户拍板）**：原型右上角 A/B/C 圆钮不用，改放主界面同款小衣服 `ThemePickerPill(onSurface:true)` 于表单面板右上角（宽窄屏都落白底）。
> - **登录已知差异（功能位保留）**：门店编号/账号历史下拉（后缀箭头）+ 密码可见切换（后缀眼睛）为原型没有的功能件；密码空值显示 hint（原型演示值 8 dots）；服务器错误条/离线条/授权锁定引导卡在按钮上方按需出现。「记住我」= 记录并预填最近登录账号（关闭则不记录），「忘记密码」= toast 提示联系管理员。
> - **注册已知差异（用户拍板 2026-07-03：先不加）**：无「门店编号（留空自动分配）」「授权兑换券」两字段——后端 RegisterInput 暂不支持；门店地址必填（后端 binding:required，原型选填）；密码下限 6 位（后端 min=6，原型文案 8 位）。表单因此少两行 → **fidelity 暂撤册**（screens.mjs 有注释存根），golden ×3 锁回归；后端补 shop_code/voucher 后恢复入闸。
> - 校验口径 = 原型：提交时逐项 toast（DsToast），无内联错误文案，38 高盒式字段不抖动。
>
> **出入库定价重设计（2026-07-03 用户拍板，plan 批准）**：
> - 出库详情明细：单价/金额 两列 → **成本价/售价/利润** 三列（管理员）；operator 见 售价/小计。合计区双行：合计金额（总售价）+ 合计利润（管理员）。
> - 出库建单：金额列（=售价×数量，qty=1 与售价重复）→ **利润**列（实时，负数 danger）；商品名称下带编码（字体同系列列）；底栏加合计利润；进价/利润列仅管理员。
> - 入库建单列头：进价 → **进价（单瓶）**、售价 → **参考售价**、金额 → **总进价**。
> - 原型已同步（stock-in.js 双模式 + stock-out-list.html 详情抽屉），与真实页一致。
> - 底层字段消歧：unit_price/total_price/total_amount → cost_price/cost_amount/cost_total(入)/sale_amount/sale_total/profit_total(出)，见 CLAUDE.md「定价字段口径」。
>
> **全局对话框统一（2026-07-03 用户要求遍历）**：
> - 主题层钉真相源：`DialogTheme`（surface/r-xl/边框/标题 fs-h2·700）、全局 `InputDecorationTheme`（.input 盒式，禁下划线兜底）、Elevated/FilledButton 主题（.btn.primary 规格）。
> - 全部 AlertDialog 动作行换 `DsButton`（取消=ghost / 确认=primary / 删除·拒绝=danger / 通过=success / 撤回·结清=accent，`DsBtnVariant` 扩 success/accent）；表单字段改 `DsField`（label 在上）+ 盒式输入（添加设备等）。
> - 例外保留：`public_product_screen`（对外扫码页，自有品牌配色非 ds 体系）；表格行内链接式 TextButton（备注/打标签/测试打印）非对话框不在此列。
>
> **出入库列表 KPI 口径（2026-07-03 用户拍板）**：
> - 原型「本月入库/出库笔数·金额 + 较上月」自然月口径月初必然全 0（7-03 实测 0/¥0/▼100% 观感如坏数据）→ 卡片与头部小字改「近30天」滚动窗（`summary?window=rolling30`，对照前一个 30 天）；财务屏仍用自然月口径（原型「本月销售/采购额」文案不变），同一接口两种 window。
>
> **财务屏已知差异（2026-07-02 Phase2 第 9 屏）**：
> - KPI3/4 delta：原型「逾期 ¥9.2万 / 本周到期 ¥4.8万」无到期日数据源 → 改「未结清 N 笔 / 按到期及时结清」。
> - KPI 应收/应付值 = `/finance/summary` 实算求和（原型硬编码 ¥48.6万 与其汇总表行自身不一致）。
> - 流水类型 chips 原型 3 个扩到 5（含应收/应付），并追加 状态/操作 两列（结清能力不回退）；关联单号列显示 `单据类型 #id`（原型 SK/FK 单号字符串无对应模型）。
> - 时间范围 chips 真实过滤流水（原型只改文案）；趋势柱最高 140px（原型 ~157，标签悬浮方式不同）。
>
> **六项前端优化收尾（2026-07-14，T1-T6 合入 + T7 台账回填）**：
> - T1 库存商品抽屉补供应商+批次号信息行（`inventory.html`/`m-inventory.html`/`product-editor.js` 同步）。
> - T2 库存列表桌面批次号与生产日期列位对调（`inventory.html` 同步）。
> - T3 出入库单详情抽屉明细增加生产日期+批次号双行列、抽屉加宽至 660（`stock-in-list.html`/`stock-out-list.html`/`m-stock-*-list.html` 同步）。
> - T4 出入库列表状态筛选由单选改多选 chip，默认勾选「草稿+待审核」（此前默认全量，行为变化见手册核查结论）。
> - T5 新建入库/出库单默认填充门店默认仓库（`stock-in.js` 同步）。
> - T6 财务筛选新增「往来单位」下拉、时间范围改用统一自定义时间组件（`finance.html`/`m-finance.html`/`atoms.css` 同步）。
> - T7 体检结论：`node tools/fidelity.mjs inventory stock-in stock-out finance` 12 屏×主题全绿（数值见块 4 对应行，均 ≤ 各屏阈值，阈值本身 ≤8% 铁律线）；移动侧对应 8 个 golden 自比测试文件全绿；手册核查 `web/content/docs.md`/`docs/manual/user-manual.html` 均未见与「出入库默认显示/状态筛选」「财务筛选」冲突的既有描述，按红线不新增描述，本轮手册未改动。
>
> **设备/设置/用户/关于 已知差异（2026-07-02 Phase2 第 6-8 屏）**：
> - 设备：外设设备=登记式本地存档（店级 `custom_fields.peripherals`，无真实连接协议），测试打印/配置/模板预览为占位 toast；打印模板静态两卡。
> - 设置：子导航比原型多「编号规则」（真实功能保留）；门店卡多 Logo 行；授权卡保留降级说明；偏好即时生效无「保存」按钮；原型「系统参数」假设置删除。
> - 用户：独立页挂 `/settings/users`（原型导航同样高亮系统设置）；角色四级（后端为准），原型 settings 预览三级口径弃用；授权数据 settings/about 同源 licenseProvider（原型两处数字不一致）。
> - 关于：旧版 帮助文档/扫码防伪/系统信息 卡删除，构建号并入版本 cell；更新日志走 `/public/release`（与官网时间线同源），接口不可达回退只显当前版本。

**验收法（HTML→Flutter 特例）**：HTML(Chromium) 与 Flutter 渲染器不同，**严格 0.1% pixelmatch 不适用跨渲染器**（见 design-distill `references/flutter-golden.md`）。本项目双闸：
1. **保真闸（人工目检）**：`node tools/ds-compare.mjs --html design/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`，一屏一闭环，禁积压。