AI摘要
本文介绍了一个面向AI的元数据定义模板（YAML版），包括领域模型元数据定义、字段级元数据、关联关系元数据、业务规则与约束以及示例代码片段。通过这个模板，AI可以更好地理解架构认知、进行业务逻辑自检和数据库迁移同步。
==========================================
领域模型元数据定义 (Domain Metadata)
版本: 1.0
设计者: Wang Dayong (Architect)
==========================================
entity_name: "Order" # 实体语义名称（AI 将以此命名类和变量）
table_name: "t_sales_orders" # 物理表名
business_domain: "Sales" # 所属业务领域
description: "处理客户购买电信服务的订单主表，是财务结算的唯一凭证"
--- 1. 字段级元数据 (Field-Level) ---
fields:
- name: "order_id"
type: "BigInt"
is_primary: true
description: "全局唯一订单编号"
ai_hint: "生成代码时作为主键，遵循 Snowflake 算法" - name: "status"
type: "Integer"
description: "订单生命周期状态"
enums:
0: "Draft (草稿) - 用户尚未确认"
1: "Paid (已支付) - 资金已到账，待开通服务"
2: "Completed (已完成) - 服务已开通"
-1: "Cancelled (已取消) - 交易终止"
ai_hint: "状态机流转只能是 0 -> 1 -> 2，且只有 0 可以变为 -1" - name: "total_amount"
type: "Decimal(18,2)"
description: "应付总金额"
logic: "sum(items.price * items.quantity) - discount"
ai_hint: "所有涉及金额计算的逻辑必须在此字段基础上进行验证"
--- 2. 关联关系元数据 (Relationship-Level) ---
relationships:
- target_entity: "User"
relation_type: "ManyToOne"
join_on: "user_id"
description: "下单用户" - target_entity: "OrderItem"
relation_type: "OneToMany"
join_on: "order_id"
description: "订单详情行项"
--- 3. 业务规则与约束 (Business Rules & Constraints) ---
这是 AI 最喜欢的部分，能极大减少逻辑错误
business_rules:
- name: "Refund_Policy"
rule: "状态为 Completed 且超过 7 天的订单不允许发起退款"
severity: "Critical" - name: "Security_Constraint"
rule: "查询时必须强制关联 current_user_id，严禁越权访问"
--- 4. 示例代码片段 (Few-Shot Prompting) ---
给 AI 一个参考，让它模仿你的编程风格（如 Delphi 或 Python）
coding_style_reference: |
// 预期生成的代码风格示例
if Order.Status = osPaid then
ExecuteProvisioning(Order.ID);
面向AI编程的好处：
“喂”给 AI 做架构认知
对话示例：
“@order_metadata.yaml 这是我定义的订单元数据。请根据这个定义，帮我写出 FastAPI 的 models.py 和对应的 Pydantic schemas.py。注意，状态枚举值请使用 Python Enum 类实现。”
进行业务逻辑自检
对话示例：
“我要写一个退款接口，请参考 @order_metadata.yaml 里的 business_rules，确保我的接口逻辑没有违反业务约束。”
数据库迁移同步
对话示例：
“根据 @order_metadata.yaml 的字段定义，帮我写出 Alembic (Python) 或 SQL 的 DDL 变更脚本，并自动加上字段 Comment。”
