weaver-e10-builder 1.0.11-beta → 1.1.0

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

@@ -0,0 +1,121 @@
+# 字段联动（跨表带出赋值）指南
+
+## 概述
+
+字段联动（FormDataLinkage）：表单字段值改变时，自动查询**另一张表**（按数据ID=触发字段值过滤），把查到的字段值**带出赋值**到本表单字段。支持单跳（一次直接带出）和多跳链式（多次中转后带出）。
+
+背后是一个 ESB FieldLinkage 动作流（触发 + N 个 EnquiryForm 查询 + Output 赋值），CLI 自动完成建 ESB app + saveDesign + 绑定。
+
+## 三种联动对比
+
+| | 属性联动（显隐） | 关联表带出（form relate） | **字段联动（field-linkage）** |
+|---|---|---|---|
+| 命令 | `form linkage add` | `form relate` | `form field-linkage add` |
+| 接口 | viewlinkage | ffRelateField module:hrm | saveFormDataLinkage + saveDesign（ESB） |
+| 作用 | 改字段显示属性（hide/show/required） | 换 Employee/Department→带 HRM 属性 | **查任意表→带出任意字段赋值** |
+| 源 | 表单字段值条件 | Employee/Department（HRM 源） | 任意字段→任意表查询 |
+| 复杂度 | 简单 | 简单（单源单属性） | 复杂（跨表多跳，ESB 动作流） |
+| 关系 | — | — | **字段联动是关联表带出的进阶版** |
+
+## 何时用多跳
+
+**Text 字段赋值必须用名称（多跳），不能直接赋 ID。**
+
+| 场景 | 跳数 | 示例 |
+|------|------|------|
+| 带出字段是 EBuilder（存 ID）→ 目标也是 EBuilder | 单跳 | 关联合同→查合同信息表→带出关联客户（ID→EBuilder 字段） |
+| 带出字段存 ID → 目标是 Text（要名称） | **多跳** | 关联客户→查客户信息表→客户类型(ID)→查客户类型表→类型名称(Text)→填 Text 字段 |
+
+**判断原则**：目标字段是 EBuilder/Select（存 ID）→ 单跳即可；目标字段是 Text（要展示名称）→ 必须多跳到名称表取名称。
+
+## CLI 命令
+
+```bash
+# 列出
+e10-cli form field-linkage list <appId> <objId>
+
+# 回读单条
+e10-cli form field-linkage read <appId> <objId> <linkageId>
+
+# 查源表可带出字段
+e10-cli form field-linkage fields <appId> <formId>
+
+# 删除（批量）
+e10-cli form field-linkage delete <appId> <objId> <linkageId...>
+```
+
+### 新增（add）
+
+**单跳**（一次直接带出）：
+```bash
+e10-cli form field-linkage add <appId> <objId> \
+  --trigger <触发字段名> \
+  --source-form <目标表objId> \
+  --query-field <目标表带出字段名> \
+  --target <本表目标字段名>
+```
+
+**多跳**（多次中转后带出）：
+```bash
+e10-cli form field-linkage add <appId> <objId> \
+  --trigger <触发字段名> \
+  --target <本表目标字段名> \
+  --hops "<源表objId:带出字段名,源表objId:带出字段名,...>"
+```
+
+`--hops` 格式：每跳 `objId:字段名`，逗号分隔。前一跳的带出值 = 下一跳的过滤值（数据ID=前一跳结果）。最后一跳的带出值赋给 `--target`。
+
+## 配置示例
+
+### 示例1：单跳——关联合同→合同信息表→关联客户
+
+```
+关联合同(EBuilder→合同信息表) 值改变
+→ 查合同信息表 by 数据ID=关联合同
+→ 带出关联客户(EBuilder→客户信息表，存ID)
+→ 赋值到本表.关联客户(EBuilder字段，存ID)
+```
+
+```bash
+e10-cli form field-linkage add <appId> <objId> \
+  --trigger 关联合同 --source-form <合同信息表objId> --query-field 关联客户 --target 关联客户
+```
+
+### 示例2：多跳——关联客户→客户信息表→客户类型→客户类型表→类型名称→填Text
+
+```
+关联客户(EBuilder→客户信息表) 值改变
+→ Step1: 查客户信息表 by 数据ID=关联客户 → 带出客户类型(EBuilder→客户类型表，存ID)
+→ Step2: 查客户类型表 by 数据ID=客户类型(Step1结果) → 带出类型名称(Text)
+→ 赋值到本表.客户类型(Text字段，要名称不要ID)
+```
+
+```bash
+e10-cli form field-linkage add <appId> <objId> \
+  --trigger 关联客户 --target 客户类型 \
+  --hops "<客户信息表objId>:客户类型,<客户类型表objId>:类型名称"
+```
+
+### 示例3：链式联动（两条独立 linkage 串联）
+
+关联合同→(linkage1)→关联客户→(linkage2)→客户类型→(linkage3)→类型名称
+
+每条 linkage 的 `--trigger` 是上一条的 `--target`。分开 `add` 多次即可。
+
+## 查源表字段
+
+```bash
+# 查某表单有哪些可带出字段
+e10-cli form field-linkage fields <appId> <formId>
+```
+
+或用 `e10-cli form read <objId> --app-id <appId>` 取字段 fieldId（配置 --hops 时需知道字段名）。
+
+## 注意事项
+
+1. **Text 字段必须多跳取名称**：目标字段是 Text → 带出值必须是名称（文本），不能是 ID。如果源表存的是 ID（EBuilder/Select），需多跳到名称表取名称。
+2. **orgId 必须正确**：CLI 自动从 getForm 取 orgId，传给 application/save 建 ESB app。没有 orgId 的 app 不完整，saveDesign 会 500。
+3. **多跳 EnquiryForm 需要 sources**：非首跳的查询动作必须有 `sources` 指向前一跳，否则服务器报"有两个起始执行组件"（CLI 已处理）。
+4. **FormData 引用格式**：触发字段 `FormData.<本表formId>.<触发字段id>`；查询结果 `FormData.<源表objId>[].field_<带出字段id>`。
+5. **--hops 的 objId 是表单 objId**（不是 formId）。CLI 内部自动解析 objId→formId。
+6. **联动名称**：不传 `--name` 时自动生成 `<本表名>.<触发字段>→<最后源表名>.<最后带出字段>`。

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

@@ -0,0 +1,108 @@
+# 关联页签：目标视图、显示布局与数据筛选
+
+在来源表单的记录页面上新增关联页签，打开已有目标视图，并将当前记录字段作为筛选参数传入。例如：客户信息表 → “全部合同”页签 → 合同信息表的“全部合同”视图。
+
+## 配置前查询
+
+```bash
+e10-cli form association list <objId> <appId>
+e10-cli form association views <objId> <appId>
+e10-cli form association fields <objId> <appId> --view <viewId>
+e10-cli --json form association get <objId> <appId> <associationId>
+```
+
+- `objId` 是放置页签的来源表单，不是目标视图所属表单。
+- `views` 返回目标视图 ID、名称、所属表单。名称重复时必须传 ID。
+- `fields` 分别返回来源字段 `source` 与目标字段 `target`。不要把两端字段 ID 混用。
+- 跨应用通过 `--target-app <appId>` 显式选择，命令验证目标应用菜单树和视图实际归属。
+- `get --json` 的正确写法是全局 `--json`（如上），保留原始权限配置，并额外提供解析后的权限条件 `rules`。
+
+## 创建关联页签
+
+```bash
+e10-cli form association create <objId> <appId> "全部合同" --view <viewId> --layouts 显示 --terminals PC MOBILE --permissions @association-permissions.json --mappings @association-mappings.json
+```
+
+创建时必须明确权限。方案要求所有人可见时，`association-permissions.json` 可写：
+
+```json
+[
+  {
+    "selectedType": "all",
+    "dataid": "0",
+    "levelScope": {"minShowlevel": "", "maxShowlevel": ""},
+    "condition": {"rootdata": ""}
+  }
+]
+```
+
+不要在方案没有要求时默认采用所有人权限。其他组织、角色等权限按平台实际配置提供完整数组；本命令不推断权限对象。
+
+筛选映射文件格式：
+
+```json
+[
+  {"targetField": "关联客户", "sourceField": "客户名称"}
+]
+```
+
+每项含义为“目标视图字段 ← 当前来源记录字段”。支持字段 ID 或唯一显示名称，自动补全 `compType/fieldName/dataIndex` 等元数据。仅支持主表字段到主表字段的映射；明细字段及固定值筛选不在本次支持范围。
+
+上例复现抓包中的配置，不代表所有关联字段都应传名称。目标 EBuilder 字段可能需要记录 ID：应按业务语义选择 `sourceField: "数据ID"` 或指定字段，并用实际记录确认筛选结果。命令不会擅自把用户提供的名称字段改成 ID。
+
+默认启用，默认适用于 PC 和 MOBILE，默认仅显示布局。省略 `--mappings` 表示不添加关联参数；目标视图自身的筛选仍独立生效。创建检测同名页签，重复时停止，改用 `update`。
+
+## 显示布局与其他设置
+
+| 参数 | 含义 |
+|---|---|
+| `--layouts 显示` | `showLayout="0"`：打开显示布局，关闭编辑布局 |
+| `--layouts 编辑` | `showLayout="2"`：仅编辑布局 |
+| `--layouts 显示 编辑` | `showLayout="0,2"`：两种布局都显示 |
+| `--layouts none` | 两种布局均不显示 |
+| `--terminals PC MOBILE` | 两端适用；可只传其中一个 |
+| `--enabled true/false` | 启用或停用页签 |
+
+```bash
+e10-cli form association update <objId> <appId> <associationId> --layouts 显示
+e10-cli form association update <objId> <appId> <associationId> --name "相关合同" --terminals PC --enabled true
+e10-cli form association update <objId> <appId> <associationId> --view <newViewId> --mappings @association-mappings.json
+```
+
+`update` 保留未指定属性以及原动作、权限条件和提示。布局、终端参数表示替换对应集合。修改绑定视图且已有映射时必须显式提供新映射（`[]` 可清空），避免原目标表字段被用于新视图。
+
+## 修改和清空关联数据筛选
+
+```bash
+e10-cli form association set-filter <objId> <appId> <associationId> --mappings @association-mappings.json
+e10-cli form association clear-filter <objId> <appId> <associationId>
+```
+
+设置会替换目标动作的全部筛选映射。存在多个视图动作时，用 `--action <actionId>` 明确选择；只修改该动作，其余动作保留。
+
+这里处理的是 `associationActions[].url` 内的 `params`（`nameType/type=FORMFIELDS`），不会修改目标视图的全局过滤，也不会修改页签的权限条件。
+
+## 权限条件是另一项能力
+
+```bash
+e10-cli form association set-condition <objId> <appId> <associationId> --perm 1 --rules @permission-rules.json --logic or
+e10-cli form association clear-condition <objId> <appId> <associationId> --perm 1
+```
+
+这两条操作 `associationPermissions[].condition.rootdata`，规则格式为 `[{"fieldId":"...","func":"contains","value":"..."}]`。`--perm` 为 1 开始的序号或 `selectedType`；支持 `and/or`。此条件按来源表单字段生成，与“目标视图数据筛选映射”分别配置。
+
+平台权限条件读回是明文 JSON，写入需 LZW 压缩。更新布局或数据筛选时也会重新压缩原有权限条件；不要自行传入压缩字符串。
+
+## 验证与计划
+
+保存后回读目标视图、筛选映射、显示布局、终端、动作和权限相关配置，成功输出 `verified: true`。创建响应可能不带顶层 ID，命令通过列表差集和详情确定新关联 ID。若提示已提交但无法匹配，先 `list/get`，不要直接再次创建。
+
+配置回读不等于验证了浏览器展示或实际筛选结果。验收还应打开来源记录的显示/编辑布局，检查页签显示范围，并用已知关联与非关联记录检查目标视图结果。
+
+在计划模板 3.3 中逐项填写：
+
+- 关联页签：来源表单/objId、页签名称/associationId、目标应用/表单/视图 ID、权限依据。
+- 布局与终端：显示布局是否开启、编辑布局是否开启、PC/MOBILE、启用状态。
+- 数据筛选：每条目标字段 ← 来源字段，注明传记录 ID 还是字段值，以及配置回读和实际结果验收情况。
+
+先创建目标视图，再创建依赖它的关联页签；关联 ID、视图 ID、动作 ID 不能互换。未验证的项保留待办，不预先打勾。

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

@@ -0,0 +1,54 @@
+# 台账视图按钮显示位置
+
+用于将已有系统按钮或自定义按钮显示在指定视图的行上、行末下拉或顶部。配置的是按钮 `showPosition`，与整行点击的 `form list-event`、字段点击的 `form list-click` 独立。
+
+## 查询与设置
+
+```bash
+e10-cli form button list <objId> <appId>
+e10-cli form button views <objId> <appId> <buttonId>
+e10-cli form button position <objId> <appId> <buttonId> --view <listId> --position 行上
+```
+
+`views` 返回平台 `getViewDatas` 对此按钮开放的视图，以及现有位置配置。`--view` 支持视图 ID、唯一名称、表单页语义“新建/编辑/显示”；多个同名视图必须用 ID。省略视图或使用“台账”时，必须只有一个可选台账，否则拒绝保存。
+
+| 显示位置 | 平台值 |
+|---|---|
+| 右上 | `rightTop` |
+| 右上下拉 | `rightTopDropDown` |
+| 行上（行内） | `lineEnd` |
+| 行末下拉 | `LineEndDropDown` |
+
+行上、行末下拉只适用于台账，不适用于表单新建/编辑/显示页。
+
+## 多视图及替换语义
+
+普通设置默认合并：仅更新指定视图，保留其余台账及表单页的位置。同一视图的旧位置数组由此次指定的位置数组替换；需要多位置时一次传齐。
+
+```bash
+e10-cli form button position <objId> <appId> <buttonId> --view <listId> --position 行上 右上
+e10-cli form button position <objId> <appId> <buttonId> --show-position @button-positions.json
+```
+
+不同视图使用不同位置时，JSON 文件示例（将 ID 占位替换为实际值）：
+
+```json
+{
+  "<listIdA>_table": ["lineEnd"],
+  "<listIdB>_table": ["LineEndDropDown"],
+  "show_form": ["rightTop"],
+  "edit_form": ["rightTopDropDown"]
+}
+```
+
+`--show-position` 也默认合并，不能与 `--position/--view` 同时使用。显式 `--replace` 才替换全部页面配置；未列出的页面不再显示该按钮。`--show-position '{}' --replace` 清空所有显示位置。
+
+新建自定义按钮也支持 `form button add ... --view <listId> --position 行上`。按钮点击动作仍由原有动作配置决定；改变显示位置不会自动添加行数据参数。
+
+## 保存与验证
+
+命令先分页查找按钮，再读取动作、权限和可选视图。提交时保留按钮基础配置、完整动作和权限，及接口返回的日志/自定义提示设置，并按视图实际名称重建 `showPositionSpan`。
+
+保存后回读按钮位置并核对动作、权限 ID 集合；成功输出 `verified: true`。若提示“已保存，但回读不一致”，远端可能已修改，必须先重新查询再处理。该验证属于配置回读，不代表已验证按钮点击行为或浏览器渲染。
+
+计划模板 3.3 中必须记录：按钮名称/ID、目标视图名称/ID、显示位置、验证结果。只有需求涉及按钮展示时才填写，无需求标“— 无”。系统删除按钮测试仅核对配置和显示，不点击删除业务数据。

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

@@ -0,0 +1,48 @@
+# 表单数据 CLI 操作
+
+通过 CLI 读写表单数据（不需要写页面代码）。JS 编码 API（getSimpleData/saveFormData 等）见 `coding/guide-form-crud.md`。
+
+## 读数据
+
+```bash
+e10-cli form data list <objId> [--page <n>] [--size <n>]
+```
+
+返回该表单数据记录。`--page` 页码（缺省 1）、`--size` 每页条数（缺省 1000；不传 pageInfo 平台默认卡 10 条）。
+
+## 写数据（新增）
+
+```bash
+e10-cli form data add <objId> <appId> @data.json
+# 或直接传 JSON：e10-cli form data add <objId> <appId> '{"单行文本":"x","金额":1000,"类型":"A"}'
+```
+
+data.json 格式（`@` 开头为文件路径）。key 可用 **fieldId（长 ID）或字段名（中文）**，CLI 自动按字段类型构造（走 `form/core/saveFormData`，dataDetails 按类型分）：
+
+```json
+{
+  "单行文本": "张三",
+  "金额": 1000,
+  "签订日期": "2026-01-01",
+  "类型": "A",
+  "备注": "一段文字"
+}
+```
+
+| 字段类型 | 值格式 |
+|---------|--------|
+| Text / Number / Money | 直接值 |
+| TextArea | 直接值（文本） |
+| Date / DateTime | `"2026-01-01"` / `"2026-01-01 10:30"` |
+| Select / RadioBox | **选项名（自动解析为 valueKey）** 或 valueKey（长 ID） |
+| CheckBox / SelectMultiple | 选项名数组 `["A","B"]` 或 valueKey 数组 |
+| Employee / Department | 用户/部门 ID（暂未支持按名解析） |
+| FileComponent | `"fileid1,fileid2"` |
+
+> **除非用户明确要求，否则不要往表单写入任何数据。** 表单创建完成后只需确认字段正确即可，不要自动插入测试数据。
+
+## 删数据
+
+```bash
+e10-cli form data delete <objId> <dataId>
+```