业务建模一次，人和AI共用：单一事实源驱动AI应用落地

过去两年我们团队落地 AI 应用时，反复遇到同一个问题：业务部门维护的领域规则和 AI 系统实际使用的 Prompt、工具定义、RAG 知识文档，常常各写各的。业务同学说“订单已支付”指某个状态，AI 助手却把“已发货但未完成”也当成已支付；开发同学改了一张表结构，AI 侧的 JSON Schema 和 Function Calling 参数又忘了同步。表面上是沟通问题，本质是缺少单一事实源。

本文要讨论的，就是标题里这句话：“Model your business once – for humans and AI alike”。它不是一句抽象口号，而是一套可落地的工程方法：把业务模型用一种结构化、语义化、可版本化的方式建模一次，让人类团队用同一份模型做开发和评审，让 AI Agent 用同一份模型做上下文注入、工具调用和规则校验。本文会从一个电商订单场景出发，完整演示术语表、实体 Schema、状态机、OpenAPI 契约以及 AI 消费脚本的编写方法，并提供可复制的代码示例。

1. 为什么业务模型要先“建模一次”，再给人和 AI 共用

很多团队对“业务建模”的印象还停留在传统开发阶段：画 UML 图、写 PRD、设计数据库表、维护接口文档。这些资料确实承载了业务知识，但问题是它们形态各异，既有 Word 又有 PDF，既有流程图又有表格，计算机很难稳定解析。

当 AI 进场之后，这个矛盾被放大了。AI Agent 要执行任务，通常依赖三种输入：

• Prompt 中的业务规则描述；
• 工具定义的参数 Schema；
• RAG 检索到的知识片段。

如果这些内容来自不同渠道，且由不同人手工维护，最终必然出现同一个业务对象在多个地方定义不一致。AI 的理解就会漂移，甚至产生看似合理但违背业务规则的输出。

所谓“Model your business once”，核心理念是建立一份单一事实源（Single Source of Truth）。这份模型需要做到：

这背后的工程价值很直接：模型只维护一份，任何消费方都从同一份模型派生、校验或同步。业务变了，只改模型文件，然后重新生成 AI 上下文和 API Schema，人为复制粘贴造成的不一致会大幅减少。

这里需要区分一个容易混淆的概念：业务模型不是数据库表结构。数据表描述存储结构，关注列、主键、索引；业务模型描述领域语义，关注术语、状态、规则、约束。数据库表结构是实现细节，业务模型是稳定契约。AI 不应该被要求直接理解表结构，而应该理解业务模型。

2. 一个可复用的业务模型包含哪些要素

要让模型既服务人类又服务 AI，单一文件通常不够，最佳实践是“按关注点拆分，按目录组织”。一个较完整的业务模型通常包含以下五类要素。

2.1 领域术语表

术语表解决命名一致性问题。比如“订单”“订货单”“Order”到底是不是同一个概念；“已支付”和“支付成功”是否等价。AI Agent 在回答业务问题时，最容易在这些地方出错。

术语表推荐用 YAML 或 Markdown 维护，每条术语包含定义、别名、关联实体、以及面向 AI 的提示词说明。

2.2 实体与关系 Schema

实体描述业务对象的结构，包括必填字段、类型、取值范围、业务含义。推荐使用JSON Schema或OpenAPI Schema保存，因为这两个格式既能做程序化校验，也能被多种 AI 工具链识别。

实体 Schema 里最关键的不是类型约束，而是description字段。很多团队写 Schema 只写类型，不写业务语义，AI 拿到之后还是不知道某个字段到底代表什么。后续实战中我会反复强调这一点。

2.3 状态机与业务规则

状态机是约束业务对象生命周期最直接的方式。哪些状态之间存在合法流转路径，触发事件是什么，前置条件是什么，这些都要显式建模。

业务规则适合用 YAML 声明式描述。既方便人类阅读，也方便在 AI 调用工具前做二次校验，避免 AI 生成一个不合法的状态变更。

2.4 对外服务契约

当 AI Agent 需要操作业务对象时，它需要知道系统暴露了哪些方法、每个方法接收什么参数、返回什么结果。这就是 OpenAPI 或 Function Calling Schema 的作用。

服务契约是业务模型与 AI 工具调用之间的桥梁。理想情况下，服务契约里的字段引用和实体 Schema 保持一致，而不是各自独立维护。

2.5 元数据与描述信息

最后也是最重要的，是元数据。每个文件都应该有版本号、领域名、维护人、变更说明。AI 消费模型时，版本信息能帮助它判断知识时效；人类消费模型时，版本信息能帮助评审变更影响。

3. 环境准备与项目结构

本文的实战示例使用 Python 编写，不依赖任何重量级框架，重点在于演示建模方法和 AI 消费方式。

示例环境如下：

• 操作系统：Linux / macOS / Windows 均可；
• Python：3.9 及以上；
• 依赖库：jsonschema、PyYAML；
• 编辑器：VS Code 或任意支持 YAML、JSON 的 IDE。

如果你的机器上没有安装依赖，可以执行：

pip install jsonschema PyYAML

版本需要根据你的项目实际情况调整，本文示例以常见环境为例，重点演示配置思路。

示例项目最终会形成这样的目录结构：

business-model-demo/ ├── business/ │ ├── glossary.yaml │ ├── entities/ │ │ └── order.schema.json │ └── rules/ │ └── order-rules.yaml ├── api/ │ └── order-service.yaml ├── scripts/ │ ├── validate_order.py │ └── ai_assistant.py ├── data/ │ ├── order.example.json │ └── order.invalid.json └── README.md

下面按照这个结构逐步实现。

4. 完整实战：订单业务模型建模与 AI 消费

这一节用电商订单场景完整演示“建模一次，双端复用”。场景设定为：业务团队需要一套订单领域模型，开发团队基于模型开发接口，AI 助手基于同一套模型回答订单问题、执行查询与创建操作。

4.1 创建项目结构

首先创建目录和基础文件：

mkdir -p business/entities business/rules api scripts data

创建项目后，我们按“先术语、再实体、后规则、最后契约”的顺序建模。这个顺序很重要：先统一语言，再定义结构，然后约束行为，最后暴露能力。

4.2 编写领域术语表

在business/glossary.yaml中定义订单域核心术语：

# 文件路径：business/glossary.yaml domain: ecommerce version: 1.0.0 maintainer: order-domain-team terms: - term: Order aliases: [订单, sales order] definition: > 客户在一次购买行为中创建的一组商品明细、价格与履约信息。 一个 Order 至少包含一个 OrderItem。 related_entities: [OrderItem, Customer, Shipment] ai_prompt_hint: 当用户提到“下单 / 订单 / 购买记录”时，对应本实体。 - term: OrderItem aliases: [订单明细, 明细行] definition: > 订单中的单一商品行，包含 SKU、购买数量和成交单价。 同一订单内不允许出现重复 SKU。 related_entities: [Order, Product] - term: CREATED aliases: [已创建, 待支付] definition: > 订单刚创建，尚未支付。这是订单的初始状态。 ai_prompt_hint: 如果用户询问“未支付订单”，通常指 status = CREATED。

你可以看到，每条术语除了基本定义，还增加了ai_prompt_hint字段。这非常关键：它直接告诉 AI 模型在什么场景下应该关联该术语，比单纯定义更贴近 Agent 使用习惯。

4.3 定义订单实体 Schema

在business/entities/order.schema.json中定义订单实体：

{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://example.com/business/order.schema.json", "title": "Order", "description": "订单聚合根。创建订单时必须至少包含一个商品明细，状态必须从 CREATED 开始。", "type": "object", "required": ["orderId", "customer", "status", "items", "totalAmount"], "properties": { "orderId": { "type": "string", "description": "订单唯一标识，由订单中心生成，格式如 SO20250501001" }, "customer": { "type": "object", "description": "客户概要信息", "required": ["customerId"], "properties": { "customerId": { "type": "string", "description": "客户唯一标识" }, "name": { "type": "string", "description": "客户显示名称，可省略" } } }, "status": { "type": "string", "enum": ["CREATED", "PAID", "SHIPPED", "COMPLETED", "CANCELLED", "REFUNDED"], "description": "订单生命周期状态，状态流转规则见 rules/order-rules.yaml" }, "items": { "type": "array", "description": "订单明细行，至少一项", "minItems": 1, "items": { "type": "object", "required": ["sku", "quantity", "unitPrice"], "properties": { "sku": { "type": "string", "description": "商品 SKU 编码" }, "quantity": { "type": "integer", "minimum": 1, "description": "购买数量，必须大于 0" }, "unitPrice": { "type": "number", "exclusiveMinimum": 0, "description": "成交单价，单位：元，必须大于 0" } } } }, "totalAmount": { "type": "number", "description": "订单总金额，由服务端计算，客户端和 AI 调用方禁止直接传值覆盖" } } }

这里有几个设计点需要说明：

第一，required字段显式声明必填项。AI 在 Function Calling 场景中，如果缺少required，模型很可能漏传参数。

第二，每个字段都写了description。这不是冗余，而是给 AI 的关键提示。比如totalAmount描述中明确“禁止直接传值覆盖”，AI 在生成参数时就会知道这个字段不应该由它生成。

第三，status的枚举值同状态机文件保持一致。后面我们会通过校验脚本保证一致性，避免人工维护导致偏差。

4.4 定义订单状态机与业务规则

在business/rules/order-rules.yaml中描述订单状态流转：

# 文件路径：business/rules/order-rules.yaml name: OrderStateMachine version: 1.0.0 description: 订单状态流转规则，业务团队与 AI Agent 均以本文件为准。 states: [CREATED, PAID, SHIPPED, COMPLETED, CANCELLED, REFUNDED] transitions: - from: CREATED to: PAID event: PAYMENT_SUCCESS condition: "订单金额与支付金额一致" - from: CREATED to: CANCELLED event: USER_CANCEL condition: "支付前用户取消，或超时未支付自动取消" - from: PAID to: SHIPPED event: SHIP condition: "库存可用" - from: SHIPPED to: COMPLETED event: CONFIRM_RECEIPT condition: "用户确认收货，或系统超时自动确认" - from: PAID to: REFUNDED event: REFUND condition: "售后退款通过，原路退回"

状态机文件的消费方有两个：

• 人类业务人员可以评审每个流转是否合理；
• AI 助手可以把这些规则折叠进 Prompt，回答“订单能不能取消”“取消条件是什么”这类问题；
• 后端代码也可以读取该文件，在状态变更接口中做前置校验。

一个实际项目里的状态机可能更复杂，可能包含状态层级、并行状态、超时事件，但建模思路是一致的：把规则显式化，而不是藏在代码if/else里。

4.5 定义 AI 可消费的 API 工具

业务模型最终需要通过 API 暴露给 AI。在api/order-service.yaml中定义 OpenAPI 契约：

# 文件路径：api/order-service.yaml openapi: 3.0.0 info: title: Order Service Business API version: 1.0.0 description: 电商订单业务 API，供人类开发者和 AI Agent 统一调用。 paths: /orders: get: summary: 查询订单列表 operationId: listOrders description: 可按订单状态或客户 ID 过滤订单，适合处理“有哪些待发货订单”等查询场景。 parameters: - name: status in: query required: false schema: type: string enum: [CREATED, PAID, SHIPPED, COMPLETED, CANCELLED, REFUNDED] description: 按订单状态过滤 - name: customerId in: query required: false schema: type: string description: 按客户 ID 过滤 responses: '200': description: 订单列表 content: application/json: schema: type: array items: $ref: 'https://example.com/business/order.schema.json' post: summary: 创建订单 operationId: createOrder description: 创建一笔新订单，订单状态必须为 CREATED，且至少包含一个明细行。 requestBody: required: true content: application/json: schema: $ref: 'https://example.com/business/order.schema.json' responses: '201': description: 创建成功

这份 OpenAPI 既可以直接提供给人类前端团队联调，也可以导入到支持 OpenAPI 的 Agent 平台，自动生成 AI 可调用的工具。$ref引用同一份实体 Schema，是实现“单一事实源”的关键手法。

4.6 编写 AI 消费示例

下面编写两个脚本。第一个负责校验订单数据是否符合实体 Schema：

# 文件路径：scripts/validate_order.py import json import sys from pathlib import Path from jsonschema import Draft202012Validator def load_json(path: Path): return json.loads(path.read_text(encoding="utf-8")) def main(): if len(sys.argv) != 5: print("用法：python validate_order.py --order <订单json> --schema <schema.json>") sys.exit(1) args = sys.argv[1:] order_path = Path(args[args.index("--order") + 1]) schema_path = Path(args[args.index("--schema") + 1]) if not order_path.exists() or not schema_path.exists(): print("文件不存在，请检查路径") sys.exit(1) order = load_json(order_path) schema = load_json(schema_path) validator = Draft202012Validator(schema) errors = sorted(validator.iter_errors(order), key=lambda e: list(e.path) if e.path else []) if errors: print("校验失败：") for err in errors: path_str = ".".join(str(p) for p in err.path) or "<root>" print(f" - {path_str}: {err.message}") sys.exit(1) print("订单数据通过业务模型校验") if __name__ == "__main__": main()

第二个脚本演示如何把业务模型转化为 AI 可读上下文和工具描述：

# 文件路径：scripts/ai_assistant.py import json from pathlib import Path import yaml def load_business_context( base_dir: str = "business", glossary_path: str = "business/glossary.yaml", rules_path: str = "business/rules/order-rules.yaml", ) -> str: """把术语表、状态机汇总为 AI 可读的上下文文本。""" glossary = yaml.safe_load(Path(glossary_path).read_text(encoding="utf-8")) order_rules = yaml.safe_load(Path(rules_path).read_text(encoding="utf-8")) lines = [] lines.append("你是订单业务域 AI 助手。请严格遵循以下业务模型：") lines.append("\n===== 领域术语 =====") for item in glossary["terms"]: aliases = "、".join(item.get("aliases", [])) definition = item["definition"].strip().replace("\n", " ") lines.append(f"- {item['term']}（{aliases}）：{definition}") lines.append("\n===== 订单状态机 =====") for t in order_rules["transitions"]: lines.append( f"- {t['from']} -> {t['to']}，事件：{t['event']}，条件：{t['condition']}" ) return "\n".join(lines) def build_order_tool_schema(): """把业务 API 转换为 Function Calling Schema，供 LLM 平台使用。""" return [ { "type": "function", "function": { "name": "list_orders", "description": "查询符合条件的订单列表，适合回答“有哪些待发货订单”之类的问题。", "parameters": { "type": "object", "properties": { "status": { "type": "string", "enum": ["CREATED", "PAID", "SHIPPED", "COMPLETED", "CANCELLED", "REFUNDED"], "description": "按订单状态过滤", }, "customerId": { "type": "string", "description": "按客户 ID 过滤", }, }, }, }, }, { "type": "function", "function": { "name": "create_order", "description": "创建一笔新订单。使用前必须确认至少存在一个明细行，状态固定为 CREATED。", "parameters": { "type": "object", "properties": { "customerId": {"type": "string"}, "items": { "type": "array", "items": { "type": "object", "properties": { "sku": {"type": "string"}, "quantity": {"type": "integer", "minimum": 1}, }, }, }, }, "required": ["customerId", "items"], }, }, }, ] if __name__ == "__main__": print("===== AI 可读业务上下文 =====") print(load_business_context()) print("\n===== Function Tool Schema =====") print(json.dumps(build_order_tool_schema(), ensure_ascii=False, indent=2))

真实项目中，build_order_tool_schema可以由 OpenAPI 文件自动生成，不需要手写。这里手写是为了让读者直观看到 AI 最终拿到的结构长什么样。

4.7 运行与验证

准备一份合法订单数据data/order.example.json：

{ "orderId": "SO20250501001", "customer": { "customerId": "C10001", "name": "张三" }, "status": "CREATED", "items": [ { "sku": "SKU-001", "quantity": 2, "unitPrice": 199.0 } ], "totalAmount": 398.0 }

再准备一份非法订单数据data/order.invalid.json：

{ "orderId": "SO20250501002", "customer": { "customerId": "C10001" }, "status": "PAID", "items": [], "totalAmount": -50.0 }

非法数据缺少客户名称、明细为空、总金额为负数，同时状态直接是 PAID，属于典型的不符合业务模型的数据。

运行校验脚本：

cd business-model-demo python scripts/validate_order.py \ --order data/order.example.json \ --schema business/entities/order.schema.json python scripts/validate_order.py \ --order data/order.invalid.json \ --schema business/entities/order.schema.json

预期第一次校验输出：

订单数据通过业务模型校验

预期第二次校验输出类似：

校验失败： - totalAmount: -50.0 小于最小值 0 - items: [] 短于最小长度 1 - status: 'PAID' 不是枚举 ['CREATED', 'PAID', ...] 中的值

运行 AI 消费脚本：

python scripts/ai_assistant.py

输出会展示 AI 拿到的业务上下文和工具定义。你可以在支持 Function Calling 的 LLM 平台中直接使用build_order_tool_schema()返回的列表，也可以把load_business_context()的结果拼进 system prompt。

5. 常见问题与排查思路

在给团队和客户落地这套方案的过程中，以下问题出现频率最高。

一个常见的误区是：只把业务模型当成“给 AI 读的说明书”。实际上，同一份模型可以同时驱动前端表单校验、后端参数校验、接口文档生成和 AI 工具定义。如果你发现某个消费方和模型不同步，第一件事不是改消费方的临时代码，而是检查为什么模型变更没有自动传播。

排查这类问题，我一般按下面的顺序来：

1. 检查模型文件是否已正确更新且通过版本管理；
2. 检查消费脚本是否重新生成或重新加载了模型；
3. 用校验脚本跑一遍样例数据，确认 Schema 本身没问题；
4. 检查 AI 平台是否使用了旧的工具定义或缓存。

6. 最佳实践与工程建议

把“一次建模，双端复用”落到生产环境，需要从工程上建立一套可持续的机制，而不只是写几个 YAML 文件。

6.1 把业务模型当成代码来管理

业务模型文件应该进入 Git 仓库，走代码评审流程。术语表、实体 Schema、状态机文件都应当有版本号。模型变更时，关联的 API 文档、AI Prompt、数据库映射脚本要同步评估影响面。

每次变更建议写清晰的 changelog，例如：

version: 1.1.0 changes: - "新增 REFUNDED 状态，允许已支付订单在售后审核通过后退款" - "新增字段 totalAmount 只读约束"

6.2 为 AI 消费场景设计描述信息

JSON Schema 本身并不要求写description，但面向 AI 消费时，description几乎是模型里最重要的字段。它直接影响 LLM 对字段语义的理解，进而影响工具参数生成的正确性。

写description有几个技巧：

• 说明业务含义，而不是重复字段名；
• 说明取值边界或生成约束；
• 说明与其他字段的关系；
• 对 AI 特别容易混淆的状态、别名，给出判断提示。

6.3 用工具保证模型一致性

人工同步多个文件总会有纰漏。建议在 CI 中增加一条检查：读取实体 Schema 中的status枚举，与状态机文件中的states做比对；读取 OpenAPI 中的enum，与实体 Schema 比对。任何不一致直接让流水线失败。

更进一步的方案是：从实体 Schema 自动生成部分 OpenAPI 定义，而不是手写两遍。这样“单点定义，多点引用”才能落到实处。

6.4 给 AI 工具调用设置安全边界

这是生产环境中优先级最高的一点。AI Agent 能够调用业务 API，不代表它拥有无限制的操作权限。

需要明确：

• AI 工具在执行写操作前，必须经过身份认证和权限校验；
• 状态类变更必须经过业务规则引擎校验，不能只靠 Prompt 约束；
• 所有 AI 触发的操作都应该有审计日志，记录调用来源、参数和结果；
• 涉及退款、取消、删除、金额变更等敏感操作，建议加入人工审批环节。

“让 AI 更智能”和“让 AI 更安全”不矛盾。模型的语义越清晰，安全校验越容易做。

6.5 设计模型演进机制

业务会变，模型也会变。建议在早期就考虑模型演进机制。

比较保守且实用的做法是：

• 兼容性变更（新增可选字段、新增枚举值）直接升级小版本；
• 破坏性变更（改字段名、改必填项、删除枚举值）必须走专项评审，并在模型文件中标注迁移逻辑；
• 为 AI 消费方提供“模型生效时间”元数据，避免线上 Agent 还在使用旧模型。

6.6 让业务同学参与模型评审

业务建模不是纯技术工作。术语表的准确性、状态条件的合理性，都需要业务同学确认。建议在每次模型变更后，把 YAML 文件渲染成人类可读的 Markdown 或表格，发给业务方走读确认。让业务同学看到“这份模型能被 AI 理解”，他们才会愿意持续维护。

7. 总结与下一步学习建议

本文围绕“Model your business once – for humans and AI alike”展开，介绍了业务模型作为人与 AI 共同消费的单一事实源这一核心思路。我们完成了电商订单领域的术语表、实体 Schema、状态机和 OpenAPI 契约的定义，并用 Python 脚本演示了模型校验和 AI 上下文生成两个典型消费场景。

如果你现在开始在自己的项目里实践这套方法，我建议按以下节奏推进：

1. 先从一个小领域开始，比如订单、支付或用户，只定义术语表和实体 Schema；
2. 接入一个 AI 消费场景，比如让 Agent 基于 Schema 做工具调用；
3. 逐步加入状态机、规则校验和 CI 一致性检查；
4. 当模型稳定后，再把文档生成、前端校验等消费方接入同一份模型。

下一步可以学习的方向包括：领域驱动设计（DDD）中的聚合与事件风暴、知识图谱与本体建模、OpenAPI 工具的自动生成方案，以及主流 LLM 平台的 Function Calling 和 Tool Use 机制。这些内容都会加深你对“人和 AI 共用模型”的理解。

如果你也在搭建类似的企业级业务模型，建议从最小闭环开始：一份术语表、一个实体 Schema、一个 AI 工具定义。跑通之后，再逐步扩展。模型的价值不在于一次性设计得多完美，而在于后续每次业务变化时，能让所有“读者”保持一致。