Commands

Commands are the operation layer in AuraBoot. Every meaningful business action is represented as a command: create a lead, update an order, submit an approval request, close a ticket, send a webhook, or archive a record.

The command model exists because business applications rarely need raw CRUD alone. Real operations need validation, permissions, state guards, audit logs, field defaults, computed values, side effects, and error handling. AuraBoot gives those concerns one shared execution path.

Command types

Use create, update, and delete for standard data operations. Use state_transition when the operation should only be valid from specific states. Use custom when a handler or extension must run code that cannot be expressed as simple field mapping.

Command definition

{
  "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" }
  }
}

The command decides what the user is allowed to provide. inputFields is the list of field codes the client may submit; autoSetFields declares the fields the system fills in (fixed values, auto-generated codes, the current user, the current time). A model can have many commands with different field sets — for example, crm:create_lead, crm:qualify_lead, and crm:lose_lead can all target the same model while enforcing different rules.

Create vs update semantics

Commands should be explicit about operation intent. For update and delete operations, the caller must identify the target record. For create operations, the target record is absent until the command succeeds.

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

This avoids ambiguous behavior where the frontend thinks it is editing a record but the backend treats the request as a create.

State transition commands

State transition commands protect lifecycle changes:

{
  "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"]
}

If a lead is already lost, this command should fail instead of silently changing the record. That behavior is intentional: invalid state transitions are business errors, not recoverable UI hints.

Field behavior

A command declares how data is accepted through two properties: inputFields lists the field codes a client may submit, and autoSetFields declares the fields the system fills in along with their strategy. The client cannot set the fields in autoSetFields directly, which keeps audit and consistency intact.

Strategies supported by autoSetFields:

Commands keep forms and backend validation aligned. A create form should be generated from a create command, not from the raw model alone.

Side effects

Commands may trigger follow-up behavior:

• Audit log entries
• Timeline events
• Notifications
• Webhook dispatch
• Automation rules
• BPM process creation
• Cache invalidation

The important constraint is that side effects should be attached to the command lifecycle, not hidden in unrelated UI code. That makes operations testable and auditable.

How commands are executed

All command execution follows the same conceptual path:

Request
  -> resolve command
  -> authenticate user
  -> authorize permission
  -> validate payload
  -> apply defaults and computed fields
  -> enforce state guards
  -> write data
  -> audit and publish events
  -> return response

For the detailed execution stages, read Command Pipeline.

Design guidelines

• Name commands namespace:verb_noun: crm:create_task, crm:submit_invoice, crm:approve_request.
• Keep lifecycle transitions explicit; do not use generic update commands for approvals.
• Declare submittable fields with inputFields and system-filled fields with autoSetFields (fixed values, defaults, auto-generated codes, current user, current time).
• Use a dedicated permission per command so roles can execute only the operations they need.
• Add side-effect descriptions for commands that notify users or external systems.
• Prefer config-first commands; add custom handlers only when the behavior cannot be declared.

Next steps

• Command Pipeline
• BPM Workflows
• Webhooks