AI 工程协作·03|业务术语不统一,AI 会越写越错:供应商评价的领域建模

很多跨模块 bug 并不是某行代码写错了，而是团队用同一个词，谈论三种不同的事实。

在供应商评价业务中，最容易误用的一个词是「供应商」。它可能指来源服务维护的主数据，也可能指被平台选入评价范围的本地配置，还可能指某次公司任务下发时被冻结的历史对象。如果代码里都叫 supplier，AI 即便写对 SQL，也可能从错误的数据源读取「正确」的字段。

领域建模的第一步，不是画一张复杂的类图，而是回答：谁拥有事实？事实什么时候生效？历史能不能被当前变化改写？

我们把评价业务拆成「外部主数据 → 本地评价配置 → 任务快照」三层。

外部主数据属于供应商、组织和身份等来源服务。评价服务可以通过契约读取并校验，但不能因为要做评价，就复制出第二套权威的供应商或账号。否则一旦供应商改名、账号停用，两个系统会争论「谁才是真的」。

本地评价配置回答另一个问题：哪些来源供应商被选入评价范围，哪些部门有评价资格，此刻谁是公司管理员。它引用来源对象，但配置本身由评价业务负责。一个来源 ID、一个本地映射 ID，并不是同一种 ID。

任务快照则回答历史问题：某次任务正式下发时，采用了哪版规则、选了哪些供应商与部门、分配了哪些评价员和审核员。后续主数据或配置变化不能自动重写已经下发的任务。快照 ID 也不能拿来当来源 ID 用。

区分这三层之后，一个常见争议就有了答案：「任务页面展示历史供应商名称，是否应该实时回读主数据？」历史复核应基于冻结事实；而此刻是否有权管理某家公司，则必须检查当前授权关系。历史展示和现时授权不能偷用同一份快照。

供应商评价还区分「当前公司管理员」「候选角色资格」和「冻结流程角色」。公司管理员负责此刻的配置管理；候选资格说明某人可以被选为评价员或审核员；只有任务正式下发时确定的冻结分配，才定义这次任务的办理权限。

这不是文字游戏。若把候选资格当成办理权，尚未分配到某个任务的人也可能看到评分单；若把历史管理员快照当成现时授权，已经撤换的管理员仍可能下载当前资料。前端隐藏按钮并不能修复这种后端对象级授权错误。

所以领域文档里既要有术语，还要有不变量：「公司管理员变更不改写历史快照」「候选资格不自动授予任务权限」「平台不计算跨公司总分」。这些句子比一份没有时间语义的字段表更能约束 AI。

项目的 ADR 曾比较三种方式：每次实时关联其他服务的数据；在评价服务完整复制来源主数据；只保存评价业务特有的本地配置，并在任务下发时生成不可变快照。

实时关联看似省存储，但当前主数据一变化，历史重放就可能漂移，还容易形成跨库耦合。完整镜像让本地查询方便，却带来同步冲突和第二权威来源。最终选择的是第三种：当前事实由来源服务拥有，评价配置由本域拥有，历史任务由快照保存。

这个选择也有代价。外部对象停用或删除时，评价服务需要明确的引用保护；远程响应未知时不能猜成功，再继续写入本地业务。ADR 的意义不在于宣布「我们用了快照」，而在于记下为什么没选其他路，以及为了这个决定必须承担哪些校验和恢复责任。

好的领域文档不能停在名词表。接口参数要标清来源 ID 还是本地映射 ID；任务下发代码要写清快照生成时机；历史查询不能悄悄回读当前主数据替换旧值；权限测试要覆盖管理员变更前后、跨公司和未被冻结分配的角色。

当实现与文档冲突时，也不能简单让 AI「以最新代码为准」。代码可能只是未完成的切片，领域文档也可能需要修订。先找到已确认的业务决策，再看当前实现和测试分别覆盖到哪里，才有资格修改其中一个。

这也是为什么我们把长期稳定的术语和不变量放在 CONTEXT.md，把较难逆转的取舍放在 ADR，把本次交付范围与验收放在 Spec。三者相互指向，却不互相替代。

让 AI 成为架构协作者，第一步不是要求它「懂 DDD」，而是给它能够判断事实归属、时间语义和权限边界的明确词汇。下一篇，我们顺着一个 B 端操作继续向外走：同一个业务动作穿过 REST、Dubbo 和数据库时，契约怎样保持一致？

我是用编程拯救世界，关注 AI 工程化、软件架构与技术实践。

既然看到这里了，如果觉得有用，随手点个赞、在看、转发三连吧。

THANKS FOR READING