ERDL 快速入门指南

准备工作

确保你已经完成以下步骤：

• 已部署 OpenOBA 开源原型（参见 部署指南）
• 确认 erdl/ 目录存在（项目根目录下）
• 有一个文本编辑器（VS Code 推荐）

Step 1：创建 ERDL 文件

在 erdl/ 目录下新建文件，命名规范：行业名.erdl。例如：

# 文件路径: erdl/my-retail.erdl

namespace: industry.my_retail
version: "1.0.0"
name: "我的零售系统定义"

Step 2：定义实体（Entity）

实体对应你的业务对象。每个实体在系统中会自动生成对应的数据表、API 和前端表单。

entity Product:
  productName: String!           # ! 表示必填
  description: String            # 无 ! 表示可选
  price: Float!
  category:
    type: String!
    enum: [ELECTRONICS, CLOTHING, FOOD, OTHER]

类型说明：

类型	说明	示例
String!	必填字符串	商品名称
String	可选字符串	备注
Int!	必填整数	库存数量
Float!	必填小数	零售价
Boolean	布尔值	是否上架

Step 3：添加行业别名（Alias）

别名将你行业内的"黑话"映射为标准字段名。Agent 听到用户说"售价"时，自动翻译为 retailPrice。

aliases:
  Product:
    售价: retailPrice
    货号: productCode
    上架时间: listingDate

Step 4：声明可执行操作（Action）

Action 告诉 Agent 它可以对这个实体做什么。

actions:
  create_product:
    description: "创建新商品"
    params:
      productName: String!
      price: Float!
      category: CategoryEnum!
    requireApproval: true          # 需要人工确认

  update_price:
    description: "调整商品价格"
    params:
      productCode: String!
      newPrice: Float!
    操作约束（可选，定义业务规则边界）

Step 5：保存 & 验证

保存文件（Ctrl+S）后，系统将自动：

1. 解析 ERDL 文件
2. 注册到 ERDL Registry
3. 生成对应的数据库迁移
4. Agent 即时可使用新定义

你可以在管理后台的 ERDL 管理 页面看到已加载的文件及其状态。

常见问题

修改 .erdl 文件需要重启吗？

不需要。ERDL 支持 Hot Reload，保存即生效。

我可以定义多少个 Entity？

无限制。每个 Entity 对应一张数据表。

enum 里的值可以修改吗？

可以修改，但新增值和删除已有值需要谨慎——删除已有枚举值可能影响已有数据。

Action 支持哪些约束？

支持声明式定义操作参数的合法范围和业务边界条件。详细语法请参阅技术白皮书。