weaver-e10-builder 1.0.11-beta → 1.1.0

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

@@ -0,0 +1,284 @@
+# 表单视图：新建与验收
+
+表单创建后已有默认台账；只有用户明确需要额外视图时才创建。表格视图是 `nListView` 数据列表，和普通 `formView` 是两条不同链路。
+
+## 需求判别
+
+- “新建表单” → `form create --fields`。
+- “客户信息表需要一个客户信息视图”等普通列表需求 → 先查询并复用该表单默认台账；“客户信息表”和“客户信息”的名称差异不构成额外新建理由。
+- “在已有表单下明确新增一个额外表格视图” → `form table-view create`；命令必须同时保存显示列并回读。
+- “在已有表单下新增表单视图” → `form view create --type formView`，随后必须 `form view populate`；不得新建另一张表单。
+
+## 默认台账复用
+
+1. 用 `form list-view <objId> <appId>` 查询已有列表，确认目标属于当前表单且用途符合需求，记录实际名称和 listId。存在多个候选时核对数据范围、权限和展示配置，不仅凭名称或第一条记录选择。
+2. 普通列表需求直接在该 listId 上配置显示列、筛选、排序、统计和事件；需要整组配置显示列时用 `form list-columns <objId> <appId> <listId> --set @columns.json`。`table-view ensure` 只用于空列补齐，不负责视图选择或重命名。
+3. 默认保留平台生成的名称，不统一去掉末尾“表”字。用户明确要求名称对齐时应改已有视图名称并保留 ID；目前 CLI 未提供视图重命名命令，不能用新建同用途视图代替改名。表单名、视图名和菜单名分别处理。
+4. 只有明确需要“我的客户”“重点客户”等额外独立视图，或不同展示类型时，才进入新增流程。已有重复视图需先核对菜单、关联页签等引用及配置，不能自动删除。
+
+例如：已建“客户信息表”，方案中的“客户信息视图”可由其默认台账满足，plan 标记“复用默认台账”，填写实际 listId 即可。
+
+## 命令
+
+```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 端；`list-columns --terminal mobile` 可改移动端显示列。**保存时先读回真实移动端 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 <fieldId1> <fieldId2>
+e10-cli form list-columns <objId> <appId> <listId> --remove <fieldId1> <fieldId2>
+
+# 按文件完整设置业务列顺序、宽度和格式（未列入的业务列会移除）
+e10-cli form list-columns <objId> <appId> <listId> --set @columns.json --json
+# 详见 references/form/guide-list-columns.md
+
+# 列显示格式：千分位/小数位（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
+
+# 主表/明细统计完整指南：references/form/guide-list-stats.md
+# 明细 count 支持只填 type/subFormId；批量入口：form list-stats detail
+# PC/MOBILE 可能共享统计项；以保存后的 mobileStatistics 为准，不能承诺只影响 PC
+# 顶部统计：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主键自动保留，禁止移除）。显示列命令保存后回读校验，`otherTerminalPreserved:true` 表示另一终端配置核对一致。
+
+## 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/guide-list-columns.md

@@ -0,0 +1,52 @@
+# 台账显示列批量配置
+
+适用于已有 `nListView`、`multiView` 的显示列。`listId` 取 `form list-view <objId> <appId>`；新建表格视图仍使用 `form table-view create`。关联浏览框的显示字段使用 `form ebuilder-columns`。
+
+## 查看、追加、移除
+
+```shell
+e10-cli form list-columns <objId> <appId> <listId> --json
+e10-cli form list-columns <objId> <appId> <listId> --add <字段ID1> <字段ID2> --json
+e10-cli form list-columns <objId> <appId> <listId> --remove <字段ID1> <字段ID2> --json
+```
+
+`--add` 按输入顺序追加到隐藏主键之前，已存在的列复用原配置；重复执行且无变化时返回 `unchanged:true`，不保存。`--remove` 可与 `--add` 同时使用，但不能对同一字段同时增删。移除不存在的列会报错；数据主键禁止移除。
+
+## 一次设置顺序、宽度和格式
+
+先读取当前列，按需求生成 UTF-8 的 `columns.json`。数组表示**完整业务列清单**：未列入的业务列会移除；数组顺序就是显示顺序。字段 ID 使用字符串，支持 `fieldId` 或 `id`，也支持仅填 ID 字符串。
+
+```json
+[
+  {"fieldId":"1310832462830059523","width":220},
+  {"fieldId":"1310832462830059527","width":150,"format":"yyyy-MM-dd"},
+  {"fieldId":"1310832462830059528","width":150,"format":"THOUSANDS","decimalLength":2}
+]
+```
+
+```shell
+e10-cli form list-columns <objId> <appId> <listId> --set @columns.json --json
+```
+
+示例 ID 来自维森测试93项目任务表，其他表单需替换。`--set` 不能与增删选项混用；空数组只保留数据主键。配置文件不是原始 `tableField` 快照，不要填隐藏主键、uid、eventGroup 等内部属性。
+
+| 属性 | 语义 |
+|---|---|
+| `fieldId` / `id` | 必填，当前表单的字段 ID，不可重复 |
+| `text` | 非空显示名称 |
+| `width` | 正数列宽，新列默认 150 |
+| `format` | 日期格式或数值 `THOUSANDS`；`null` 清除 |
+| `decimalLength` | 0–20 整数；`null` 清除 |
+| `hidden` | 是否隐藏业务列，布尔值 |
+| `viewDataDetail` | 是否显示关联数据详情，布尔值 |
+
+已有列只覆盖明确提供的属性，未指定的格式、单位、点击事件、uid 等保留；新列从字段元数据构造。明细子字段从 `ds/fields` 嵌套目录解析，必要时 `getFormField` 补查；设置 `mainField:false`，不带明细展开容器属性。不能把明细子表容器作为普通列添加。
+
+## 保存与验收
+
+- 默认改 PC，可用 `--terminal mobile` 修改移动端 `tableField`；移动端卡片布局的 `listField/cardLayout` 不属于此命令。
+- 全部字段与参数解析成功后，只调用一次 `saveNListConfig`。先读取真实 PC/MOBILE 配置，另一终端原样回传；读取失败默认中止。仅明确只用 PC 时允许 `--pc-only`，此时若移动端读取失败，结果标明未保留校验。
+- 自动保留隐藏数据主键，缺失时补齐。保存后回读核对列 ID、顺序、属性以及另一终端配置；仅忽略平台每次读取重新生成的按钮动作/事件 ID。
+- `verified:true` 表示接口回读通过。回读不一致时返回错误，保存可能已发生，应读取配置定位差异后处理；页面实际显示仍按需求验收。
+
+计划模板的「台账/视图配置 → 显示列批量设置」记录目标视图、终端、增量或整组模式、字段顺序、宽度/格式、配置文件路径与回读/页面验收结果。

package/skill-docs/references/form/guide-list-stats.md

@@ -0,0 +1,83 @@
+# 顶部统计：主表与明细
+
+`form list-stats` 配置已有台账视图的顶部统计。支持 sum/count/avg/max/min，以及千分位、小数位、万/亿单位、条件统计。来源表单 `objId`、应用 `appId`、目标视图 `listId` 与明细子表 `subFormId` 是不同 ID。
+
+## 查询及单项配置
+
+```bash
+e10-cli form list-stats <objId> <appId> <listId> --json
+e10-cli form list-stats <objId> <appId> <listId> --add @stat.json
+e10-cli form list-stats <objId> <appId> <listId> --remove <statId>
+```
+
+主表与明细字段均使用真实 fieldId；CLI 展开 `ds/fields` 的明细分组，未命中时按 `getFormField` 补查。字段必须属于当前表单，指定 subFormId 时必须与字段实际归属一致。
+
+付款金额统计示例：
+
+```json
+{
+  "fieldId": "1310832033224278033",
+  "type": "sum",
+  "name": "合同付款金额",
+  "decimalPlaces": "2",
+  "thousandths": true
+}
+```
+
+明细记录计数可省略 fieldId：
+
+```json
+{
+  "type": "count",
+  "subFormId": "1310832033224278030",
+  "name": "付款记录数"
+}
+```
+
+计数写为 `fieldId="5" + subFormId`，统计明细记录数。传明细字段做 count 也会转成该子表的记录计数，并非此字段非空值计数。主表记录计数可使用 `{"type":"count","name":"记录数"}`；已有传主表 fieldId 的用法继续接受。
+
+主表的 subFormId 写 `-1`，明细写实际子表 ID。**当前平台会将明细字段 sum 等字段聚合回读的 subFormId 规范化为 `-1`，仍由唯一 fieldId 定位明细字段；明细 count 必须保留子表 ID。** 回读校验兼容这种规范化，不允许字段或计数子表发生变化。
+
+格式参数：`thousandths` 为布尔值；`decimalPlaces` 为 -1 或 0–20 的整数；单位支持 `unit: "万"/"亿"` 或 `unitType: "none"/"tenThousand"/"hundredMillion"`。主表保持原默认小数位 -1，明细非计数默认 2，计数默认 -1。sum/avg 要求数值字段。
+
+## 条件统计
+
+```json
+{
+  "fieldId": "1310832033224278033",
+  "type": "sum",
+  "name": "正数付款金额",
+  "conditions": [
+    {"fieldId": "1310832033224278033", "func": "gt", "value": 0}
+  ]
+}
+```
+
+条件支持主表字段和本次统计子表字段，多个条件默认 AND。`valueField` 可引用字段 ID 或唯一名称，字段引用也校验子表归属。跨其他明细子表的条件拒绝保存，避免产生不明确的关联语义。
+
+条件写入明文 `rootdata`，无需 LZW。明细节点携带 `mainField=false`、`subTableId` 等信息；不能把它当成主表字段。操作符与现有条件构建器一致：eq/neq/gt/lt/range/aggregate/unaggregate/contains/uncontains/empty/nempty/startWith/endWith，支持原兼容别名。
+
+## 批量明细统计
+
+```bash
+e10-cli form list-stats detail <objId> <appId> <listId> <subFormId> --fields <金额fieldId> --name-prefix "付款-"
+```
+
+为指定数值字段分别生成 sum，并增加一项子表 count；一次保存。省略 `--fields` 时使用字段目录中该子表的全部数值字段。名称为“前缀+字段名+合计”和“前缀+子表名+记录数”。
+
+重复运行时，已有同名同配置项会复用并返回 `unchanged/reused`，不会重复新增；同名不同配置则报错，应先查询并明确移除旧项。批量操作同样可以使用 `--pc-only`。
+
+## 保存与移动端
+
+- 保留 PC 完整配置，仅更新 `listStatistics`；删除用 `operation: DELETE`，不能只从数组移除。
+- 读取真实移动端配置作为 `mConfig` 原样回传。默认移动端读取失败就停止；仅明确不使用移动端时加 `--pc-only`。
+- 保存后校验新增项、原有项、删除结果及移动端配置。`verified: true` 表示配置回读一致，不等于已经核对实际统计数值。
+- **维森测试93当前平台按 listId 共享 PC/MOBILE 统计项。** 当保存前后两端统计集合均对应一致时，返回 `mobileStatistics: "shared"`；改统计会同时影响两端。移动端独有统计丢失或其他配置变化仍报错。不要承诺共享环境下“只改 PC 统计”。
+- 比较移动端配置时，仅排除已实证每次读取会重建的按钮事件临时 ID；业务按钮 ID、动作内容、列配置等仍核对。`mobilePreserved` 表示移动端其余配置及独立统计得到保护。
+- 如果提示“已保存，但回读不一致”，先查询统计和移动端状态，不直接重试新增。
+
+## 计划与验收
+
+计划模板 3.3 的顶部统计项应记录：视图 ID、主表/明细范围、子表名称/ID、字段名称/ID、聚合方式、条件、格式、统计项 ID、PC/MOBILE 共享状态及验证结果。
+
+在“合同付款”视图验证：明细金额 sum、子表 count、明细条件、主表回归、重复运行、删除回读和移动端保护。不要改写用户已经配置的“合同付款金额”“付款记录数”；使用独立名称测试，结束清理临时项。实际金额与记录数须另用已知数据核对，不能仅凭保存成功认定数值正确。

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": ["所有人"]
+  }]
+}
+```
+
+> **只有包含工作流的应用**才能挂载工作流系统页面。表单台账会自动挂入菜单，无需手动操作。