name: api-regression-planner description: 根据 OpenAPI、接口文档或服务端校验代码，生成有依据的接口回归用例、测试数据和断言；适用于接口上线前补测试与评审覆盖，不用于单纯 JSON 格式转换。

接口回归用例设计

交付测试人员或开发者能执行的回归计划。每个用例必须说明依据、输入变化、预期断言与数据恢复方法。不要用通用测试清单替代针对当前接口的分析。

输入与取证

先查用户提供的接口文档、OpenAPI 和仓库中的控制器、DTO 校验、鉴权、异常处理及已有测试。记录文件位置、接口方法及路径、文档版本和代码版本；不同来源冲突时分别列出，不能用实现覆盖合同或反过来。

至少需要一个接口定义；只有一份 JSON 示例时，只能确认示例结构，不能推断必填、枚举全集、成功码或最大长度。先产出可确认部分，将缺口写进 questions.md，不要把推测写成通过条件。

若输入为 OpenAPI：

• 区分参数自身的 required、requestBody.required 和对象的 required 属性数组。
• 解析可访问的本地 $ref；循环引用、外部引用或复杂组合无法确认时列出未覆盖节点，不凭空补定义。
• 区分 OpenAPI 3.0 的 nullable 与 3.1 的含 null 类型；required 仅约束属性存在，不意味着非空或非 null。
• 读取接口级与全局 security；接口覆盖全局，security: [] 表示本接口不要求安全机制。security 数组中的方案是备选，同一对象内的多个机制需组合满足。
• example/default 不是已被服务端执行的验证规则；format 的校验强度需依据运行时实现确认。

用例选择

使用 references/case-design.md 生成与证据匹配的用例。先构造一条满足所有已知约束的基线请求，再一次仅改变一个条件，避免一个请求同时违反多个规则导致无法定位失败原因。

优先覆盖会造成越权、重复业务操作、数据损坏和客户端中断的变化。权限、幂等和并发只有在接口涉及这些语义时展开；测试所需的第二个租户、用户或资源均需说明准备条件。

分开写 HTTP 状态、业务码、响应字段与持久化副作用的断言。例如“HTTP 200”不能代替“订单创建成功”；“返回错误”不能代替“数据库没有新增记录”。错误码无文档依据时标为待确认，不臆造 400/422 等精确值。

交付

在用户指定目录，或默认 artifacts/api-regression/ 下生成：

1. cases.md：基线请求与用例表。每行包含 ID、优先级、合同/实现依据、前置条件、输入变更、HTTP 断言、业务/数据断言、清理方式、状态。未运行时统一写“未执行”，不填通过率。
2. fixtures.json：与用例对应的演示请求及变量，使用合成数据；不能把真实凭据写进文件。
3. questions.md：冲突、缺失约束、未解析引用和未覆盖分支；说明各自阻塞哪些用例。

需要自动化时，沿用项目现有测试框架生成针对性测试；不要在用户只要求计划时额外安装依赖或调用接口。只有环境和调用范围已获授权时才执行请求。写入、重试或并发测试需限定在获准的测试环境及可清理数据中。

验收

• 每个精确预期都有合同或代码依据；建议项与已确认规则明确区分。
• 必填的缺失/null/空串分别判断；边界的取值仍满足其他规则。
• 涉及分页/筛选时验证总数、范围、稳定排序与隔离，而不只检查列表非空。
• 计划、生成测试代码、实际执行结果分别报告；不能把文件生成成功当作接口通过。

查看 examples/input.md 与 examples/result.md 了解交付粒度。它们是人工编写的演示，不是线上实测结果。