规格 · API 与传输
适用范围
约束所有对外接口：功能之间、平台与执行端之间、平台与外部系统之间的请求与响应。
不约束：界面内部的组件间调用；实现仓内部的函数签名；传输协议的具体选型（HTTP 方法、路径命名由各功能自行决定，只要满足本规格）。
规范条款
形状与解析
- 必须为每个接口声明形状版本；版本变化必须经显式评审，必须不以"兼容字段静默扩展"的方式演进。
- 必须做严格形状校验：未知字段、错误类型、未知版本必须拒绝；必须不做宽松解析或静默忽略未知字段。
- 请求与响应必须是机器可判定结构；必须不依赖自然语言文本传递语义。
- 形状校验必须在任何副作用之前完成，失败即 fail closed。
作用域寻址
- 每个请求必须携带足以确定唯一作用域的寻址信息（工作空间 / 项目 / 对象）。
- 凭据可认证但作用域不成立时，必须返回与"对象不存在"同形的结果；必须不通过错误内容泄漏其它作用域是否存在。
- 必须不接受客户端提交的作用域覆盖：URL 指向的作用域必须就是实际生效的作用域。
幂等
- 所有变更类接口必须携带幂等身份，且幂等身份必须位于请求语义内；必须不依赖传输头作为唯一幂等依据。
- 幂等身份必须每次尝试唯一，必须不跨进程复用。
- 同幂等身份 + 同规范化请求体 → 必须返回同一结果，且必须不重复应用变更。
- 同幂等身份 + 不同请求体 → 必须冲突失败，必须不执行任一版本。
- 只读接口必须不要求幂等身份。
重放与模糊响应
- 只有无法判定的响应（超时、连接中断）可以按原身份原负载重放。
- 明确的客户端类失败（形状错误、认证失败、权限不足）必须不被重放。
- 冲突类失败必须丢弃陈旧结果并先同步当前状态，必须不盲目重试。
时钟与时间
- 服务端时钟是所有到期判定的唯一权威；必须不设客户端宽限期。
- 客户端可以据响应建立单调本地截止，但只可以用于更早收敛；必须不用于延后判定。
- 响应中的到期时刻必须由服务端写入；必须不接受客户端提交的到期时刻。
校验顺序
- 接口必须声明校验顺序，且必须依次为：身份与作用域 → 幂等重放 → 业务前置。
- 前置条件不成立时必须不产生排队、执行或状态变化。
违反时的失败语义
| 违反情形 | 必须的行为 |
|---|---|
| 未声明形状版本 | 视为规格违反；评审阶段必须拦截，不得合入 |
| 宽松解析未知字段 | 必须改为拒绝；已发布接口按版本与兼容处置 |
| 幂等身份来自传输头 | 必须改为请求语义内；否则无法保证经代理后仍一致 |
| 作用域不符却泄漏存在性 | 必须改为同形返回 |
| 客户端时钟参与到期判定 | 必须改为服务端时钟；客户端截止只能更早收敛 |
| 明确失败被重放 | 必须停止重放，按冲突或失败处理 |
校验方式
| 校验对象 | 判据 | 失败表现 |
|---|---|---|
| 形状版本声明 | 每个变更类接口必须能定位到其形状版本 | 缺失即失败 |
| 严格校验 | 注入未知字段与错误类型的请求必须被拒绝 | 被接受即失败 |
| 作用域同形 | 以有效凭据访问非授权作用域，响应必须与"不存在"同形 | 可区分即失败 |
| 幂等身份位置 | 幂等身份必须可在请求语义内定位 | 仅存在于传输头即失败 |
| 幂等语义 | 同身份同体重放不产生第二次变更；同身份异体冲突 | 任一不符即失败 |
| 重放边界 | 明确失败不得触发重放 | 触发即失败 |
| 时钟权威 | 篡改客户端时钟不得改变到期判定 | 改变即失败 |
| 校验顺序 | 身份与作用域校验必须先于业务前置校验 | 顺序不符即失败 |