weaver-e10-builder 1.5.12 → 1.5.13

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

@@ -1,16 +1,26 @@
-# 表单字段显隐联动指南
+# 显示属性联动指南
 
 ## 概述
 
-字段显隐联动：当某些字段的值满足条件时，自动改变其他字段的显示属性（隐藏/显示/编辑/只读/必填）。
+显示属性联动根据字段值或布尔公式的结果，改变字段、选项或明细表组件的显示与读写属性。它适合在同一布局中按业务条件动态切换；不同流程节点无条件地采用不同布局或固定权限时，仍使用节点布局或节点字段权限。
 
-## CLI 命令
+条件不满足时，目标恢复到布局中的默认读写属性。不同规则同时命中同一字段时，平台优先级为：隐藏 > 只读 > 必填 > 编辑；同一触发字段或目标字段尽量避免落入多条相互冲突的规则。
+
+## 规则生命周期
 
 ```bash
-e10-cli form linkage add <appId> <objId> <name> --config @<json文件>
+e10-cli form linkage add <appId> <objId> <名称> --config @rule.json [--disabled]
+e10-cli form linkage list <appId> <objId> [--keyword <名称>]
+e10-cli form linkage get <appId> <objId> <规则ID> --json
+e10-cli form linkage layout-targets <appId> <objId>
+e10-cli form linkage state <appId> <objId> <规则ID> --set on|off
+e10-cli form linkage update <appId> <objId> <规则ID> [--name <新名称>] [--config @patch.json]
+e10-cli form linkage delete <appId> <objId> <规则ID>
 ```
 
-## 配置 JSON 格式
+规则名最长 200 字。新增默认启用，`--disabled` 可新建为停用；启停独立保存并读回。更新先读详情，只替换 `--name` 或配置中明确提供的 `conditions`、`detailType`、`effect`、`actions`、公式；未提供的部分保持原样。`actions` 是整组替换，修改前先用 `get --json` 核对现有目标。删除时按当前表单核对规则归属，再删除并回读确认。
+
+## 配置结构
 
 ```json
 {
@@ -23,6 +33,7 @@ e10-cli form linkage add <appId> <objId> <name> --config @<json文件>
   ],
   "actions": [
     {
+      "linkageObj": "field",
       "prop": "hide",
       "fields": [
         {
@@ -62,9 +73,9 @@ e10-cli form linkage add <appId> <objId> <name> --config @<json文件>
 
 **怎么认出明细字段**：`form read` 的输出里，明细字段会标注所属明细表 —— 带 `明细表: xxx` 那些就是，照它填 `isDetail: true`。
 
-### conditions（触发条件）
+### 简易条件 `conditions`
 
-多个条件之间是 **AND** 关系（全部满足才触发）。
+多个条件用顶层 `detailType: "AND" | "OR"` 指定全部满足或任一满足；未指定时由平台采用默认值。
 
 | 字段 | 说明 |
 |------|------|
@@ -72,6 +83,8 @@ e10-cli form linkage add <appId> <objId> <name> --config @<json文件>
 | operator | 比较符，见下表 |
 | value | 普通字段的比较值（文本/数字）。**「为空 / 不为空」不要给** |
 | options | Select/RadioBox 字段的选项，格式：`[{"optionId": "选项ID", "content": "选项名"}]` |
+| sourceFieldId | 以另一个表单字段的值作右值，走 `VARIABLE`，与常量值二选一 |
+| sourceContent | 人员、日期等结构化常量对象，直接编码为平台 `sourceContent`；与 `value/options` 二选一 |
 
 比较符：
 
@@ -85,6 +98,8 @@ e10-cli form linkage add <appId> <objId> <name> --config @<json文件>
 
 **「为空」的算子写错，报错会指向完全无关的地方。** 平台不认 `EMPTY` 这类写法时不会说「算子不合法」，而是在写库时抛一句 `mybatis PersistenceException / Error updating database` —— 容易让人误判成字段配置问题（真实发生过：被当成「目标字段 `dataKey` 为空导致 NOT NULL」去查，而 `dataKey` 留空本身是没问题的）。用 `NULL` / `NOT_NULL`，或者写 `EMPTY` 交给命令归一。
 
+触发字段可以是主表或明细表字段，也可包含平台返回的系统字段 ID。主表触发控制明细字段时，目标整列变化；明细字段触发本表同一行的目标字段时，按行变化。明细字段触发主表或其他明细表目标时，任意一行满足即可触发。复杂值类型先从现有字段和选项读回真实 ID，不猜测。
+
 ### 多个条件之间：任一 / 全部
 
 界面上的「满足以下**任一**条件」= `OR`，「满足以下**全部**条件」= `AND`。在 config 顶层写 `detailType`：
@@ -95,6 +110,10 @@ e10-cli form linkage add <appId> <objId> <name> --config @<json文件>
 
 **不写这个键时由平台取自己的默认值** —— 设计器每次都显式发，所以缺省行为没有依据，命令不替平台决定。多条件时建议明确写。
 
+### 布尔函数条件
+
+与 `conditions` 二选一。编写前用 `e10-cli form formula functions --scene form-view-linkage` 查询该场景可选函数；例如不为空用 `NOT(ISEMPTY(...))`。可在配置中写 `"formula":"{主表.任务编号}==1111"` 并可选写 `formulaName`，CLI 解析字段引用，按 `Boolean` 返回类型保存公式，再把返回的公式 ID 绑定到显示属性联动。也可传已有公式的 `formulaId` 和 `formulaName`。公式保存若要求平台二次验证，命令会明确报错并停止，不会把未保存的公式当成成功；公式已保存而联动保存失败时应先核对公式 ID，避免重复创建。
+
 ## 生效维度（生效范围）
 
 联动可以只对**某一种展示形态**生效。在 config 里用 `effect` 指定：
@@ -136,13 +155,35 @@ e10-cli wf-form linkage <formId> "规则名" --workflow-id <流程ID> --config @
 | 属性 | prop 值 | 效果 |
 |------|---------|------|
 | 隐藏 | `hide` | 字段隐藏不可见 |
-| 隐藏行 | `hideLine` | 字段所在行整行隐藏（仅表格布局；`hideRow` 兼容旧写法） |
+| 隐藏行 | `hideLine` | 字段所在行整行隐藏（表格式布局；流式布局效果与隐藏相同；`hideRow` 兼容旧写法） |
 | 显示（只读） | `show` | 字段显示但不可编辑 |
 | 编辑 | `edit` | 字段显示且可编辑 |
 | 只读 | `readonly` | 字段显示且不可编辑（同 show） |
 | 必填 | `required` | 字段显示且必填（条件满足时必填） |
 
-**优先级**：`hide` > `readonly` > `edit`
+对象类型写在每个 action 的 `linkageObj`：
+
+| 对象 | 写法与允许效果 |
+|---|---|
+| 字段 `field`（缺省） | `fields[]` 指目标字段；hide/show/edit/readonly/required/hideLine。明细目标加 `isDetail:true` |
+| 选项 `option` | `fields[]` 指选项所属字段，`options[]` 逐项给 `fieldId/optionId/optionName`；hide/disabled |
+| 明细表组件 `detail` | `fields[]` 指明细表组件 ID、名称与类型；hide/show/edit/readonly/hideLine |
+| 布局组件 `layout` | `fields[]` 指布局组件 ID，CLI 从 `layout-targets` 查询并补全完整组件对象；hide/show/hideLine |
+
+一条规则可含多个不同对象的 action。选项型对象包含单选框、复选框、下拉单选／多选、图片单选／多选；按平台的真实选项 ID 配置。布局组件以 `layout-targets` 实际返回的可选列表为准；当前抓包已确认折叠分组 `Fold` 的保存结构，其他类型是否可选取决于当前表单布局和平台返回值。
+
+布局组件示例：先执行 `form linkage layout-targets <appId> <objId>` 取得分组的 `id`，再在配置中写：
+
+```json
+{
+  "conditions": [{"fieldId":"updater","operator":"EQUAL","sourceContent":{"valueType":"LIST","optionValues":[{"valueType":"TEXT","textValue":"员工ID","name":"员工名"}]}}],
+  "actions": [{"linkageObj":"layout","prop":"hideLine","fields":[{"id":"布局组件ID"}]}]
+}
+```
+
+CLI 会根据 `id` 读取可选目标并使用平台返回的完整对象保存；不在可选列表中的组件会被拒绝。`hideLine` 在表格式布局隐藏所在行，流式布局与隐藏效果一致。
+
+**优先级**：`hide` > `readonly` > `required` > `edit`
 
 多个联动规则同时满足时，优先级高的生效。
 
@@ -182,7 +223,7 @@ e10-cli wf-form linkage <formId> "规则名" --workflow-id <流程ID> --config @
   "conditions": [
     {
       "fieldId": "金额字段ID",
-      "operator": "GREATER_THAN",
+      "operator": "GREATER",
       "value": "10000"
     }
   ],
@@ -204,66 +245,15 @@ e10-cli wf-form linkage <formId> "规则名" --workflow-id <流程ID> --config @
 
 ## 注意事项
 
-1. **主表 vs 明细表**：主表触发字段可修改主表或明细字段；明细表触发字段只能修改本行字段。
+1. **主表 vs 明细表**：主表触发字段可修改主表或明细字段（明细目标按整列变化）；明细表触发本表同一行字段时按行变化，触发主表或其他明细表目标时任意一行满足即可触发。
    目标落在明细表里时，`actions[].fields[]` 那个条目**必须带 `isDetail: true`**；不带的话这个目标会被当作主表字段提交
-2. **表格布局限制**：通过隐藏行/列/单元格自定义属性隐藏的字段，无法通过联动显示出来
-3. **明细表字段列隐藏**：需在明细表第一行配置操作按钮元素
-4. **多规则冲突**：避免同一个触发字段或同一个目标字段出现在多个规则里
+2. **表格布局限制**：通过隐藏行/列/单元格自定义属性隐藏的字段，无法通过联动显示出来；表格式布局中的“隐藏”只隐藏标题与字段组件，不隐藏单元格区域和样式
+3. **明细表字段列隐藏**：需在明细表第一行配置操作按钮元素。明细表本体与表内字段的读写属性独立；即使所有列只读，明细表仍可能允许增删行。默认隐藏的明细字段不能由本行联动重新显示；默认显示的明细字段按行联动隐藏时，列标题仍可显示
+4. **多规则冲突**：避免同一个触发字段或同一个目标字段出现在多个规则里。若规则 A 只看字段 A、规则 B 同时看 A 和 B，B 满足时可能覆盖 A；B 不满足时平台可能回落默认读写属性，而非继续执行规则 A
 5. **默认属性**：字段的默认显示属性为设计器中设置的"读写属性"或"字段权限"
 6. **目标字段 dataKey**：`form read` 不返回它，**留空即可** —— 平台按 `fieldId` 定位，`dataKey` 空着能正常建规则（已对照验证）。填上真值也行，但别为了凑它去猜；它**不是**某些报错的原因。
 7. **Select 选项 ID**：必须用 `form read --app-id` 返回的真实 `valueKey`（自动生成的长 ID，如 `1294601918674214939`），不能用建表单时给的短 `valueKey`（如 `"GQ"` / `"5"`）
 
 ---
 
-## 值带出（编辑已有字段的 ffRelateField）
-
-值带出不是 `linkage add` 的显隐规则，而是**字段级配置**（`ffRelateField`）：当 EBuilder 关联字段选中某条记录后，自动将该记录的某个字段值复制到当前字段。例如：选客户→自动带出联系人；选合同→自动带出合同金额。
-
-### 创建时配置
-
-`form create --fields` 里用 `relateFrom` 定义，CLI 在 create Step 3 自动配置 ffRelateField：
-
-```json
-{ "componentKey": "Text", "fieldName": "联系人",
-  "relateFrom": { "ebuilderField": "关联客户", "sourceFieldId": "1296220571782152194" } }
-```
-
-### 创建后补配
-
-```bash
-e10-cli form edit-field <objId> <appId> <fieldId> \
-  --relate-from <EBuilder字段名> \
-  --relate-from-source <目标表单源字段fieldId>
-```
-
-> ⚠️ **`sourceFieldId` 和 `--relate-from-source` 必须传字段的数字 fieldId**（如 `1296220571782152194`），不能传字段名（如"联系人姓名"）。用 `form read <objId> --app-id <appId>` 获取字段的 fieldId。
-
-- `--relate-from`：本表单中的 EBuilder 关联字段名（如 `"关联客户"`）
-- `--relate-from-source`：关联目标表单中要复制值的字段 fieldId
-
-### HRM 值带出（form relate，表内 Employee/Department 源）
-
-换表内的**人员字段**或**部门字段**自动填目标字段。源字段是表单里的 Employee/Department 类型，目标字段按 HRM 属性带出值。结构差异：**Employee 源 ffRelateField 带 `module:"hrm"`，Department 源不带**。
-
-```bash
-# 换「申请人」(Employee) → 自动填「申请人工号」为邮箱
-e10-cli form relate <appId> <objId> 申请人工号 --from 申请人 --key email
-
-# 换「所属部门」(Department) → 自动填「申请人工号」为部门编号
-e10-cli form relate <appId> <objId> 申请人工号 --from 所属部门 --key code
-```
-
-参数：
-| 参数 | 说明 |
-|------|------|
-| `<targetField>` | 目标字段（被填充），名称或 fieldId |
-| `--from <field>` | 源字段（触发），必须 Employee 或 Department 类型 |
-| `--key <key>` | 带出属性 key。默认 Employee=`department`、Department=`name`。不传 `--title` 时自动取属性中文名 |
-
-`--key` 从平台清单校验（`listBusinessField`），非法 key 会报错并列出可选属性：
-
-**Employee 源**（人员属性，部分）：`username`姓名 / `email`邮箱 / `superior`上级 / `mobile`手机 / `jobNum`工号 / `hiredate`入职时间 / `department`部门 / `position`岗位 / `grade`职级 / `allSuperiors`所有上级 …
-
-**Department 源**（部门属性，全部）：`name`部门名称(→Text) / `code`部门编号(→Text) / `parent`上级部门(→Department) / `fullname`部门全称(→Text) / `department.coadjutant`协办人(→RelateBrowser) / `deptEmployee`部门人员(→Employee)
-
-> 目标字段类型与属性不匹配时命令只提示警告、不阻止（如 `deptEmployee` 通常只能填 Employee 字段）。
+字段值带出与赋值（`relateFrom`、`form relate`、`form field-linkage`）见 [字段联动指南](guide-field-linkage.md)。

package/skill-docs/references/workflow/guide-workflow.md

@@ -139,7 +139,7 @@ e10-cli workflow nodes <workflowId>
 ```bash
 # 指定人
 e10-cli workflow set-operator <workflowId> <nodeId> 张三
-# 指定角色
+# 指定角色（名称精确优先；子串命中多个时会列出候选，要求改用完整名称或角色 ID）
 e10-cli workflow set-operator <workflowId> <nodeId> 财务主管 --type role
 # 发起人上级
 e10-cli workflow set-operator <workflowId> <nodeId> --type superior