verification.md 2.8 KB

SOP:验证

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

分层验证(按改动类型选,不必每次都全跑)

改动类型 至少要做到
纯文案 / 注释 / 文档 构建通过
样式、模板结构 构建通过 + 实际页面看一眼
业务逻辑(不改协议) 构建通过 + 在 tools/ 写脚本对真实数据断言
任何接口 / 协议相关 上面全部 + 对真实后端端到端跑一遍(见下)

构建

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

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

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

# 后端
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 — 对应功能的 verificationevidence

完成门槛:只有验证成功、且证据已记录,功能状态才能切 passing

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

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

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

反模式

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