目标:"我验证过了"要有可复现的依据,而不是"我记得跑过"。 这个项目吃过几次亏,下面的规则都是踩出来的。
| 改动类型 | 至少要做到 |
|---|---|
| 纯文案 / 注释 / 文档 | 构建通过 |
| 样式、模板结构 | 构建通过 + 实际页面看一眼 |
| 业务逻辑(不改协议) | 构建通过 + 在 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,顶部写清"验证什么、怎么跑"验证通过后,当场写进两个地方(不要攒到会话结束):
harness/progress.md — 本轮 session 记录里写「运行过的验证」和「已记录证据」harness/feature_list.json — 对应功能的 verification 与 evidence完成门槛:只有验证成功、且证据已记录,功能状态才能切 passing。
记录这些是为了避免后来者(包括未来的自己)去"修"不该修的东西:
| 现象 | 真相 |
|---|---|
| 政策「更多」面板选中任何部门都筛出空列表 | 按用户要求刻意保持最初的固定部门列表 + 字面匹配;新接口返回的部门是全称,字面不相等。不要当 bug 修。 |
answer.text 与 summary.text 首句重复 |
后端内容重复(同一段话既在 answer 又在 summary 开头),不是前端渲染问题 |
| 上游公司数据服务偶发失败 | 表现为 status: failed 或空响应;属上游问题,前端只负责正确展示 |