weaver-work-cli 0.1.23 → 0.1.25

package/skills/weaver-e10-builder/references/form/guide-form-layout-incremental.md

@@ -0,0 +1,90 @@
+# 给已有表单改布局
+
+给已经建好的表单加字段、改字段的显示属性时读这篇。**不是自己建的表尤其要读**：改错了别人的版式，对方要一个个调回来。
+
+## 布局是两套数据
+
+| | 存在哪 | 一条是什么 |
+|---|---|---|
+| **字段定义** | 字段管理接口 | 一个字段一条（`fieldId` / `type` / `componentKey` / `title` / `dataKey` / `columnName` …） |
+| **布局组件** | 表单布局接口的 `pageLayouts[].comps` | **平铺一维数组**，每个字段占**两个**：一个标签组件、一个值组件 |
+
+**判断「这个组件属于哪个字段」只能看 `config.associatedId`。**
+标签组件的 `config.fieldId` 是布局自己另生成的一个 id，与字段定义没有对应关系 —— 拿它去找字段会找不到。
+
+明细字段也在同一个平铺数组里，靠 `config.subFormId` 归属；它的 `excel.parent` 指向明细表容器的 `nodeId`，普通字段的 `excel.parent` 是 `ROOT`。
+
+**EXCEL 布局还有第三份：网格。** `pageLayouts[].config.workbook.Sheet1.cells` 里每个组件占**一格**，靠 `style.cellType.comId` 认到自己的组件，位置也以格子自己的 `row` / `col` 为准 —— **设计器按网格渲染**。所以 EXCEL 表里「组件的 `config.excel.row` / `col`」和「格子的 `row` / `col`」是同一件事的两份副本，**改一份必须改两份**：只改组件层的话接口会回成功，但设计器里画不出来。
+
+FLOW 布局**没有** `config.workbook`（它靠 `config.flow.parent` / `nodes` 排布），这条对它不适用。
+
+> 这份同步由 CLI 负责，不用手工做。但**手工在页面上改过布局的老表**如果在 EXCEL 上有字段显示不出来，在设计器里保存一次即可 —— 设计器会按组件重算网格。
+
+## 字段属性分两类
+
+有些属性**只存在于布局组件里，字段定义没有这个键** —— 只写字段定义等于什么都没做：接口回成功、命令也报成功，表单上一点变化都没有。
+
+| 只存在于布局组件 | 字段定义里也有 |
+|---|---|
+| `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`、`switchType` …）各类型都不一样，**按类型名拼一个出来只会猜错，而猜错不报错、只是渲染异常**。所以增量插入一向是**照同类型的现成组件整套抄**。
+
+表里没有同类型字段时，模板改从平台取：命令会调 `getFormFieldExist`，拿**平台按这个字段生成的组件模板**（`configPC`）—— 顶层样式键（按类型）与类型专有键平台都给全了，结构尾键从同作用域的现成组件借，位置和身份键由命令自己写。**全程不重建布局。**
+
+两点要知道：
+
+- 明细表字段拿不到这个接口的模板（它只返回主表与系统字段），但模板是**按类型而不是按作用域**的，此时借主表同类型的那一份。
+- 拿模板只在**真的缺**时才多打一次接口；表里已有同类型字段时，路径与从前一字不差。
+
+### 明细表的字段是横着排的
+
+同一个「加字段」，**主表和明细表落的轴不一样**：主表是一行一个字段（新字段**往下加行**），明细表是一个字段占一列（新字段**往右加列**）。明细表还有自己的一张网格（`workbook` 的键就是 `DetailTable` 组件的 id），明细字段的格子在那张里，不在 `Sheet1`。
+
+遇到中止时，两个选择：
+
+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/skills/weaver-e10-builder/references/form/guide-form-layout-planning.md

@@ -0,0 +1,68 @@
+# EB 表单布局规划
+
+本指南用于从需求文档识别 FLOW/EXCEL 布局，并将布局要求完整写入 plan 和 `fields.json`。表单创建顺序见 [新建 EBuilder 表单](guide-create-form.md)。
+
+## 确认布局类型
+
+- `FLOW`：流式布局。
+- `EXCEL`：表格式布局。
+- 使用 `form create --layout FLOW|EXCEL` 在创建时指定。
+- 需求未明确且选择会改变最终布局时，建表前向用户确认。
+
+## 识别布局样表
+
+识别发生在读取需求文档之后、编写 `plan.md` 之前。先整理字段定义，再扫描布局章节和表格。
+
+出现以下特征时，将表格作为布局样表：
+
+- 上下文说明“表格式布局”“Excel 样式”或“按照如下布局”；
+- 单元格包含 `[字段名]`，或呈现标签与字段控件交替结构；
+- 存在表单标题、分组标题、合并单元格、有意义的空白位置；
+- 表格表达字段摆放位置，而不是重复列出字段名称、类型和说明。
+
+逐行识别表单标题、分组标题、字段标签、字段控件、空白占位、同排字段、合并和跨列关系，以及必填、只读、独占一行等显示属性。优先使用 `e10-cli docx read` 生成的 Markdown 表格；合并区域不清晰时查看原 DOCX 中对应表格结构。
+
+## 写入 Plan
+
+识别结果分别写入同一表单的两个部分：
+
+1. “字段定义”：保存字段类型和可以直接创建的属性。
+2. “表单布局蓝图”：逐行保存标题、分组、字段同排关系、顺序、空白占位、跨列信息和原文说明。
+
+```markdown
+##### 表单布局蓝图
+
+| 行 | 区域/分组 | 左侧 | 右侧 | 布局说明 |
+|---|---|---|---|---|
+| 1 | 标题 | 项目信息表 | — | 合并整行 |
+| 2 | 基本信息 | 项目名称 | 项目编号 | 同排两列 |
+| 3 | 基本信息 | 项目简介 | — | 独占整行 |
+```
+
+轻量核对原样表中的每个字段，确保同时出现在字段定义和布局蓝图中，并保留同排关系和分组顺序。
+
+## 转换为 fields.json
+
+- 数组顺序表示字段展示顺序。
+- `group` 表示需求明确的分组。
+- `singleRow:true` 表示独占一行。
+- `required:true`、`readOnly:true`、`hidden:true` 表示显示属性。
+
+```json
+[
+  {"componentKey":"Text","fieldName":"项目名称","group":"基本信息","required":true},
+  {"componentKey":"Text","fieldName":"项目编号","group":"基本信息","readOnly":true},
+  {"componentKey":"TextArea","fieldName":"项目简介","group":"基本信息","singleRow":true}
+]
+```
+
+只有需求明确要求分组时才设置 `group`；需求未要求时保持不分组。
+
+## 创建与局部调整
+
+```bash
+e10-cli form create <appId> "<表单名>" --fields @fields.json --layout EXCEL
+e10-cli form layout read <objId>
+```
+
+创建后需要调整局部位置或显示属性时，使用 `form layout` 下的移动、只读和必填设置命令；具体参数通过 `form layout --help` 查询。

package/skills/weaver-e10-builder/references/form/guide-form-linkage.md

@@ -0,0 +1,269 @@
+# 表单字段显隐联动指南
+
+## 概述
+
+字段显隐联动：当某些字段的值满足条件时，自动改变其他字段的显示属性（隐藏/显示/编辑/只读/必填）。
+
+## CLI 命令
+
+```bash
+e10-cli form linkage add <appId> <objId> <name> --config @<json文件>
+```
+
+## 配置 JSON 格式
+
+```json
+{
+  "conditions": [
+    {
+      "fieldId": "触发字段ID",
+      "operator": "EQUAL",
+      "options": [{"optionId": "选项ID", "content": "选项名"}]
+    }
+  ],
+  "actions": [
+    {
+      "prop": "hide",
+      "fields": [
+        {
+          "fieldId": "目标字段ID",
+          "name": "字段名称",
+          "dataKey": "字段编码",
+          "fieldType": "Employee",
+          "isDetail": false
+        }
+      ]
+    }
+  ]
+}
+```
+
+### actions[].fields[]（联动目标字段）
+
+| 键 | 说明 |
+|------|------|
+| fieldId | 目标字段的 fieldId（从 `form read --app-id` 获取） |
+| name | 字段名（显示用） |
+| dataKey | 字段编码；`form read` 不返回它，**留空即可**（用 fieldId 代替可行） |
+| fieldType | 字段类型，如 `Text` / `Employee` / `Date` |
+| **`isDetail`** | **目标落在明细表里时必须为 `true`**。不传 = 主表字段 |
+
+**目标字段在明细表里，就加 `"isDetail": true`** —— 这是「主表字段控制明细列显隐」的写法，两个方向都支持（`hide` / `required` 均可）：
+
+```json
+{
+  "conditions": [{ "fieldId": "<主表字段ID>", "operator": "EQUAL", "value": "Y" }],
+  "actions": [{
+    "prop": "hide",
+    "fields": [{ "fieldId": "<明细列ID>", "name": "明细列A", "dataKey": "", "fieldType": "Text", "isDetail": true }]
+  }]
+}
+```
+
+**怎么认出明细字段**：`form read` 的输出里，明细字段会标注所属明细表 —— 带 `明细表: xxx` 那些就是，照它填 `isDetail: true`。
+
+### conditions（触发条件）
+
+多个条件之间是 **AND** 关系（全部满足才触发）。
+
+| 字段 | 说明 |
+|------|------|
+| fieldId | 触发字段的 fieldId（从 `form read --app-id` 获取） |
+| 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 值 | 效果 |
+|------|---------|------|
+| 隐藏 | `hide` | 字段隐藏不可见 |
+| 隐藏行 | `hideLine` | 字段所在行整行隐藏（仅表格布局；`hideRow` 兼容旧写法） |
+| 显示（只读） | `show` | 字段显示但不可编辑 |
+| 编辑 | `edit` | 字段显示且可编辑 |
+| 只读 | `readonly` | 字段显示且不可编辑（同 show） |
+| 必填 | `required` | 字段显示且必填（条件满足时必填） |
+
+**优先级**：`hide` > `readonly` > `edit`
+
+多个联动规则同时满足时，优先级高的生效。
+
+## 示例
+
+### 示例 1：优先级=高 时隐藏负责人字段
+
+```json
+{
+  "conditions": [
+    {
+      "fieldId": "1290473132445114373",
+      "operator": "EQUAL",
+      "options": [{"optionId": "1290473132445114394", "content": "高"}]
+    }
+  ],
+  "actions": [
+    {
+      "prop": "hide",
+      "fields": [
+        {
+          "fieldId": "1290473132445114370",
+          "name": "负责人",
+          "dataKey": "fzr48cef",
+          "fieldType": "Employee"
+        }
+      ]
+    }
+  ]
+}
+```
+
+### 示例 2：金额 > 10000 时审批人变为只读
+
+```json
+{
+  "conditions": [
+    {
+      "fieldId": "金额字段ID",
+      "operator": "GREATER_THAN",
+      "value": "10000"
+    }
+  ],
+  "actions": [
+    {
+      "prop": "readonly",
+      "fields": [
+        {
+          "fieldId": "审批人字段ID",
+          "name": "审批人",
+          "dataKey": "spr89abc",
+          "fieldType": "Employee"
+        }
+      ]
+    }
+  ]
+}
+```
+
+## 注意事项
+
+1. **主表 vs 明细表**：主表触发字段可修改主表或明细字段；明细表触发字段只能修改本行字段。
+   目标落在明细表里时，`actions[].fields[]` 那个条目**必须带 `isDetail: true`**；不带的话这个目标会被当作主表字段提交
+2. **表格布局限制**：通过隐藏行/列/单元格自定义属性隐藏的字段，无法通过联动显示出来
+3. **明细表字段列隐藏**：需在明细表第一行配置操作按钮元素
+4. **多规则冲突**：避免同一个触发字段或同一个目标字段出现在多个规则里
+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 字段）。

package/skills/weaver-e10-builder/references/form/guide-form-message.md

@@ -0,0 +1,74 @@
+# 消息提醒（表单数据提醒）
+
+表单数据发生**新建 / 修改 / 删除**时，按配置把消息推给指定的人。位置在 **表单模型 → 消息提醒 → 表单数据提醒**（同一页面还有个「动作流提醒」页签，是另一条链路）。
+
+一条提醒由这几样组成：**触发时机 + 推送渠道 + 标题内容 + 落地页 + 提醒对象**，整体可**启用 / 停用**。
+
+## 命令
+
+| 命令 | 用途 |
+|---|---|
+| `form message list <appId> [--obj-id <objId>] [--keyword <kw>]` | 列出提醒。不传 `--obj-id` 就是把整个应用的列出来 |
+| `form message get <appId> <triggerId>` | 看单条，含**推送渠道**与提醒对象 |
+| `form message add <appId> <objId> --name <名称>` | 新建 |
+| `form message edit <appId> <triggerId> [...]` | 修改，没传的项保持原值 |
+| `form message delete <appId> <triggerId>` | 删除（不可逆） |
+| `form message enable \| disable <appId> <triggerId>` | 启用 / 停用 |
+
+`get` / `edit` / `delete` / `enable` / `disable` 的 `--obj-id` 可以省 —— 不传会自动反查这条提醒挂在哪张表单上。
+
+### `add` / `edit` 的选项
+
+| 选项 | 说明 |
+|---|---|
+| `--type <类型>` | 触发时机：`新建` / `修改` / `删除`，逗号分隔，也可以写 `all`。缺省 `all` |
+| `--channels <渠道>` | 推送渠道：`im`（站内）/ `cloud-bridge`（云桥）/ `email`（邮件）/ `sms`（短信），逗号分隔，也可以写 `all`。**缺省只发 `im`** —— 不会替你打开短信 |
+| `--title` / `--content` | 提醒标题与内容。纯文本会自动包成富文本；不传时标题取提醒名称、内容按触发时机生成一句话（如「数据新建、修改了」） |
+| `--pc-link` / `--mobile-link` | 点开提醒后的落地页，缺省是这条记录的表单卡片页 |
+| `--rule <spec>` | 提醒对象，可重复（写法见下） |
+| `--rule-json '<json>'` | 提醒对象原始报文，逃生口 |
+| `--disabled` | 建成即停用（`edit` 用 `--enable` / `--disable`） |
+
+## 提醒对象怎么写
+
+五类：`user` 人员、`dept` 部门、`role` 角色、`company` 分部、`matrix` 矩阵。
+
+写法是 `<类型>:<值>[,name=<显示名>][,extra=0|1]`：
+
+- **`<类型>:<名字>`** —— 工具按名字去查。**同名多条会报错并列出候选（带 ID）**，不会替你挑一条，免得配错人还看不出来。
+- **`<类型>:<ID>,name=<名字>`** —— 名字有歧义、或手上只有 ID 时用这个：`<值>` 直接当 ID 用，不查。
+
+`extra` 是组织范围上的附加项 —— 页面上部门 / 分部的提醒对象显示成「营销部:本部门含兼职人员」就是它。部门 / 分部缺省开、人员 / 角色 / 矩阵缺省关，需要时显式覆盖。
+
+### 矩阵提醒对象（`matrix`）
+
+```bash
+form message add <appId> <objId> --name 有新数据了 --type 新建 --channels im \
+  --rule matrix:门店经理矩阵
+```
+
+矩阵那条报文的**键集合与其余四类完全不同**（真机报文坐实）：只有 `selectedType` / `containExtra` / `name` /
+`jobLevelText` / `jobLevelTextSpan` / `matrixValueRelation` / `matrixConditionData` / `ruledetail` / `id`，
+**没有** `levelScope` / `fieldtype` / `roleLevel` / `relation` 那一套，而且**不带 `ruletype`** —— 平台靠
+`selectedType='matrix'` 认它。工具会按矩阵的**值字段**自动构造 `matrixValueRelation`
+（决定用哪一列匹配当前用户），矩阵没配值字段时直接报错。
+
+> ⚠ **矩阵的「条件」这一层暂时配不了**。设计器能给矩阵提醒对象再加条件（`matrixConditionData`），
+> 但那个对话框里的右值是一种新形态（`type:"custom"` + 一组选中的对象数组 + `customSelect`），
+> CLI 还没有对应的构造；报文里这个键会发空串。要带条件的，先去设计器里配。
+
+```
+form message add <appId> <objId> --name 有新数据了 \
+  --type 新建 --channels im,email \
+  --rule user:任来仪 \
+  --rule dept:营销部 \
+  --rule role:会议管理员
+```
+
+## 几个容易踩的点
+
+- **列表是应用级的**：这条接口按应用列，`--obj-id` 是命令在**本地按表单收口**（平台不认那个过滤参数，传了也照回全应用）。
+- **渠道勾选要单条看**：列表和详情返回里都不带渠道，`form message get` 会额外读一次补上。
+- **停用不等于删除**：`disable` 只是不再推，配置留着；`delete` 才是真的没了。
+- **修改是整份保存**：`edit` 先读回现有配置再合并你改的项，**没传的项不会被清空**。提醒对象默认保持原样，要整份替换就传 `--rule`，要清空传 `--clear-rules`。
+- **提醒名称**就是列表里显示的那个名字，建的时候起的 `--name` 别随手写。

package/skills/weaver-e10-builder/references/form/guide-form-physical-table.md

@@ -0,0 +1,146 @@
+# 多物理表（一个表单的字段分散到多张物理表）
+
+设计器里「表单 → 字段管理」有三个页签：**主表 | 明细表 | 其他**。本文说的是**「其他」** —— 同一个表单的字段分散在多张**物理表**上。
+
+## 什么时候用
+
+**字段数过多时的容量兜底**（单表字段超过 100 个左右）。正常表单用不到，属于偶尔一用的结构级能力。业务上要「一行对多行」请用**明细表**，那是另一回事（见 `guide-form-sub-detail.md`）。
+
+## ⚠ 和「明细表」是两根轴，别混
+
+| | 明细表 | **物理表（本文）** |
+|---|---|---|
+| 建表命令 | `form add-detail-table` | **`form add-physical-table`** |
+| 加字段命令 | `form add-field --sub-form-id` | **`form add-physical-field`** |
+| 建表端点 | `saveSubForm` | **`saveFormTable`** |
+| 标志 | `isSubForm: true` | **`isSubForm: false`** |
+| `tableType` | `MAIN` | **`SUBSIDIARY`** |
+| 布局里 | `DetailTable` 组件 | 无（不自动进布局，见下） |
+| 语义 | 一对多业务建模 | 一个表单自己的字段拆到多张表 |
+
+## 命令
+
+```shell
+# 1) 列出表单的全部物理表（含主表）—— 忘掉 formTableId 时就用它
+e10-cli form physical-table list <objId> <appId>
+
+# 2) 建一张附属物理表 —— 输出 formTableId，后面都要用它
+e10-cli form add-physical-table <objId> <appId> \
+  --name 物理表A \
+  --table-name uf_ryxxb_6_1
+
+# 3) 往那张表里加字段（任意类型，能力同 form add-field）
+e10-cli form add-physical-field <objId> <appId> <formTableId> <字段名> <类型> [标题] [选项]
+
+# 4) 改名
+e10-cli form rename-physical-table <objId> <appId> <formTableId> \
+  --name 新名字 --table-name uf_ryxxb_6_1
+
+# 5) 删除（可一次删多张；表里的字段一并删除，不可逆）
+e10-cli form delete-physical-table <objId> <appId> <formTableId...>
+```
+
+`add-physical-field` 的选项与 `form add-field` 同名同义（`--precision` / `--format` / `--default` / `--data-key` / `--column-name` / `--multiple` / `--option-template` / `--browser-type` / `--sform-id` …）—— 两者**共用同一份字段构造器**，所以字段形状是同一套，不存在「这个命令能建那个命令不能建」的差异。
+
+| 参数 | 说明 |
+|---|---|
+| `--name <名>` | 物理表**显示名**，设计器里那排 chip 上的字 |
+| `--table-name <名>` | **数据库表名**（如 `uf_ryxxb_6_1`）。⚠ 平台的建议命名规则未抓到报文，**必填**；改名时也要原样回传 |
+
+## 表 id 从哪来
+
+建表输出里就带着：
+
+```
+物理表已建: 物理表A  formTableId=1323895867900731392  tableName=uf_ryxxb_6_1
+```
+
+事后想找回，用 `form physical-table list`（走 `getFormAGroupList`，就是设计器那排 chip 的数据源）：
+
+```
+$ e10-cli form physical-table list 1323898521989193728 1323897873591762945
+表单 1323898521989193728 共 3 张物理表:
+  多物理表测试表单  [主表]  formTableId=1323898521989193731  库表=uf_dwlbcsbd_5766  字段2
+  表1  [附属]  formTableId=1323898595055067136  库表=uf_dwlbcs_t1  字段3
+  表2  [附属]  formTableId=1323898612300947456  库表=uf_dwlbcs_t2  字段3
+```
+
+⚠ 注意这只列**物理表**。`form detail-table list`（走 `querySubForms`）是另一回事，只列**明细表**。
+
+字段**归属**也随时可读：`form read <objId> --app-id <appId>` 每个字段后面会带 `· 物理表: 表1`。
+
+> 读 `getFormAGroupList` 时别碰那条记录里的 `id` 键 —— 它是 **formId**，`formTableId` 才是表 id。这个子系统里 `id` 反复是这个陷阱。
+
+## ⚠ `add-physical-field` **不碰布局**
+
+字段建在这张物理表上，但**不会自动进表单布局**——它是否需要在布局里出现、怎么放，尚未抓到报文。别默认它已经挂在表单上了；要不要进布局请在设计器里确认。
+
+（`form add-field` 会做布局插入，是因为它落在主表/明细表这些**本来就在布局里**的落点上。）
+
+## 报文契约
+
+### 建表 / 改名 —— 同一个端点，带不带 `id` 决定是哪种
+
+```
+POST /api/ebuilder/form/form/field/manage/saveFormTable?apid=<appId>
+header ebbusinessid: <formId>
+```
+
+```json
+{"module":"ebuilderform",
+ "formTable":{"id":"<表id：改名时带，新建时不带>",
+              "name":"物理表A",
+              "tableName":"uf_ryxxb_6_1",
+              "tableType":"SUBSIDIARY",
+              "form":{"id":"<formId>"},
+              "otherProperties":"{}"},
+ "customParam":{"appId":"...","objId":"..."}}
+```
+
+响应：`{"code":200,"status":true,"data":{"formTableId":"..."}}` —— 新表的 id 在 `data.formTableId`。
+
+### 加字段 —— **不是**批量端点
+
+```
+POST /api/ebuilder/form/form/field/manage/saveFormFieldNew
+body {"formId":...,"module":"ebuilderform","jsonObj":"{... 带 \"formTableId\":\"<表id>\" ...}"}
+```
+
+字段落点由 **jsonObj 里的 `formTableId`** 决定。这条与「建表时连字段一起建」的 `batch/save/formField` + `formTableList` **不是同一条路**。
+
+### 删表
+
+```
+POST /api/ebuilder/form/form/field/manage/deleteFormTable?apid=<appId>
+body {"module":"ebuilderform","formId":"<formId>","ids":["<表id>"],"customParam":{...}}
+```
+
+### 列表（`form physical-table list`）
+
+```
+POST /api/ebuilder/form/form/field/manage/getFormAGroupList?apid=<appId>
+body {"module":"ebuilderform","formId":"<formId>","customParam":{...}}
+```
+
+响应 `data.formList[]` 每条：`name`（显示名）/ `tableName` / `tableType`（`MAIN` | `SUBSIDIARY`）/ `formTableId` / `systemTable` / `dataCount`；
+另外 `data.groupList[]` 是字段分组。**主表也在 `formList` 里**（`tableType: MAIN`）。
+
+⚠ 记录里的 `id` 键是 **formId**，不是表 id。
+
+## 踩过的两条坑（都别再走）
+
+**1. 不能把已有字段搬到另一张表。** 试过把字段的 `formTableId` 改成新表再整份写回，平台明确拒绝：
+
+```
+【备注】此字段不属于当前物理表，不能更改位置
+```
+
+所以**别指望「字段超 100 之后把老字段挪走」**——至少这条路径不行。能做的只有：**一开始就把新字段建到新表上**。这也解释了设计器的真实用法：先建附属表，后续新增的字段直接落在它上面。
+
+**2. 平台会对形状不认的字段回 `200` 但静默不落库。** 在 `batch/save/formField` 那条路上，`DateTime` / `Percent` / `Browser` 三种就是这样——接口回成功，字段根本没建出来。所以 `add-physical-field` **每次写完都回读确认**，「接口回 200」不等于「建上了」。带配置的类型（如 Select 的选项）建完再用对应命令补。
+
+## 注意事项
+
+1. **删除不可逆**，表里的字段一并删除。执行前先确认表 id。
+2. **`--table-name` 必填**。设计器用的是 `uf_<表单名拼音>_<n>_<m>` 这类命名，但规则没抓到报文，CLI 不替你猜 —— 重名/非法由平台报错（`此表的数据库表名称与数据库现有表存在冲突`）。
+3. **建完的空表照样存在**于「其他」页签里；要清掉用 `delete-physical-table`。