契约与事件 ​

contracts/ 是跨服务、SDK 和外部接入的机器可读源。当前目录只有骨架，本文规定未来契约应满足的共同规则。

契约分区 ​

版本规则 ​

每个契约有稳定 ID、语义版本和所有者。向后兼容变更只增加可选字段或新枚举处理策略；删除字段、改变类型、改变必填性或副作用语义需要新主版本。消费者必须忽略允许扩展的未知字段，同时对关键未知枚举采取安全失败。

事件信封 ​

事件信封包含：

事件至少一次投递，不承诺全局顺序。需要顺序的消费者按明确聚合键和序列处理，并能应对重复、迟到和缺失事件。

错误契约 ​

错误包含稳定 code、人类可读 message、traceId、retryable、可选重试时间和安全细节。业务拒绝、权限拒绝、输入错误、预算超限、临时依赖失败、结果未知和内部错误使用不同类别。

生成与验证 ​

服务端类型、客户端 SDK 和参考文档从契约生成。CI 检查语法、示例、破坏性变更和所有者。生成物不手工修改；任何行为变化先更新契约，再更新实现和说明。