docs: 设计真相源铁律升级——原型与真实代码 100% 一致、前端改动原型先行

- CLAUDE.md:废除 2026-07-04「不追求全量同步」三态治理,改动必须先改原型、同提交落地;漂移即 bug
- CONTRACT.md:真相源口径同步;授权面板/购买卡移出代码先行清单(已回填);授权管理独立屏三 tab 台账登记

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
wangjia
2026-07-10 20:19:13 +08:00
parent 13b7274dbd
commit 1669ce6602
2 changed files with 21 additions and 23 deletions
+4 -7
View File
@@ -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 真相源)