AuraBoot
免费开始
English简体中文

Command

Command 是 AuraBoot 的操作层。每个有意义的业务动作都表达为一个 Command:创建 Lead、更新订单、提交审批请求、关闭工单、发送 Webhook、归档记录等。

之所以存在 Command 模型,是因为业务应用很少只需要原始 CRUD。真实操作需要校验、权限、状态守卫、审计日志、字段默认值、计算值、副作用与错误处理。AuraBoot 为这些关注点提供了一条共享的执行路径。

Command 类型

类型用途示例
create插入一条新记录Create Lead
update修改一条已存在的记录Update Opportunity
delete删除或归档一条记录Archive Task
state_transition在生命周期内推进记录Submit、Approve、Reject
custom执行自定义业务逻辑Merge Duplicates、Generate Invoice

标准数据操作使用 create、update、delete。当操作仅在特定状态下有效时,使用 state_transition。当 Handler 或扩展必须执行无法用简单字段映射表达的代码时,使用 custom。

Command 定义

{
  "code": "crm:create_lead",
  "displayName:zh-CN": "新建线索",
  "displayName:en": "Create Lead",
  "modelCode": "crm_lead",
  "type": "create",
  "inputFields": [
    "crm_lead_company",
    "crm_lead_contact_name",
    "crm_lead_contact_email",
    "crm_lead_source"
  ],
  "autoSetFields": {
    "crm_lead_status": { "strategy": "fixed_value", "value": "new" }
  }
}

Command 决定用户可以提交什么。inputFields 是用户可提交的字段编码列表,autoSetFields 则声明由系统自动填充的字段(如固定值、自增编号、当前用户、当前时间)。一个 Model 可以拥有多个 Command,每个使用不同的字段集。例如,crm:create_lead、crm:qualify_lead 与 crm:lose_lead 可同时指向相同的 Model,但执行不同的规则。

create 与 update 语义

Command 应明确表达操作意图。对于 update 与 delete 操作,调用方必须标识目标记录。对于 create 操作,目标记录在 Command 成功之前并不存在。

{
  "commandCode": "crm:update_lead",
  "operationType": "UPDATE",
  "targetRecordId": "lead_123",
  "payload": {
    "crm_lead_contact_phone": "+1-555-0100"
  }
}

这样可以避免前端以为在编辑记录、后端却把请求当作创建处理的歧义行为。

state_transition Command

state_transition Command 保护生命周期变更:

{
  "code": "crm:qualify_lead",
  "displayName:zh-CN": "标记合格",
  "displayName:en": "Qualify Lead",
  "modelCode": "crm_lead",
  "type": "state_transition",
  "stateField": "crm_lead_status",
  "fromStates": ["new", "contacted"],
  "toState": "qualified",
  "inputFields": ["crm_lead_score", "crm_lead_requirement"]
}

如果一个 Lead 已处于 lost,该 Command 应失败,而不是静默修改记录。这一行为是刻意为之:无效的状态流转是业务错误,而不是可恢复的 UI 提示。

Field 行为

Command 通过两个属性声明数据如何被接收:inputFields 列出客户端可提交的字段编码,autoSetFields 声明由系统自动填充的字段及其策略。客户端无法直接设置 autoSetFields 中的字段,从而保证审计与一致性。

autoSetFields 支持的策略:

策略含义
fixed_value固定常量,始终覆盖请求中的值(需配 value)
default_value默认常量,仅当请求未提供该字段时生效(需配 value)
auto_generate按 pattern 自动生成编号(如 LEAD-{yyyyMMdd}-{seq})
current_username当前登录用户名
current_datetime当前 UTC 时间戳

Command 让表单与后端校验保持一致。创建表单应由 create Command 生成,而非仅从原始 Model 生成。

副作用

Command 可触发后续行为:

  • 审计日志条目
  • Timeline 事件
  • 通知
  • Webhook 分发
  • 自动化规则
  • BPM 流程创建
  • 缓存失效

关键约束是副作用应附着在 Command 生命周期之上,而不是隐藏在不相关的 UI 代码中。这样操作才可测试、可审计。

Command 的执行方式

所有 Command 执行遵循同一概念路径:

请求
  -> 解析 Command
  -> 用户认证
  -> 权限授权
  -> 校验 payload
  -> 应用默认值与计算字段
  -> 执行状态守卫
  -> 写数据
  -> 审计与发布事件
  -> 返回响应

详细执行阶段见 Command Pipeline。

设计建议

  • 用「命名空间:动词_名词」命名 Command:crm:create_task、crm:submit_invoice、crm:approve_request。
  • 显式表达生命周期流转;不要用通用的 update Command 完成审批。
  • 用 inputFields 声明可提交字段,用 autoSetFields 声明系统自动填充字段(固定值、默认值、自增编号、当前用户、当前时间)。
  • 为每个 Command 配置独立权限,让角色只能执行它需要的操作。
  • 为会通知用户或外部系统的 Command 补充副作用描述。
  • 优先使用配置驱动的 Command;只有当行为无法声明式表达时才加 custom Handler。

下一步