AuraBoot
免费开始
English简体中文

Plugin Development

Plugin 管理器 — 已安装插件

Plugin 是 AuraBoot 业务能力的打包单元。一个 Plugin 可以包含 Model、字典、Command、Page、Menu、Permission、数据源、i18n 文件以及可选的后端或前端扩展。

对于大多数业务模块,先从 Config-only Plugin 开始。仅当模块需要无法用 DSL 资源表达的行为时,再添加 Java 或 React 扩展。

Plugin 内容

plugins/crm-starter/
  plugin.json
  config/
    models.json
    fields/
    commands/
    pages/
    dicts.json
    named-queries/
    menus.json
    permissions.json
    roles.json
    i18n.json
资源用途
plugin.jsonManifest、版本、依赖、资源位置
config/models.json业务数据结构
config/fields各 Model 的字段定义(按 Model 拆文件)
config/commands创建、更新、删除、流转或自定义操作
config/pagesList、Form、Detail 与 Dashboard schema
config/dicts.json用于下拉与状态的受控取值
config/named-queries供 Dashboard 或报表使用的查询定义
config/menus.json导航入口
config/permissions.json访问控制定义
config/roles.json初始 Role 与 Permission 分配
config/i18n.json本地化 label

Manifest

{
  "pluginId": "com.example.crm-starter",
  "namespace": "crm",
  "version": "1.0.0",
  "displayName:en": "CRM Starter",
  "description": "Lead and account management module",
  "author": "Example Team",
  "minPlatformVersion": "1.0.0",
  "dependencies": [],
  "resourceDirs": {
    "models": "config/models.json",
    "fields": "config/fields",
    "commands": "config/commands",
    "pages": "config/pages",
    "dicts": "config/dicts.json",
    "menus": "config/menus.json",
    "permissions": "config/permissions.json",
    "roles": "config/roles.json"
  }
}

使用稳定的 pluginId。它会参与升级、依赖与市场相关行为。使用 namespace 让 Model、Command、Page 与 Permission 的 code 保持有组织。

开发流程

Create manifest
  -> add dictionary values
  -> add models
  -> add commands
  -> add pages
  -> register menus and permissions
  -> validate plugin
  -> publish plugin
  -> verify generated UI

这种顺序能尽早发现错误。不要等到最后才一次性导入所有资源。

示例 Task Model

{
  "code": "pm_task",
  "displayName:en": "Task",
  "modelType": "entity",
  "modelCategory": "entity",
  "fields": [
    { "code": "title", "displayName:en": "Title", "dataType": "string", "constraints": { "required": true, "maxLength": 200 } },
    { "code": "description", "displayName:en": "Description", "dataType": "text" },
    { "code": "status", "displayName:en": "Status", "dataType": "enum", "dictCode": "pm_task_status", "defaultValue": "todo" },
    { "code": "priority", "displayName:en": "Priority", "dataType": "enum", "dictCode": "pm_task_priority", "defaultValue": "medium" },
    { "code": "assignee", "displayName:en": "Assignee", "dataType": "reference", "referenceModelCode": "sys_user", "refTarget": { "targetModel": "sys_user", "targetField": "id" } },
    { "code": "due_date", "displayName:en": "Due Date", "dataType": "date" }
  ]
}

示例 create Command

{
  "code": "pm:create_task",
  "displayName:en": "Create Task",
  "type": "create",
  "modelCode": "pm_task",
  "inputFields": [
    "title",
    "description",
    "priority",
    "assignee",
    "due_date"
  ],
  "autoSetFields": {
    "status": {
      "strategy": "fixed_value",
      "value": "todo"
    }
  },
  "permissions": [
    "pm.task.manage"
  ]
}

示例列表 Page

{
  "pageKey": "pm_task_list",
  "modelCode": "pm_task",
  "kind": "list",
  "schemaVersion": 4,
  "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": 120, "renderType": "tag", "dictCode": "pm_task_status" },
        { "field": "priority", "width": 120, "renderType": "tag", "dictCode": "pm_task_priority" },
        { "field": "assignee", "width": 160 },
        { "field": "due_date", "width": 140, "sortable": true }
      ],
      "searchFields": [
        "title"
      ]
    }
  ],
  "name:en": "Tasks",
  "title": { "zh-CN": "任务列表", "en": "Tasks" }
}

校验与发布

尽量使用 CLI:

aura plugin validate plugins/my-plugin
aura plugin publish plugins/my-plugin --yes

校验应当能捕获 schema 漂移、缺失引用、非法 Command code、Menu 与 Permission 不匹配以及缺失的资源文件。

验证清单

发布 Plugin 后:

  1. 确认 Plugin 出现在 Plugin 列表中。
  2. 确认目标 Role 看得到 Menu。
  3. 从 Menu 打开列表 Page,而不仅仅是用 URL。
  4. 通过自动生成的表单创建一条记录。
  5. 编辑该记录。
  6. 用非管理员 Role 验证 Permission。
  7. 查看后端日志中的导入警告。

何时引入代码

需要后端扩展的场景:

  • 自定义 Command Handler 逻辑
  • Event Listener
  • 外部 API 集成
  • 无法用配置表达的复杂校验

需要前端扩展的场景:

  • 专用可视化
  • 自定义编辑器
  • 自定义 Dashboard Block
  • 非标准 Workflow 操作面

默认路径保持配置优先。它更易校验、评审与升级。

后续步骤