CModel 数据契约

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

统一响应

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

{
  "errorCode": "0",
  "value": "成功",
  "data": {},
  "systemCurrentTime": 1785984572000
}

• errorCode：成功固定为字符串 "0"，失败为稳定错误码。
• value：简短结果说明或可展示的错误摘要。
• data：成功数据；失败时为 null。
• systemCurrentTime：服务生成响应时的 Unix epoch 毫秒整数。
• 失败响应还必须包含结构化 error，具体规则见 CModel 错误模型。

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

类型定义

模块和工作流必须使用结构化 DataType，包括数组元素和对象属性。下面的 groups 不是泛化的 array<object>，而是可被平台校验、生成表单和传递给调用方的完整契约：

{
  "name": "groups",
  "type": {
    "@type": "DataType",
    "type": "array",
    "nullable": false,
    "items": {
      "@type": "DataType",
      "type": "object",
      "nullable": false,
      "additionalProperties": false,
      "required": ["conversationId", "conversationName"],
      "properties": {
        "conversationId": { "@type": "DataType", "type": "string", "nullable": false },
        "conversationName": { "@type": "DataType", "type": "string", "nullable": false },
        "memberCount": { "@type": "DataType", "type": "integer", "nullable": true },
        "lastTimestamp": { "@type": "DataType", "type": "integer", "nullable": true }
      }
    }
  }
}

公共契约必须遵守：

• 对象明确 properties、required 和 additionalProperties。
• 数组明确 items，不能只声明为泛化对象。
• 可空和缺省是两种语义；nullable 不等于可以省略必填参数。
• ID、金额、时间、持续时间和枚举不得为了组件显示方便改成字符串。
• 发生不兼容的字段改名或类型变化时，发布主版本，并同步升级所有生产者、消费者和 Bundle 锁定版本。

边界规则

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

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

变更检查

发布前至少验证：

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