lan-low-code-cli 2.6.0 → 2.8.0

package/skills/lan-low-code-cli/references/cli-contract.md

@@ -18,8 +18,9 @@ llc -v | --version
 - 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`) require `--yes`; without it the CLI
-  only warns and does **not** execute.
+- 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
@@ -122,8 +123,8 @@ maintained by the platform; the CLI only lists them and manages **custom** opera
 |---|---|---|---|
 | `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` | `--position list\|view` `--need-select` `--url` `--script <code\|@file>` `--dialog-id` `--desc` `--mobile-icon` `--dry-run` `--json` | creates an operation definition |
-| `llc operation update` | `--id <fdId>` | `--name` `--code` `--desc` `--position` `--type` `--url` `--script <code\|@file>` `--dialog-id` `--need-select`/`--no-need-select` `--enable`/`--disable` `--mobile-icon` `--dry-run` `--json` | edits an existing operation; `--type script` switches a button to script mode |
+| `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) |
@@ -221,7 +222,77 @@ without error but never fires, so confirm it first:
 | `--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. Common failures
+## 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` `--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` `--out` `--force` `--json` | compiles to `fdDesign` (JSON string) + `basicInfo`; **offline** |
+| `llc flow validate` | `--spec` | layout options, `--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 |
+| `llc flow get` | `--id` | `--with-design` `--raw` `--json` | `--with-design` parses `fdDesign` |
+| `llc flow category list` | `--app-code` | `--keyword` `--json` | read-only |
+| `llc flow logs` | `--id` | `--limit` `--endpoint` `--json` | log endpoints differ per deployment; `--endpoint` overrides |
+| `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 `--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 `--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 |
+
+**Flow Spec** (JSON — no new runtime dependency):
+
+```json
+{
+  "appCode": "cli-test", "name": "My flow", "code": "flow_a",
+  "startWay": "StartActiveNode", "centerX": 679,
+  "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) reproduces the platform's arrangement — main chain centred on
+  `--center-x` (default `679`), `BranchNode` 56×56, branch successors on the same rank at lanes ±1,
+  join one rank lower, rank spacing `maxHeight + 52`. `layered` pushes branch successors to the
+  next rank; `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 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.
+- 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 |
 |---|---|

package/skills/lan-low-code-cli/references/cli-contract.zh-CN.md

@@ -15,7 +15,7 @@ llc -v | --version        # 版本号
 - 配置优先级：`--base-url`/`--token` > `LLC_BASE_URL`/`LLC_TOKEN` > `./lcode.config.json`（当前目录）> `~/.lcode/config.json`（`llc config set` 写入）；`timeout` 默认 `30000` ms。
 - 多数查询/变更命令支持 `--json`（结构化输出，便于脚本处理）。
 - 退出码：`0` 成功（含 `--help`/`--version`）；`1` 失败（参数、校验、接口错误）。`LLC_DEBUG=1` 额外打印堆栈。
-- 破坏性命令（`app|form delete`、`app|form delete-data`）必须带 `--yes`，否则仅告警且**不执行**。
+- 破坏性命令（`app|form delete`、`app|form delete-data`、`flow delete`、`flow disable`）必须带 `--yes`，否则仅告警且**不执行**；`flow apply` 同样需要 `--yes`，默认只打印提交体。
 - `llc help xxx` 路径不存在时报 `未知命令：llc xxx` 并退出 `1`；未知子命令由 commander 报错（同为退出码 1）。
 
 ## 2. config
@@ -116,8 +116,8 @@ llc form create --name "简版分类表单" --app-id <appId> --type simpleCatego
 |---|---|---|---|
 | `llc operation list` | `--form-id <fdId>` | `--keyword <kw>` `--page-no <n>=1` `--page-size <n>=100` `--json` | 按表单列出操作（含内置） |
 | `llc operation get` | `--id <fdId>` | `--json` | 详情；默认展开 `fdConfig` JSON |
-| `llc operation create` | `--form-id` `--name` `--code` `--type` | `--position list\|view` `--need-select` `--url` `--script <code\|@file>` `--dialog-id` `--desc` `--mobile-icon` `--dry-run` `--json` | 新建操作定义 |
-| `llc operation update` | `--id <fdId>` | `--name` `--code` `--desc` `--position` `--type` `--url` `--script <code\|@file>` `--dialog-id` `--need-select`/`--no-need-select` `--enable`/`--disable` `--mobile-icon` `--dry-run` `--json` | 修改已有操作；`--type script` 可把按钮切换为脚本模式 |
+| `llc operation create` | `--form-id` `--name` `--code` | `--type link\|script\|dialog` **或** `--trigger-flow <动作流fdId>`；`--position list\|view` `--need-select` `--url` `--script <code\|@file>` `--dialog-id` `--inc-params <json\|@file>` `--desc` `--mobile-icon` `--dry-run` `--json` | 新建操作定义；`--trigger-flow` 绑定动作流（`fdTriggerType=3`） |
+| `llc operation update` | `--id <fdId>` | `--name` `--code` `--desc` `--position` `--type` `--url` `--script <code\|@file>` `--dialog-id` `--trigger-flow <动作流fdId>` `--inc-params` `--need-select`/`--no-need-select` `--enable`/`--disable` `--mobile-icon` `--dry-run` `--json` | 修改已有操作；`--type script` 切脚本、`--trigger-flow` 切动作流触发 |
 | `llc operation delete` | `--id <fdId>` `--yes` | — | 先查引用（`listByRefer`），被引用时拒绝删除 |
 | `llc operation attach` | `--form-id` `--operation-id` | `--target list\|view` `--view-id` `--platform desktop\|mobile` `--position top\|rightHand\|rightSide` | 把按钮写入视图 `operationList`；省略 `--view-id` 时自动定位唯一视图 |
 | `llc operation detach` | `--form-id` `--operation-id` | `--target list\|view` `--view-id` `--platform` | 从视图移除按钮（保留操作定义） |
@@ -211,7 +211,75 @@ llc operation detach --form-id <fdId> --operation-id <operationId>            #
 | `--locale` | `"Cn,Us,Tw"` 或 `all` | 逗号分隔，**第一个为主语言**；`all` = `Cn,Us,Tw` |
 | `--lang-file` | `{"Us":{"姓名":"Name"}}` | 内层 key 可为字段标题或字段名；选项支持 `字段名#值` |
 
-## 10. 常见失败提示
+## 10. flow（动作流 / process define）
+
+应用级动作流（`fdAppCode`）。所有写命令都需要 `--yes` 与显式 `--app-code`（或 spec 中的 `appCode`）。
+`--json` 输出到 stdout，其余输出走 stderr。
+
+| 命令 | 必填 | 主要选项 | 说明 |
+|---|---|---|---|
+| `llc flow spec` | — | `--app-code` `--name` `--code` `--start-way` `--out` `--json` | 生成 Flow Spec 模板；开始/结束节点由编译器自动补齐 |
+| `llc flow compile` | `--spec <@文件\|json>` | `--layout ide\|layered\|passthrough` `--center-x` `--rank-padding` `--lane-gap` `--min-gap` `--sub-center-x` `--emit-waypoints` `--out` `--force` `--json` | 编译出 `fdDesign`（JSON 字符串）与 `basicInfo`；**纯离线** |
+| `llc flow validate` | `--spec` | 布局选项、`--json` | 仅离线校验；有错误退出 `1` |
+| `llc flow list` | `--app-code` | `--keyword` `--status draft\|stopped\|enabled` `--page-no` `--page-size` `--json` | 只读 |
+| `llc flow get` | `--id` | `--with-design` `--raw` `--json` | `--with-design` 解析 `fdDesign` |
+| `llc flow category list` | `--app-code` | `--keyword` `--json` | 只读 |
+| `llc flow logs` | `--id` | `--limit` `--endpoint` `--json` | 日志端点因部署而异；`--endpoint` 可覆盖 |
+| `llc flow schema` | `--kind` | `--entity-id` `--code` `--app-code` `--api-type` `--api-method-path` | 只读、恒为 JSON。kind：`businessNodes` `events` `source` `jsonSchema` `condition` `out` `active` `event` `interface` `apiMethod` `flowBots` `meta` `dataModel` `recycle` |
+| `llc flow templates` | `--from <@文件\|json>` | `--out` `--json` | 从 `get` 响应 / 编译结果 / 设计对象抽取 golden 节点骨架；剥离 `drawAttr.bounds` |
+| `llc flow apply` | `--spec` `--app-code` | `--draft` `--enable` `--resolve-schema` `--strict-schema` 布局选项 `--force` `--yes` `--json` | **默认预览**；`--yes` 才调用 `addPublish`/`addDraft`（spec 带 `fdId` 时走 `update*`），随后回读 |
+| `llc flow diff` | `--id` `--spec` | `--no-ignore-bounds` `--resolve-schema` `--strict-schema` 布局选项 `--json` | 对比本地与远端设计；默认忽略坐标 |
+| `llc flow script` | `--id` | `--out` `--json` | 生成 `MKXFORM.flow_<fdCode>` 按钮脚本 |
+| `llc flow run` | `--operation-id` `--yes` | `--view-id` `--doc-id` `--doc-ids` `--inc-params` `--json` | 通过绑定动作流的业务操作执行一次（`sysModelingMain/other`），返回 `success` / `responseMsg` |
+| `llc flow enable` | `--id` | `--json` | `startup` |
+| `llc flow disable` | `--id` `--yes` | `--json` | `stop` |
+| `llc flow delete` | `--id` `--yes` | `--json` | 删除前先查 `listByRefer` |
+
+**Flow Spec**（JSON，不引入新的运行时依赖）：
+
+```json
+{
+  "appCode": "cli-test", "name": "示例流程", "code": "flow_a",
+  "startWay": "StartActiveNode", "centerX": 679,
+  "trigger": { "fdRunType": ["operate"], "fdFormRelation": "0", "dataType": 1,
+    "inParamType": 2, "inParam": { "id": "requestBody", "type": "object", "properties": {} } },
+  "nodes": [
+    { "id": "N2", "type": "QueryDataNode", "name": "查询",
+      "config": { "target": { "entityId": "sys-modeling#<fdId>" }, "resultType": "single" } },
+    { "id": "N3", "type": "BranchNode", "name": "条件分支" },
+    { "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": "是", "formula": { "type": "Script", "script": "return true" } },
+    { "from": "N3", "to": "N5", "name": "否", "default": true }
+  ]
+}
+```
+
+- `--code` 需匹配 `^[a-zA-Z0-9_]{1,30}$`；节点 `id` 需匹配 `^[0-9a-zA-Z_]{2,32}$`。
+  开始/结束节点及其连线自动补齐，无入边/无出边的业务节点自动接线。
+- **布局**：`ide`（默认）复刻平台编排——主链以 `--center-x`（默认 `679`）居中，`BranchNode`
+  为 56×56，分支后继与分支节点同层、泳道 ±1，汇聚下移一层，层距 = 该层最高节点 + 52。
+  `layered` 把分支后继放到下一层；`passthrough` 沿用 spec 中的 `bounds`。
+  `drawAttr.bounds` 是左上角 `x/y` 且带 `relative:false`，IDE **原样持久化、不会重算坐标**。
+- 分支处理：`defaultTargetRef` 取自 `"default": true` 的出边；自动生成引用真实连线 ID 的
+  `formulaConfig.branchFormulas`；分支连线写入 `exitX=0/1` 锚点，避免 IDE 内两条线重叠。
+- `--resolve-schema` 通过 `getSourceJsonSchema` / `getProcessDataOutJsonSchema` 补齐
+  `extraAttr.context_*`。这两个端点要求 `entityId` 带 `sys-modeling#` 前缀（CLI 自动补）。
+  失败默认只告警，`--strict-schema` 时升级为错误。
+- `AddDataNode` / `AddOrUpdateNode` 的 `fields` 使用平台真实结构
+  （`{field:{...},value:{format,valueJson}}`）；CLI 原样透传并只校验字段名，**不臆造公式**。
+  需要真实结构请用 `llc flow templates` / `flow get` 抽取 golden 骨架。
+- 发布时后端从 `startNodeDef` 派生 `fdProcessActive`；`fdStatus=1` 表示已启用。
+  `flow logs` 端点因部署而异（`ModelingProcessLog/findAll` 与
+  `sysModelingLog/findAllWithAppId`）；默认都失败时用 `--endpoint` 指定。
+- 运行时触发：`flow script` 生成 `MKXFORM.flow_<fdCode>` 调用，可用
+  `llc operation create --type script --script @文件` + `llc operation attach` 挂载。
+  `executeFlowForAjax` 位于 `sys-xform` 运行时包，没有文档化的 REST 端点。
+
+## 11. 常见失败提示
 
 | 提示 | 原因与处理 |
 |---|---|