---
name: solution-planning
description: 实施方案与验收条件设计方法论——方案结构五件套（现状/方向/涉及文件/预期变更展示/验收条件）、分档验收条件方法论（冒烟红线/端到端/后端/前端三层/自查清单）、方案前置澄清纪律、活文档落盘规范。Use when 探索完成后需要产出可执行、可验收的实施方案，或任何「动手前先定验收标准」的规划任务。
when_to_use: 已摸清现状、需要把「要做什么」落成结构化方案时。方案的验收条件必须二值可判定（能/不能、通过/不通过），并按改动类型分档设计。与 exploration-method（同包）衔接：它产出的举证锚点直接进方案的「现状」节。
language: zh
---

# Solution Planning — 方案与验收条件设计方法论

定位：把探索结论转成**实现方可直接执行、验收方可二值判定**的实施方案。方案的硬通货是验收条件——动手之前先定义「怎么算做完、怎么算做对」。

## 1. 方案前置澄清

有歧义先问，不猜。澄清纪律：

- **必须问**：多种合理方向且取舍影响架构/用户体验；任务缺少无法自行合理补全的关键信息。
- **不问**：存在合理默认做法时，直接推进并在方案里写明假设——用户可纠偏，不要用提问打断所有事。
- **问法**：用 `AskUserQuestion` 给可点击的选项（结构化 UI 比读文本问题快）；多个有依赖关系的问题用单次调用的 `dependsOn` 条件分支一次问完，不分成多轮顺序问。
- 澄清结果写进方案（「已确认：…」），成为后续验收的事实前提。

## 2. 方案结构五件套

每份方案固定五节，顺序不变：

1. **现状**：当前实现是什么，每条论断带 `路径:行号` 举证（沿用 exploration-method 的举证纪律）。没有举证的「现状」不算现状。
2. **方向**：要改成什么样 + 为什么。多个候选方向时写取舍理由，不只写结论。
3. **涉及文件**：将触动的文件清单（路径 + 改动性质：新增/修改/删除）。
4. **预期变更展示**：关键改动的前后对比或 diff 示意，让读者不动手也能看见改完长什么样。
5. **验收条件**：见下节——方案的成败完全由这一节定义。

## 3. 验收条件方法论

核心原则：**每条验收条件二值可判定**（通过/不通过，无「基本可用」），且**每条都有对应的验证手段**。按改动类型分档：

### 3.1 冒烟红线（一切验证的前提）

最先跑、成本最低、失败即停的最小检查集。红线不过，后续所有验证无意义。典型条目：

- 编译/构建通过；
- 进程起得来、端口在听；
- 核心端点/首页可访问（非 5xx）。

红线清单要短——它是闸门，不是全覆盖测试。

### 3.2 端到端验证

从用户动作到可观察结果的完整链路跑通：触发入口 → 经过被改动的环节 → 最终结果可见。端到端条件回答「这个特性在真实路径上是否真的工作了」，而不是「各部分各自看起来没问题」。

### 3.3 后端改动验收

- API 契约：`curl` 打端点，断言状态码 + 响应字段结构（关键字段存在、类型正确）；
- 错误路径：非法输入返回预期错误码，不 500、不挂死；
- 有持久化时：写入后重读验证落盘内容。

### 3.4 前端改动验收（三层递进，缺一不可）

1. **资源层（curl）**：页面与静态资源可达、无 404、构建产物包含新代码（可按特征字符串 grep 产物）；
2. **DOM 层（Playwright/无头浏览器）**：关键元素存在且可见、console 零错误零 failed request、交互后 DOM 状态符合预期——断言口径要在方案里写到可执行（比文案就给 i18n key、比状态就给显式语义、比布局就给基线口径）；
3. **交互层（截图 + 真实路径）**：模拟真实用户操作路径走一遍并截图，亮/暗主题与关键响应式断点各留证据。视觉结论必须截图佐证，不裸断言。

### 3.5 自查清单

交付前对照每条验收条件自跑一遍，逐条标 PASS/FAIL + 证据（命令输出/截图路径/断言结果）。自查不过的条目不交付、不辩解——要么修到过，要么显式声明未达成及原因。

## 4. 落盘：活文档规范

- 方案写到 `{{data_root}}/docs/<folderName>/`（按域/项目归 folder），文件名含日期或版本号，可被后续引用。
- **活文档**：头部带状态字段（如 draft → 确认 → 完成），执行过程中发现的事实偏差回写文档，不另起矛盾的新版本；阶段文档记录各阶段结论。
- 方案被确认后再动工；动工后方案文档与实现保持同步（验收条件被打回修订时，文档同步修订并标注版本变化）。

## 5. 反模式清单

- 验收条件写「功能正常」「体验良好」等不可判定措辞；
- 只有 happy path 验收，无错误路径与边界；
- 前端只验资源层（curl 通了就交付）；
- 方案无举证锚点，实现方还要重新摸一遍现状；
- 该问的不问、猜错方向返工；或不该问的连环问、阻塞推进。