weaver-e10-builder 1.2.5 → 1.5.1

package/skill-docs/references/common/ref-cli-commands.md

@@ -9,7 +9,7 @@
 | 命令 | 说明 |
 |------|------|
 | `e10-cli docx read <文件>` | 解析 Word 文档为 markdown + 提取图片到 `_images/`。**禁止自己写 python-docx 脚本** |
-| `e10-cli interface import <文件> [--system-pool-name <名称>] [--apply] [--out <文件>]` | 解析 `.docx/.pdf/.md/.txt` 为 Postman Collection；默认预览，`--apply` 才调用 ESB 创建系统接口。未传系统池名称时从文档文件名推导；完整规则见 `references/esb-interface/guide-import.md` |
+| `e10-cli interface import <文件> [--system-pool-name <名称>] [--apply] [--out <文件>]` | 解析 `.docx/.pdf/.md/.txt/.xlsx/.xls` 为 Postman Collection（Excel 有解析限额，超限报错不截断）；默认预览，`--apply` 才调用 ESB 创建系统接口。未传系统池名称时从文档文件名推导；完整规则见 `references/esb-interface/guide-import.md` |
 
 ---
 
@@ -45,25 +45,25 @@
 | `e10-cli form read <objId> [--app-id <appId>] [--out <file>]` | 读取表单字段。`--app-id` 含明细表字段+Select/RadioBox/CheckBox 选项；`--out fields.json` 写 UTF-8 JSON（推荐，机器可读）。旧版 `[dir]` 参数写 memo.md，已过时 |
 | `e10-cli form read <objId> --app-id <appId> --out fields.json` | 读取字段含选项（Select/RadioBox/CheckBox 自动带 options）。**含明细表字段**，配动作流/联动拿明细 fieldId 用这个 |
 | `e10-cli form list <appId>` | 列出应用下的所有表单 |
-| `e10-cli form create <appId> <name> <dir> --fields @<json文件>` | 创建表单。`--fields` **必填**。支持 DetailTable(嵌套formFields)、EBuilder(sformId+dataTitle)、relateFrom(联动)。fields.json 字段可带 `"required":true`/`"readOnly":true` 直标（写进布局 comps）。**字段名与平台系统字段重名（标题/创建者/创建时间/数据ID/最后更新人/数据状态）→ 不新建物理字段、复用系统字段**，并把该字段在**布局置为可见**（platform 系统字段默认隐藏；可写 `"singleRow":true` 独占一行、`"hidden":true` 保持隐藏）。`--json` 返回 `skippedSys`。**默认不加菜单**，要入口传 `--menu`（台账菜单 VIEWPORT）；漏加 `e10-cli menu add-table <appId> <objId>` 补 |
+| `e10-cli form create <appId> <name> <dir> --fields @<json文件>` | 创建表单。`--fields` **必填**。支持 DetailTable(嵌套formFields)、EBuilder(sformId+dataTitle)、relateFrom(联动)。fields.json 字段可带 `"required":true`/`"readOnly":true` 直标（写进布局 comps）。**字段名与平台系统字段重名（标题/创建者/创建时间/数据ID/最后更新人/数据状态）→ 不新建物理字段、复用系统字段**，并把该字段在**布局置为可见**（platform 系统字段默认隐藏；可写 `"singleRow":true` 独占一行、`"hidden":true` 保持隐藏）。`--json` 返回 `skippedSys`。**默认不加菜单**，要入口传 `--menu`（台账菜单 VIEWPORT）；漏加 `e10-cli menu add-table <appId> <objId>` 补。**`--table-name <名>` 自定义数据库表名**（平台前缀如 `uf_` 由 CLI 自动补，传 `cs_khxx` 与 `uf_cs_khxx` 等价；字母开头、只含字母数字下划线；自定义部分受平台长度上限约束——`uf_` + 总长 30 时最多 27 位，越界直接报错不建半张表；建成后回读校验实际表名；仅物理表应用适用） |
 | `e10-cli form virtual source-groups` / `sources <groupId>` | 查询 EB 表单和系统业务数据源分组、数据源列表 |
 | `e10-cli form virtual dataset-groups` / `datasets <groupId>` / `dataset-info <id>` | 查询数据加工分组、数据集和数据集定义 |
 | `e10-cli form virtual fields <appId> --source-id ... --source-group ...` | 校验数据源 ID 字段并读取可映射字段 |
 | `e10-cli form virtual create <appId> <name> --source-id ... --source-group ... --fields @json` | 创建虚拟表；`--source-type LOGIC|ETEAMS`，支持 `--layout FLOW|EXCEL`。字段默认沿用来源类型，只允许兼容的同族展示类型 |
 | `e10-cli form virtual read <objId> <appId>` | 读取虚拟表来源、字段映射和默认视图信息 |
 | `e10-cli form virtual add-fields <objId> <appId> <formId> --source-id ... --source-group ... --fields @json` | 从原数据源向虚拟表增加字段 |
-| `e10-cli form add-field <objId> <appId> <name> <type> [title]` | 添加字段。`<type>`=componentKey（Text/Select/Employee/Money/DetailTable 等同 form create）；`[title]` 字段显示名，不传同 name。Select 类型需单独 `field-options` 配选项。**`--sub-form-id <明细表subFormId>` 在明细表里加字段**（自动重新布局）。Number 类型：**`--percent` 百分比显示**（numberType=percentage，缺省 1 位小数）、**`--default <值>` 默认值**（如 `--default 1000` 工时单价默认 1000）、`--precision <n>` 精度。**EBuilder/Flow 类型**：`--sform-id <目标表单objId>`（EBuilder 表关联 / Flow 浏览-流程字段，数据来源=浏览流程）。EBuilder 字段**自动配关联浏览弹窗显示列**（=目标表全部业务字段，去系统字段）。**`--multiple` 多选**（人员/部门/EBuilder/Browser 默认单选；**下拉 Select --multiple → SelectMultiple 类型**）。**`--max-len <n>` 文本最大长度**（Text 缺省 100、TextArea 缺省 4000）。**`--single-row` 独占一行显示**。**`--option-template <模板ID或名>` Select 绑定选项预设模板**（选项来自模板，与 `field-options` 二选一） |
+| `e10-cli form add-field <objId> <appId> <name> <type> [title]` | 添加字段。`<type>`=componentKey（Text/Select/Employee/Money/DetailTable 等同 form create）；`[title]` 字段显示名，不传同 name。Select 类型需单独 `field-options` 配选项。**默认「增量插入」——只往布局里加这一个字段，不动其它组件、不动样式模板、不动位置**（读快照 → 加一对组件 → 保存）。**`--reinit` 改成整表重建**（initLayout：换样式模板 + 重排所有已有位置 + 标签组件全部换新 id）——**只在是自己建的表上用**；不是自己建的表（尤其字段多、手工调过版式的）绝不能用。**布局里没有同类型字段可参照时命令会中止**并说明，这是设计如此（新组件的键集只能从同类型的现成组件抄，按类型名拼会静默渲染异常）；此时要么先在设计器里手工加一个同类型字段，要么显式 `--reinit`。**`--required` 设为必填**（写布局组件）。**`--sub-form-id <明细表subFormId>` 在明细表里加字段**（同样走增量）。**自动为字段标题建立多语言标签**并写进字段记录。Number 类型：**`--percent` 百分比显示**（numberType=percentage，缺省 1 位小数）、**`--default <值>` 默认值**（如 `--default 1000` 工时单价默认 1000）、`--precision <n>` 精度。**EBuilder/Flow 类型**：`--sform-id <目标表单objId>`（EBuilder 表关联 / Flow 浏览-流程字段，数据来源=浏览流程）。EBuilder 字段**自动配关联浏览弹窗显示列**（=目标表全部业务字段，去系统字段）。**`--multiple` 多选**（人员/部门/EBuilder/Browser 默认单选；**下拉 Select --multiple → SelectMultiple 类型**）。**`--max-len <n>` 文本最大长度**（Text 缺省 100、TextArea 缺省 4000）。**`--single-row` 独占一行显示**。**`--option-template <模板ID或名>` Select 绑定选项预设模板**（选项来自模板，与 `field-options` 二选一）。**`--data-key` / `--column-name` 分别指定字段编码与数据库列名**（两者是两个独立的东西，可分别指定；只给 `--data-key` 时列名跟随，都不给则同为字段名拼音首字母） |
 | `e10-cli form detail-table list/read <objId> <appId> [...]` | 列出明细表，或读取指定明细表的二级明细开关与配置 |
 | `e10-cli form detail-table sub-detail candidates <objId> <appId> <父明细表>` | 查询当前父明细可选择的子明细；列表排除自身、直属父级和祖先。反转父子方向时，先 `remove` 原关系，再查询新父级候选并 `add` 反向关系 |
 | `e10-cli form detail-table sub-detail add <objId> <appId> <父明细表> --target <子明细表> --target-field <子级文本标识> [--parent-field <父级标识>] [--default-expand]` | 保留已有关系并增加或更新一条二级明细关系。父级标识缺省 `rowId`，也支持 Text/RadioBox/Select；子级标识必须是 Text。表和字段可写名称或 ID，保存后自动回读 |
 | `e10-cli form detail-table sub-detail set <objId> <appId> <父明细表> --target <子明细表> --target-field <子级文本标识> [--parent-field <父级标识>] [--default-expand]` | 完整替换父明细的子明细配置。另有 `remove --target <子明细表>` 删除指定关系，`enable`、`disable`（保留配置）、`clear`（清空配置）；完整规则见 `references/form/guide-form-sub-detail.md` |
-| `e10-cli form edit-field <objId> <appId> <fieldId> [选项]` | 编辑字段属性。`--title` 显示名、**`--type <类型>` 改字段类型**（取值同 `add-field`，如 `Text`/`Number`/`Date`/`Select`/`Department`；走读-改-写，**不用删字段重建**，显示名/列名/位置都保留；改成 `EBuilder`/`Flow` 必须同时给 `--sform-id`）、`--required`/`--no-required`、`--sform-id`（改EBuilder关联）、`--relate-from`（值带出）、**`--multiple`/`--no-multiple`**（人员/部门/EBuilder/Browser 多选切换）、**`--data-title`**（关联字段的标题栏，写 `dataTitle`）。改成 `EBuilder` 或换关联表时，**浏览显示列按新目标表自动补齐**（只在没配过、或旧列不属于新目标表时才写，不冲掉手工配的）。**⚠ 字段已有数据时平台拒绝改动结构**（显示名例外）——报「此列已存在数据不可修改数据库字段名称」，该文案与实际情况不符，它拦的不止字段名 |
+| `e10-cli form edit-field <objId> <appId> <fieldId> [选项]` | 编辑字段属性。`--title` 显示名、**`--type <类型>` 改字段类型**（取值同 `add-field`，如 `Text`/`Number`/`Date`/`Select`/`Department`；走读-改-写，**不用删字段重建**，显示名/列名/位置都保留；改成 `EBuilder`/`Flow` 必须同时给 `--sform-id`）、`--required`/`--no-required`、`--sform-id`（改EBuilder关联）、`--relate-from`（值带出）、**`--multiple`/`--no-multiple`**（人员/部门/EBuilder/Browser 多选切换）、**`--data-title`**（关联字段的标题栏，写 `dataTitle`）。**`--required`/`--no-required` 写的是布局组件**（必填只存在于布局里，字段定义没有这个键），命令会顺带把布局一并保存。改成 `EBuilder` 或换关联表时，**浏览显示列按新目标表自动补齐**（只在没配过、或旧列不属于新目标表时才写，不冲掉手工配的）。**`--data-key` / `--column-name` 分别改字段编码与数据库列名**（两者独立；只给 `--data-key` 时列名跟随）。**⚠ 字段已有数据时平台拒绝改动结构**（显示名例外）——报「此列已存在数据不可修改数据库字段名称」，该文案与实际情况不符，它拦的不止字段名 |
 | `e10-cli form field-lang get <objId> <appId> <fieldId>` | 查看字段名称的中英文多语言配置；未配置时返回当前中文名称和 `configured:false` |
 | `e10-cli form field-lang set <objId> <appId> <fieldId> --zh <中文> --en <English>` | 设置字段名称多语言。先保存多语言标签，再读取完整字段并回写 `labelObj.title`，不会覆盖字段其他属性 |
 | `e10-cli form serial-mark set <objId> <appId> <fieldId> --segments @<json>` | **表单编号**（纯建模表）：用 JSON 数组组合任意编号规则，数组顺序即拼接顺序。段类型 `fixed`/`year`/`serial`/`field`/`system`/`date`；field 段可 inline `shortName` 代字映射。子命令组：`set`(配置,--segments) / `add-segment`(增量追加段) / `short-name`(代字 list/set) / `read`(查看) / `fields`(查可绑定字段) / `enable`(启用) / `disable`(停用，可加 `--field <fieldId>` 只停某一个字段的编号) / `clear`(解除绑定)。**`disable` 停用 ≠ `clear` 解除**：停用只关开关（`isUse=0`），绑定记录与组成段原样保留、可 `enable` 恢复；解除走删除接口，绑定不可逆。要「暂时不生成编号」一律用 `disable`。被编码字段平台自动只读。**⚠ 仅对未绑流程的纯建模表有效——eb表单绑流程后表单编号字段在流程提交时不生效，编号改走流程编号（`workflow numbering`，落到 REQUEST_NO 系统字段）** |
 | `e10-cli form field-options <objId> <appId> <fieldId> --options @<json> [--default <key>]` | 设选项/默认值。options.json: `[{"name":"选项名","valueKey":"可选"}]`；`--default` 用平台生成的长 valueKey（`form read --app-id` 获取），不是 name |
 | `e10-cli form option-template <list\|read\|create\|copy\|delete>` | **Select 选项预设模板管理**（下拉选项复用：多个表单共享一套选项，模板改了各表单跟着变）。`list [--system]` 列模板（默认自定义模板，--system 看系统内置）；`read <模板ID> [--flat]` 看选项树；`create <名称> --options @<json> [--level 1] [--describe 文本]` 建模板（options.json: `[{"name":"低","valueKey":"10","children":[]}]`，**valueKey 必须数字**，children 嵌套=多级）；`copy <模板ID>` 复制（系统 default 模板不可复制）；`delete <模板ID>` 删模板（被引用时平台拒绝）。**字段引用模板**：`form add-field --option-template <模板ID或名>` 或 fields.json 写 `"optionTemplate":"模板名"`（Select 专有，选项不内联） |
-| `e10-cli form linkage add <appId> <objId> <name> --config @<json>` | 添加字段显隐联动规则 |
+| `e10-cli form linkage add <appId> <objId> <name> --config @<json>` | 添加字段显隐联动规则（`conditions[]` 用 fieldId + operator + value/options；`actions[]` 用 prop + fields[]）。**「为空 / 不为空」的 operator 写 `NULL` / `NOT_NULL`**（写 `EMPTY` 会被归一，但写别的平台不认的码会报一句与条件无关的写库异常）。目标字段 `dataKey` 留空即可（平台按 fieldId 定位）。多条件关系用 `detailType`（`OR`=任一 / `AND`=全部，界面就叫「任一」「全部」，不写则由平台取默认）；生效维度用 `effect`（不写=当前表单，`"formLayout"`=表单布局，或给 `{effectType,effectName,effectValue}` 对象；**布局维度要的是 multipleLayoutId，命令自己查**）。**本命令只有 add / list，没有 delete** —— 建错要去设计器里删。详见 `form/guide-form-linkage.md` |
 | `e10-cli form relate <appId> <objId> <目标字段> --from <源字段>` | **HRM 值带出联动**：源字段为表内 Employee（人员）或 Department（部门）类型，换源自动填目标字段（换申请人→填邮箱/工号/部门；换所属部门→填部门编号/上级部门）。`--key` 从平台清单校验（默认 Employee=department、Department=name），`--title` 指定显示名（默认属性中文名）。详见 `form/guide-form-linkage.md` |
 | `e10-cli form delete-field <objId> <appId> <fieldId...>` | **删除字段**（可一次多个，批量）。**仍被布局引用的字段平台不允许删除**（报「当前字段已被布局引用，不允许删除」）；加 `--force` 时 CLI 先从布局移除再重试——会**连字段的标题组件一起摘**（一个字段在布局里是「字段本体 + 标题标签」两个组件），否则表单上会留下孤儿标签。字段**有数据**时同样删不掉 |
 | `e10-cli form delete <objId> <appId>` | 删除**整个表单**（不是字段；删字段用上面的 delete-field） |
@@ -108,7 +108,7 @@
 | 命令 | 说明 |
 |------|------|
 | `e10-cli form button list <objId> <appId>` | 列出所有按钮 |
-| `e10-cli form button add <objId> <appId> <name> [--url <url>\|--open-view <视图>\|--open-layout <表单>\|--start-workflow <流程>] [--layout-type 新建\|编辑\|显示] [--map "目标字段:来源字段"...] [--target-app <appId>] --view <来源视图> --position <位置...>` | 添加通用打开页面按钮。支持固定 URL、平台视图、表单布局及流程快捷入口；`--map` 把当前行来源字段传给目标字段，可多项。当前行映射只允许行上/行末下拉；右上按钮无单行上下文。目标名称不唯一时使用 ID，保存后回读动作和映射 |
+| `e10-cli form button add <objId> <appId> <name> [--url <url>\|--open-view <视图>\|--open-layout <表单>\|--start-workflow <流程>] [--layout-type 新建\|编辑\|显示] [--map "目标字段:来源字段"...] [--target-app <appId>] --view <来源视图> --position <位置...>` | 添加通用打开页面按钮。支持固定 URL、平台视图、表单布局及流程快捷入口。`--map` 把当前行的来源字段传出去，可多项，但**两种动作的写法不同**：视图/布局/流程动作写 `"目标字段:来源字段"`，**URL 动作写 `"参数名:来源字段"`**（参数名会成为目标 URL 的查询键）。⚠ **URL 动作的页面类型缺省 `LINK`**（平台设计器对 URL 路径用的就是这个；`CUSTOMPAGE` 是「自定义页面」，`pageId` 要页面 id，装 URL 路径点不开）。⚠ **平台不认 URL 里的 `{字段}` 占位符**，传参只能用 `--map`。当前行映射只允许行上/行末下拉；右上按钮无单行上下文。目标名称不唯一时使用 ID，保存后回读动作和映射 |
 | `e10-cli form button action-set <objId> <appId> <buttonId> [--open-view ...\|--open-layout ...\|--start-workflow ...] [--map ...]` | 更新已有自定义按钮的单一 `openpage` 动作，保留按钮位置和权限；适合修正目标页面或动态字段映射，避免重复创建同名按钮 |
 | `e10-cli form button toggle <objId> <appId> <buttonId>` | 启用/禁用按钮 |
 | `e10-cli form button position <objId> <appId> <buttonId> [--view <视图...> --position <位置...>] [--show-position <json或@文件>] [--replace]` | 设置已有按钮位置并回读验证。默认合并、保留未指定页面；`--replace` 全量替换。视图支持 ID/唯一名称/新建/编辑/显示；多台账不能省略具体视图。系统按钮适用，保留动作权限及返回的日志/提示配置。详见 `references/form/guide-form-button.md` |
@@ -133,6 +133,14 @@
 | `e10-cli form field-linkage fields <appId> <formId>` | 查源表可带出字段 |
 | `e10-cli form field-linkage delete <appId> <objId> <ids...>` | 删除（批量） |
 | `e10-cli form field-linkage add <appId> <objId> --trigger <字段名> --target <字段名> --hops "<objId:字段名,...>"` | 新增。`--hops` 多跳链式（单跳用 `--source-form/--query-field`）。**Text 字段必须多跳取名称**。详见 `form/guide-field-linkage.md` |
+| `e10-cli form formula-linkage list <appId> <objId>` | 函数联动（**本表**字段间公式赋值，`linkageType=excel`）：列出 |
+| `e10-cli form formula-linkage read <appId> <objId> <id>` | 回读单条（含公式表达式与参数） |
+| `e10-cli form formula-linkage events <appId> <objId>` | 列出可用的触发事件（值改变时 / 载入时 / 创建数据时 …） |
+| `e10-cli form formula-linkage columns <appId> <objId>` | 列出可引用/可触发的字段（业务字段 / 系统模块字段分两桶） |
+| `e10-cli form formula-linkage add <appId> <objId> --target <字段> --expression <函数体>` | 新增函数联动。`--event`（默认 `changeField`）、`--trigger <字段...>`（字段级事件必填）、`--effect form\|formLayout`（生效维度，默认当前表单）、`--name`。表达式**只给右侧**，左侧 `{主表.目标}=` 自动拼。**目标只能是业务字段**，模块字段可作来源/触发。详见 `form/guide-formula-linkage.md` |
+| `e10-cli form formula-linkage update <appId> <objId> <id> [--event] [--trigger] [--effect] [--name] [--state on\|off]` | 改触发条件/生效维度/名称/启停。不传则沿用现有 |
+| `e10-cli form formula-linkage delete <appId> <objId> <ids...>` | 删除（批量）。`form field-linkage delete` 删不掉这类，会报错指路 |
+| `e10-cli form formula set <objId> <appId> --target <fieldId> --expression "<公式>"` | 给 eb 表字段**绑定**计算公式。`{主表.字段}` / `{明细表名.字段}`（平台存储格式）与设计器的 `[字段]` 两种写法都收，保存前归一化成花括号再下发。`--name`、`--return-type`（不传按目标字段类型推断）。**`--formula-id <id>` 原地更新已有公式**（平台认这个字段：不新建、返回 id 不变、字段绑定不受影响），不传才是新建；更新时不传 `--name` 会沿用原公式名，不会被改成「公式_&lt;时间戳&gt;」。另：`formula get <id>` / `list <objId> <appId>` / `functions`。**⚠ 公式语法四条**：函数名必须大写（自定义 JS 脚本函数除外）、逻辑比较用 `==`、给字段赋值用 `=`、跨表粘贴要换掉非本表字段变量 —— 写错**不报错**只是算不对，见 `references/form/guide-form-formula-functions.md` |
 
 > **创建表单流程**：
 > 1. 读取 `references/form/guide-create-form.md` 了解标准创建流程；确定字段类型和参数时读取 `references/form/ref-form-fields.md`
@@ -150,7 +158,13 @@
 | `e10-cli role list` | 列出所有角色（树形结构，含层级关系） |
 | `e10-cli role create <name>` | 创建角色，`--parent <id>` 指定父角色，`--code` 编码，`--remark` 备注 |
 | `e10-cli role delete <ids...>` | 删除角色（可多个） |
-| `e10-cli role add-member <roleId> <keyword>` | 搜索人员并添加到角色 |
+| `e10-cli role add-member <roleId> <名字...> [--type <类型>]` | 添加角色成员，**可一次给多个名字**（各自独立搜索）。`--type` 取 `resource`(人员，缺省) / `department`(部门) / `subcompany`(分部) / `position`(岗位) / `channel`(渠道) —— 这几项正是平台 `objectTypeFilter` 白名单里**可以逐个选**的对象，白名单另三项 `all`/`external`/`allExternal` 不是逐个选的对象，本命令不支持。五类走**同一个保存端点**，靠 `objType` 选各自数组（`obj_resource` / `obj_department` / `obj_subcompany` / `obj_position` / `obj_channel`）。搜索**精确同名优先**；同名多条、或多条命中却没有同名项，一律**报错不取首条**（取首条会静默加错人）。`--sec-min/--sec-max`、`--is-seclevel` 覆盖安全级别（**这两个值随租户配置变**，缺省 `0`/`100` + false）；`--department-attribute subordinate,partTimeStaff` 给部门/分部指定是否含下级 / 含兼职。**增量追加**，不会冲掉已有成员 |
+| `e10-cli role member-list <roleId>` | 列出角色成员（人员 / 部门 / 分部 / 岗位 / 渠道，含成员级别与分权范围） |
+| `e10-cli org department create <name> [--code <编号>] [--parent <父部门id>] [--subcompany <机构id>]` | 新建部门。**四步链**：`organization/getForm` 取保存模板（含平台**现生成**的 targetId）→ `form/core/getFormLayout` 取布局 id → `form/core/saveFormData` 落数据并回吐 recordId → `organization/saveForm` 落组织树。`--parent` 不传即顶层部门，挂在当前用户机构下（机构自动解析，可用 `--subcompany` 覆盖）。⚠ 模板里 `parent` 是数组、`subcompany` 是对象数组，命令内部转成平台要的字符串形状 —— **别拿模板直接发** |
+| `e10-cli org department edit <id> [--name] [--code] [--parent] [--disporder]` | 编辑部门：改名 / 改编号 / **移动父级** / 改排序。是「**读现状 → 改 → 写回**」：`organization/getForm?id=` 读回这个部门的**完整当前状态**（含 tenantKey / creator / datarank / createTime 等，全部原样回传，别自己造），改完再 `organization/saveForm`。⚠ 编辑报文与新建**形状不同**（认 `id`，没有 `targetId`/`formdata`/`recordId`，`advanceForm:false`），不能共用构造函数。命令会自动**回读确认**改名生效，静默失败会报错 |
+| `e10-cli org department delete <id> [--parent <父部门id>] [--subcompany <机构id>]` | 删除部门。`--parent` 是该部门的**父**（顶层部门的父就是机构 id），不传按当前机构的上下文解析。⚠ 删除是**软删**（`isDelete: true`），删完用 `getForm?id=` 仍能读出来 —— 判存在与否要看 `isDelete` 字段，别看接口有没有返回 |
+| `e10-cli org employee template [--out <路径>]` | 导出人员导入模板（xlsx）。**模板是随包发的资源**（含富文本表头和「注意事项」工作表），直接复制，不用代码重建 |
+| `e10-cli org employee import <file> [--dry-run] [--mode add\|update] [--find-by <字段>] [--review <n>]` | 从 Excel 批量导入人员。**先 `--dry-run` 预览再真导** —— 干跑到「预览」为止不落库，能看出平台解析出的列/行跟你原表对不对。⚠ 模板自带示例行，导入前删掉。细节见 `references/hrm/guide-org-employee.md` |
 
 ## 流程
 
@@ -158,23 +172,29 @@
 |------|------|
 | `e10-cli workflow create <appId> <formObjId> <name> [desc]` | 创建 EB 流程，当前命令按固定模式创建并自动设置所有人可发起。**默认不加菜单**，要入口传 `--menu`（发起菜单 LAYOUT，指向表单新建页 `/sp/ebdfpage/card/1/<formObjId>/0`，点开即触发流程）；漏加 `e10-cli menu add-start <appId> <formObjId>` 补 |
 | `e10-cli workflow create-workflow <name>` | **非默认路径**。仅当用户明确强调「用流程表单 / 工作流程 / 流程中心建流程、不在应用下」时才用；默认走上一条 `workflow create`（eb 应用内）。关联流程表单：不传 `--form-id` 自建（`relateForm=0`，服务端建表回吐 `data.formId`）/ `--form-id <已有>` 绑定（`relateForm=1`）。`--odoc` 创建公文流程（两种表单方式均支持，增加 `bridgeService=odoc`）；`--workflow-type`（默认 -1=其它）、`--sub-company <机构>`、`--belong-type <0个人/1团队>`（默认 1）、`--table-name`、`--desc`、`--is-free`、`--layout <FLOW流式(默认)/EXCEL表格式>`（自建模式下 EXCEL 走 formmanage/saveForm 建表后绑定；建表后不可切换）。不带 source/messageParams |
-| `e10-cli workflow auth-resp <list\|create\|update\|read\|configure\|save-design>` | 独立权责表管理。`configure <id> --config @json` 从零创建变量、开始/结束节点、中间节点及操作者、分支条件和路径并保存回读；`save-design` 用于完整设计结构的保留式保存 |
-| `e10-cli workflow auth-resp variable <list\|add>` | 独立管理权责表变量，变量先创建后供权责表条件引用。支持字符串、数值、选项、浏览和关联浏览变量 |
+| `e10-cli workflow auth-resp <list\|create\|update\|read\|configure\|save-design>` | 独立权责表管理。`configure <id> --config @json` 从零创建变量、开始/结束节点、中间节点及操作者、分支条件和路径并保存回读；条件支持统一的 `system` / `form` 业务来源与原始 `childrens`；`save-design` 用于完整设计结构的保留式保存 |
+| `e10-cli workflow auth-resp condition-fields <id> --source-id <分支ID> --workflow-id <流程ID\|-99999999>` | 查询权责表条件来源。流程内返回系统字段与实际表单字段；独立权责表返回系统字段与变量，变量在复用流程时映射为实际表单字段 |
+| `e10-cli workflow auth-resp variable <list\|add>` | 独立管理权责表变量，变量先创建后供权责表条件引用。支持字符串、数值、选项、浏览和关联浏览变量；`add ... --detail` 创建明细变量，条件用 `detail:any/all` 表示任一行或所有行 |
 | `e10-cli workflow auth-resp reference <list\|add\|remove>` | 管理权责表路径中的嵌套权责表。`list <宿主baseId>` 仅返回首尾为中间节点且不会形成循环引用的权责表；`add` 按分支与顺序写入 `addMethod=2` 的引用；`remove` 删除引用列及对应路径。 |
-| `e10-cli workflow auth-resp-flow create <name> --base @json (--new-table <name>\|--reuse-table <id>)` | 按权责表方式创建流程。新建模式直接使用表单字段；复用模式可加 `--mappings @json` 保存权责表变量到当前表单字段的映射 |
-| `e10-cli workflow auth-resp-flow <bind\|design-read\|design-apply\|mapping-read\|mapping-save>` | 对已有权责表流程维护绑定关系、权责表流转设计及变量映射。节点、分支条件和路径通过权责表设计维护。详细顺序见 `workflow/guide-workflow-auth-resp.md` |
+| `e10-cli workflow auth-resp-flow create <name> --base @json (--new-table <name>\|--reuse-table <id>)` | 按权责表方式创建流程。一般需求默认用 `--new-table`，直接使用当前流程表单字段；仅多重嵌套或明确需要跨流程复用权责规则时使用 `--reuse-table`，并用 `--mappings @json` 保存权责表变量到当前表单字段的映射 |
+| `e10-cli workflow auth-resp-flow <bind\|design-read\|design-apply\|mapping-read\|mapping-save>` | 对已有权责表流程维护绑定关系、权责表流转设计及变量映射。明细变量映射到实际表单的同类型明细字段；节点、分支条件和路径通过权责表设计维护。详细顺序见 `workflow/guide-workflow-auth-resp.md` |
 | `e10-cli workflow odoc <list\|read>` | 查询公文流程列表，或读取单个公文流程及公文设置摘要。`list` 支持 `--name`、`--sub-company`、`--belong-type`、分页参数 |
-| `e10-cli workflow odoc setting <get\|set> <workflowId>` | 读取或修改公文设置。`set --config @json` 读取当前配置后合并保存并回读；常用参数含 `--official-type`、`--request-title-field`、`--upload-word/pdf/ofd`、`--text-in-form`、`--column-position`、`--attach-area`、`--archive-node`、`--open-text-select`、`--open-text-node`、`--edit-text-node`、`--ai-odoc/--ai-abstract/--ai-format`。`--open-text-node` / `--edit-text-node` / `--archive-node` 可写节点名称，CLI 会查回节点 ID；节点名称在流程内重复时报错，不擅自挑一个 |
+| `e10-cli workflow odoc setting <get\|set> <workflowId>` | 读取或修改公文设置。`get` 返回平台设置分组、当前值与候选项；`set --config @json` 读取当前配置后合并保存并回读。常用参数及十九组公文配置见 `workflow/guide-workflow-odoc-setting.md` |
 | `e10-cli wf-form read <formId>` | **流程表单管理（非默认路径）**。读流程表单字段（getConfig）。`<formId>` 由 `workflow create-workflow` 回吐。与 eb 表 `form read` 对齐，走 `/api/workflow/core/form/...`（module=workflow、customParam={}、无 apid） |
-| `e10-cli wf-form add-field <formId> <字段名> <类型> [标题]` | 给流程表单加字段。类型：Text/TextArea/Number/Money/Date/DateTime/Select/Employee/Department/Browser（浏览按钮），**以及全部富组件类型**（Time/Score/Signature/Project/Location/Order/Contract 等，走与 eb 表同一张映射表）。`--sub-form-id <明细subFormId>` 明细字段；`--multiple` 多选；`--precision`/`--percent`/`--default`（Number/Money）；`--format`（日期精度）。formTableId 省略 |
+| `e10-cli wf-form add-field <formId> <字段名> <类型> [标题]` | 给流程表单加字段。类型：Text/TextArea/Number/Money/Date/DateTime/Select/Employee/Department/SubCompany（分部选择）/Browser（浏览按钮），**以及全部富组件类型**（Time/Score/Signature/Project/Location/Order/Contract 等，走与 eb 表同一张映射表）。`--sub-form-id <明细subFormId>` 明细字段；`--multiple` 多选；`--precision`/`--percent`/`--default`（Number/Money）；`--format`（日期精度）。formTableId 省略 |
 | `e10-cli wf-form add-field <formId> <名> Browser <标题> --browser-type <源>` | **浏览按钮必须指定浏览数据源**，否则平台报「程序异常」。源可选 `workflow`(缺省=工作流) / `hrcontract` / `role` / `archive` / `form`；用 `form` 时再配 `--browser-form-source business\|ebuilder`。落到平台是 `type=RelateBrowser` + `browserType:{module,name,id,type}` |
 | `e10-cli wf-form add-field <formId> <名> Browser <标题> --browser-name "CLM-合同类型"` | **按名字指定浏览数据源**，含自定义浏览框（`customBrowser_xxx`，没有固定 id 必须现查）。名字**精确匹配**，查不到会停下并列候选，不用近似项顶替。优先于 `--browser-type`。批量 `add-fields` 直接在 JSON 里写 `browserType:{...}` 对象 |
 | `e10-cli wf-form add-fields <formId> @fields.json [--no-init]` | **批量加字段**：JSON 数组每项 `{name,type,title?,subFormId?,multiple?,precision?,percent?,default?,format?,singleRow?,defaultCurrent?}`；加完**自动跑一次 layout init 重新布局**（`--no-init` 跳过）。字段多时比逐条 `add-field` 省事 |
 | `e10-cli wf-form ebuilder-scope <formId> <ebuilder字段Id> --rule "目标表字段:操作:值" [--sform-id <objId>] [--workflow-id <wfId>]` | 给流程表单的**关联浏览字段**设数据范围（如关联客户只选「客户状态=启用」的）。操作用 `eq`/`neq`/`like`/`isnull`/`notnull`；Select 值填**选项名**。对应 eb 表的 `form ebuilder-scope` |
-| `e10-cli wf-form edit-field <formId> <fieldId> [--title <标题>] [--multiple|--single]` | 编辑已有字段（read-modify-write）。`--multiple`/`--single`：Employee/Department/Browser 切 isSingle，Select↔SelectMultiple。必填为布局级用 `wf-form layout init --required` |
+| `e10-cli wf-form edit-field <formId> <fieldId> [--title <标题>] [--multiple|--single]` | 编辑已有字段（read-modify-write）。`--multiple`/`--single`：Employee/Department/SubCompany/Browser 切 isSingle，Select↔SelectMultiple。必填为布局级用 `wf-form layout init --required` |
 | `e10-cli wf-form delete-field <formId> <fieldId...> [--force]` | 删除流程表单字段（可批量）。**仍被布局引用的字段平台拒删**；`--force` 让 CLI 先从布局摘掉这些字段的组件（含它的标题标签）再删。eb 表侧对应 `form delete-field` |
-| `e10-cli wf-form formula set <formId> --expression "DAYS({主表.开始时间},{主表.结束时间})" --target <fieldId>` | 给流程表单字段绑定计算公式。`{主表.字段}`/`{明细表名.字段}` 引用（getConfig 解析）→ `/api/excel/formula/save`(module=workflow) → ffExpress 绑字段 + saveSourceForm。`--name`/`--return-type`。另：`formula get <id>` / `list <formId>` / `functions` |
-| `e10-cli wf-form linkage <formId> <联动名> --config '{"conditions":[{"field":"请假天数","operator":"EQUAL","value":"3"}],"actions":[{"prop":"hide","fields":["请假事由"]}]}'` | 显隐联动。`--config` 写字段名（自动 getConfig 解析 fieldId/dataKey）。prop: hide/show/edit/readonly/required/hideLine；operator: EQUAL/NOT_EQUAL/GREATER/LESS/EMPTY 等 |
+| `e10-cli wf-form formula set <formId> --expression "DAYS({主表.开始时间},{主表.结束时间})" --target <fieldId>` | 给流程表单字段绑定计算公式。`{主表.字段}`/`{明细表名.字段}` 引用（getConfig 解析）→ `/api/excel/formula/save`(module=workflow) → ffExpress 绑字段 + saveSourceForm。`--name`/`--return-type`/**`--formula-id <id>`（原地更新已有公式，不新建）**。另：`formula get <id>` / `list <formId>` / `functions`。**⚠ 公式语法四条**：函数名必须大写（自定义 JS 脚本函数除外）、逻辑比较用 `==`、给字段赋值用 `=`、跨表粘贴要换掉非本表字段变量 —— 写错不报错只是算不对，见 `references/form/guide-form-formula-functions.md` |
+| `e10-cli wf-form formula-linkage list <formId> --workflow-id <id>` | 流程表单的**函数联动**（`linkageType=excel`，走 `/api/ebuilder/flow/form/linkage`，module=`ebuildercard`）。`read` / `delete <ids...>` 同形 |
+| `e10-cli wf-form formula-linkage events <formId> --workflow-id <id>` | 列出触发事件（**17 个**：字段组 5 + 表单组 5 + 流程组 7） |
+| `e10-cli wf-form formula-linkage columns <formId> --workflow-id <id>` | 列出可引用/可触发的字段，按「可作 / 不可作赋值目标」分桶。字段清单取自 `findFormDrivingColumns`，**不依赖 getFormLayout**（后者在部分流程表单上会 500） |
+| `e10-cli wf-form formula-linkage add <formId> --workflow-id <id> --target <字段> --expression <函数体>` | 新增。`--event`（默认 `changeField`）、`--trigger <字段...>`、`--effect form\|formLayout\|workFlow\|includeNode`（后两者需 `--workflow-id`，`includeNode` 另需 `--node`）、`--name`。表达式只给右侧，左侧自动拼。详见 `form/guide-formula-linkage.md` |
+| `e10-cli wf-form formula-linkage update <formId> --workflow-id <id> <linkageId> [--event] [--trigger] [--effect] [--node] [--name] [--state on\|off]` | 改触发条件/生效维度/名称/启停。不传的项沿用现有 |
+| `e10-cli wf-form linkage <formId> <联动名> --config '{"conditions":[{"field":"请假天数","operator":"EQUAL","value":"3"}],"actions":[{"prop":"hide","fields":["请假事由"]}]}'` | 显隐联动。`--config` 写字段名（自动解析 fieldId/dataKey）；**为空写 `NULL`（或 `EMPTY`，会归一）、不为空写 `NOT_NULL`**（写错平台报的是一句与条件无关的写库异常）。prop: hide/show/edit/readonly/required/hideLine；operator 另有 EQUAL/NOT_EQUAL/CONTAIN/GREATER/LESS 等。顶层可选 `"detailType":"AND\|OR"`（界面「所有/任一」）。**`"effect"` 指定生效维度**（这条路由有四种）：不写=当前表单、`"formLayout"`=**表单布局**、`"workFlow"`=**当前工作流**、`"includeNode"`+`"nodeId"`=**选择节点**（后两者需配 `--workflow-id`） |
 | `e10-cli wf-form validate add <formId> <字段名...> [--remind] [--help <提示>]` | 字段查重规则（多字段 AND，重复禁止提交/提醒）。`list`/`delete <ruleId>`。字段名自动 getConfig 解析 |
 | `e10-cli wf-form relate <formId> <目标字段> --from <Employee/Department源字段> [--key email/department/code/name] [--title <名>]` | 值带出：换表内 Employee/Department 字段自动填目标字段（HRM 属性带出）。`--key` 默认 Employee=department/Department=name。机制同 eb 表（ffRelateField，Employee 源 module=hrm） |
 | `e10-cli wf-form permission get <formId>` | 查看流程表单字段权限（display/readOnly/required/disableEdit）。**写字段权限用 `workflow node field-permission`**（节点级，流程表单表单级写平台多返 500） |
@@ -186,7 +206,8 @@
 | `e10-cli wf-form field-prop <formId>` | 设置运行时布局字段属性：`--required <字段...>`、`--no-required <字段...>`、`--readonly <字段...>`、`--editable <字段...>`、`--single-row <字段...>`。字段可传名称或 ID；内部 getConfig 读取并由 initLayout 保存，同时保留已有分组和独占一行设置 |
 | `e10-cli wf-form group <formId> --groups '{"基本信息":["字段名/ID",...]}'` | 给**已建好的流程表单**加字段分组（折叠容器，对齐 eb 表 `form group`）。建组 saveFieldGroup → 分配 updateFormFieldGroup → initLayout generateCollapse 渲染。`--groups` 可 `@文件`；同名分组复用不重复建（去重） |
 | `e10-cli workflow list <appId>` | 列出应用下的所有流程 |
-| `e10-cli workflow search` | 通用搜索流程（不依赖 appId）。`--name`/`--id`/`--type`/`--belong` |
+| `e10-cli workflow search` | 通用搜索流程（不依赖 appId）。`--name`/`--id`/`--type`/`--belong`。⚠ 列表只回 id/名称/类型名/描述这一层，**不含「绑了哪张表」** |
+| `e10-cli workflow info <workflowId>` | 单个流程的基础信息 + **它关联的表单**（流程 → 表单反查）。给出 `formId`、表单名、启用状态、是 eb 表还是流程表单。⚠ **formId 不是 objId**，表单类命令要 objId，而平台没有直通的 formId → objId 接口 —— 得先确认表单在哪个应用下再按 formId 匹配 |
 | `e10-cli workflow nodes <workflowId>` | 查看流程节点详情（名称、类型、操作者、连线含 linkId） |
 | `e10-cli workflow nodes <wf> --mode list` | 列表视图：展示全节点含 nodeAttr、合流方式（比 chart XML 更全） |
 | `e10-cli workflow set-operator <wf> <node> [keyword]` | 设置节点操作者。`--type user`(指定人) / `role`(指定角色) / `dept`(指定部门) / `position`(指定岗位) / `all`(所有人) / `free`(自由选择) / `superior`(发起人上级) / `initiator`(流程发起人本人) / `prev-node`(上一节点) / `form`(表单相关人员) / `matrix`(矩阵对应,需 `--matrix-id` `--value-config-id` `--matrix-rule`)。`--sign-order` 会签/非会签/竞签/依次处理/抄送/抄送需批注（概念见 guide-workflow）；**`--type form` 另支持「或签」**，等价于竞签（表单字段里多人任一人签，语义一致），已登记的签署顺序里没有单独一档。**依次处理倒序**用 `--execute-order 2-2`(默认)/`2-1`正序/`1-1,2-2`安全级别正序+倒序。**`--dept-scope 本部门`**=单个部门内会签/`本及下级`默认。**一个节点多人用逗号分隔 keyword**（如 `"区域经理,部门领导"`，user/dept 都支持）；默认每次全量重建操作者组（先清空再新建），重复设置不堆积。**多操作者组叠加（如「部门领导矩阵 + 门店经理矩阵」双组会签）：先用 set-operator 配第一组，再用 `--append` 配第二组**，`--append` 不清空已有组，两组合起来就是双矩阵会签 |
@@ -250,7 +271,7 @@
 | `e10-cli workflow plan-range add <planId> --obj-type department\|employee --target-id <id> [--target-name <名>]` | 添加定时触发人员范围（多个目标 ID 用逗号分隔） |
 | `e10-cli workflow plan-range delete <planId> --id <记录ID[,记录ID]>` | 删除定时触发人员范围（**多条逗号分隔**） |
 | `e10-cli workflow advanced schedule-range <wf>` | ⚠ **已弃用**，请改用 `workflow plan-range`。旧命令列表恒显示 0 条、删除恒报「入参不全」 |
-| `e10-cli workflow delete <workflowId>` | 删除流程。`--with-form` 同时删除关联表单 |
+| `e10-cli workflow delete <workflowId>` | 删除流程。`--with-form` 同时删除关联表单。⚠⚠ **只接受流程 ID，不解析名称**：平台对**不存在的 workflowId 也回「删除成功！」**（顶层与 data 层全说成功），所以传名称进去会「报成功但什么都没删」。命令现在**删之前先确认该 id 存在**，查不到就中止并提示用 `workflow search --name <名称>` 拿真实 id；删完还会回读确认 |
 | `e10-cli workflow delete-link <wf> <linkIds...>` | 删除连线（列表 API，可多个）。自动清理关联节点 |
 | `e10-cli workflow delete-node <wf> <nodeId>` | 删除节点（自动清理关联出口）。`--bridge` 桥接上下游 |
 | `e10-cli workflow save-layout <wf> @xmlfile` | 保存完整流程图 XML（浏览器 mxGraph 格式：数字 cell id + nodeId/linkId）。服务器只认浏览器格式，勿转 node_X。新增节点/连线会自动注入 flag="add" |
@@ -436,12 +457,12 @@ e10-cli report py preagg --report-id <id> [--app-id <id>]
 |------|------|
 | `e10-cli matrix list [--name <关键词>] [--enable-status 0\|1] [--org-id <id>]` | 查询矩阵列表（**含停用矩阵**，带状态；`--out` 写 JSON 文件） |
 | `e10-cli matrix create <name> [选项]` | 新建矩阵（**新建即为启用**，要停用再跑 `matrix disable`）。所属机构的字段名由**分权状态**决定，CLI 自动判断并在缺省时用当前机构兜底，分权租户无需手写机构 |
-| `e10-cli matrix config <id>` / `config-edit <id>` | 查看 / 编辑矩阵配置（条件字段 + 值字段） |
+| `e10-cli matrix config <id>` / `config-edit <id>` | 查看 / 编辑矩阵配置（条件字段 + 值字段）。**`config-edit` 的 `--condition` 可省略**，省略则沿用现有条件列（部门/分部矩阵的条件列是平台建矩阵时自动给的，不该手写；已有列要带 `id`，不带会被当成新列去取号）；保存后按列 id 回读比对 |
 | `e10-cli matrix enable <id>` / `disable <id>` | 启用 / 停用（停用后数据只读） |
 | `e10-cli matrix update <id>` / `delete <ids...>` | 更新基本信息（名称/描述/同步方式）/ 删除（级联删配置、数据、维护者） |
-| `e10-cli matrix data` | 矩阵数据维护（映射行） |
+| `e10-cli matrix data` | 矩阵数据维护（映射行）。`data save` 简写为 `[{rowId?, "<列configId>": ["<实体ID>"]}]`：**带 `rowId` 改那一行、不带为新增**（行 id 用 `data list` 拿；同步型矩阵的行 id 就是部门 id）。改行只给要改的列即可，CLI 自动补全其余列并回读比对 |
 
-> 系统矩阵与自定义矩阵的区别、以及「条件列 → 人员列 → 数据映射 → 运行时读回」的完整步骤见 `references/hrm/guide-matrix.md`。
+> 行从哪来（`syncType`）、字段能不能改（`permList` 里有没有 `FIELD`）、以及「条件列 → 人员列 → 数据映射 → 运行时读回」的完整步骤见 `references/hrm/guide-matrix.md`。
 
 ---
 
@@ -499,7 +520,11 @@ e10-cli form read <objId> --app-id <appId> --out fields.json  # 写入 fields.js
 
 # 5. 角色管理
 e10-cli role create 财务主管 --code CW01 --remark "审批角色"
-e10-cli role add-member <roleId> 张三
+e10-cli role add-member <roleId> 张三 李四                        # 人员，可一次多个
+e10-cli role add-member <roleId> 营销三组 --type department      # 部门
+e10-cli role add-member <roleId> 总经理 --type position          # 岗位
+e10-cli role add-member <roleId> 华东分部 --type subcompany      # 分部
+e10-cli role member-list <roleId>                               # 读回成员
 
 # 6. 创建流程
 e10-cli workflow create <appId> <formObjId> 会议室审批

package/skill-docs/references/esb-interface/guide-import.md

@@ -7,7 +7,9 @@ e10-cli interface import "<文档路径>" --out collection.json
 e10-cli interface import "<文档路径>" --system-pool-name "<连接器/系统池名称>" --apply --out collection.json
 ```
 
-支持 `.docx`、`.pdf`、`.md`、`.txt`。默认只解析预览；只有用户明确要求创建时才加 `--apply`。PDF 解析依赖当前机器可用的 `pdftotext`（Poppler）。
+支持 `.docx`、`.pdf`、`.md`、`.txt`、`.xlsx`、`.xls`。默认只解析预览；只有用户明确要求创建时才加 `--apply`。PDF 解析依赖当前机器可用的 `pdftotext`（Poppler）。
+
+`.xlsx` 是表格版接口文档（按「接口目录」+ 每接口一个工作表组织）；`.xls` 是旧版二进制格式，客户/厂商的老文档里常见 —— **别把它当不支持、让用户先转格式**。
 
 ## 处理规则
 
@@ -18,6 +20,7 @@ e10-cli interface import "<文档路径>" --system-pool-name "<连接器/系统
 5. 文档中的密码、token、Authorization、secret、apiKey 等敏感示例值在本地生成 Collection 时脱敏；不要把 Eteamsid 写进文件。
 6. 创建成功必须同时满足外层 `code=200` 和 `data.res=true`，并报告 `systemPk`、接口名称和接口 ID；不能只看 HTTP 200。
 7. 创建接口是新增语义，不提供更新/去重；格式校验先在本地完成，避免重复调用在线接口留下重复系统。
+8. Excel 文档按**不可信输入**对待，解析限额：单文件 ≤ 20 MB、工作表 ≤ 50 个、单表 ≤ 5000 行、单元格总数 ≤ 50 万。超限**直接报错中止**，**不会截断后继续解析** —— 截断会算出一份看不出错的接口清单，比直接失败坏得多。真遇到超限，先跟用户确认是不是拿错了文件（接口文档通常几行到几十行），再谈拆分。
 
 ## 文档提取重点
 

package/skill-docs/references/form/guide-create-form.md

@@ -23,6 +23,19 @@ e10-cli form read <objId> --app-id <appId> --out fields-created.json
 
 需要同时生成台账菜单入口时，在创建命令中增加 `--menu`；建成后也可使用 `menu add-table <appId> <objId>` 添加。默认台账视图与应用菜单入口是两个资源。
 
+### 自定义数据库表名
+
+不指定时表名按表单名拼音首字母加随机数生成（如 `uf_xsddb_4683`）。需要固定或对齐既有命名时用 `--table-name`：
+
+```bash
+e10-cli form create <appId> "客户信息表" --fields @fields.json --table-name cs_khxx
+```
+
+- **平台前缀由 CLI 自动补**：传 `cs_khxx` 与传 `uf_cs_khxx` 结果相同（`uf_cs_khxx`）。
+- **格式约束**：字母开头，只含字母、数字、下划线。前缀之外的部分受平台长度上限约束 —— 前缀 `uf_`、总长上限 30 时，自定义部分最多 27 位。越界会直接报错，不会建成一半。
+- **建成后回读校验**：实际表名与预期不一致会报错，不静默通过。
+- 仅对**物理表**应用有效；应用未启用物理表时该选项不适用（CLI 会先查存储设置并拒绝）。
+
 ## 各阶段配置范围
 
 | 阶段 | 配置内容 |

package/skill-docs/references/form/guide-field-linkage.md

@@ -17,6 +17,8 @@
 | 复杂度 | 简单 | 简单（单源单属性） | 复杂（跨表多跳，ESB 动作流） |
 | 关系 | — | — | **字段联动是关联表带出的进阶版** |
 
+> 本文讲的是**跨表**带出。本表字段之间用公式互相计算赋值的是**函数联动**（eb 表 `form formula-linkage`、流程表单 `wf-form formula-linkage`），见 `guide-formula-linkage.md` —— 两者 `linkageType` 不同（`excel` vs `template`），`form field-linkage list/delete` 看不到也删不掉函数联动。
+
 ## 何时用多跳
 
 **Text 字段赋值必须用名称（多跳），不能直接赋 ID。**

package/skill-docs/references/form/guide-form-formula-functions.md

@@ -14,6 +14,42 @@
 > **纯常量公式**（不含任何字段引用）平台允许，会带一条提示正常保存。
 > 完整原始数据含参数说明/示例结果：`senba6/公式表.json`。
 
+## ⚠️ 写公式前先记住这几条
+
+这四条是**平台侧的语言规则**，写错**不报错**，只是算不对或整段失效 —— 出问题很难往回找。
+
+**1. 函数名称必须大写。** `CONCAT(...)` / `VALUE(...)` / `IF(...)` / `SUM(...)`，小写平台不认。
+> **例外：自定义 JS 脚本函数保持原样大小写** —— `default()`、`replaceAll()`、`countRelate()`、`getAddHrmIds()` 这些（见「自定义JS脚本函数」一类）是用户脚本注册的，名字怎么写就怎么用，**别跟着一起改成大写**。
+
+**2. 逻辑比较用 `==`（两个等号），不是 `=`（一个等号）。**
+
+```
+✅ IF({主表.状态}=="已完成", 1, 0)
+❌ IF({主表.状态}="已完成", 1, 0)      ← 单个等号是赋值语义，不是比较
+```
+
+**3. 给字段赋值用 `=`（一个等号），它只出现在整条公式的最左边。**
+
+```
+{主表.销售金额}=VALUE({主表.数量})*VALUE({主表.单价})
+└──── 赋值，一个等号 ────┘└──── 函数体内部，比较用两个等号 ────┘
+```
+
+顶层那个 `=` 与函数体里的 `==` 是**两个层次**的东西，别因为看见 `=` 就写成 `==`，也别在函数体里把比较写成 `=`。函数联动的赋值式与 CLI 的关系见 `guide-formula-linkage.md`。
+
+**4. 跨表复制粘贴公式，必须把非本表的字段变量换掉。** 从别的表单复制来的公式里，`{主表.X}` / `{明细表.X}` 指的是**原来那张表**的字段。粘到当前表必须逐个替换成本表字段 —— 平台按名字找字段，找不到、或者找到同名但语义不同的字段，**都不会拦住你**，只会静默算出不对的结果。
+
+**5. 选项型控件（Select / RadioBox / CheckBox）要比的值，得引用「选项本身」，不能拿字符串比。**
+
+```
+✅ IF({主表.性别}=={主表.性别.男}, 65, 60)     ← 三段式：表.字段.选项
+❌ IF({主表.性别}=='男', 65, 60)               ← 恒不成立
+```
+
+选项在库里存的是 **valueKey**（一串 id），不是选项名，所以拿 `'男'` 去比**永远不相等**；而平台**照收、不报错、回 200** —— 写完看着全绿，结果永远不对，是最难查的一类错。`e10-cli` 解析到「选项型字段 与字符串字面量 做 `==`/`!=`」会**出声警告**并给出正确写法，但**不会替你改**（表达式合不合法最终由平台定）。
+
+⚠ 选项引用必须写**完整三段**。`[性别.男]` 只有两段，会被当成「明细表 `性别` 里的字段 `男`」—— 两段的方括号写法是既有的「明细表.字段名」，两者撞车，不给它开后门。
+
 ## 函数速查矩阵
 
 | 分类 | 函数（中文名） |

package/skill-docs/references/form/guide-form-layout-incremental.md

@@ -0,0 +1,75 @@
+# 给已有表单改布局
+
+给已经建好的表单加字段、改字段的显示属性时读这篇。**不是自己建的表尤其要读**：改错了别人的版式，对方要一个个调回来。
+
+## 布局是两套数据
+
+| | 存在哪 | 一条是什么 |
+|---|---|---|
+| **字段定义** | 字段管理接口 | 一个字段一条（`fieldId` / `type` / `componentKey` / `title` / `dataKey` / `columnName` …） |
+| **布局组件** | 表单布局接口的 `pageLayouts[].comps` | **平铺一维数组**，每个字段占**两个**：一个标签组件、一个值组件 |
+
+**判断「这个组件属于哪个字段」只能看 `config.associatedId`。**
+标签组件的 `config.fieldId` 是布局自己另生成的一个 id，与字段定义没有对应关系 —— 拿它去找字段会找不到。
+
+明细字段也在同一个平铺数组里，靠 `config.subFormId` 归属；它的 `excel.parent` 指向明细表容器的 `nodeId`，普通字段的 `excel.parent` 是 `ROOT`。
+
+## 字段属性分两类
+
+有些属性**只存在于布局组件里，字段定义没有这个键** —— 只写字段定义等于什么都没做：接口回成功、命令也报成功，表单上一点变化都没有。
+
+| 只存在于布局组件 | 字段定义里也有 |
+|---|---|
+| `required`（必填）、`readOnly`、`singleRow`（独占一行）、`display`、`isHideTitle`、`excel`（位置）、`layout` | `title`、`dataKey`、`columnName`、`maxLen`、`componentKey`、`type`、`format` … |
+
+必填是个典型：一张真实表 53 条字段记录里，**没有一条**带 `required`。设必填就是改布局组件。
+
+## 加字段：默认增量，别动不动重建
+
+`e10-cli form add-field` 默认**只往布局里加这一个字段**，不动其它组件、不动样式模板、不动位置。
+
+`--reinit` 才是整表重建，它会：
+
+- 把样式模板换成工具默认的那一个；
+- 按字段顺序**重算所有位置**（手工调过的行列全没了）；
+- 把标签组件**全部换成新 id**；
+- 布局层的自定义（合并格、列宽、配色）一并丢失。
+
+**不是自己建的表不要用 `--reinit`。** 字段越多越经不起 —— 真实的一张订单主表有 131 个组件。
+
+### 什么时候加字段会中止
+
+布局里**没有同类型的字段可参照**时，命令会中止并说明。
+
+这是设计如此，不是缺陷：新组件的键集（`format`、`earlyDate`、`pointSize`、`showDimension` …）各类型都不一样，只能从同类型的现成组件整套抄过来；按类型名拼一个出来，**猜错不报错、只是渲染异常**。
+
+遇到中止时，两个选择：
+
+1. 先在设计器里手工加一个同类型字段（它就成了可参照的样板），再重跑命令；
+2. 确认这张表是自己建的、不在乎版式被重排 → 显式加 `--reinit`。
+
+## 哪些 id 可以自己生成，哪些必须由平台发号
+
+这一条最容易踩：**编一个 id 不会报错**，而是在之后某个看不出来的环节静默失效。
+
+| 位置 | 能否自己生成 | 说明 |
+|---|---|---|
+| 布局组件的 `id` | ✅ | 布局内唯一即可，形如 32 位十六进制串 |
+| 布局组件的 `excel.nodeId` | ✅ | 布局内唯一即可，短随机串 |
+| 标签组件的 `config.fieldId` | ✅ | 只在布局内有意义，与字段定义无关 |
+| **`labelObj.title` / `titleLabelId`** | ❌ **必须平台发号** | 见下 |
+
+### 为什么标题的 id 必须平台发号
+
+平台把**字段标题存的是标签 id，不是文本本身**。这个 id 要调多语言标签接口（`i18n/multilangLabel/saveLabel`）由平台分配。
+
+自己拼一个（比如拿时间戳凑）的后果：接口**照样回成功**，之后任何要显示这个标题的地方都取不到文字 —— 字段名变成空的，看着就像这个字段不存在。
+
+判断一个标签 id 是否有效：用 `-1` 去查标签，拿到的是一行空值（模板行）。**查一个不存在的标签，返回的结果与查 `-1` 完全一致** —— 所以「查得回来」不等于「标签存在」，要看有没有值。
+
+现成命令：`e10-cli form field-lang set <objId> <appId> <fieldId> --zh <中文> --en <英文>` 会建标签并回写字段，写完还能回读校验。`form add-field` 建字段时也会自动建标签。
+
+## 相关
+
+- 建表时的布局规划见 [EB 表单布局规划](guide-form-layout-planning.md)。
+- 字段类型与属性码表见 [表单字段定义参考](ref-form-fields.md)。

package/skill-docs/references/form/guide-form-linkage.md

@@ -69,10 +69,68 @@ e10-cli form linkage add <appId> <objId> <name> --config @<json文件>
 | 字段 | 说明 |
 |------|------|
 | fieldId | 触发字段的 fieldId（从 `form read --app-id` 获取） |
-| operator | 比较符：`EQUAL`（等于）、`NOT_EQUAL`（不等于）、`CONTAIN`（包含）、`NOT_CONTAIN`（不包含） |
-| value | 普通字段的比较值（文本/数字） |
+| operator | 比较符，见下表 |
+| value | 普通字段的比较值（文本/数字）。**「为空 / 不为空」不要给** |
 | options | Select/RadioBox 字段的选项，格式：`[{"optionId": "选项ID", "content": "选项名"}]` |
 
+比较符：
+
+| 写法 | 含义 | 备注 |
+|------|------|------|
+| `EQUAL` / `NOT_EQUAL` | 等于 / 不等于 | |
+| `CONTAIN` / `NOT_CONTAIN` | 包含 / 不包含 | |
+| `GREATER` / `LESS` / `GREATER_EQUAL` / `LESS_EQUAL` | 大于 / 小于 / 大于等于 / 小于等于 | |
+| **`NULL`** | **为空** | 也可以写 `EMPTY` / `IS_NULL`，命令会归一成平台码 |
+| **`NOT_NULL`** | **不为空** | 也可以写 `NOT_EMPTY` / `IS_NOT_NULL` |
+
+**「为空」的算子写错，报错会指向完全无关的地方。** 平台不认 `EMPTY` 这类写法时不会说「算子不合法」，而是在写库时抛一句 `mybatis PersistenceException / Error updating database` —— 容易让人误判成字段配置问题（真实发生过：被当成「目标字段 `dataKey` 为空导致 NOT NULL」去查，而 `dataKey` 留空本身是没问题的）。用 `NULL` / `NOT_NULL`，或者写 `EMPTY` 交给命令归一。
+
+### 多个条件之间：任一 / 全部
+
+界面上的「满足以下**任一**条件」= `OR`，「满足以下**全部**条件」= `AND`。在 config 顶层写 `detailType`：
+
+```json
+{ "detailType": "OR", "conditions": [ ... ], "actions": [ ... ] }
+```
+
+**不写这个键时由平台取自己的默认值** —— 设计器每次都显式发，所以缺省行为没有依据，命令不替平台决定。多条件时建议明确写。
+
+## 生效维度（生效范围）
+
+联动可以只对**某一种展示形态**生效。在 config 里用 `effect` 指定：
+
+| 写法 | 含义 |
+|------|------|
+| 不写 | **当前表单**（最常见） |
+| `"effect": "formLayout"` | 只对**某个表单布局**生效（布局 id 现查） |
+| `"effect": { ... }` | 直接给 `{effectType, effectName, effectValue}`，自行指定 |
+
+⚠ **布局维度的值要的是 `multipleLayoutId`，不是 `formLayout.id`** —— 同一张表上这两个值**相邻但不同**（实测某表是 `…375` 与 `…376`）。给错了命令**不报错**，只是指向另一个布局，而且平台按这个 id 解析不出名字，回读时生效范围是个空白（`表单布局: `）。命令取的是前者，不用手填。
+
+### 工作流表单那条路由的维度不一样
+
+上面的表是 **eb 表**（`form linkage add`）的。**原生工作流程表单**（`wf-form linkage`）提供的是另外四种，写法也不同：
+
+| 界面上的维度 | `effect` 写什么 | 取值 | 额外参数 |
+|---|---|---|---|
+| 当前表单 | 不写（缺省） | 表单 formId | — |
+| **表单布局** | `"formLayout"` | **布局 id**（默认布局；可用 `"layoutId"` 指定别的） | — |
+| **当前工作流** | `"workFlow"` | **流程 ID** | `--workflow-id` |
+| **选择节点** | `"includeNode"` | **节点 ID** | `--workflow-id` + `"nodeId"`（可写节点名） |
+
+```bash
+e10-cli wf-form linkage <formId> "规则名" --workflow-id <流程ID> --config @cfg.json
+```
+
+```json
+{ "effect": "workFlow",  "conditions": [ ... ], "actions": [ ... ] }
+{ "effect": "includeNode", "nodeId": "1级审批", "conditions": [ ... ], "actions": [ ... ] }
+```
+
+**这条路由的 `refId` 始终是流程 ID**，是「这条联动挂在哪个流程上」，**不是**选项的取值 —— 给「选择节点」时选项取值是节点 ID，两者不同，别照着取值抄。流程表单 formId 与流程 ID 不是一回事，用 `workflow info <流程ID>` 可以反查。
+
+选项的显示名里那个 `【V1】` 是**平台按活动版本自己加的**，写节点名进去它会补成「节点名【V1】」。
+
 ### actions（联动效果）
 
 | 属性 | prop 值 | 效果 |
@@ -152,7 +210,7 @@ e10-cli form linkage add <appId> <objId> <name> --config @<json文件>
 3. **明细表字段列隐藏**：需在明细表第一行配置操作按钮元素
 4. **多规则冲突**：避免同一个触发字段或同一个目标字段出现在多个规则里
 5. **默认属性**：字段的默认显示属性为设计器中设置的"读写属性"或"字段权限"
-6. **目标字段 dataKey**：config 里目标字段需要 `dataKey`，但 `form read` 不返回这个字段——用 `fieldId` 代替可行（`dataKey` 留空或用 `fieldId` 均可）
+6. **目标字段 dataKey**：`form read` 不返回它，**留空即可** —— 平台按 `fieldId` 定位，`dataKey` 空着能正常建规则（已对照验证）。填上真值也行，但别为了凑它去猜；它**不是**某些报错的原因。
 7. **Select 选项 ID**：必须用 `form read --app-id` 返回的真实 `valueKey`（自动生成的长 ID，如 `1294601918674214939`），不能用建表单时给的短 `valueKey`（如 `"GQ"` / `"5"`）
 
 ---