学习指南: 第9部分。功能验证：从规格到事实

模块「第9部分。功能验证：从规格到事实」中第 2 / 5 节课

您正在未登录状态下查看课程。请登录，以保存进度并参加测试。

主题：第9部分。功能验证：从规范到事实

难度级别：中级

预计学习时间：4-6小时（理论2小时，实践2-4小时）

先决条件：基本理解Git和分支操作

具备编写测试的经验（单元/集成测试）

熟悉TypeScript和npm基本命令

理解客户端-服务器架构（HTTP、REST）

具备使用markdown文档的经验

建议：熟悉课程第1-8部分的内容（SDD、规范、路线图）

学习目标：为任何功能编写包含清晰、可验证事实的validation.md，区分事实与散文式愿望

基于功能类型的风险矩阵，选择最优的事实级别（示例、不变量、属性、契约）

应用事实生命周期状态（草稿 → 强制 → 已实现 → 延期）来控制合并前的质量

为审查形成证据包（evidence bundle），包括事实状态、命令痕迹和手动验证结果

使用智能体（Qwen Code）自动比对代码与validation.md，识别规范偏差

概述：本课程部分致力于从文本规范到可验证事实的关键转变——这是一种将意图转化为功能合并就绪证明的机制。规范解释了应该做什么，但本身不能保证正确实现。事实是机器或人类可以无需重新解释即可确认的可执行或明确可验证的陈述。材料涵盖四个事实级别、用于选择适当检查密度的风险矩阵、validation.md文件结构、事实生命周期、CI/CD集成、手动和自动验证，以及为审查形成证据包。特别强调与编写代码的智能体协作：由于模型可能对同一规范做出不同解释，事实成为唯一可靠的合并准入条件。

核心概念：事实：可执行或明确可验证的陈述，无需解释。示例：npm run typecheck以代码0退出；GET /返回200；响应包含<h1>AgentClinic</h1>。与散文式愿望如"确保页面看起来不错"形成对比。

规范 vs 事实：规范指导开发，解释意图和边界。事实通过提供客观证据允许合并。简短公式："规范指导。事实允许合并。"

四个事实级别：示例（具体的输入-输出对：一个curl命令，一个测试），不变量（始终为真的陈述：重复运行迁移不会改变模式），属性（验证一类情况：任何超出1..5范围的评分都被拒绝），契约（前置条件 → 操作 → 后置条件：如果会话未认证，则GET /dashboard响应重定向到/login）。

风险矩阵：根据功能类型选择最低充分事实级别的工具。视觉变更需要手动事实；数据迁移需要不变量和属性；授权需要属性和契约；支付需要示例和契约。矩阵的目标是发现遗漏的检查，而非制造官僚主义。

Validation.md：功能验证的核心工件。包含一组事实，每个事实带有命令/检查、预期结果、负责人（自动/手动验证）和状态。不是检查清单，而是用于合并准入的事实集合。

事实生命周期：草稿（已提议，未确定）→ 强制（被接受为功能标准）→ 已实现（有测试、命令或确认）→ 延期（有意识地推迟到未来阶段并附解释）。帮助区分意图和证据。

手动事实：由人类执行但具体且明确的验证。弱示例："检查界面"。强示例："在375px宽度下，/feedback页面显示姓名字段、消息字段、提交按钮，无水平滚动和元素重叠"。手动事实对UI是必需的，对语气和可访问性也有用。

证据包（evidence bundle）：合并时提供给审查者的紧凑工件：规范链接、带状态的事实列表、命令运行痕迹（退出代码、输出）、手动验证结果、实现过程中做出的决策、提交链接。审查者不应重新运行所有内容——他应该理解作者验证了什么，并在有疑问时进行针对性复核。

人机协同验证：智能体发现机械性不一致；人类评估产品和架构方面：是否符合使命、边界蔓延、未说明的依赖、新开发者对结构的理解程度、风险行为是否有事实支撑、仅留在聊天中的决策。

规范、计划和事实的同步更新：当实现表明需要新结构时（例如，拆分为Layout/Header/Main/Footer），需要同时更新plan.md和validation.md，以便未来的智能体会话不会回到旧解释。

实践练习：标题：将愿望转化为事实

问题：给定一个散文式验证："确保反馈表单正常工作，在手机上看起来正常"。将其转化为validation.md的3-4个具体事实，包括自动和手动验证。指明每个事实的级别（示例、不变量、属性、契约或手动事实）。

解答：1. F1 — 示例：curl -X POST http://localhost:3000/feedback -d '{"name":"Test","message":""}'返回400 Bad Request。级别：示例 + 契约（空消息 → 拒绝）。

F2 — 属性：任何评分超出1..5范围的POST /feedback返回400，不受其他字段影响。级别：属性。
F3 — 不变量：使用有效数据成功POST /feedback后，feedback表中的记录数恰好增加1，且响应重定向到/feedback。级别：不变量 + 契约。
F4 — 手动事实：在375px宽度下，/feedback页面显示姓名字段（type='text'）、消息字段（textarea）、提交按钮（type='submit'）和最近3条记录列表，无水平滚动、元素重叠或文本截断。级别：手动事实。

关键区别：每个事实都包含具体的命令或验证条件、预期结果和排除歧义解释的成功标准。

难度：初级

标题：应用风险矩阵

问题：团队正在开发以下功能：(A) 在首页添加促销横幅，(B) 数据库迁移为users表添加email字段，(C) 新端点POST /payments用于处理支付，(D) 注册表单验证并检查email唯一性。为每个功能确定根据风险矩阵哪些事实级别是必需的，并解释原因。

解答：A — 横幅（视觉/UI变更）：示例（正确渲染的HTML）+ 手动事实（视觉层次、移动设备可读性）。没有手动验证无法确认视觉质量。

B — 数据迁移：不变量（重复运行不改变模式/不重复列）+ 属性（迁移对所有现有记录幂等地应用）。示例不足：需要保证大规模数据安全。

C — 支付端点：示例（具体成功支付通过）+ 契约（无效凭证时 → 400并带具体错误；重复幂等键时 → 409）。副作用需要严格的契约。

D — 注册验证：示例（有效数据创建用户）+ 属性（任何重复email被拒绝）+ 契约（缺少必填字段时 → 400并指明缺失字段）。表单验证需要对一类无效输入的属性。

验证：如果迁移B只指定了示例而没有不变量——这是重写validation.md的信号。

难度：中级

标题：创建完整的validation.md

问题：为功能"Hello Hono"——基于Hono的最小化Web应用，包含服务端渲染——设计validation.md。功能包括：安装Hono和tsx、返回含AgentClinic标题的HTML的GET /路由、连接static/style.css、类型检查脚本。使用生命周期状态并指明验证负责人。

解答：```markdown

验证 — Hello Hono

事实集合

F1 — TypeScript编译通过

命令：npm run typecheck
预期：退出代码0，无类型错误
负责人：自动验证（CI + 本地）
状态：强制 → 已实现

F2 — 开发服务器启动

命令：npm run dev（后台），然后curl -s http://localhost:3000
预期：HTTP 200，Content-Type包含text/html
负责人：自动验证
状态：强制 → 已实现

F3 — HTML包含标记

命令：curl -s http://localhost:3000 | grep '<h1>AgentClinic</h1>'
预期：恰好一处匹配，grep退出代码为0
负责人：自动验证
状态：强制 → 已实现

F4 — 静态文件可访问

命令：curl -s -o /dev/null -w '%{http_code}' http://localhost:3000/static/style.css
预期：HTTP 200，正文包含CSS规则（通过| head -c 100验证）
负责人：自动验证
状态：强制 → 已实现

F5 — 页面结构语义正确

验证：打开响应源代码（curl -s http://localhost:3000）
预期：存在<header>、<main>、<footer>标签且层级正确
负责人：开发者手动验证
状态：强制 → 已实现

F6 — 移动端视觉完整性

验证：DevTools，宽度375px，高度667px
预期：标题、主体内容和页脚不重叠；无水平滚动
负责人：开发者手动验证
状态：强制 → 已实现

就绪标准

[x] 所有自动事实（F1-F4）在CI中通过
[x] 手动事实（F5-F6）已在本地验证
[x] 路线图已更新：Hello Hono阶段标记为完成
[x] 提交包含specs/和src/的所有变更

注意：F1-F4是自动的、可复现的命令；F5-F6是手动的，但有具体条件和标准。没有任何散文式愿望。

难度：中级

标题：分析规范偏差

问题：验证"反馈表单"功能时测试通过，但实现：(1) 添加了requirements.md中未指定的"电话"字段，(2) 提交后重定向到/success而非/feedback，(3) 未验证消息长度（要求≤500字符）。编写给Qwen Code的分析偏差请求，并描述需要同步更新哪些文件。

解答：给Qwen Code的请求：

/clear 将此分支与@specs/2026-05-01-feedback-form/validation.md进行比较。

展示：

已实现并通过的事实；
缺少的事实（消息长度验证≤500）；
模糊且需要重写的事实；
实现中未在requirements.md中描述的决策（"电话"字段、重定向到/success）；
规范中的过时陈述。

暂时不要修改文件。

分析后同步更新：
1. **requirements.md**：要么为"电话"字段和/success添加依据，要么恢复到原始要求。
2. **plan.md**：如果添加字段需要新组件，更新组件结构。
3. **validation.md**：
   - 添加F-new：POST /feedback且消息>500字符时返回400。
   - 更新F-redirect：预期改为/feedback或/success——取决于产品决策。
   - 如果保留电话字段则添加事实；否则从实现中移除。
4. **代码**：与更新后的规范和事实保持一致。

原则：实现过程中做出的任何决策都应反映在specs中，而非仅留在聊天或提交消息中。

难度：高级

标题：为合并形成证据包

问题：基于完成的练习，为功能"Hello Hono"准备合并请求描述（证据包）。包含证据包的所有必需元素，并展示审查者如何针对性复核任何事实。

解答：```markdown
## 证据包：Hello Hono

### 规范
- 文件夹：`specs/2026-05-01-hello-hono/`
- requirements.md：记录意图（Hono上的最小化SSR）
- plan.md：Layout/Header/Main/Footer结构
- validation.md：6个事实（见下文）

### 事实状态
| ID | 事实 | 状态 | 确认 |
|---|---|---|---|
| F1 | TypeScript编译通过 | ✅ 已确认 | `npm run typecheck` → exit 0 |
| F2 | 服务器返回200 | ✅ 已确认 | `curl -s -o /dev/null -w '%{http_code}' http://localhost:3000` → 200 |
| F3 | HTML包含<h1>AgentClinic</h1> | ✅ 已确认 | `curl -s http://localhost:3000 \| grep '<h1>AgentClinic</h1>'` → match |
| F4 | static/style.css可访问 | ✅ 已确认 | `curl -s -w '%{http_code}' http://localhost:3000/static/style.css` → 200 |
| F5 | 语义结构 | ✅ 已确认 | 手动验证：源代码包含<<header>、<<main>、<<footer> |
| F6 | 移动端完整性 | ✅ 已确认 | 手动验证：DevTools 375×667，附截图 |

### 命令痕迹

$ npm run typecheck > tsc --noEmit

exit code 0

$ npm run dev & $ curl -s http://localhost:3000 | head -c 200 <!DOCTYPE html><html><head>...<<h1>AgentClinic</h1>...

$ curl -s -w '\nHTTP %{http_code}' http://localhost:3000/static/style.css body { font-family: system-ui; } HTTP 200

### 实现过程中的决策
- 添加Layout组件以保持一致性：plan.md已更新，添加事实F5。
- static/style.css通过Layout中的`<link>`连接，非内联：计划和事实已同步。

### 提交
- `a1b2c3d` — feat: Hono setup with SSR
- `e4f5g6h` — feat: Layout/Header/Main/Footer structure
- `i7j8k9l` — docs: validation.md and roadmap update

### 审查者针对性复核