CModel 数据契约

CModel 是百积木内部能力之间的统一数据契约。新接口、模块方法、Connector 业务载荷、工作流输入输出、异步任务和持久化模型都必须先定义 CModel 类型，再由各语言实现映射；不能以某个框架、数据库或前端组件的默认序列化结果作为公共契约。

CModel 错误响应使用显式 contractVersion，当前稳定契约为 1.0.0。完整结构、HTTP 语义和机器可读 Schema 见 CModel 错误模型。

统一响应

非流式调用统一返回以下 envelope。三个基础字段均为必填：

{
  "contractVersion": "1.0.0",
  "errorCode": "0",
  "data": {}
}

• contractVersion：严格 SemVer；当前为 1.0.0。
• errorCode：成功固定为字符串 "0"，失败为稳定错误码。
• data：成功数据；失败时为 null 或标准 { message, retryable } 公开错误详情。
• 成功和业务失败响应都使用 HTTP 200；业务成败只由 errorCode 判断，失败详情只用于展示和重试策略。具体规则见 CModel 错误模型。

禁止返回只包含 success、message 或 error 字符串的私有 envelope。网关、模块和调用方不得用 HTTP 状态或自然语言错误文本判断业务错误类型。

类型定义

业务数据使用平台公共 Type，完整语法、对象开放性、必填/可空、约束、接口与引用统一见类型系统。本页只规定响应和边界，不另行维护类型字段规则。

生产者、方法定义、消费者和持久化模型必须使用一致的类型与业务单位。外部返回结构尚未明确时，应先核对实际契约；不能将所有不确定值直接声明为开放对象。具体选择见数据类型。

边界规则

外部系统可以使用 RFC 3339、秒级时间戳或供应商私有 envelope，但适配器必须在进入百积木业务边界时一次性转换为 CModel；内部链路不得继续传播外部格式。对外调用时同样只在最外层适配器转换。

如果某个传输协议强制规定了自己的元数据格式，该格式只存在于协议 envelope 中，不能复制到业务 payload、模块参数或数据库列。业务数据仍按 CModel 传递。

变更检查

发布前至少验证：

1. 生产者输出、方法定义、消费者入参和数据库列使用同一类型与单位。
2. 成功和失败响应都符合 CModel envelope；反序列化失败也不能返回纯文本或 HTML。
3. 错误类型、错误码和时间单位通过自动化测试覆盖。
4. Bundle Manifest、模块版本、平台应用版本和 Connector 版本锁定到同一代契约。
5. 线上回归同时验证正确输入和错误单位、错误类型的拒绝行为。