张胜宇
bc61d5c579
## 为什么做这一步 权威文档 74 份此前**只在本机**，评审者 clone 分支后看不到任何设计文档；而仓库里那两份同名目录 是 **2026-09-16 之前的过期副本，连文件名都是旧的**（无体系编号）。本次按「**权威覆盖过期**」入库。 ## 入库内容 | 目录 | 文件数 | 体积 | 说明 | |---|---|---|---| | `客服agent/` | 24 | 0.77 MB | `D2.1`~`D2.6` 对外交付四件套 + 演示脚本/答辩报告 + `_build` 构建工具 | | `开发文档/` | 50 | 2.16 MB | `D1.x` 索引与决策、`D3.x` 方案、`D4.x` 清除与重构留痕、`D5.x` 业务流程、`D6.x` 业务事实基座、`D7.x` 交付物、`D8.x` 规范 | **旧的过期副本整体移除**（`客服Agent执行Todolist.md` → `D2.1-客服Agent执行Todolist.md` 之类 的改名 + 新增 `D2.5`/`D2.6`），入库后目录内容与权威副本**逐文件一致（零差异，已复核）**。 ## 入库前的安全扫描（必须留痕） - 扫描规则：`sk-` 类密钥 / `Bearer` 长串 / `password=`、`api_key=` 赋值 / 会话中出现过的两把明文 key 片段。 - 结论：**真实密钥只出现在 `.env`**（已被 `.gitignore` 命中，未入库）；`.env.example` 与 `config/risk.env.example` 只有**空占位**。 - 文档内唯一命中是 `D3.1` 里一处**截断的示例 JWT**（`Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...`）， 末尾带省略号，是接口文档的示意值，**不是可用凭据**。
6.6 KiB
6.6 KiB
AI Coding Testing Rules
体系编号：
D8.5· 域：八、AI 协作规则 · 编号体系见D1.1§4.0
本文档是 AI Coding Agent 的测试规范。
本规范用于约束 AI 在完成代码修改后如何设计测试、执行验证、说明风险。
本规范优先级低于：
D8.3-01_READING_RULES.md D8.7-05_PROJECT_CONTEXT.md D8.4-02_EXECUTION_RULES.md高于输出规范。
1. 核心原则
测试的目标不是证明“代码能跑”。
测试的目标是证明：
需求被正确实现
旧功能没有被破坏
边界情况被覆盖
异常路径可控
修改可以被验证
问题可以被回归
任何代码修改后，都必须说明如何验证。
2. 测试分层
AI 必须根据任务类型选择合适的测试层级。
常见测试层级：
Unit Test
Integration Test
E2E Test
Regression Test
Manual Verification
Stability Test
Security Test
Performance Test
不是所有任务都需要全部测试。
但任何任务都必须至少有一种验证方式。
3. Unit Test 规则
适用于：
纯函数
工具函数
规则判断
状态转换
Parser
数据转换
权限判断
边界逻辑
Unit Test 应覆盖：
正常输入
异常输入
空值
边界值
非法状态
历史 Bug 场景
要求：
测试必须稳定
不依赖外部服务
不依赖真实网络
不依赖真实第三方 API
可以重复执行
4. Integration Test 规则
适用于：
多个模块协作
Service 调用 Repository
API 调用 Service
任务编排
数据库读写
缓存交互
外部服务 Mock
Integration Test 应验证：
模块之间能正确协作
数据流转正确
事务边界正确
异常可以被正确处理
依赖服务失败时行为符合预期
默认原则：
第三方 API 默认 Mock
LLM 默认 Mock
邮件默认 Mock
支付默认 Mock
外部网络默认 Mock
5. E2E Test 规则
适用于：
核心业务链路
用户关键路径
提交 / 审批 / 支付 / 登录 / 上传 / 通知 等完整流程
E2E Test 应验证：
用户入口
前后端请求
数据写入
结果展示
权限限制
异常提示
E2E 不应过多。
只覆盖核心路径和高风险路径。
6. Regression Test 规则
凡是修复 Bug，必须补充回归测试或回归验证步骤。
必须说明：
原 Bug 如何复现？
修复后如何证明不再发生？
是否会影响相邻功能？
是否需要新增测试用例？
禁止只修 Bug 不说明回归验证。
7. Manual Verification 规则
如果当前项目没有自动化测试，或者任务不适合自动化测试，必须提供手工验证步骤。
手工验证必须具体。
禁止：
手动测试一下
页面看一下
接口测一下
必须写成：
1. 打开哪个页面 / 调用哪个接口
2. 使用什么输入
3. 预期看到什么结果
4. 失败时会出现什么现象
5. 如何确认旧功能未受影响
8. LLM / AI 功能测试规则
涉及以下内容时适用：
Prompt
Agent
RAG
Tool Calling
Embedding
Retriever
LLM Output Parser
结构化输出
默认规则：
日常测试默认 Mock LLM
Prompt 变更才需要真实模型稳定性测试
LLM 输出必须校验结构
Parser 必须测试异常输出
必须覆盖 Prompt Injection 或越权输入
至少验证：
正常输出
格式错误输出
空输出
超时
模型拒答
注入攻击
Fallback 逻辑
9. 外部服务测试规则
涉及：
邮件
短信
支付
对象存储
搜索服务
第三方 API
消息队列
Webhook
默认规则：
日常测试使用 Mock 或测试环境
禁止默认调用生产环境
禁止默认发送真实通知
禁止默认扣费或创建真实订单
禁止默认写入真实外部资源
必须验证：
成功路径
失败路径
超时
重试
幂等性
异常日志
10. 数据库测试规则
涉及数据库时，必须验证：
新增数据是否正确
历史数据是否兼容
唯一约束是否生效
外键关系是否正确
事务失败是否回滚
软删除是否受影响
Migration 是否可升级和回滚
涉及数据库结构变更时，必须提供：
升级验证
回滚验证
历史数据兼容验证
11. 权限测试规则
涉及权限时，必须覆盖：
有权限用户
无权限用户
不同角色用户
越权访问
前端隐藏按钮绕过
后端接口直接调用
权限测试必须以后端结果为准。
前端隐藏按钮不能作为权限验证依据。
12. 状态流转测试规则
涉及状态变化时，必须覆盖：
合法状态流转
非法状态流转
重复提交
并发提交
失败回滚
历史状态兼容
禁止只测最终结果，不测状态过程。
13. 安全测试规则
涉及以下内容时必须增加安全验证：
认证
权限
文件上传
下载
路径访问
SQL
命令执行
HTML 渲染
外部链接
Webhook
Prompt
至少考虑：
越权
注入
路径穿越
XSS
CSRF
SSRF
敏感信息泄露
Prompt Injection
14. 性能与稳定性测试规则
以下情况需要考虑性能验证：
循环查询
批量导入
大文件处理
高频接口
异步任务
搜索
LLM 调用
复杂计算
至少说明：
是否存在 N+1 查询
是否可能超时
是否需要分页
是否需要限流
是否需要异步处理
是否需要缓存
15. 测试矩阵输出要求
进入实现或完成实现后，AI 必须输出测试矩阵。
格式：
# 测试矩阵
| 场景 | 类型 | 输入 / 操作 | 预期结果 | 验证方式 |
|---|---|---|---|---|
| 正常路径 | Unit / Integration / E2E | xxx | xxx | xxx |
| 异常路径 | Unit / Integration | xxx | xxx | xxx |
| 权限路径 | Integration / Manual | xxx | xxx | xxx |
16. 测试执行说明
AI 必须说明：
已执行哪些测试
未执行哪些测试
为什么未执行
需要用户手动执行什么
测试失败时如何排查
禁止：
测试通过
但没有说明测试内容。
17. 最终原则
没有验证方案的代码，不算完成。
没有回归验证的 Bug 修复，不算完成。
没有权限验证的权限修改，不算完成。
没有回滚验证的数据库修改，不算完成。
测试不是最后一步。
测试是修改方案的一部分。