# llc CLI contract (commands and options)

Command tree, options, spec-string syntax and exit codes for `llc` (lan-low-code-cli).
`llc <command> --help` and actual behaviour are authoritative.

## 1. Invocation

```bash
llc <group> <subcommand> [options]
llc help [command...]        # multi-level, e.g. llc help form create
llc -v | --version
```

- Global options `--base-url <url>` / `--token <token>` work before or after the subcommand
  (root options are forwarded via a `preAction` hook).
- Precedence: `--base-url`/`--token` > `LLC_BASE_URL`/`LLC_TOKEN` > `./lcode.config.json` (cwd) >
  `~/.lcode/config.json` (written by `llc config set`). `timeout` defaults to `30000` ms.
- Most commands accept `--json` for script-friendly output.
- Exit codes: `0` success (including `--help`/`--version`); `1` failure (arguments, validation, API).
  `LLC_DEBUG=1` also prints the stack.
- Destructive commands (`app|form delete`, `app|form delete-data`, `flow delete`, `flow disable`) require
  `--yes`; without it the CLI only warns and does **not** execute. `flow apply` also needs `--yes` —
  by default it only prints the payload.
- An unknown `llc help` path prints `未知命令：llc ...` and exits `1`.

## 2. config

| Command | Options | Notes |
|---|---|---|
| `llc config set` | `--base-url <url>` `--token <token>` `--timeout <ms>` `--default-form-type <n>` | merges into the global config; with no options it only prints usage |
| `llc config show` | — | JSON: global/project config paths, baseUrl, masked token (`abcd****wxyz`), timeout, defaultFormType, controlMapKeys, env vars |
| `llc config clear` | `--all` | clears `baseUrl`/`token`; `--all` also `timeout`/`defaultFormType`/`controlMap` |

## 3. app

| Command | Required | Optional | Notes |
|---|---|---|---|
| `llc app list` | — | `--keyword <name>` `--no-auth` `--json` | columns `fdId/应用名称/应用编码/状态`; `fdId` is the `--app-id`; `--no-auth` uses the no-auth endpoint |
| `llc app get` | `--id <fdId>` | `--json` | detail (code/description/visitors/maintainers) |
| `llc app create` | `--name <name>` | `--code <code>` `--desc <text>` `--category <fdId>` `--icon <name\|json>` `--order <n>` `--json` | backend also creates the default home page; `--json` returns `{fdId}` |
| `llc app update` | `--id <fdId>` | `--name` `--code` `--desc` `--category` `--icon` `--order` | loads the detail first, then patches; warns if nothing to change |
| `llc app forms` | `--id <fdId>` | `--json` | forms under the app (preview before delete) |
| `llc app delete` | `--id <fdId>` `--yes` | — | lists the forms that will be deleted along with the app |
| `llc app delete-data` | `--id <fdId>` `--yes` | — | deletes business data only |

`--code` must match `^[a-zA-Z0-9-]+$` (letters/digits/hyphen; **no underscore**).

## 4. form

| Command | Required | Optional | Notes |
|---|---|---|---|
| `llc form create` | `--name <name>` | see groups below | creates the form and generates field config from the data model |
| `llc form list` | — | `--keyword <kw>` `--page-no <n>=1` `--page-size <n>=20` `--json` | **`generalFormDefine` only (approval-opinion forms)**; use `app forms` for app forms |
| `llc form get` | `--id <fdId>` | `--with-config` `--json` | reads modeling → general → design; prints JSON by default |
| `llc form publish` | `--id <fdId>` | `--api <family>` `--desc <text>` | modeling uses `saveDesignAndPublish` |
| `llc form autofill` | `--id <fdId>` | field groups + `--apply` `--publish` `--from-model` `--icon` | rebuilds field config from the data model; **without `--apply` it only previews** |
| `llc form category-list` | — | `--json` | form categories (max 1000) |
| `llc form delete` | `--id <fdId>` `--yes` | — | deletes the data model too (irreversible) |
| `llc form delete-data` | `--id <fdId>` `--yes` | — | runtime data only |

`create` / `autofill` share these option groups:

- **Basics** (create only): `--code <code>` (auto-generated by default), `--type <type>`, `--source-form-id <fdId>` (required for `type=refer`), `--category <fdId>`, `--readers <ids>`, `--editors <ids>`, `--icon <icon>`.
- **API family** (create only): `--api auto|modeling|general|design`, `--app-id <appId>`, `--fd-entity-id` `--fd-entity-name` `--fd-entity-key` `--fd-run-entity-name`, `--table-name`, `--group-id`, `--edit-draft`/`--no-edit-draft`, `--reader-flag`, `--data-source-id`, `--outer-mapping`, `--mechanism-entity-name` `--mechanism-entity-code`.
- **Fields**: `--from-model <fdId>`, `--fields <names>`, `--add-field <spec>`, `--option <spec>`, `--org-type <spec>`, `--detail <spec>`, `--include-system`.
- **Layout**: `--per-row <n>` (default 2), `--span <n>`, `--layout rows|grid|tabs`, `--grid-columns <n>`, `--tabs <spec>`, `--tab-layout rows|grid`.
- **Permissions**: `--required <fields>` `--readonly <fields>` `--hidden <fields>`, `--auth-file <path>`.
- **Actions / relations**: `--action <spec>`, `--action-file <path>`, `--relation <spec>`.
- **i18n**: `--locale <locales>`, `--lang-file <path>`.
- **Execution**: `--no-config`, `--dry-run` (create only; prints the request body), `--publish`, `--force` (skip required-prop validation), `--json`.

`--api auto` rules: `--app-id` given → `modeling`; `--type` omitted or `general` → `general`; otherwise `design`.
The `general` family only supports `general` (approval-opinion) forms; `modeling` requires `--app-id`;
`type=refer` does not store `fdConfig`.
`--type` values: `common|general|config|modal|template|refer` (or `1..6`; Chinese names also work).

### 4.1 Category forms / simple category forms (`--type category|simpleCategory`)

Uses the `categoryModel` family (`/data/sys-modeling/categoryModel/`), independent from normal forms:

| `--type` | `fdType` | Tables | Notes |
|---|---|---|---|
| `category` (alias `categoryForm`) | 1 | category + template + main | category tree with multiple templates |
| `simpleCategory` (alias `simpleCategoryForm`) | 2 | polymers + main | category and template merged; always multi-level; no shared category |

```bash
llc form create --name "Purchase categories" --app-id <appId> --type category --publish
llc form create --name "Simple categories" --app-id <appId> --type simpleCategory --publish
```

- Flow: `categoryModel/init` → `categoryModel/add` → (with `--publish`: `get` + `save` + `publish`);
- Extra options: `--category-table-name` `--template-table-name` `--polymers-table-name` `--share-category <fdCode>` `--no-support-hierarchy`;
- Table names default to `sysModelingXForm/generateTableName`; `--table-name` is still the main table;
- **Limits**: category forms carry no business fields, so `--add-field` / `--fields` / `--from-model` are rejected;
  templates must be created in the platform's launch-page designer (the template table metadata is generated
  there on first save), calling `categoryTemplate/init` directly returns a null-pointer error;
- deletion is platform-only (`categoryModel/delete` rejects direct client calls); `form get --id` reads category forms.

### 4.2 Category form templates (`llc template`)

| Command | Required | Optional | Notes |
|---|---|---|---|
| `llc template list` | `--category-code` | `--json` | runtime tree (category nodes + template cards) |
| `llc template create` | `--category-code` `--name` | `--from-form <fdId>` `--fields <names>` `--table-name` `--category-node <fdId>` `--category-name` `--code` `--publish` `--dry-run` `--json` | creates a template, optionally porting fields/views/permissions from an existing form |
| `llc template add-fields` | `--template-id` `--add-field` | `--category-code` `--per-row` `--keep-layout` `--publish` `--dry-run` `--json` | appends fields to an existing template; rebuilds a grid layout by default, `--keep-layout` keeps the current one |
| `llc template delete` | `--category-code` | `--template-id <fdId>` (repeatable) `--all` `--yes` `--json` | deletes templates; `--all` wipes every template of that category form |

- Category forms (`fdType=1`) use `categoryTemplate/add`; simple category forms (`fdType=2`) use `virtualPolymers/add`;
  read/write through `virtualCommonTemplate/get|save|publish`;
- **Skips the official `init`** (null pointer until the template table metadata exists): `add` carries
  `mechanisms['sys-xform'].fdBuildNew=true` so the backend creates the table, then `sys-xform/sysXFormDesign/save` writes the design;
- `--from-form` clones the source form's main-table business fields, view layout (tabs/grid) and field permissions,
  replacing table names and dropping detail nodes; `--fields` limits the ported fields;
- Category-form templates must sit under a category node: without `--category-node` one is created
  (name from `--category-name`).

## 5. operation (form business operations)

Adds buttons to a form's list/view page (the "业务操作" tab of a form). Built-in operations (`fdType=1`) are
maintained by the platform; the CLI only lists them and manages **custom** operations.

| Command | Required | Optional | Notes |
|---|---|---|---|
| `llc operation list` | `--form-id <fdId>` | `--keyword <kw>` `--page-no <n>=1` `--page-size <n>=100` `--json` | lists a form's operations (built-ins included) |
| `llc operation get` | `--id <fdId>` | `--json` | detail; prints the parsed `fdConfig` |
| `llc operation create` | `--form-id` `--name` `--code` | `--type link\|script\|dialog` **or** `--trigger-flow <flowId>`; `--position list\|view` `--need-select` `--url` `--script <code\|@file>` `--dialog-id` `--inc-params <json\|@file>` `--desc` `--mobile-icon` `--dry-run` `--json` | creates an operation definition; `--trigger-flow` binds an action flow (`fdTriggerType=3`) |
| `llc operation update` | `--id <fdId>` | `--name` `--code` `--desc` `--position` `--type` `--url` `--script <code\|@file>` `--dialog-id` `--trigger-flow <flowId>` `--inc-params` `--need-select`/`--no-need-select` `--enable`/`--disable` `--mobile-icon` `--dry-run` `--json` | edits an existing operation; `--type script` switches to script mode, `--trigger-flow` switches to action-flow trigger |
| `llc operation delete` | `--id <fdId>` `--yes` | — | checks references (`listByRefer`) and refuses while still in use |
| `llc operation attach` | `--form-id` `--operation-id` | `--target list\|view` `--view-id` `--platform desktop\|mobile` `--position top\|rightHand\|rightSide` | writes the button into the view `operationList`; auto-detects the single view when `--view-id` is omitted |
| `llc operation detach` | `--form-id` `--operation-id` | `--target list\|view` `--view-id` `--platform` | removes the button from a view (definition kept) |

`--type` (P0 supports three):

| type | fdType | fdViewType | Required | Notes |
|---|---|---|---|---|
| `link` | 2 | 4 | `--url` | open a link |
| `script` | 3 | 5 | `--script` (`@file` supported) | run a script |
| `dialog` | 3 | 1 | `--dialog-id` | run a dialog |

```bash
llc operation list --form-id <fdId>
llc operation create --form-id <fdId> --name 打开帮助 --code openHelp \
  --type link --position view --url https://example.com
llc operation create --form-id <fdId> --name 批量归档 --code archive \
  --type script --script @archive.js
llc operation get --id <operationId>
llc operation update --id <operationId> --type script --script @examples/operation-script-modal-table.js
llc operation delete --id <operationId> --yes
llc operation attach --form-id <fdId> --operation-id <operationId>            # list view / desktop / top
llc operation attach --form-id <fdId> --operation-id <operationId> --target view --position rightHand
llc operation detach --form-id <fdId> --operation-id <operationId>            # remove from list view
```

- `--code`: starts with a letter, letters/digits/underscore/hyphen only, ≤15; `--name` ≤30; `--desc` ≤500.
- New operations are **admin-only by default**; set visitors on the platform's "业务操作" page.
- No row selection is required by default (`fdListViewIdValid=false`); pass `--need-select` when the button
  must run on selected rows (for links this also sets `fdUrlType=2`, i.e. call the link as an API).
- `attach` / `detach` only touch view config: list views use `fdExtendConfig[platform].operationList`,
  view pages use `fdConfig[platform].operationList`; the whole config is saved back, so other settings and
  existing buttons are preserved, and re-attaching is idempotent.
- `--position`: `top` (toolbar), `rightHand` / `rightSide` (row actions); `--platform` accepts `desktop` / `mobile`.
- Permissions, display conditions and triggers are still out of scope; `attach` does not validate the
  operation's `fdPosition` and only warns on a mismatch.
- `--dry-run` prints the payload (`fdConfig` is a JSON string) without sending it.

## 6. field

| Command | Options | Notes |
|---|---|---|
| `llc field list` | `--form-id <fdId>` / `--model-id <fdId>` / `--table <tableName>` (at least one), `--json` | errors when all three are missing; columns 字段名/标题/数据类型/控件类型/长度/系统字段/uuid |
| `llc field library` | `--keyword <kw>` (`fdName` contains), `--page-no <n>=1`, `--page-size <n>=20`, `--json` | environment field library |
| `llc field gen-key` | `--name <name>`, `--table <table>` | generates the physical field key |

## 7. control / locale

| Command | Options | Notes |
|---|---|---|
| `llc control list` | `--kind control\|layout\|appearance` (default `control`), `--all`, `--json` | remark marks 已登记/容器类/支持选项/已废弃/需设计器配置 |
| `llc control show` | `--element <@elem/xform-xxx>` or `--type <moneytext>`, `--json` | widget metadata plus property-panel items and defaults |
| `llc locale list` | `--element <pkg>` (default `@elem/xform-input`), `--json` | returns the raw code (e.g. `zh-cn`) and the normalized code (e.g. `Cn`, usable in `--locale`); all environment locales are not exposed by any API |

## 8. Which events a control supports

`$global` actions are fixed to `onLoad` / `onBeforeSubmit` / `onAfterSubmit` (validated by the CLI).

Control-level events are defined by the **widget package implementation**. The CLI has no built-in
whitelist and does not check whether a control supports a given event: `--action` only requires a valid
identifier (`^[A-Za-z_$][\w$]*$`, e.g. `onChange`/`onFocus`/`onBlur`). An unsupported event is saved
without error but never fires, so confirm it first:

1. **Designer property panel** (authoritative): select the control in the form designer → "控件动作"
   group → event dropdown. That list is the set the control supports.
2. **Widget metadata** (auxiliary): `llc control show --element @elem/xform-<short> --json` returns the
   package `config.json` verbatim under `meta`; the CLI only parses `xform` (type/dataType/dictType, …)
   and `config` (property-panel items) and **does not parse events** — if the package happens to declare
   them (`meta.events`, `meta.xform.events`), use them directly; otherwise fall back to the other options.
   The human-readable output does not print those keys, so **use `--json`**.
3. **Inspect existing forms**: in `llc form get --id <fdId>` output, the keys of
   `fdConfig.attribute.formAttr.controlAction.control['<table>.<controlUuid>']` are the events already
   configured for that control; `llc form autofill --id <fdId> --json` (without `--apply`) previews the
   action structure that would be written.
4. **Widget frontend source**: events are the callback props the widget emits (`onChange` / `onBlur` /
   `onFocus` / `onClick`, …). Use the `@elem/xform-*` source or widget docs only if the above fails.

> §8 of `references/mkxform-api.md` (`MKXFORM.onChange/beforeSubmit/afterSubmit`) is the **runtime
> listener API**, not the same event set as control actions — do not mix them up.

## 9. Spec strings

| Option | Syntax | Notes |
|---|---|---|
| `--add-field` | `"name:label[:dataType\|controlType[:controlType]]"` | repeatable; the 3rd token accepts `varchar`/`number` or a control type such as `select`/`moneytext`; an existing field name only gets its label and control type overwritten |
| `--option` | `"field=option1,option2:value2"` | repeatable, merged per field; without `:value` values are `1..n` |
| `--org-type` | `"field=org,dept,person"` | codes `1` org / `2` dept / `4` post / `8` person / `16` user group / `256` identity; `all` = org+dept+post+person+user group |
| `--detail` | `"DetailTitle=field:label[:controlType],field2:label2"` | repeatable; an existing detail table is reused and adjusted |
| `--tabs` | `"Title:field1,field2\|Title2:field3"` | `--layout tabs` only; unlisted fields go to a trailing "其它" tab |
| `--required`/`--readonly`/`--hidden` | `"field1,field2"` | add/edit required, add/edit read-only, add/edit/view hidden |
| `--auth-file` | `{"add":{"fd_col_a":{"required":true}}}` | keys `add`/`edit`/`view`, merged with the flags above |
| `--action` | `"field:event:source"` or `"field:event:@file.js"` | repeatable; `$global` accepts only `onLoad`/`onBeforeSubmit`/`onAfterSubmit`; see §8 for how to find control events |
| `--action-file` | `{"field":{"onChange":"source"},"$global":{"onLoad":"source"}}` or `[{target,event,source,name?}]` | merged with `--action` |
| `--relation` | `"field=TargetForm[:显示值=field][:显示项=field1,field2]"` | target may be a form name or `fdId`; writes `relationCfg` + `datasource` |
| `--locale` | `"Cn,Us,Tw"` or `all` | comma-separated, **first entry is primary**; `all` = `Cn,Us,Tw` |
| `--lang-file` | `{"Us":{"姓名":"Name"}}` | inner keys may be field labels or field names; options support `field#value` |

## 10. flow (action flow / process define)

Application-scoped action flows. Every write command needs `--yes` and an explicit `--app-code`
(or `appCode` in the spec). `--json` goes to stdout; all other output goes to stderr.

| Command | Required | Key options | Notes |
|---|---|---|---|
| `llc flow spec` | — | `--app-code` `--name` `--code` `--start-way` `--category-id` `--log-detail` `--out` `--json` | prints a Flow Spec template; Start/End nodes are added by the compiler |
| `llc flow compile` | `--spec <@file\|json>` | `--layout ide\|layered\|passthrough` `--center-x` `--rank-padding` `--lane-gap` `--min-gap` `--sub-center-x` `--emit-waypoints` `--category-id` `--log-detail` `--out` `--force` `--json` | compiles to `fdDesign` (JSON string) + `basicInfo`; **offline** |
| `llc flow validate` | `--spec` | layout options, `--category-id` `--log-detail` `--json` | offline checks only; exits `1` on errors |
| `llc flow list` | `--app-code` | `--keyword` `--status draft\|stopped\|enabled` `--page-no` `--page-size` `--json` | read-only; shows category and `fdLogDetail` |
| `llc flow get` | `--id` | `--with-design` `--raw` `--json` | `--with-design` parses `fdDesign`; shows category and `fdLogDetail` |
| `llc flow category list` | `--app-code` | `--keyword` `--parent-id` `--json` | read-only |
| `llc flow category get` | `--id` | `--json` | read-only |
| `llc flow category create` | `--app-code` `--name` | `--dynamic-props <json\|@file>` `--yes` `--json` | preview by default; `--yes` writes |
| `llc flow category update` | `--id` `--name` | `--app-code` `--dynamic-props <json\|@file>` `--yes` `--json` | preview by default; `--yes` writes |
| `llc flow category delete` | `--id` `--yes` | `--json` | flows under the category move to "Unclassified" |
| `llc flow logs` | scope: `--app-code` \| `--app-id` \| `--id` | `--id` `--app-code` `--app-id` `--group` `--month` `--from-time` `--to-time` `--limit` `--offset` `--success` `--trace-id` `--endpoint` `--raw` `--json` | runtime log list; resolves `fdModule=sys-modeling:<app fdId>`, defaults to current month, Long ms time range |
| `llc flow logs get` | `--log-id` | `--group` `--endpoint` `--json` | single log detail via `sys-log/interface/get` (legacy endpoint fallback) |
| `llc flow logs relation` | `--log-id` | `--node-log-id` `--group` `--recursive` `--max-depth` `--include-detail` `--endpoint` `--json` | node relation logs; `--recursive` drills into loop/sub-canvas child logs, `--node-log-id` starts from a specific node, `--include-detail` fetches `get` per node; auto-generates `mechAuthToken` when needed |
| `llc flow schema` | `--kind` | `--entity-id` `--code` `--app-code` `--api-type` `--api-method-path` | read-only, always JSON. Kinds: `businessNodes` `events` `source` `jsonSchema` `condition` `out` `active` `event` `interface` `apiMethod` `flowBots` `meta` `dataModel` `recycle` |
| `llc flow templates` | `--from <@file\|json>` | `--out` `--json` | extracts golden node skeletons from a `get` response / compile result / design; strips `drawAttr.bounds` |
| `llc flow apply` | `--spec` `--app-code` | `--draft` `--enable` `--resolve-schema` `--strict-schema` layout options `--category-id` `--log-detail` `--force` `--yes` `--json` | **preview by default**; `--yes` calls `addPublish`/`addDraft` (or `update*` when the spec has `fdId`), then reads back |
| `llc flow diff` | `--id` `--spec` | `--no-ignore-bounds` `--resolve-schema` `--strict-schema` layout options `--category-id` `--log-detail` `--json` | compares local design with remote; ignores coordinates by default |
| `llc flow script` | `--id` | `--out` `--json` | generates a `MKXFORM.flow_<fdCode>` button script |
| `llc flow run` | `--operation-id` `--yes` | `--view-id` `--doc-id` `--doc-ids` `--inc-params` `--json` | executes a button bound to a flow via `sysModelingMain/other`; returns `success` / `responseMsg` |
| `llc flow enable` | `--id` | `--json` | `startup` |
| `llc flow disable` | `--id` `--yes` | `--json` | `stop` |
| `llc flow delete` | `--id` `--yes` | `--json` | checks `listByRefer` before deleting |

- **Categories and detailed logs**: `fdLogDetail` (record detailed logs) defaults to `true` in generated
  flows; disable it with `fdLogDetail:false` in the spec or `--log-detail off`. `--log-detail` accepts
  `on|off`, `true|false`, `1|0`, `yes|no`. `--category-id <fdId>` binds a flow to a category and, like
  `--log-detail`, overrides the spec in `spec` / `compile` / `validate` / `apply` / `diff`.
  `flow list` / `flow get` display `fdCategory` and `fdLogDetail`.
- **Runtime log query**: `flow logs` sends `QueryRequestLogExtendVO` — top-level `fdGroup`
  (default `modeling.process.log`), `conditions.fdBeginTime.$gte/$lte` as millisecond Long values,
  `conditions.fdModule = sys-modeling:<app fdId>`, and optional `conditions["fdEntity.fdId"]` for one flow.
  `groupId` / `moduleName` / `viewModuleName` are frontend `LogQuery` props, not backend fields. The CLI
  resolves `--app-code` to the app `fdId` (or reads it from `--id`), defaults to the current month, maps
  `--success on|off` to `fdSuccess "1"/"0"`, and supports `--trace-id`, `--limit`, `--offset`, `--raw`.
  Endpoint fallback: `sysModelingLog/findAllWithAppId` → `sysModelingLog/findAll` →
  `sys-log/interface/findAll` → legacy `ModelingProcessLog/findAll`. Detail uses
  `sys-log/interface/get`; relation uses `sys-log/interface/relation` and auto-fetches
  `getLogDetailToken` when needed.
- **Loop / child-node logs**: the first `relation` call only returns top-level node logs. Loop nodes are
  `BATCH_CHILD` logs whose own `fdId` can be passed to `relation` again to obtain sub-canvas logs
  (`开始` / `子动作` / `结束` per iteration). `llc flow logs relation --recursive` performs this
  recursion, `--node-log-id` starts from a specific loop node, `--include-detail` calls `get` for each
  tree node, and `--max-depth` (1–5, default 2) caps the depth. `--json` returns a normalized `tree`
  alongside the raw `relation`; non-JSON output renders an indented level tree.

**Flow Spec** (JSON — no new runtime dependency):

```json
{
  "appCode": "cli-test", "name": "My flow", "code": "flow_a",
  "startWay": "StartActiveNode", "centerX": 679, "fdLogDetail": true,
  "trigger": { "fdRunType": ["operate"], "fdFormRelation": "0", "dataType": 1,
    "inParamType": 2, "inParam": { "id": "requestBody", "type": "object", "properties": {} } },
  "nodes": [
    { "id": "N2", "type": "QueryDataNode", "name": "query",
      "config": { "target": { "entityId": "sys-modeling#<fdId>" }, "resultType": "single" } },
    { "id": "N3", "type": "BranchNode", "name": "branch" },
    { "id": "N4", "type": "TransformNode", "name": "A", "config": { "outParamType": 0 } },
    { "id": "N5", "type": "TransformNode", "name": "B", "config": { "outParamType": 0 } }
  ],
  "edges": [
    { "from": "N2", "to": "N3" },
    { "from": "N3", "to": "N4", "name": "yes", "formula": { "type": "Script", "script": "return true" } },
    { "from": "N3", "to": "N5", "name": "no", "default": true }
  ]
}
```

- `--code` must match `^[a-zA-Z0-9_]{1,30}$`; node `id` `^[0-9a-zA-Z_]{2,32}$`. Start/End nodes
  and their edges are auto-added; disconnected roots/leaves are wired automatically.
- **Layout**: `ide` (default) uses **dagre** (Sugiyama: layering → ordering → coordinates). Main chain
  centred on `--center-x` (default `679`), `BranchNode` 56×56 and others 180×38, branch successors on
  the next rank, parents centred over children, joins centred under parents, rank gap
  `--rank-padding` (default 52), same-rank gap 60. `layered` keeps the legacy rank+lane algorithm
  (branch successors on the same rank, left/right symmetric); `passthrough` keeps `bounds` from the
  spec. `drawAttr.bounds` uses top-left `x/y` with `relative:false` and is persisted verbatim by the
  IDE (it never recomputes coordinates). Branch edges get `exitX=0/1` from the actual relative x;
  multi-in/multi-out edges get `exitX`/`entryX` 0.25/0.75 to avoid sharing one anchor point.
- Branch handling: `defaultTargetRef` comes from the edge with `"default": true`; a
  `formulaConfig.branchFormulas` referencing the real line IDs is generated automatically, and branch
  edges get `exitX=0/1` anchor styles so they do not overlap in the designer.
- `--resolve-schema` fills `extraAttr.context_*` via `getSourceJsonSchema` /
  `getProcessDataOutJsonSchema`. Those endpoints require a `sys-modeling#` prefixed `entityId`
  (the CLI adds it). Failures are warnings unless `--strict-schema`.
- `fields` of `AddDataNode` / `AddOrUpdateNode` uses the platform's real shape
  (`{field:{...},value:{format,valueJson}}`); the CLI passes it through and only validates field
  names — it does **not** synthesise formulas. Use `llc flow templates` / `flow get` for golden shapes.
- **Per-node required fields** mirror the IDE rules table (`configuration/nodes/utils.tsx`) plus its
  exemptions (`validate.ts`):
  `TransformNode` requires `outParam` **and** `outputParamMapping` (`valueFormula`, or non-empty
  `pointMappings`; mapping is exempt only when `outParam` is empty);
  `ExecuteNode`/`InterfaceNode`/`SubActionNode`/`FlowBotsNode` require their code field
  (`executeCode`/`apiMethodPath`/`actionFlowCode`/`flowBotsCode`) and a mapping when an inbound
  Schema exists; `BranchNode` requires `conditionType`/`flowWay` plus the matching
  `formulaConfig`/`ruleConfig` (auto-generated when branch edges exist); `LoopNode` requires
  `loopDefine.type`; `MessageNode` validates `notifyType`/`subject`/`templateCode`/`linkPage`/`linkUrl`
  by `subjectType` and `messageLink.linkType`; `AddDataNode`/`AddOrUpdateNode` skip `flow` for
  category forms or when `commitType` is absent. Diagnostics carry `field` and `hint`; errors exit `1`.
- **Parameter mapping shorthand**: `TransformNode` accepts `config.outParam` as a field map
  (`{"fd_title":{"type":"string","description":"标题"}}`) or a full JSON Schema / Schema string, plus
  `config.mapping` as `{"targetPath":"$<nodeId>.<path>"}` (also `$context.<path>`). The compiler emits
  `outParamType=1`, `outParam` (Schema string), `outputParamMapping` (`pointMappings`) and copies the
  Schema into `extraAttr.context_outputParam`. When `mapping` is absent it is inferred from an upstream
  `context.context_outputParam` by matching field names (`MAPPING_AUTO_INFERRED` warning). Constants or
  expressions require `{"paramMappingWay":"formula","valueFormula":"..."}`. `ExecuteNode` /
  `InterfaceNode` / `SubActionNode` / `FlowBotsNode` reuse `config.mapping` for `inputParamMapping`.
- **Code / mapping hardening**: business nodes always get `code` (`spec.code || id`); empty or invalid
  `code` and empty `name` are errors. `ExecuteNode` / `InterfaceNode` / `SubActionNode` / `FlowBotsNode`
  missing `inputParamMapping` get a `NODE_MAPPING_UNVERIFIED` warning offline; `--resolve-schema` fetches
  the target input schema and raises `NODE_INPUT_MAPPING_REQUIRED` (error) when params exist. Empty
  `UpdateDataNode` / `AddOrUpdateNode` `fields` and empty `LoopNode` sub-canvases are warnings.
  `flow diff` normalises a missing `code` to `id`.
- Publishing derives `fdProcessActive` on the backend from `startNodeDef`; `fdStatus=1` means enabled.
  `flow logs` endpoints vary by deployment (`ModelingProcessLog/findAll` vs
  `sysModelingLog/findAllWithAppId`); use `--endpoint` if the defaults fail.
- Runtime trigger: `flow script` emits a `MKXFORM.flow_<fdCode>` call; attach it with
  `llc operation create --type script --script @file` + `llc operation attach`.
  `executeFlowForAjax` lives in the `sys-xform` runtime package, not in a documented REST endpoint.

## 11. Common failures

| Message | Cause / fix |
|---|---|
| `缺少必要配置：baseUrl ... token ...` | no credentials; run `llc config set` or pass `--base-url`/`--token` |
| `未知的控件类型：xxx，可选值：...` | wrong 3rd token in `--add-field`; check `llc control list` |
| `"detail" 是容器类控件，不能用 --add-field 创建` | use `--detail`; `bigDetail`/`paged` are unsupported |
| `控件必填属性校验失败（共 N 项），已中止保存/发布` | fix the listed props; `--force` skips the check |
| `未获取到数据模型字段，无法自动完善` | `form autofill` found no data model; check `--id` / `--from-model` |
| `未知命令：llc ...` | wrong `llc help <command...>` path |
