# 02 · 流程模型

> 9 个阶段的完整定义。这是所有模式共享的**模型层**；
> 各模式的差异体现在提示词术语、映射参照与能力包上（WPF 模式见 WPF-README.md）。

---

## 1. 总览

| # | 阶段 | 产物 | 出口条件（怎么算做完） | 工具链 |
|---|---|---|---|---|
| 0 | 功能蓝图 | 页面清单 + Mermaid 页面流转图 + 独立 `flow-*.html` | 页面无遗漏、主操作路径明确、流程图可独立浏览 | — |
| 1 | 风格探索 | 2-3 个视觉方向 + 选定结果 | 人选定一个方向（配色/字体/风格参数） | — |
| 2 | 定令牌 | `tokens.css` + `token-preview.html` | 每个值都有语义化名字；0 魔法数字；关键令牌可实时预览 | — |
| 3 | 搭组件库 | `app.css` | 每个组件有全部 8 种状态 | — |
| 4 | 画主界面 | `fig1-*.html` | 信息分区 / 主操作路径说清 | — |
| 5 | 画规格页 | `fig2..N-*.html` | 交互入口与非默认状态都有定义 | — |
| 6 | 体检出图 | 体检报告 + PNG | 三类问题为 `[]`；长文案撞过墙 | check-layout.js / export-png.py |
| 7 | 写映射 | `wpf-mapping.md` | "找不到落点"清单为空或已确认 | — |
| 8 | 交接开发 | 项目级提示词 + 实现顺序 | 设计资产完备，可开始编码 | — |

**每个阶段的通用交互约定**：

- 开始前：AI 检查"依赖"中的前置产物是否已存在；缺则先回补
- 结束时：AI 停下来，把产出摆给人看，等人说"行"或提修改
- 回退时：按"回退影响面"提示需要复查的下游文件

---

## 2. 阶段定义

### 阶段 0 · 功能蓝图（微立项）

| 字段 | 内容 |
|---|---|
| 目标 | 把模糊的想法变成结构化的功能清单和页面流转图；同时完成“微立项”——用最小代价明确目标/边界/角色/验收，确保后续灵感→UI 的转化不跑偏 |
| 产物 | （1）项目定位（一句话说清“这是什么”和“这不是什么”）（2）角色与主操作路径 （3）编号化功能清单 （4）页面/窗口清单 （5）Mermaid 流转图的独立 HTML 文档（如 `design/flow-页面流转.html`）（6）里程碑骨架 （7）裁定记录（初始为空） |
| 出口条件 | 目标/非目标明确；每个页面有明确职责；主操作路径清晰；Mermaid 流转图已有独立 HTML 文档；常见遗漏被检查过 |
| 依赖 | 无（流程起点） |
| 规则 | 先列全再排序；不纠结控件细节；暂不考虑技术限制；凡输出 Mermaid 流程图，必须同步落成独立 HTML 文档，不能只写在 Markdown 设计文档里；**微立项 ≠ 完整项目章程：不做排期/预算/团队分工，只做到“UI 设计不跑偏”所需的最小立项量** |
| AI 引导要点 | 1. 先问清“这是什么工具、给谁用、解决什么问题、不做什么” 2. 问清核心角色和典型操作路径 3. 引导列全功能点（编号化） 4. 从功能清单推导页面清单 5. 输出 Mermaid 流转图并同步生成独立 HTML 流程图文档 6. 问清里程碑骨架 7. 主动检查遗漏项 |
| 常见坑 | 一开始就纠结控件细节；把视觉问题混进来；页面职责重叠；**跳过微立项直接画页面（后续必然返工）**；**微立项做得太重（变成完整项目章程，偏离 UI 设计焦点）** |
| 回退影响面 | 改页面清单 → 下游所有阶段受影响（尽早确认） |
| 人确认点 | 目标/非目标认同？页面清单没有多余、没有遗漏？主操作路径认同？ |

提示词模板（骨架）：

```
作为 UI 设计引导师，请帮我完成应用设计的第一步。

【我的想法】我想做一个 xxx 工具，核心功能：
1. …
2. …

请帮我：
1. 列出这个应用需要的所有页面/视图
2. 每个页面的核心功能点
3. 用户的典型操作路径
4. 用 Mermaid 画出页面跳转流程图，并同步创建独立 HTML 文档（如 design/flow-页面流转.html）
```

---

### 阶段 1 · 风格探索

| 字段 | 内容 |
|---|---|
| 目标 | 通过参考图与 AI 生成，确定视觉风格方向 |
| 产物 | 2-3 个视觉方向描述（配色/字体/圆角/间距/风格关键词）+ 人选定结果 |
| 出口条件 | 人明确选定一个方向，并记录选定理由 |
| 依赖 | 阶段 0 的页面清单（AI 需知道有哪些界面要覆盖） |
| 规则 | 参考图 ≤3 张；先出多方向再选，不要一次只出一个方案；用"情绪词"而非技术词描述 |
| AI 引导要点 | 1. 请用户提供参考图/参考产品/配色网站锚点 2. 用情绪词问清期望感觉 3. 生成 2-3 个完整方向（各含配色/字体/风格参数 + 一张 HTML 演示） 4. 用户选定后，把方向固化为书面描述 |
| 参考来源 | 用户收集的应用截图；开源配色体系（如 Tailwind 色板、Radix Colors、Open Color）；优秀产品官网 |
| 常见坑 | 跳过探索直接微调（"把蓝色换成绿色"）会错过更好的方向；参考图给太多会混淆 AI |
| 回退影响面 | 改选定方向 → 下游全部（令牌/组件/稿件）受影响（这是最"上游"的视觉决策） |
| 人确认点 | 三个方向并排看过？选定理由是明确的？ |

---

### 阶段 2 · 定令牌

| 字段 | 内容 |
|---|---|
| 目标 | 把选定风格固化为唯一取值来源（设计令牌） |
| 产物 | `tokens.css`（颜色/圆角/间距/字号/尺寸基准）+ `token-preview.html`（直接引用令牌的实时预览页） |
| 出口条件 | 每个值都有语义化名字；后续任何文件不许出现魔法数字和手写色值；`token-preview.html` 可打开并能实时预览主色 / radius / 行高变化 |
| 依赖 | 阶段 1 的选定方向 |
| 规则 | 令牌与组件必须分文件（换皮只改令牌）；名字描述"用途"而非"长相"（用 `--color-danger` 而非 `--color-red`）；生成令牌时必须同时生成 `token-preview.html`，预览页只引用 `tokens.css`，不复制第二份令牌值 |
| AI 引导要点 | 1. 把选定方向交给 AI，要求输出令牌文件 2. 要求按类别分组、每个变量带用途注释 3. 同步生成 `token-preview.html`，提供主色、radius、行高等控件做实时预览 4. 与用户逐组过一遍（色彩组/间距组…） |
| 常见坑 | 令牌数量过多或过少；名字无语义；与组件样式混在一个文件；只给 `tokens.css` 没有预览页，导致关键视觉参数只能靠想象 |
| 回退影响面 | 改 tokens.css → `app.css` 需核对引用、所有 `fig*.html` 需复查视觉 |
| 人确认点 | 颜色/尺寸过目一遍，视觉方向确认无误 |
| WPF 模式附加 | 同步产出 WPF ResourceDictionary 版本（SolidColorBrush / CornerRadius / Thickness），但预览页仍以 `tokens.css` 为唯一视觉来源 |

工程细节见 WPF-README.md §2（阶段 1. 定令牌）。

---

### 阶段 3 · 搭组件库

| 字段 | 内容 |
|---|---|
| 目标 | 建立可复用的组件样式库，覆盖全部交互状态 |
| 产物 | `app.css`（按钮/输入/卡片/树/弹层…，每块顶部注明对应的目标控件） |
| 出口条件 | 每个组件有**全部状态**：默认 / hover / 按下 / 禁用 / 选中 / 加载 / 错误 / 空 |
| 依赖 | 阶段 2 的 `tokens.css` |
| 规则 | 组件只引用令牌，不写死值；允许"核心组件先行、增量补齐"，但已做组件必须全状态 |
| AI 引导要点 | 1. 从页面清单推导需要哪些组件 2. 让 AI 逐个输出组件及其全状态 3. 用一张"组件展示页"（或直接在主界面里看）验证 |
| 常见坑 | 组件只画默认态（实现时 hover/禁用/加载/空态靠猜）；重复发明已有组件 |
| 回退影响面 | 显著改组件 → 使用该组件的所有 fig 页需复查 |
| 人确认点 | 组件清单有无缺少？状态表完整？ |

工程细节见 WPF-README.md §2（阶段 2. 搭组件库）。

---

### 阶段 4 · 画主界面

| 字段 | 内容 |
|---|---|
| 目标 | 画出产品的主界面，说清信息架构与主操作路径 |
| 产物 | `fig1-*.html`（窗口壳层稿，固定尺寸 = 目标窗口尺寸） |
| 出口条件 | 一张图能说清：信息分几区、每区放什么、主操作路径是哪一条 |
| 依赖 | 阶段 3 的 `app.css` |
| 规则 | 窗口壳层必须固定尺寸 + 左上角绝对定位（不要用 100%/vh，不要居中）；只引用令牌与组件 |
| AI 引导要点 | 1. 先与用户对齐"分几区、主路径"再让 AI 动手 2. 生成后一起看，用自然语言迭代 3. **此阶段结束前不碰规格页** |
| 常见坑 | 结构没对齐就让 AI 铺开画；用响应式/百分比做壳层导致截图尺寸不可控 |
| 回退影响面 | 改布局结构 → 规格页需同步；若动到组件，回阶段 3 |
| 人确认点 | 分区合理？主路径清楚？没有多余装饰干扰？ |

工程细节见 WPF-README.md §2（阶段 3. 画主界面）、§3.3（页面稿参数）。

---

### 阶段 5 · 画规格页

| 字段 | 内容 |
|---|---|
| 目标 | 把关键部件逐项展开：状态色、尺寸、交互入口、边界情况 |
| 产物 | `fig2..N-*.html`（规格稿，高度随内容，自动裁剪） |
| 出口条件 | 主操作路径上的每个交互入口 + 组件库里所有非默认状态，都有视觉定义 |
| 依赖 | 阶段 4 的 `fig1`（结构与主路径已确认） |
| 规则 | 一个文件 = 一组"面向部件"的规格；规格稿同样只引用令牌与组件 |
| AI 引导要点 | 1. 从主界面上圈出关键部件 2. 逐个让 AI 展开规格 3. 对照组件状态表检查覆盖度 4. 流程规格中的 Mermaid 图必须同步生成可独立打开的 HTML；可按业务特征一页容纳多个流程图，不强制每张图一个文件 |
| 常见坑 | "关键"没有定义导致漏项（按出口条件执行可避免）；规格页里重新发明新样式；Mermaid 只埋在 Markdown 里，评审时缺少可独立打开的流程图 HTML；把强相关流程拆成过多文件导致业务上下文割裂 |
| 回退影响面 | 改规格 → 若有新组件状态，回阶段 3 补齐后重跑体检 |
| 人确认点 | 对照出口条件逐项点名，确认无漏 |

工程细节见 WPF-README.md §2（阶段 4. 画规格页）。

---

### 阶段 6 · 体检出图

| 字段 | 内容 |
|---|---|
| 目标 | 用工具查出肉眼看不见的问题，并产出交付图 |
| 产物 | 体检报告（三类问题清单）+ 归档 PNG |
| 出口条件 | 三类问题全为 `[]`；稿子里刻意塞过"故意很长"的样例文字并撞过墙 |
| 依赖 | 阶段 5 的全部 `fig*.html` |
| 规则 | 先塞长文案再体检（否则是虚假数据下的虚假通过）；PNG 是派生物，永远不手改 |
| AI 引导要点 | 1. 检查环境（见下方环境要求） 2. 提醒用户先塞长文案 3. 运行 check-layout.js 4. 有问题 → 回对应 fig 修 → 重跑 5. 通过后运行 export-png.py 出图 |
| 环境要求 | 见 §3：Node 22.4+ / Python 3.9+ / Pillow（可选）/ Edge 或 Chrome |
| 常见坑 | 跳过体检直接出图；体检后手动改 PNG；没塞长文案就宣告通过 |
| 回退影响面 | 体检发现的问题按所在文件回退（fig → 可能牵动 app.css → 可能牵动 tokens） |
| 人确认点 | 看过体检报告；PNG 归档完整 |

工程细节见 WPF-README.md §3（export-png.py）、§4（check-layout.js）。

---

### 阶段 7 · 写映射

| 字段 | 内容 |
|---|---|
| 目标 | 产出"设计 → 实现"的翻译表，验证设计在目标框架里做得出来 |
| 产物 | `wpf-mapping.md`（七部分：布局/尺寸/颜色/组件/速查表/反向清单/坑清单） |
| 出口条件 | "找不到落点"的清单为空或已确认可接受 |
| 依赖 | 阶段 2-5 的全部设计文件 |
| 规则 | 这是**设计文档**，不是实现代码（不写完整 XAML，不碰 src/）；每个结论必须指向具体 class 或令牌名，不许空泛 |
| AI 引导要点 | 1. 用 WPF-README.md §6.2 的提示词模板生成 2. 让它自己核对"class 是否都能在速查表查到" 3. 重点审视"找不到落点"和"坑清单"两节 |
| 常见坑 | 满篇"完美对应"（多半没认真查）；伪造对应关系比缺失更危险；坑清单写空泛的"注意性能" |
| 回退影响面 | 发现"做不出来"的落点 → 回到对应设计阶段修改设计 → 重跑体检 |
| 人确认点 | "找不到落点"清零或逐条确认接受 |

生成模板见 WPF-README.md §6.2、§6.3（验收三条检验）。

---

### 阶段 8 · 交接开发

| 字段 | 内容 |
|---|---|
| 目标 | 把全部设计资产整理成交接包，进入 AI 编码阶段 |
| 产物 | 项目级提示词（含设计资产摘要）+ 实现顺序 |
| 出口条件 | 设计资产完备（令牌/组件/主界面/规格/映射齐全），可交给 AI 编码助手逐页实现 |
| 依赖 | 阶段 7 的映射表 |
| 规则 | 不把所有页面一次性丢给 AI；逐页实现、每页检查；token 定型后不再随意改设计方向 |
| AI 引导要点 | 1. 汇总资产清单 2. 生成"项目级系统提示词"（技术约束 + 资产位置 + token 引用要求） 3. 给出实现顺序建议 4. 生成第一个页面的实现提示词 |
| 常见坑 | 交接时丢掉令牌与映射（AI 会重新发明样式）；一次性要求实现全部页面 |
| 回退影响面 | 实现阶段若发现设计问题 → 回到对应设计阶段修正 → 重跑体检/映射 → 再继续 |
| 人确认点 | 资产清单核对完毕；开始编码 |

---

## 3. 环境要求（阶段 6 附带）

| 组件 | 最低版本 | 为什么 | 检查命令 | 安装 |
|---|---|---|---|---|
| Node.js | 22.4 | check-layout.js 依赖全局 WebSocket（22.4+ 默认可用） | `node --version` | https://nodejs.org |
| Python | 3.9 | export-png.py 运行环境 | `python --version` | https://python.org |
| Pillow | 任意（可选） | export-png.py 自动裁剪空白；缺失只影响裁剪 | `python -c "import PIL"` | `pip install pillow` |
| Edge / Chrome | 现代版本 | 无头浏览器截图（两个工具共用） | 检查常见安装路径 | 系统通常自带 Edge |

交互流程：AI 逐项检查 → 报告缺失项 → 与用户确认 → 安装 → 复检 → 继续。
详见 docs/06-设计工具链.md。

---

## 4. 回退影响面速查

| 改动点 | 需要复查的下游 |
|---|---|
| 页面清单（阶段 0） | 全部下游 |
| 选定风格（阶段 1） | tokens → app.css → 所有 fig |
| `tokens.css` | token-preview.html、app.css、所有 fig（可 grep 变量名定位） |
| `app.css` | 使用该组件的 fig 页 |
| `fig1` 布局结构 | 规格页是否仍一致 |
| 规格页新增状态 | 回阶段 3 补齐组件状态 → 重跑体检 |
| 映射表发现"做不出来" | 回对应设计阶段改设计 → 重跑体检与映射 |

---

## 5. 与 WPF-README.md 的关系

| | 本文件（流程模型） | WPF-README.md |
|---|---|---|
| 定位 | 全模式共享的模型层 | WPF 模式的工程操作权威 |
| 覆盖 | 阶段 0-8 的完整模型（含入口与交接） | 阶段 2-7 的工程细化（目录约定/六个阶段/工具用法/坑清单） |
| 使用 | MCP 与页面端的内容骨架 | 可直接复制进目标项目；阶段 2-7 的执行细则以它为准 |

**流程模型补全了 WPF-README 缺失的两端**：
入口（阶段 0 功能蓝图 + 阶段 1 风格探索）与出口（阶段 8 交接开发）。