给 AI 接业务数据前，怎样写清主键、状态和数据合同

数据合同是提供方与使用方共同遵守的约定。对于 AI 项目，它不只是一份字段 JSON，还要告诉调用方何时可以依赖这个值。订单、客户、申请和工单应有稳定身份，不用名称或聊天里的称呼当主键。

如果 CRM 与 ERP 都有客户编号，建立映射关系并说明谁维护。租户或业务单位必须参与对象定位；不能因为两个部门都有订单 1001 就默认它们是同一条记录。查不到映射时返回待确认，不让模型选择最像的名称。

Anthropic 的工具设计文章强调输入名称和输出语义要明确。把这种原则扩展到主键和状态，是本文的业务接口设计建议。

这张表是教学约定，不是要求所有企业采用这些字段名。关键是每个字段都有含义、格式、来源和异常处理。金额、百分比、重量等尤其要明确单位，不能让下游通过数值大小猜测。

null 可能表示尚未签收，也可能表示系统没有保存签收时间。如果两种情况会触发不同动作，应该提供原因字段或明确的状态。空字符串、零和未知枚举也不能随意互换。

还要区分“没有这条记录”与“无权查看”。面向普通用户的提示可以统一以免泄露对象存在性，内部诊断记录则需要保留真实错误类型，并限制谁能读取。Agent 不应该把无权限理解为订单不存在，再创建重复记录。

当来源处于同步延迟中，返回数据更新时间和可接受的使用范围。例如历史状态可以用于解释查询，却不能用来放行新的退款。新鲜度标准由具体业务制定。

模型可以提出“建议退款”，不能据此把状态改成 refunded。业务服务必须核对当前状态、操作者权限、金额和记录版本。外部执行结果尚不明确时保留 processing，避免把网络超时当作失败，也避免把受理当作到账。

状态图还应标出 rejected、cancelled 和 failed 的处理方式。不是所有失败都能返回上一状态；已经发生的外部动作可能需要独立补偿记录。

增加一个状态值也可能破坏旧逻辑。旧系统若把“不等于 cancelled”都当作可以执行，新加的 on_hold 就会被误放行。调用方应显式识别允许状态，并对未知值返回需要处理的错误。

拿一条付款已完成、履约尚未完成的订单做桌面演练。模型收到的结果应同时保留付款与履约状态，不能只得到“已完成”。继续模拟签收时间缺失、记录被他人更新、退款余额已变化，观察服务如何拒绝不满足条件的动作。

如果调用方遇到未知状态后仍能继续执行，合同缺少失败语义；如果金额由 100 变成 10000 后下游只能猜单位，合同缺少单位约定；如果重复查询返回不同来源，却没有版本信息，合同缺少可复核依据。问题应落实到具体字段或动作条件。

交付时保存一组合法与非法样例，不只保留成功示例。它们可以由提供方用于接口测试，也可以由使用方用于回归。数据合同因此成为持续检查的一部分，而不是一份上线后没人打开的附件。

选一个最常用业务对象，逐项核对主键、租户、权威系统、金额单位、时间含义、状态转换、权限和版本。发现两个部门回答不一致，先处理语义冲突，再讨论向量库或模型选型。

这份合同适合有多个业务系统、需要 Agent 读取或修改记录的项目。只做公开资料问答时，复杂状态机未必必要，但文档身份、来源和版本仍要约定。数据合同不能替代业务负责人的确认，也不能保证来源本身没有错误。