diff --git a/CLAUDE.md b/CLAUDE.md index 1c82e9e..c1b828e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -255,17 +255,14 @@ cd client && flutter test - 使用 `dart:io` 的 `Platform` 类前,必须先检查 `kIsWeb`(`import 'package:flutter/foundation.dart'`) - Web 平台不支持 `dart:io`,直接使用会在 Web 构建时崩溃 -### 设计真相源分层(原型漂移治理,2026-07-04 拍板) +### 设计真相源分层(2026-07-10 铁律升级:原型与真实代码 100% 一致) -原型(`design/prototype/`)与真实页面**不追求全量永久同步**,按层分治: +**总铁律(2026-07-10 用户拍板,取代 2026-07-04「不追求全量同步」旧口径)**:原型(`design/prototype/`)与真实页面必须 **100% 一致**;**任何前端改动必须先改设计系统原型,才能改真实页面**(design-first 全量化)。原型先行评审,代码随后落地,**同一提交同时包含原型与代码改动**(先例:`2c25bbf`)。发现原型与真实不一致 = bug,先回填原型再继续开发。 - **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 为唯一像素基准。 +- **L2 屏级**(台账 = `design/CONTRACT.md` 块 4「真相源」列):目标态只有一个——`同步`(原型=真实,桌面+移动两端都要有原型)。旧三态中的 `快照`/`代码先行` 仅作历史遗留标记:**凡改到该屏,必须先把原型补齐到当前真实形态(升级回同步)再做新改动**,不再允许「只更 golden 不回填原型」。 - **L3 新屏/整屏改版**:design-first 不变(原型 → CONTRACT → 实现 → fidelity 验收),建成后入 `同步` 态。 -- **漂移体检**:不逐提交强制同步;大版本/整屏改版前跑 `node tools/fidelity.mjs`,按报告逐屏决定「重新对齐原型」或「降级快照」,结果回填 CONTRACT。 +- **漂移体检**:漂移即 bug。大版本前跑 `node tools/fidelity.mjs` 全量体检,超阈一律「重新对齐原型」(「降级快照」选项已废除),结果回填 CONTRACT。2026-07-10 已做一轮集中回填(库存/设置授权关于/日期组件三域)。 - **CI 闸**(`.gitea/workflows/checks.yml`,PR + main push 自动跑):① `check-ds.mjs` 原型 12 道;② `tools/check-l1-sync.mjs` L1 同源四道(tokens 快照逐字节 / icons 两端同集同内容 / 官网 token 值对齐原型主题 A / web 硬编码 hex,白名单 #fff、#1677ff,`ds-allow` 可豁免);③ `client/tool/check_ds_code.mjs` Flutter 颜色单源;④ codegen 新鲜度(regen→`dart format`→与入库产物零 diff)。本地可直接跑同名命令。 ### 表格与筛选/排序(ds 真相源) diff --git a/design/CONTRACT.md b/design/CONTRACT.md index 64039d0..71f3e1e 100644 --- a/design/CONTRACT.md +++ b/design/CONTRACT.md @@ -3,9 +3,10 @@ > design-distill 阶段 1 产物。token 走 codegen 单源(已在 P0 落地);还原由截图 diff 验收,不靠目测。 > 本文件是**执行真相源**(与 plan `.md` 同性质,机器/diff 引用),随逐屏推进增补。 > -> **真相源分层(2026-07-04 拍板,全文见 CLAUDE.md「设计真相源分层」)**:原型仅对 -> 设计系统层(tokens/atoms/icons)与「真相源=同步」态屏是唯一基准;`快照`/`代码先行` -> 态屏以 **golden + 本文件文字规格**为准,小迭代不回填原型。屏的状态登记在块 4「真相源」列。 +> **真相源铁律(2026-07-10 升级,全文见 CLAUDE.md「设计真相源分层」)**:原型与真实 +> 页面必须 **100% 一致**;任何前端改动**必须先改原型再改真实页面**,同一提交两者同落。 +> `快照`/`代码先行` 仅为历史遗留标记——凡改到该屏须先回填原型(升级回 `同步`)再动代码, +> 「小迭代不回填原型」旧口径作废。屏的状态登记在块 4「真相源」列。 ## 阶段 0 · 归一化产物(已就位) @@ -90,10 +91,9 @@ AppTokens 目前**仅颜色**。原型还驱动: ## 块 4 · 逐屏验收清单(每屏 × 主题;diff 闸) -**「真相源」列三态**(治理规则见 CLAUDE.md「设计真相源分层」): -`同步` = 注册于 `tools/screens.mjs`,桌面走 fidelity 像素闸(移动走 golden),整屏改版须原型先行; -`快照` = 原型退役为历史参考,golden + 本表文字规格为准,小迭代不回填原型; -`代码先行` = 无原型屏,golden 为唯一像素基准(清单见块 4 末尾小节)。 +**「真相源」列**(2026-07-10 铁律升级,治理规则见 CLAUDE.md「设计真相源分层」): +`同步` = 唯一目标态:原型=真实 100% 一致,注册于 `tools/screens.mjs`,桌面走 fidelity 像素闸(移动走 golden),**一切改动原型先行、同提交落地**; +`快照` / `代码先行` = 历史遗留标记(旧三态治理已废除):**凡改到该屏,必须先把原型补齐到当前真实形态、升级回 `同步`,再做新改动**;不再允许只更 golden 不回填原型。 | 屏 | 原型 | Flutter | 真相源 | a(基准) | b | c | |---|---|---|---|---|---|---| @@ -107,27 +107,28 @@ AppTokens 目前**仅颜色**。原型还驱动: | 出库列表(桌/移) | `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 | +| 系统设置(桌/移) | `settings.html` | `settings_screen.dart` | 同步 | ✅ **Phase2 重建**;假「系统参数」已删;fidelity 1.7–2.3%≤8%;**2026-07-10 授权管理面板迁出**(提升为独立一级屏 `license.html`),subnav 剩 门店信息/用户管理/偏好(真实端同步待实现) | ✅ 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 自比 | -| 授权管理(移动) | `m-license.html` | `license_screen.dart`(`/me/license`) | 同步 | ✅ 独立屏复用公共 `LicensePanel` 四卡(内容属代码先行区,见下小节) | ✅ golden(licPanel 随 settings) | ✅ 同左 | +| 授权管理(桌面) | `license.html` | 未实现(原 settings 授权 tab 提升独立屏,侧边栏「系统」组) | 同步(design-first) | 🟡 2026-07-10 原型建成评审中:**授权信息/在线购买续费/订单管理三 tab**(tab1=授权三格+兑换券+降级规则+iOS 客服卡;tab2=购买卡三阶段,iOS 合规态整 tab 隐藏;tab3=license_purchases 订单流水 KPI/筛选/表格/抽屉);实现后补 fidelity | — | — | +| 授权管理(移动) | `m-license.html` | `license_screen.dart`(`/me/license`) | 同步 | ✅ 原型已回填(三格横排/购买卡/iOS 双态);**2026-07-10 升级三 tab**(授权/购买续费/订单管理,订单 tab=KPI/筛选 sheet/订单卡流/详情 sheet),真实端 tab 化待实现 | ✅ golden(licPanel 随 settings) | ✅ 同左 | | 库存盘点(移动) | `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),录单仅桌面 | — | — | -### 代码先行屏/面板(无原型,golden 为唯一像素基准) +### 代码先行屏/面板(历史遗留清单,2026-07-10 铁律后逐步清零) -2026-07-04 用户拍板:以下功能为代码先行交付,**不反向补建原型**;后续小迭代只更 golden 与本表规格。 +~~2026-07-04「不反向补建原型」旧口径~~ **已被 2026-07-10 铁律取代**(原型=代码 100% 一致,改到即回填)。清单只剩未回填项: -| 屏/面板 | Flutter | 像素基准 | 说明 | +| 屏/面板 | Flutter | 像素基准 | 状态 | |---|---|---|---| -| 设置→授权管理面板(授权信息/在线购买续费/兑换券/降级规则 四卡) | `settings/license_panel.dart`(公共 `LicensePanel`,2026-07-04 自 settings_screen 抽取;桌面设置 tab 与移动 `/me/license` 独立屏共用) | 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` 为当初设计参考,已漂移,视为历史快照 | +| ~~设置→授权管理面板~~ | `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 落地**) @@ -146,7 +147,7 @@ AppTokens 目前**仅颜色**。原型还驱动: | Web 营销站 | ✅ **已对齐品牌**:`web/assets/color.css` 的 `--brand-500:#2563AC` / `--accent` 酒红 / 灰阶 与原型令牌一致,roadmap「Web 镜像品牌」已满足 | ### 仍属「新建功能」(Phase 6,非重建既有屏) -~~应用内注册 / 购买·套餐·下单~~ → **2026-07 已交付**(支付宝支付打通,App 内购买卡 + 官网 checkout),按「代码先行」登记于块 4 末尾小节,不再走 design-first 补票。后续 net-new 功能仍各自 spec→设计→实现。 +~~应用内注册 / 购买·套餐·下单~~ → **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=`。