weaver-e10-builder 1.0.11-beta → 1.0.12-beta

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

@@ -0,0 +1,267 @@
+# 表单视图：新建与验收
+
+表单创建后已有默认台账；只有用户明确需要额外视图时才创建。表格视图是 `nListView` 数据列表，和普通 `formView` 是两条不同链路。
+
+## 需求判别
+
+- “新建表单” → `form create --fields`。
+- “在已有表单下新增表格视图” → `form table-view create`；命令必须同时保存显示列并回读。
+- “在已有表单下新增表单视图” → `form view create --type formView`，随后必须 `form view populate`；不得新建另一张表单。
+
+## 命令
+
+```bash
+# 查询表单下全部视图
+e10-cli form view list <objId> <appId>
+
+# 创建可用表格视图；默认放入全部已有字段
+e10-cli form table-view create <objId> <appId> "审批数据表格" --pc-only
+
+# 创建看板视图（默认 PC + FLOW 布局）
+e10-cli form view create <objId> <appId> "按状态看板" --type kanbanView
+
+# 新增表单视图——流式布局（FLOW）
+e10-cli form view create <objId> <appId> "新增-流式视图" --type formView --layout-type FLOW
+
+# 新增表单视图——表格式布局（EXCEL）
+e10-cli form view create <objId> <appId> "新增-EXCEL视图" --type formView --layout-type EXCEL
+
+# 第 2 步：把已有字段按目标布局类型填入新建 formView（流式/EXCEL 各自生成对应组件）
+e10-cli form view populate <objId> <appId> <viewId>
+
+# 创建移动端日历视图
+e10-cli form view create <objId> <appId> "交付日历" \
+  --type calendarView --terminal MOBILE --layout-type FLOW
+```
+
+**给已有表单加表单视图是两步闭环**（缺一不可）：
+1. `form view create --type formView --layout-type FLOW|EXCEL` —— 建一个**空**的 formView 实体，`--layout-type` 决定流式(FLOW)还是表格式(EXCEL)。同一张表单可同时存在多个 formView，布局类型可不同（如一张表既加流式视图又加 EXCEL 视图）。
+2. `form view populate <objId> <appId> <viewId>` —— 把已有字段按目标布局类型填进去。流式视图生成流式组件、EXCEL 视图生成表格定位，**不得把 EXCEL 定位直接复制到 FLOW 视图**。
+
+`form view populate` 以原表单 `formId` 读取字段，以新视图 `viewId` 作为 `layoutMultiId` 读取目标布局，再按目标的 FLOW/EXCEL 类型重新生成字段组件并独立回读。不得把视图的 `versionId` 或 `pageLayoutId` 当成 `formId`。
+
+看板、日历、思维导图目前只确认创建实体和视图列表回读，尚不能据此宣称设计器已有可用组件。
+
+普通 `form view create --type` 只接受：
+
+- `formView`：详情视图
+- `kanbanView`：看板视图
+- `calendarView`：日历视图
+- `mindMapView`：思维导图视图
+- `multiView`：多维表格视图（无 layoutType/terminalType，带 `extConfig:{listVersion:5}`）。**数据维度**：缺省主表（`subFormId:""/subFormMain:false`）；明细表维度用 `--detail <明细名>`（按名解析明细 subFormId）或 `--sub-form-id <明细subFormId>`（直传），传值即 `subFormId:<明细subFormId>/subFormMain:true`。明细子表名/subFormId 用 `dataset/v1/getFields` detailFields 查（真 subFormId 在 `fields[].subFormId`，非 `dt.id`）。**多维表格显示列**复用台账同一套 `saveNListConfig/getNListConfig`，直接用 `form list-columns <objId> <appId> <multiView的viewId> --add <fieldId>` 加列。
+
+`tableView`/`nListView` 不得传给普通视图命令。真实表格视图固定使用 `form table-view create`。
+
+## 表格视图固定闭环
+
+```bash
+# 1. 确认目标表单和同名列表不存在
+e10-cli form list <appId>
+e10-cli form list-view <objId> <appId>
+
+# 2. 创建 nListView、写入全部业务显示列和隐藏数据主键、独立回读
+e10-cli --json form table-view create <objId> <appId> "<表格视图名>" --pc-only
+
+# 3. 再次独立查询表单下列表
+e10-cli --json form list-view <objId> <appId>
+```
+
+命令先用 `viewType=nListView` 创建，再以新 `listId` 读取 PC 配置；业务列必须取自 `/api/ebuilder/common/ds/fields` 的完整字段对象，不能只拼字段 ID。保存时保留服务端配置和隐藏主键 `id=5`，最后回读 `tableField` 和列表实体。已有同名视图时停止，不盲目重建。
+
+`--pc-only` 只用于已确认本次验收为 PC 的场景。未指定时，命令必须取得真实 MOBILE 配置，禁止用 PC 配置推导移动端。
+
+服务器通过必须同时满足：
+
+- 创建后按返回 `listId` 找到同名列表。
+- `persisted=true`。
+- `visibleFieldCount` 等于目标业务字段数。
+- `tableFieldCount` 还包含隐藏主键。
+- 再查 `form list-view` 仍能按相同 ID 和名称找到。
+
+前端无数据时可以没有数据行，但必须看见业务字段列头；否则仍是空壳，不能验收。
+
+## 表格视图展示样式
+
+```bash
+e10-cli --json form table-view style <objId> <appId> <listId> <style>
+```
+
+`style` 使用前台语义，不直接让使用者猜内部 `mode`：
+
+| style | 前台展示样式 | mode |
+|---|---|---|
+| `table` | 表格式 | `1` |
+| `list` | 列表式 | `2` |
+| `left-diagram` | 左图式 | `3` |
+| `horizontal-list` | 横向列表式 | `4` |
+| `above` | 上图式 | `5` |
+| `grid` | 网格列表式 | `7` |
+| `editable` | 可编辑表格（编辑态） | `11` |
+
+可编辑表格内部还有数据态 `8` 和只读态 `9`；用户要求“改成可编辑表格”时必须使用编辑态 `11`，不得把只读态 `9` 当成完成。
+
+命令先确认 `listId` 属于目标 `objId`，分别读取完整 PC/MOBILE 配置，只修改 PC 顶层 `mode`，保存后重新读取 PC 配置。移动端配置必须原样保留；读取不到时，只有明确 `--pc-only` 才允许继续。
+
+前端验收：重新进入“基础设置 → 展示样式”仍显示“可编辑表格”，并且列表进入可编辑状态。
+
+## 常用搜索显示方式
+
+```bash
+# PC 常用搜索显示为高级搜索；filter 表示筛选
+e10-cli --json form table-view search-style <objId> <appId> <listId> advanced
+```
+
+显示方式固定为 `advanced → commonSearchType="0"`、`filter → commonSearchType="1"`，不得直接猜内部值。
+
+命令先确认 `listId` 属于目标表单，完整保留 PC 其他配置和真实 MOBILE 配置，保存后重新读取目标属性。前端验收：“常用搜索 → 基础信息 → 显示方式”能正常打开，且刷新后仍为目标方式；若配置页异常，接口回读成功也不能验收。
+
+## 常用搜索字段
+
+```bash
+e10-cli --json form table-view search-field add <objId> <appId> <listId> <fieldId>
+
+# 按前端字段设置面板配置搜索项
+e10-cli --json form table-view search-field configure \
+  <objId> <appId> <listId> <fieldId> \
+  --display-name "单据名称" \
+  --default-value "111" \
+  --required 0 \
+  --full-match 0 \
+  --condition like
+```
+
+命令必须从当前数据源接口取得完整字段模型，按前端最终保存结构生成搜索项：字段 `id` 与独立的 18 位 `filterId` 不得混用，字段自身 `multiSelect` 原样保留，搜索默认配置单独写入 `listFilterDefaultSets`。保存时完整保留 PC 其他配置和真实 MOBILE 配置，再独立回读字段及条件关系。
+
+具体配置固定映射：
+
+- `--default-value`：固定默认值，写为 `defaultType="1"` 与 `startValue`；`--clear-default` 清除。`Select` 字段可传选项名称或选项 ID，CLI 必须从当前数据源解析为唯一真实 ID，并保留完整选项对象供前端回显。
+- `--required 0|1`：条件是否必填，写为字段级 `required`。
+- `--full-match 0|1`：搜索内容是否完整匹配，写入 `listFilterDefaultSets.searchContentFullMatches`。
+- `--condition like|eq|...`：必须来自该字段实际允许的条件，同时更新字段层与默认设置层。
+- `--display-name`：更新搜索项 `showName`；不得覆盖原字段名和字段 ID。
+
+前端验收：打开“搜索配置”不报异常，目标字段出现在常用搜索字段中；刷新列表后可使用该字段发起搜索。只通过接口回读不能验收。
+
+## 台账显示列/搜索/排序/统计/视图数据条件/行事件/启用分组/视图权限/分类搜索（list-columns / list-search / list-sort / list-stats / list-filter / list-event / list-group / list-permission / list-search-group）
+
+直接改默认台账（nListView）的显示列、搜索条件、排序、顶部统计、视图数据条件。listId 取 `form list-view` 返回的列表视图 ID。这些命令都只改 PC 端，**保存时先读回真实移动端 mConfig 原样回传，不会清空移动端**（`saveNListConfig` 一次请求里 `config`→PC 端、`mConfig`→移动端，两端列集合/uid 各自独立）。只有明确目标只使用 PC、移动端配置确实不存在时，才加 `--pc-only`。
+
+```bash
+# 查看当前显示列
+e10-cli form list-columns <objId> <appId> <listId>
+
+# 追加字段到显示列 / 移除字段
+e10-cli form list-columns <objId> <appId> <listId> --add <fieldId>
+e10-cli form list-columns <objId> <appId> <listId> --remove <fieldId>
+
+# 列显示格式：千分位/小数位（Number/Money 列，走列对象 format/decimalLength）
+e10-cli form list-format <objId> <appId> <listId> <fieldId> --thousandths --decimal 2
+e10-cli form list-format <objId> <appId> <listId> <fieldId> --no-thousandths
+# 列显示单位：后缀/前缀（走列 showTrans.ruleConfig，与千分位是两套机制）
+e10-cli form list-unit <objId> <appId> <listId> <fieldId> "（元）"
+
+# 配置搜索：--add 进搜索面板，--quick 加顶部快捷筛选（均支持多字段）
+e10-cli form list-search <objId> <appId> <listId> --add <fieldId1> <fieldId2>
+e10-cli form list-search <objId> <appId> <listId> --quick <fieldId1> <fieldId2>
+# 主表字段直接从 ds/fields 解析；明细子字段经 getFormField 单取元数据（ds/fields 合并不展开）
+
+# 配置排序 / 清除（--field 支持多个，按传入顺序多级排序；--order 对所有字段生效）
+e10-cli form list-sort <objId> <appId> <listId> --field <fieldId1> <fieldId2> --order ASC
+e10-cli form list-sort <objId> <appId> <listId> --clear
+
+# 顶部统计：type=sum 求和 / count 计数 / avg 平均 / max 最大 / min 最小
+# 可选：thousandths=true 千分位 / decimalPlaces="2" 小数位 / unit="万" 单位（unitType=tenThousand）
+e10-cli form list-stats <objId> <appId> <listId> --add '{"fieldId":"...","type":"sum","name":"合同总金额","thousandths":true,"decimalPlaces":"2","unit":"万"}'
+
+# 条件统计：conditions 数组构造明文条件树填 rootdata（发明文保存成功、读回也是明文，无需 LZW 编码）
+# func: eq 等于 / neq 不等于 / in 属于 / notIn 不属于 / like 包含 / notLike 不包含 / gt 大于 / lt 小于 / range 区间 / isNull 为空 / isNotNull 不为空
+# 单选 Select 用 eq；notEq/between 为兼容别名自动归一为 neq/range；range 的 value 用数组 [起,止]；value 填选项 valueKey、text 填显示名；多条件默认 AND
+e10-cli form list-stats <objId> <appId> <listId> --add '{"fieldId":"金额fieldId","type":"sum","name":"研发合同额","thousandths":true,"unit":"万","conditions":[{"fieldId":"项目类型fieldId","func":"eq","value":"研发valueKey","text":"研发"}]}'
+e10-cli form list-stats <objId> <appId> <listId> --remove <statId>   # 平台 statisticsList 是 upsert 语义，删除靠标 operation:DELETE（splice 不删）
+
+# 视图数据条件：台账只显示满足条件的数据（走 saveNListConfig config.filter，明文条件树，非独立接口——
+# conditionEditor/saveOrUpdate 表单级不挂视图、saveBaseinfo 带 conditionData 都是错误端点）
+# func 取值同条件统计（eq 等于 / neq 不等于 / in 属于 / notIn 不属于 / like 包含 / notLike 不包含 / gt 大于 / lt 小于 / range 区间 / isNull 为空 / isNotNull 不为空，单选 Select 用 eq）；value 填选项 valueKey，text 填显示名；多条件默认 AND
+e10-cli form list-filter <objId> <appId> <listId> --add '{"conditions":[{"fieldId":"项目类型fieldId","func":"eq","value":"研发valueKey","text":"研发"}]}'
+e10-cli form list-filter <objId> <appId> <listId> --clear
+
+# 行事件：点击行数据 NewPage 打开（走 saveNListConfig config.eventGroup，明文 JSON，config+mConfig 都要写）
+# --add-page 选页面：pageId 缺省 "1/<objId>"（表单新建布局），"0/<objId>"=显示布局
+#   打开方式 openMode（linkInfo.openMode 权威，page.openMode 恒 4）：
+#     当前页面=4 / 新窗口=0 / 弹出窗口=5 / 右侧滑出=1(缺省) / 右侧推出=7
+#   弹出/滑出/推出 带弹窗宽高（--modal-width/--modal-height，缺省 50%）；滑出/推出 额外带 winSizeNew（--win-size，缺省 100%）
+# --add-field 选字段（URL取自行内字段值，urlFieldText/Type自动补）
+e10-cli form list-event <objId> <appId> <listId> --add-page '{"pageName":"新建数据"}'
+e10-cli form list-event <objId> <appId> <listId> --add-page '{"pageId":"0/<objId>","pageName":"显示布局","openMode":"当前页面"}'
+e10-cli form list-event <objId> <appId> <listId> --add-page '{"pageName":"弹窗详情","openMode":"弹出窗口"}' --modal-width 80%
+e10-cli form list-event <objId> <appId> <listId> --add-page '{"pageName":"侧滑详情","openMode":"右侧推出"}' --win-size 60%
+e10-cli form list-event <objId> <appId> <listId> --add-field '{"urlFieldId":"字段id"}'
+e10-cli form list-event <objId> <appId> <listId> --clear
+
+# 字段事件（列点击 list-click，区别于行事件 list-event）：点某列数据打开该行显示布局（带数据 ID）
+# 打开方式 --open-mode：当前页面/新窗口/弹出窗口/右侧滑出(缺省)/右侧推出；滑出/推出 --win-size 设宽度（缺省 800px，可 50%）
+e10-cli form list-click <objId> <appId> <listId> <fieldId> --open-mode 右侧推出 --win-size 50%
+e10-cli form list-click <objId> <appId> <listId> <fieldId> --target <目标表单objId> --open-mode 弹出窗口
+e10-cli form list-click <objId> <appId> <listId> <fieldId> --clear
+
+# 启用分组：台账按某字段分组聚合显示（走 saveNListConfig config.enableGroup 对象 {enable,groupField,groupSize}）
+# saveNListConfig 持久化成功，不走 designer/layout/save LZW。group-field 用完整字段对象（自动从 ds/fields 取）
+e10-cli form list-group <objId> <appId> <listId> --enable --group-field <分组字段fieldId> --group-size 100
+e10-cli form list-group <objId> <appId> <listId> --disable   # 禁用但保留 groupField/groupSize（仅 enable=false）
+
+# 台账视图权限（查阅/查看权限）：谁能查看这个台账（走 list/permission/save + getList，专用端点，full-replace 语义 omit即删）
+# selectedType: all(所有人) / user(人员,带--name) / role(角色,--name 缺省自动查) / matrix(矩阵,用 --add-raw 传整对象)
+e10-cli form list-permission <objId> <appId> <listId> --add-all
+e10-cli form list-permission <objId> <appId> <listId> --add-user <userId> --name <人员名>
+e10-cli form list-permission <objId> <appId> <listId> --add-role <roleId>                # --name 缺省自动从角色树查名
+e10-cli form list-permission <objId> <appId> <listId> --add-role <roleId> --share-level 2 # 加同一角色另一个共享级别
+e10-cli form list-permission <objId> <appId> <listId> --add-role <roleId> --seclevel 30-80 # 安全级别范围
+e10-cli form list-permission <objId> <appId> <listId> --add-raw '{"selectedType":"matrix","name":"...","dataid":"矩阵id",...}'
+e10-cli form list-permission <objId> <appId> <listId> --remove <权限id>
+e10-cli form list-permission <objId> <appId> <listId> --clear
+
+# 每条授权对象的两个可配维度（抓包坐实，mulinquan 2026-09-02）：
+#   安全级别 = levelScope.minShowlevel/maxShowlevel（字符串范围，--seclevel <min>-<max>，如 0-100 / 30-80；role 缺省 0-100、all 缺省空）
+#   共享级别 = roleLevel（实测: 总部=1 分部=2 全部=3）。同一角色可按不同共享级别各存一条（同 role 两条 roleLevel 1/2 并存）→ 去重键含 roleLevel
+#   幂等：目标(含 roleLevel)已存在时跳过保存，打印「无变化」
+
+# 分类搜索：按选项字段分类筛选（走 saveNListConfig config.searchConditions.groupFilters）
+# 仅主表选项类字段（Select/RadioBox/CheckBox），不支持明细字段（产品边界）
+e10-cli form list-search-group <objId> <appId> <listId> --add <选项字段fieldId>
+e10-cli form list-search-group <objId> <appId> <listId> --remove <fieldId>
+e10-cli form list-search-group <objId> <appId> <listId> --clear
+```
+
+字段 ID 来自 `form read <objId> --app-id <appId>` 或 `form list-columns` 当前列（系统列如 `2`创建者/`3`创建时间/`5`数据ID 也可增删）。保存成功后命令打印 `移动端配置: 保持原样` 即确认移动端未被触碰。
+
+## formView 固定闭环
+
+```bash
+# 1. 确认目标表单与现有视图
+e10-cli form list <appId>
+e10-cli form view list <objId> <appId>
+
+# 2. 创建视图并从输出取得 viewId
+e10-cli --json form view create <objId> <appId> "<视图名>" --type formView
+
+# 3. 填充已有字段并独立回读
+e10-cli --json form view populate <objId> <appId> <viewId>
+```
+
+`populate` 只有同时满足以下条件才算服务器验证通过：
+
+- `success=true`
+- `componentCount > 0`
+- `fieldComponentCount > 0`
+- 重复执行返回 `alreadyPopulated=true`
+
+服务器验证通过后仍需用户确认前端不是空画布、字段名称和特殊配置正确。
+
+## 执行与验收
+
+1. 计划中写明表单 objId、视图名称、类型和终端；用户确认后再写入。
+2. CLI 先调用 `createView`，再查询该表单的完整视图列表；创建响应本身不是验收。`formView` 随后调用 `populate`：`原 formId + viewId(layoutMultiId)` 读取目标布局，保留目标页面元数据，按目标布局类型重建已有字段组件并保存。
+3. 回读以返回的 viewId 优先；服务端未返回 ID 时，才按名称、类型和终端唯一匹配。多个候选视图时停止并让用户确认。
+4. `populate` 回读组件数量和字段 ID；用户再确认新视图设计页出现表单既有字段，而非只有“未分组”的空画布。
+
+服务器成功和独立回读成功但尚未前端确认时，只能标记为“待前端确认”。

package/skill-docs/references/form/style-templates.md

@@ -0,0 +1,44 @@
+# 表单布局样式模板
+
+> `form layout init --style-template <名|id>` 用这些模板初始化布局。模板列表基本不变，以下为内置 PC/EXCEL 模板（共 20 个）。
+
+| styleTemplateId | 模板名 | 说明 |
+|---|---|---|
+| `700000000000000007` | 标准版 | 默认推荐，字段可编辑 |
+| `700000000000000008` | 表格版 | **注意：生成的 comps 默认只读** |
+| `700000000000000009` | 紧凑版 | |
+| `700000000000000010` | 轻便版 | |
+| `830421425497325568` | 靛青线条 | |
+| `830662158415355904` | 简约深蓝 | |
+| `830714355284320256` | 极简淡蓝 | |
+| `830718787623460864` | 现代简约 | |
+| `830722618751066113` | 商务淡蓝 | |
+| `830743788745531393` | 极简白 | |
+| `830749075757998081` | 极简灰 | |
+| `830751622581329920` | 清新蓝绿 | |
+| `830764108161785857` | 淡蓝水晶 | |
+| `830765800429674496` | 银光浅灰 | |
+| `831747419499700225` | 暗夜流光 | |
+| `831759140499447809` | 公文样式 | |
+| `831897833480421377` | 淡雅丁香 | |
+| `917557790734188546` | 商务蓝 | |
+| `933871446777094145` | 碧海蓝天 | |
+| `1000599952745676801` | 青蓝冰水 | |
+
+## 用法
+
+```bash
+# 用模板名（推荐，好记）
+e10-cli form layout init <objId> <appId> --style-template 标准版
+
+# 或用 id
+e10-cli form layout init <objId> <appId> --style-template 700000000000000007
+
+# 指定视图 + 只读/必填
+e10-cli form layout init <objId> <appId> --view-id <viewId> --style-template 紧凑版 --read-only
+```
+
+## 注意
+
+- 模板只影响**布局样式**（间距/边框/配色），不影响字段的 readOnly/required（这俩由 `--read-only`/`--required` 或 fields.json 控制）。
+- `表格版`（008）历史问题：生成的 comps 默认 readOnly=true。`form layout init` 会显式按 `--read-only`（默认 false 可编辑）覆盖，所以即使用 008 也能可编辑。

package/skill-docs/references/hrm/guide-matrix.md

@@ -0,0 +1,103 @@
+# HRM 条件矩阵指南
+
+> 矩阵 = 「条件维度（行）→ 值维度（列）」的映射查询表。例如：部门 + 费用类型 → 审批人。用于流程中的矩阵对应操作者类型。
+
+## 命令参考
+
+### 矩阵管理
+
+| 命令 | 说明 |
+|------|------|
+| `e10-cli matrix create <name>` | 新建矩阵。`--type 0=分部/1=部门/2=自定义` `--desc` `--org-id` |
+| `e10-cli matrix update <id>` | 更新矩阵。`--name` `--desc` `--type` |
+| `e10-cli matrix list` | 查询矩阵列表。`--name` `--enable-status` `--org-id` |
+| `e10-cli matrix config <id>` | 查看矩阵配置（条件字段 + 值字段） |
+| `e10-cli matrix config-edit <id>` | 编辑配置。`--condition` `--value` 或 `--config` 一次性提交 |
+| `e10-cli matrix enable <id>` | 启用矩阵 |
+| `e10-cli matrix disable <id>` | 停用矩阵 |
+| `e10-cli matrix delete <ids...>` | 删除矩阵 |
+
+### 矩阵数据维护
+
+| 命令 | 说明 |
+|------|------|
+| `e10-cli matrix data list <matrixId>` | 分页查询矩阵数据行。`--condition` `--value` 过滤 |
+| `e10-cli matrix data save <matrixId> --rows @file` | 保存数据行（新增/修改）。简写: `[{"字段configId":["实体ID"]}]` |
+| `e10-cli matrix data delete <matrixId> <ids...>` | 删除数据行 |
+| `e10-cli matrix data template <matrixId>` | 下载导入模板（Excel） |
+| `e10-cli matrix data import <matrixId> <file>` | 从 Excel 导入。`--mode add/cover` |
+
+---
+
+## 典型工作流
+
+```bash
+# 1. 创建矩阵
+e10-cli matrix create "审批人映射表" --type 2 --desc "部门→审批人"
+
+# 2. 查 ID
+e10-cli matrix list --name "审批人"
+
+# 3. 配字段（条件=部门，值=审批人）—— 注意：首次配置可能需在 UI 操作
+e10-cli matrix config-edit <matrixId> \
+  --condition '[{"type":"department","name":"所属部门"}]' \
+  --value '[{"type":"resource","name":"审批人","singleType":1}]'
+
+# 4. 启用
+e10-cli matrix enable <matrixId>
+
+# 5. 填数据
+echo '[{"<条件configId>":["<部门ID>"],"<值configId>":["<人员ID>"]}]' > rows.json
+e10-cli matrix data save <matrixId> --rows @rows.json
+
+# 6. 查数据
+e10-cli matrix data list <matrixId>
+
+# 7. 在流程中使用矩阵
+e10-cli workflow set-operator <wf> <nodeId> --type matrix \
+  --matrix-id <matrixId> --value-config-id <值configId> \
+  --matrix-rule "<条件configId>:1:1:1"
+```
+
+---
+
+## 字段类型枚举
+
+| 中文 | API 值 |
+|------|--------|
+| 人员 | `resource` |
+| 部门 | `department` |
+| 分部 | `subcompany` |
+| 岗位 | `position` |
+| 客户 | `customer` |
+| 项目 | `project` |
+| 数据源 | `datasource` |
+
+## config-edit 参数
+
+```json
+{
+  "id": "<矩阵ID>",
+  "conditionConfigList": [
+    { "type": "department", "name": "显示名", "sort": 1 }
+  ],
+  "valueConfigList": [
+    { "type": "resource", "name": "显示名", "singleType": 1, "sort": 1 }
+  ],
+  "conditionDelList": [],
+  "valueDelList": []
+}
+```
+
+> `singleType`: 0=多选, 1=单选。条件字段不传，值字段必传。
+
+## data save 简写格式
+
+```json
+[
+  {"<条件configId>": ["<实体ID>"], "<值configId>": ["<实体ID>"]}
+]
+```
+
+CLI 自动查 config 判断 `conditionAble` 标记并展开为完整格式。
+

package/skill-docs/references/menu/system-menus.md

@@ -0,0 +1,63 @@
+# 系统内置菜单 URL 参考
+
+通过 `savePublishMenu` API 挂载系统内置页面到应用菜单。menuUrl 格式固定，禁止瞎编。
+
+> **暂不支持 H5/移动端菜单**。移动端是独立体系（不同 URL + 不同 pageId），目前尚未整理完整，禁止 AI 自行编造。
+
+---
+
+## PC 端菜单
+
+### 工作流页面 (pageType: WORKFLOW)
+
+| 菜单名 | pageId | menuUrl |
+|--------|--------|---------|
+| 待办流程 | todo | `/sp/ebdfpage/workflow/{appId}_todo` |
+| 已办流程 | done | `/sp/ebdfpage/workflow/{appId}_done` |
+| 我提交的流程 | mine | `/sp/ebdfpage/workflow/{appId}_mine` |
+| 共享给我的流程 | share | `/sp/ebdfpage/workflow/{appId}_share` |
+| 下属的待办流程 | subordinates | `/sp/ebdfpage/workflow/{appId}_subordinates` |
+| 全部流程 | all | `/sp/ebdfpage/workflow/{appId}_all` |
+| 草稿流程 | draft | `/sp/ebdfpage/workflow/{appId}_draft` |
+| 流程监控 | monitor | `/sp/ebdfpage/workflow/{appId}_monitor` |
+
+### 独立页面（不跟 appId）
+
+| 菜单名 | pageId | menuUrl |
+|--------|--------|---------|
+| 提交申请 | newflow | `/sp/ebdfpage/ebflowpage/create/` |
+
+### 其他系统页面
+
+| 菜单名 | pageId | pageType | menuUrl |
+|--------|--------|----------|---------|
+| 我的关注 | followList | BASE | `/sp/ebdfpage/followlist/{appId}` |
+| 共享给我的 | shareList | BASE | `/sp/ebdfpage/sharelist/{appId}` |
+
+---
+
+## 用法
+
+```json
+{
+  "content": "待办流程",
+  "menuType": "1",
+  "page": {
+    "pageId": "todo",
+    "pageName": "待办流程",
+    "pageType": "WORKFLOW",
+    "appid": "{appId}"
+  },
+  "menuUrl": "/sp/ebdfpage/workflow/{appId}_todo",
+  "shareMap": [{
+    "id": "0",
+    "content": "所有人",
+    "permissionId": "sys_view",
+    "targetType": 11,
+    "sourceType": 1,
+    "objIdList": ["所有人"]
+  }]
+}
+```
+
+> **只有包含工作流的应用**才能挂载工作流系统页面。表单台账会自动挂入菜单，无需手动操作。

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

@@ -0,0 +1,168 @@
+# 流程动作流指南
+
+> 流程基础（建流程、节点、连线、审批人）见 `workflow/guide-workflow.md`，分支条件见 `workflow/guide-workflow-condition.md`。本指南专讲**节点提交事件**和**跨表单动作流**（本表数据 → 目标表 新增/更新/删除 记录）。
+>
+> **动作流「生成」一律走 native `e10-cli actionflow generate`**（语义 plan → 编译 → preflight → 保存并启用 → 正式回读，event 节点 `ApproveTrigger` 自带流程节点触发绑定 `workflowPath`+`triggerTiming`+`approveNode`，不走 pathdef/addaction）。详见 `actionflows/SKILL.md` + `e10-cli actionflow component-describe <type>`。`e10-cli workflow action` 仅作动作流**管理**（`list-node`/`clear-node` 查清节点绑定、`delete`/`disable`/`batch-delete` 禁用删除动作流 app）。
+
+## 节点提交事件（字段更新）
+
+节点提交/到达时自动更新本表单字段值（actionType=0），如「审批状态置为审批中」。
+
+> CLI 接受简化 JSON，内部自动构造 `saveAddActionList` 正确 payload（`targetValue`/`firstValue:"custom"`/`customValue`/`actionType:0`/`triggerType:"pre"` 等）。也支持直接传完整 `data:[]` 结构（高级用法）——**传入的 `data:[]` 行会自动归一化**，把 `action list-node` 的读回结果原样回传是安全的。
+>
+> **合并语义**：写入前先读回节点已有动作并归一化，再追加新动作写回——不覆盖已有动作。可与节点上的 type2 动作流安全混用同一节点。若节点已被写坏（读动作恒 500），CLI 会明确提示用 `delete-node` 删节点重建（API 无法修复）。
+>
+> **fieldId 会校验**：简化 JSON 的 `fieldId` 必须是流程表单里真实存在的字段，CLI 写入前反查表单字段校验，无效会报错并列出可用字段。**切勿用占位 fieldId**（如 `"1"`）——无效 fieldId 会被服务端存成空字段映射，之后任何合并写回都会把节点写坏（读恒 500，只能 delete-node 重建）。
+
+**命令**：
+```bash
+e10-cli workflow save-action @action.json
+```
+> **只接 JSON 一个参数**：`workflowId` / `nodeId` 写在 JSON 内部，不是位置参数。写成 `save-action <wf> <node> @file` 会报错。
+
+### action.json 格式（常量赋值）
+
+```json
+{
+  "workflowId": "1296243932023734272",
+  "nodeId":     "1296243932023734278",
+  "nodeName":   "上级审批",
+  "fieldId":    "1296243579896791071",
+  "fieldName":  "审批状态",
+  "value":      "1296243644242280449"
+}
+```
+
+| 字段 | 必填 | 说明 |
+|------|------|------|
+| workflowId | 是 | 流程 ID |
+| nodeId | 是 | 节点 ID（即 `objId`） |
+| nodeName | 否 | 节点显示名（默认"节点"） |
+| fieldId | 是 | 要更新的目标字段 fieldId |
+| fieldName | 否 | 字段显示名（用于 `actionName` 展示） |
+| value | 是 | 常量值。Text/Number 字段用实际值；Select 用 option 的 valueKey |
+| trigger | 否 | 触发时机，默认 `"pre"`（到达节点时）；`leave` 离开 / `back-arrive` 退回到达 |
+
+---
+
+## 跨表单动作流（本表数据 → 目标表 新增/更新/删除 记录）
+
+跨表单动作流的**生成**统一走 `e10-cli actionflow generate`：写一份语义 plan（`event` + `actions`），CLI 编译、preflight、保存并启用、正式回读，返回设计器链接。组件参数、映射、条件的权威是 `e10-cli actionflow component-describe <type>`，参考 `actionflows/references/components/` 下对应组件 md。下面是平台机制要点，写 plan 时按此组织。
+
+### 平台机制要点
+
+**目标表字段映射**：plan 的 `mapping` 是 `{源字段 paramKey: 目标字段 ID}`。目标字段 ID 支持 `+`/`-` 前缀做加减运算（赋值不加前缀、`+`累加、`-`扣减）。源字段用本次 `actionflow workflow-context-fields` 返回的原始 `paramKey`，不写死 `FormData.*`/`ApprovalData.*` 路径（编译器自动判定）。
+
+**明细表映射（明细→明细）**：`ActionEbAdd` 的 `insert`/`batchInsert` 支持源明细表逐行写入目标明细表。同一目标明细表的映射须来自同一张源明细表（作为该表「依据值」basisValue）。明细目标字段不支持 `+`/`-` 前缀。**明细 update/delete**（含 basisValue/rowId 行匹配/updateAdd、requestId 定位）走 `ActionEbUpdate`/`ActionEbDelete` 契约的 `filterCondition`（动态右值引用 requestId），`component-describe ActionEbUpdate` 看 detail + requestId 定位参数。
+
+**更新定位方式**：`ActionEbUpdate` 的 `opType`：`id`（按数据ID更新，配 EBuilder 关联字段其值=目标记录数据ID）/ `updateData`+`filterInput`（按「目标字段=源字段值」匹配，推荐）/ `fieldUpdate`（按字段匹配，保存后右侧条件会被清空，不可用）。匹配字段不要选 `*_name`/「名称」显示字段（标签文本非真值）。
+
+**常量值**：plan 里目标字段可用固定值（constants）而非映射字段；公式计算（加减乘除多字段）用 `formula`。mapping/constants/formula 可混合。详见 `component-describe ActionEbAdd/ActionEbUpdate`。
+
+---
+
+## 流程数据写入台账（数据来源落点）
+
+**场景**：流程发起时写入目标台账、归档/退回时更新/删除台账记录（如"流程数据写入项目台账"，发起写入、归档更新、退回删除）。
+
+**核心前提：目标台账必须建「数据来源」Flow 字段**（浏览-流程，`--sform-id` 指向流程绑定的表单 objId）。它存的是**流程实例 ID（requestId）**——add 时写入它，update/delete 靠它定位是哪次流程创建的记录，点击还能跳回流程。
+
+```bash
+# 台账建「数据来源」Flow 字段（只读，来源=项目立项流程）
+e10-cli form add-field <台账objId> <appId> "数据来源" Flow --sform-id <流程表单objId>
+```
+
+**① add（发起写入）**：plan 里把流程实例 ID（requestId 系统变量）写进台账「数据来源」字段，其余字段按 mapping 映射。
+
+**② update/delete（归档更新/退回删除）**：定位条件"**台账.数据来源 = 当前流程 requestId**"。`filterCondition` 动态右值引用 requestId，编译器自动判定为 `ApprovalData` 流程数据——`paramKey` 必须用本次 `actionflow workflow-context-fields` 返回的原始键，不要写死路径。示例 plan 结构：
+
+```json
+{
+  "event": {"type":"ApproveTrigger","params":{"workflowPath":{"id":"<流程id>"},"triggerTiming":"workflow_completed"}},
+  "actions":[
+    {"type":"ActionEbUpdate","params":{
+      "targetForm":{"groupId":"<appId>","id":"<台账objId>"},
+      "person":{"id":"<人员id>","name":"<姓名>"},
+      "opType":"updateData",
+      "filterCondition":{"field":{"id":"<台账数据来源字段ID>","label":"<数据来源字段名>"},"operator":"eq","right":{"type":"context","paramKey":"<workflow-context-fields 返回的流程ID paramKey>","label":"流程ID"}},
+      "mapping":{"<源paramKey>":"<目标字段ID>"}
+    }}
+  ]
+}
+```
+
+> `filterCondition` 格式**以 `actionflows/references/condition_rules.md` 为准**：`field` 必须为 `{id,label}` 对象、`operator` 用英文操作符（`eq/neq/gt/lt/gte/lte/contains/uncontains/empty/nempty`，`empty/nempty` 无右值）、右值键必须为 `right`。`value` 别名、`=`、裸字符串 `field`、数组根节点和 `relationship:"1|0"` 都会在编译前被拒绝。需求含条件/筛选时先翻 condition_rules.md 再下笔。
+
+> 也可直接给 `actionflow generate` 下自然语言 plan（"流程归档时按数据来源更新台账，项目状态置为立项"），由组件契约承载。`generate` 默认保存并启用设计（saveDesign saveAndStart=true，正式生效），返回 appId + 设计器链接，event 节点已含流程节点触发绑定。仅 `mode:"stash"` 时走暂存（需设计器手动发布）。
+
+**③ add 回写 dataId（源表存台账记录 ID）**：若后续 update/delete 想用"源表字段 = 台账 dataId"定位，`actionflow workflow-context-fields` 提供"回写数据ID对应字段"候选查询。
+
+---
+
+## 关联 EBuilder 更新目标表数据（跨表更新）
+
+**场景**：表A（带流程）通过 EBuilder 关联字段指向表B，流程到节点时动作流更新表B的目标记录字段。
+
+**机制**：表A 的 EBuilder 关联字段的值 = 表B 记录的数据ID。plan 里 `ActionEbUpdate` 的 `opType=id`（按数据ID更新）+ `filterCondition` 用表A的 EBuilder 关联字段 → 直接用关联值定位表B记录，无需字段值匹配。
+
+### 建两张表
+
+表B「客户台账表」（被更新）：客户名称(Text)、最后拜访日期(Date)、累计拜访金额(Money)
+```json
+[
+  {"componentKey":"Text","fieldName":"客户名称"},
+  {"componentKey":"Date","fieldName":"最后拜访日期"},
+  {"componentKey":"Money","fieldName":"累计拜访金额"}
+]
+```
+
+表A「拜访登记表」（带流程）：拜访日期(Date)、拜访金额(Money)、客户关联(EBuilder→表B)
+```json
+[
+  {"componentKey":"Date","fieldName":"拜访日期"},
+  {"componentKey":"Money","fieldName":"拜访金额"},
+  {"componentKey":"EBuilder","fieldName":"客户关联","sformId":"<表B objId>","dataTitle":"客户名称"}
+]
+```
+> EBuilder 字段：`sformId`=目标表 objId，`dataTitle`=目标表显示字段（填字段名或 fieldId，CLI 自动解析）。
+
+写 plan 时 mapping 目标ID 不加前缀=**直接赋值**（源值原样写入）；加 `+`=累加，`-`=扣减。直接赋值时按目标字段类型（日期/金额/文本等）自动匹配。
+
+---
+
+## 条件性动作流（同一节点按条件走不同动作）
+
+一个节点可挂**多个动作流，各自带触发条件**——提交时只有条件命中的动作才执行。典型场景「合同变更」：变更类型=续期 → 插入台账；变更/终止 → 更新+插入。
+
+在 plan 里用 `Condition` 组件（逻辑分支）表达条件，或多个 `ActionEb*` 配 `filterCondition`。条件规则语法见 `actionflows/references/condition_rules.md`。`actionflow component-describe Condition` 看条件组件契约。
+
+> **验证**：`e10-cli workflow action list-node <wf> <node>` 会标注 `⚠️条件` 的动作为带规则动作。条件内容在流程设计器节点 → 提交事件 → 动作的规则图标里查看。
+
+---
+
+## 动作流管理
+
+生成（`actionflow generate`）之后的查/清/删/禁用：
+
+```bash
+e10-cli workflow action list-node <wf> <node>    # 列节点绑定的动作（type0 常量赋值 + type2 动作流）
+e10-cli workflow action clear-node <wf> <node>  # 清空节点动作绑定（deleteAddAction，不删动作流实体）
+e10-cli workflow action disable <appId> <name>  # 禁用动作流（禁用后可删除）
+e10-cli workflow action delete <appId> <name>   # 删除动作流（自动先禁用再 batchAddRecycle）
+e10-cli workflow action batch-delete @list.json  # 批量删除（每项 {id,name}）
+```
+
+> **clear-node vs delete**：`clear-node` 只解绑节点（动作流实体仍在）；`delete` 删动作流 app（节点残留悬空引用，前端显示「被删除」，平台无按动作流反查节点接口，逐个 `clear-node` 清理）。
+>
+> **list-node 显示**：`type0 常量赋值`（本表字段赋值，`save-action` 写的）/ `type2 动作流`（`actionflow generate` 生成的，带 appId）。
+
+---
+
+## 角色管理
+
+```bash
+e10-cli role list                              # 查看角色树
+e10-cli role create <name> --parent <id> --code <code> --remark <text>
+e10-cli role delete <ids...>                   # 删除角色（可多个）
+e10-cli role add-member <roleId> <keyword>     # 搜索人员添加到角色
+```