创建你的第一个 Model

本教程贯穿 AuraBoot 第一个有用的开发回路:定义 Model、添加 Field、创建 Command、渲染 Page,并在浏览器中验证结果。示例刻意做得很小,但它使用的概念与更大型的 CRM、ERP 和 Workflow 模块完全一致。

你将构建一个简单的 Task 模块。

你将创建什么

资源	Code	用途
Model	`pm_task`	存储 Task 记录
Dictionary	`pm_task_status`	控制 Task 生命周期取值
Commands	`pm:create_task`、`pm:update_task`、`pm:complete_task`	安全地变更 Task 记录
Page	`pm_task_list`	以列表形式展示 Task
Permissions	`pm.task.*`	控制访问
Menu	`pm_tasks`	增加导航入口

第 1 步:定义状态值

为 Task 状态创建字典:

{
  "code": "pm_task_status",
  "name": "Task Status",
  "name:zh-CN": "任务状态",
  "dictType": "static",
  "items": [
    { "value": "todo", "label": "To Do", "label:zh-CN": "待办", "sortNo": 10, "status": "enabled", "extension": { "color": "#3b82f6" } },
    { "value": "in_progress", "label": "In Progress", "label:zh-CN": "进行中", "sortNo": 20, "status": "enabled", "extension": { "color": "#f59e0b" } },
    { "value": "done", "label": "Done", "label:zh-CN": "已完成", "sortNo": 30, "status": "enabled", "extension": { "color": "#10b981" } }
  ]
}

将出现在表单、过滤、Badge、Dashboard 和 Workflow 中的取值统一收敛到字典里。

第 2 步:定义 Model

创建 models/pm_task.json:

{
  "code": "pm_task",
  "name:zh-CN": "任务",
  "name:en": "Task",
  "modelType": "entity",
  "modelCategory": "entity",
  "fields": [
    { "code": "title", "name": "Title", "dataType": "string", "required": true },
    { "code": "description", "name": "Description", "dataType": "text" },
    { "code": "status", "name": "Status", "dataType": "enum", "dictCode": "pm_task_status", "required": true },
    { "code": "assignee", "name": "Assignee", "dataType": "reference", "referenceModelCode": "sys_user" },
    { "code": "due_date", "name": "Due Date", "dataType": "date" }
  ]
}

该 Model 为 AuraBoot 提供了创建存储、校验字段类型与渲染控件所需的信息。

第 3 步:创建 Command

为新 Task 创建 Command:

{
  "code": "pm:create_task",
  "displayName:zh-CN": "新建任务",
  "displayName:en": "Create Task",
  "type": "create",
  "modelCode": "pm_task",
  "inputFields": ["title", "description", "assignee", "due_date"],
  "autoSetFields": {
    "status": { "strategy": "fixed_value", "value": "todo" }
  },
  "permissions": ["pm.task.create"]
}

创建一个 update Command:

{
  "code": "pm:update_task",
  "displayName:zh-CN": "编辑任务",
  "displayName:en": "Update Task",
  "type": "update",
  "modelCode": "pm_task",
  "inputFields": ["title", "description", "status", "assignee", "due_date"],
  "permissions": ["pm.task.update"]
}

创建一个状态流转 Command:

{
  "code": "pm:complete_task",
  "displayName:zh-CN": "完成任务",
  "displayName:en": "Complete Task",
  "type": "state_transition",
  "modelCode": "pm_task",
  "stateField": "status",
  "fromStates": ["todo", "in_progress"],
  "toState": "done",
  "permissions": ["pm.task.complete"]
}

create Command 设置默认状态。complete Command 强制执行生命周期规则,而不是允许任意状态更新。

第 4 步:创建列表 Page

创建 pages/pm_task_list.json:

{
  "pageKey": "pm_task_list",
  "modelCode": "pm_task",
  "kind": "list",
  "schemaVersion": 4,
  "name:zh-CN": "任务",
  "name:en": "Tasks",
  "layout": { "type": "stack" },
  "blocks": [
    {
      "id": "pm_task_toolbar",
      "blockType": "toolbar",
      "buttons": [
        {
          "code": "create",
          "primary": true,
          "permissionCode": "pm.task.manage",
          "label": { "zh-CN": "新建任务", "en-US": "New Task" },
          "action": { "type": "navigate", "to": "pm_task_form" }
        }
      ]
    },
    {
      "id": "pm_task_table",
      "blockType": "table",
      "columns": [
        { "field": "title", "width": 260, "sortable": true },
        { "field": "status", "width": 140 },
        { "field": "assignee", "width": 160 },
        { "field": "due_date", "width": 140 }
      ],
      "searchFields": ["title"]
    }
  ]
}

第 5 步:注册 Permission 与 Menu

创建 Permission:

[
  { "code": "pm.task.view", "name:zh-CN": "查看任务", "name:en": "View Tasks", "resourceType": "data", "module": "pm" },
  { "code": "pm.task.create", "name:zh-CN": "新建任务", "name:en": "Create Tasks", "resourceType": "operation", "module": "pm" },
  { "code": "pm.task.update", "name:zh-CN": "编辑任务", "name:en": "Update Tasks", "resourceType": "operation", "module": "pm" },
  { "code": "pm.task.complete", "name:zh-CN": "完成任务", "name:en": "Complete Tasks", "resourceType": "operation", "module": "pm" }
]

创建 Menu 入口:

[
  {
    "code": "pm_tasks",
    "name:zh-CN": "任务",
    "name:en": "Tasks",
    "type": 1,
    "path": "/p/c/pm_task_list",
    "icon": "IconChecklist",
    "permissionCode": "pm.task.view",
    "orderNo": 100,
    "visible": true
  }
]

第 6 步:校验并发布

导入前运行校验:

aura plugin validate plugins/project-tracker

然后发布:

aura plugin publish plugins/project-tracker --yes

第 7 步:在浏览器中验证

发布之后:

刷新应用。
打开 Tasks 菜单项。
创建一个 Task。
确认它出现在列表中。
编辑该 Task。
完成该 Task,并确认状态变更为 done。

如果菜单缺失,请检查 Permission 与 bootstrap 分配。如果页面加载但缺少列,请将 Page 字段 code 与 Model 对齐。

你学到了什么

你创建了 AuraBoot 业务模块的核心资源:

Model 定义数据。
Dictionary 控制状态取值。
Command 定义合法操作。
Page 渲染 Model。
Permission 与 Menu 入口让模块可被使用。

接下来,阅读 Config-only Plugins,将其打包为可复用的模块。