# SOP：验证

> 目标：**"我验证过了"要有可复现的依据**，而不是"我记得跑过"。
> 这个项目吃过几次亏，下面的规则都是踩出来的。

## 分层验证（按改动类型选，不必每次都全跑）

| 改动类型 | 至少要做到 |
|---|---|
| 纯文案 / 注释 / 文档 | 构建通过 |
| 样式、模板结构 | 构建通过 + 实际页面看一眼 |
| 业务逻辑（不改协议） | 构建通过 + 在 `tools/` 写脚本对真实数据断言 |
| **任何接口 / 协议相关** | 上面全部 **+ 对真实后端端到端跑一遍**（见下） |
| **改了 `index.html` / `redirect.html`（含内联脚本）** | 上面全部 **+ `npm run build && node harness/tools/verify-inline-scripts.mjs`** —— ⚠️ **构建不会解析内联 `<script>`**（原样拷贝），删代码删出个不配对的 `}` 也能构建通过，但页面一加载就抛语法错误、加载遮罩永远不隐藏（2026-09-24 实际踩过） |

## 构建

```bash
npm run build     # 必过。这是提交前的底线，不是充分条件
```

> ⚠️ **"构建通过"只证明能编译，不证明行为对。** 接口相关的改动只跑构建等于没验证。

## 接口改动：必须对真实后端验证

```bash
# 后端
http://192.168.2.23:8000

# 开发环境经代理访问（见 harness/docs/reference/api-chat.md）
https://localhost:8083/chat-api/api/chat
```

**关键：读原始 SSE 载荷。** 项目里踩过两次同样的坑 —— 只看自己封装的中间事件，
误判"后端不返回补问"，实际是适配层已把事件并入了 message 通道、查错了事件名。

正确做法是把原始 `event:` / `data:` 打出来看，而不是去监听封装后的事件。

## 脚本放哪里

验证脚本写到 **`harness/tools/`**，不要写进项目根目录。

- 命名 `<用途>.mjs`，顶部写清"验证什么、怎么跑"
- 有复用价值的**留着** —— 它们是"当时怎么验的"最好的证据

## 记录证据

验证通过后，**当场**写进两个地方（不要攒到会话结束）：

1. `harness/progress.md` — 本轮 session 记录里写「运行过的验证」和「已记录证据」
2. `harness/feature_list.json` — 对应功能的 `verification` 与 `evidence`

**完成门槛**：只有验证成功、且证据已记录，功能状态才能切 `passing`。

## 已知的"看起来像 bug 其实不是"

记录这些是为了避免后来者（包括未来的自己）去"修"不该修的东西：

| 现象 | 真相 |
|---|---|
| 政策「更多」面板选中任何部门都筛出空列表 | 按用户要求**刻意**保持最初的固定部门列表 + 字面匹配；新接口返回的部门是全称，字面不相等。**不要当 bug 修。** |
| `answer.text` 与 `summary.text` 首句重复 | 后端内容重复（同一段话既在 answer 又在 summary 开头），**不是前端渲染问题** |
| 上游公司数据服务偶发失败 | 表现为 `status: failed` 或空响应；属上游问题，前端只负责正确展示 |

## 反模式

- ❌ "构建通过，应该没问题了"
- ❌ 只在特定条件下跑过一次，却记成"已验证"
- ❌ 改了验证步骤让结果变好看
- ❌ 把没验证的说成验证过的（这一条比不写更糟）