# V1 规则与报告

| 标识 | 判定 | 对旧请求的影响 |
| --- | --- | --- |
| operation-removed | 原有路径和方法组合不再存在 | 旧客户端找不到原操作 |
| request-required-parameter-added | 新参数 required 为 true，旧参数不存在或非必填 | 省略该参数的旧请求不再满足约束 |
| request-required-property-added | 已有请求对象的 required 集合增加属性 | 缺少该属性的旧请求不再满足约束 |
| request-enum-value-removed | 移除字符串允许值，或无限制改为有限集合 | 曾允许的字符串被新契约拒绝 |

必填参数与属性属于“新增必填请求约束”，合计三类。对象只在旧、新都存在的属性中递归比较；全新可选对象内的必填子字段不单独报破坏。已有可选对象内部变更仍影响提供该对象的旧请求，因此继续分析。

default 是建议值，不能假设服务器会替调用方补齐。参数先合并路径级，再用操作级相同位置和名称覆盖。V1 不猜测路径重命名或参数别名。

## 状态

- complete：支持范围分析完成；有问题退出 1，没有退出 0。
- incomplete：存在不支持结构或未分析契约变化，退出 2。
- invalid：输入解析/依赖结构错误、缺失引用或文件/执行错误，退出 2。

invalid 优先于 incomplete。两者均保留已经能够确定的问题，不清空 findings。文本和 JSON 的问题内容一致。不存在的位置为 null，引用定位区分逻辑使用位置和物理定义位置。诊断包含 code、severity（error/unsupported）、side（old/new/host）、方法、路径、位置和原因。

## 复核方法

在旧文档中构造一个合法请求，检查它是否违反新约束。例如只传 name 的创建用户请求，或 cancelled 查询值，都能解释原示例中的判断。V1 提供固定场景和有限枚举空间独立测试，尚未实现通用请求反例生成，也没有声称经过真实用户或成熟工具全面差分验证。