weaver-e10-builder 1.6.16 → 1.7.0

package/skill-docs/references/form/guide-form-physical-table.md

@@ -1,148 +1,148 @@
-# 多物理表（一个表单的字段分散到多张物理表）
-
-设计器里「表单 → 字段管理」有三个页签：**主表 | 明细表 | 其他**。本文说的是**「其他」** —— 同一个表单的字段分散在多张**物理表**上。
-
-## 什么时候用
-
-**字段数过多时的容量兜底**（单表字段超过 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` 组件 | 无（不自动进布局，见下） |
-| 语义 | 一对多业务建模 | 一个表单自己的字段拆到多张表 |
-
-## 命令
-
-> **前置条件：主表至少要有一个业务字段。** 主表空着就建附属物理表，后续加字段/排布局会互相打架，命令会直接拦截并提示先 `form add-field`。
-
-```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`。
+# 多物理表（一个表单的字段分散到多张物理表）
+
+设计器里「表单 → 字段管理」有三个页签：**主表 | 明细表 | 其他**。本文说的是**「其他」** —— 同一个表单的字段分散在多张**物理表**上。
+
+## 什么时候用
+
+**字段数过多时的容量兜底**（单表字段超过 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` 组件 | 无（不自动进布局，见下） |
+| 语义 | 一对多业务建模 | 一个表单自己的字段拆到多张表 |
+
+## 命令
+
+> **前置条件：主表至少要有一个业务字段。** 主表空着就建附属物理表，后续加字段/排布局会互相打架，命令会直接拦截并提示先 `form add-field`。
+
+```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`。

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

@@ -150,9 +150,19 @@ e10-cli --json form table-view style <objId> <appId> <listId> <style>
 | `horizontal-list` | 横向列表式 | `4` |
 | `above` | 上图式 | `5` |
 | `grid` | 网格列表式 | `7` |
+| `editable-data` | 可编辑表格（数据态） | `8` |
+| `editable-readonly` | 可编辑表格（只读态） | `9` |
 | `editable` | 可编辑表格（编辑态） | `11` |
 
-可编辑表格内部还有数据态 `8` 和只读态 `9`；用户要求“改成可编辑表格”时必须使用编辑态 `11`，不得把只读态 `9` 当成完成。
+可编辑表格内部有数据态 `8`、只读态 `9`、编辑态 `11`。用户要求“改成可编辑表格”时必须使用编辑态 `11`，不得把只读态 `9` 当成完成；反过来，视图原本是 `9` 时可以用 `editable-readonly` 精确回滚，不会再被静默改成别的形态。
+
+平台以后新增、映射表里还没有的 `mode`，用逃生口直接写：
+
+```bash
+e10-cli form table-view style <objId> <appId> <listId> --raw-mode 10
+```
+
+命令会回显原 `mode`；原值不在已知映射表里时给出提示，并告诉你回滚该用哪个 `--raw-mode`。
 
 命令先确认 `listId` 属于目标 `objId`，读取目标终端的完整配置后只修改其顶层 `mode`，保存后重新读取该终端配置核对。
 
@@ -296,9 +306,11 @@ e10-cli form list-hierarchy <objId> <appId> <listId> --enable --parent-field "
 e10-cli form list-hierarchy <objId> <appId> <listId> --disable  # 关闭但保留字段及展开设置
 
 # 台账视图权限（查阅/查看权限）：谁能查看这个台账（走 list/permission/save + getList，专用端点，full-replace 语义 omit即删）
-# selectedType: all(所有人) / user(人员,带--name) / role(角色,--name 缺省自动查) / matrix(矩阵,用 --add-raw 传整对象)
+# selectedType: all(所有人) / user(人员) / dept(部门) / role(角色) / matrix(矩阵)
 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-dept <deptId>                 # --name 缺省自动取部门名
+e10-cli form list-permission <objId> <appId> <listId> --add-dept <deptId> --name "AI研发团队"
 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 # 安全级别范围
@@ -430,20 +442,63 @@ e10-cli form list-config set <objId> <appId> <listId> --set-top 1 --set-top-rule
 
 | 分组 | 选项 → 落库键 |
 |---|---|
-| 基本信息 | `--show-title` → `showTitle`（显示头部，关闭后表头区域隐藏）<br>`--hide-checkbox` → `hideCheckbox`（隐藏 check 框）<br>`--default-display-edit-modal` → `defaultDisplayEditModal`（默认显示编辑模式；人员范围 `defaultDisplayEditModalPermission` 形状未确认，暂不开放写入）<br>`--operate-column-fixed` → `operatColumnFixation`（操作按钮固定）<br>`--spread-top-button` → `enableSpreadTop`（显示展开至顶部按钮）<br>`--prefix-column` → `enablePrefixColumn`（前置列）<br>`--field-choose-width-fixed` → `fieldChooseWidthFixation`<br>`--quick-search-textarea` → `quickSearchTextArea`（快捷搜索支持富文本）<br>`--sub-form-main` / `--sub-form-show-empty` → `subFormMain` / `subFormMainShowEmpty`<br>`--page-size` → `pageSize`（1–100，落库为字符串） |
+| 基本信息 | `--show-title` → `showTitle`（显示头部，关闭后表头区域隐藏）<br>`--hide-checkbox` → `hideCheckbox`（隐藏 check 框）<br>`--default-display-edit-modal` → `defaultDisplayEditModal`（默认显示编辑模式；**单独开启 = 全体成员默认编辑**，命令会给出警示）<br>`--default-display-edit-modal-permission '<json>'` → `defaultDisplayEditModalPermission`（落库为 **JSON 字符串**，实测值 `{"hideSwitchButton":true,"includeViewPermissionData":true}`；它只含行为开关，不含人员/部门范围）<br>`--operate-column-fixed` → `operatColumnFixation`（操作按钮固定）<br>`--spread-top-button` → `enableSpreadTop`（显示展开至顶部按钮）<br>`--prefix-column` → `enablePrefixColumn`（前置列）<br>`--field-choose-width-fixed` → `fieldChooseWidthFixation`<br>`--quick-search-textarea` → `quickSearchTextArea`（快捷搜索支持富文本）<br>`--sub-form-main` / `--sub-form-show-empty` → `subFormMain` / `subFormMainShowEmpty`<br>`--page-size` → `pageSize`（1–100，落库为字符串） |
 | 网格 | `--grid-row` / `--grid-col` → `gridRow` / `gridCol`<br>`--grid-width-type` / `--grid-width` → `gridWidthType` / `gridWidth`<br>`--grid-height-type` / `--grid-height` → `gridHeightType` / `gridHeight` |
-| 显示数据 | `--permission-scope`（`isNoPermissionList`，无权限数据展示方式）/ `--data-range-type` / `--list-data-range`（数据范围）<br>`--show-follow` → `isShowFollow`（关注图标）<br>`--read-state` → `readState`（未读、反馈标识）<br>`--set-top` / `--set-top-type` / `--set-top-rule`（置顶；type 1=规则 2=手动） |
-| 批量操作 | `--batch-add` / `--batch-add-fields`<br>`--batch-edit` / `--batch-edit-fields`<br>`--batch-edit-value`；另有 `--can-delete` |
+| 显示数据 | **数据范围**统一落 `dataset.ebuilderDataConfig.dataSetup`：`--data-permission ALL\|HAVE_PERMISSION_DATA`（所有数据 / 有权限数据）、`--data-type ALL\|FORM\|APPROVE`、`--list-data-range <值>`（与 dataType 对应）、`--data-setup '<整对象 JSON>'`（推荐）<br>`--show-follow` → `isShowFollow`（关注图标）<br>`--read-state` → `readState`（未读、反馈标识）<br>`--set-top` / `--set-top-type` / `--set-top-rule`（置顶；type 1=规则 2=手动） |
+| 批量操作 | `--batch-add` / `--batch-add-fields`<br>`--batch-edit` / `--batch-edit-fields`<br>`--batch-edit-value`；另有 `--can-delete`。字段数组最小对象 `{"fieldId","fieldName","fieldType","componentKey"}`，平台补全的键（width/otherProperties/index…）不参与回读比对 |
 | 数据列表插件 | `--title` → `title`（表格名称）<br>`--hide-table-header` → `hideTableHeader`（隐藏表头，仅表格式）<br>`--table-header-operation` → `tableHeaderOperation`（表头快捷操作模式，仅表格式）<br>`--operate-btn-fixed` → `buttonConfig.operateBtnFixed`（操作按钮固定）<br>`--group '<json>'` → 整个 `enableGroup`（`enable` 分组开关 / `groupField` / `groupSize` / `expandFirstFew` 默认展开 / `isDelay` 延迟加载 / `hasDataGroupsOnly` 只显示有数据的分组 / `groupFieldQuery`）<br>`--superior '<json>'` → 整个 `superiorField`（`enable` 启用上下级 / `field` 关联字段 / `expandLevel` 默认展开级数 / `levelSelection` 层级选择限制 / `levelRange`） |
-| 展示模式 | `--open-child-list` → `openChildList`（上下级）<br>`--sup-field`（上下级关联字段 ID）<br>`--expand-level`（0–3 级）/ `--expand-num-limit`（0–500 行）<br>`--expand-page-type`（1=分页 0=更多加载）<br>`--enable-group` / `--group-field` / `--group-enable-count` / `--only-display-data-group` |
+| 展示模式 | `--open-child-list` → `superiorField.enable`（只改开关，其余子键保留）<br>`--sup-field`（顶层 `supField`，上下级关联字段 ID）<br>`--expand-level` → `superiorField.expandLevel`（0–3 级）/ `--expand-num-limit` → `superiorField.maxExpandNumLimit`（0–500 行）<br>`--expand-page-type`（1=分页 0=更多加载）<br>`--group-field` / `--group-enable-count` / `--only-display-data-group`<br>**分组一律用 `--group '<整对象 JSON>'`**（布尔写法 `--enable-group` 已删除，写布尔会覆盖对象并导致平台拒绝） |
 
 - `buttonConfig`（操作按钮的启用/位置）本版**只读展示、不提供写入**：样本里 `enable:0` 的极性未确认，避免写反。
 - 已是目标值时零写入；值没变不发保存请求。
 - 布尔键写 `true/false`；个别键平台可能落成 0/1，回读不一致时命令会直接点名报错（此时改用对应数值写法，不要硬重试）。
-- `--enable-group` 单独打开时平台会返回「系统错误」——先 `--group-field <字段ID>` 再开分组；分组字段只支持下拉框 / 关联 e-Builder 单选 / 关联浏览单选。
+- **`--default-display-edit-modal on` 单独开启 = 全体成员默认编辑。** 该开关只决定“是否默认进编辑模式”，谁算有权查看由**台账视图权限**（`form list-permission`）决定；`defaultDisplayEditModalPermission` 只是行为配置（`hideSwitchButton` / `includeViewPermissionData`），不含人员/部门范围。命令检测到“开关开、权限配置空”时会输出警示。要限定部门：先用 `form list-permission --add-dept` 配查看权限，再按需写 `--default-display-edit-modal-permission`。
+- **分组与上下级可以同时开启**，平台不互斥。平台要求 `enableGroup` 必须是对象（`enable` / `groupField` / `groupSize` / …），所以分组一律用 `--group '<整对象>'`；旧的 `--enable-group` 布尔写法已删除。先 `get` 拿现值改完再写，避免丢子键。
+- `--open-child-list` 现在只改 `superiorField.enable`，不会再写一个平台不读的顶层 `openChildList`。上下级的完整配置仍可用 `--superior '<整对象>'`。
 - `--head-merge`（`headMerge`）在平台「视图设置」面板里没有对应开关；「隐藏表头」分两种实现：台账视图用 `--show-title off`（`showTitle`），数据列表插件用 `--hide-table-header on`（`hideTableHeader`）。
-- 数据列表插件（`mode:"12"`、`_plugins` 里 `resourceType:"ebList"`）把分组/上下级存成嵌套对象，台账视图存成平铺键；两种都支持，按视图实际落库形态选。`--group` / `--superior` 是整对象写入，先 `get` 拿现值改完再写，避免丢子键。
-- `--set-top-type 2`（手动置顶）时 `setTopRule` 是字段 ID 串（如 `123,125`），`--set-top-rule` 两种形态都接受。
+- 数据列表插件（`mode:"12"`、`_plugins` 里 `resourceType:"ebList"`）把分组/上下级存成嵌套对象，台账视图存成平铺键；两种都支持，按视图实际落库形态选。
+
+### 数据范围（数据权限）
+
+真实存储位是 **`dataset.ebuilderDataConfig.dataSetup`**，不是配置顶层。旧版的 `--data-range-type` / `--permission-scope` 写的是平台不读取的游离键（全租户只有被 CLI 写过的视图有），已废弃并会直接报错给迁移提示。
+
+```bash
+# 推荐：整对象写
+e10-cli form list-config set <objId> <appId> <listId> \
+  --data-setup '{"dataPermission":"ALL","dataType":"ALL","listDataRange":"ALL"}'
+
+# 或逐项写
+e10-cli form list-config set <objId> <appId> <listId> --data-permission ALL
+e10-cli form list-config set <objId> <appId> <listId> --data-permission HAVE_PERMISSION_DATA --data-type FORM
+```
+
+`dataPermission`：`ALL`=所有数据 / `HAVE_PERMISSION_DATA`=有权限数据。
+
+### 规则置顶（setTopRule）
+
+`setTopRule` 必须是**平台标准条件树**（与「视图数据条件」`filter` 同构：顶层 `key/relationship/datas/rootStr/...`，叶子带 `objId/compType/formInfo` 等）。平台**不校验**这个键，乱写也会 200，但界面不识别。
+
+`--set-top-rule` 支持三种形态：
+
+1. **简化入参**（推荐）：给 `conditions` 数组，CLI 复用 `form list-filter` 的构造器生成标准树：
+
+```bash
+cat > rule.json <<'EOF'
+{"conditions":[
+  {"fieldId":"1326481253473714177","func":"eq","value":"{date}","text":"计划开始日期"}
+]}
+EOF
+
+e10-cli form list-config set <objId> <appId> <listId> \
+  --set-top 1 --set-top-type 1 --set-top-rule @rule.json
+```
+
+2. **标准树**：已经是 `datas + rootStr` 的对象，原样写入；缺 `rootStr` 时命令会补渲染。
+3. **手动置顶字段 ID 串**（`--set-top-type 2`）：如 `123,125`，原样写入。
+
+`get` 会检查 `setTopRule`：`setTopType=1` 但缺 `datas/rootStr` 时给出“平台可能不识别”的警示。日期条件里的 `{date}` 等系统参数占位符会原样存储、运行时求值（清单见 `ref-list-filter-date-params.md`）。
+
+> 平台实测：`saveNListConfig` 把**空字符串 / 空对象**当成“未提供”，因此 `setTopType`、`setTopRule` 一旦写过就无法通过该接口清回空值。关闭置顶用 `--set-top 0` 即可（运行时不再置顶）；不要为了清空反复重试，命令会如实报回读不一致。
 
 ## 卡片视图（cardView）
 
@@ -455,9 +510,11 @@ e10-cli form view rename <objId> <appId> <cardViewId> "新名称"
 e10-cli form view delete <objId> <appId> <cardViewId>   # ⚠ 不可逆
 ```
 
-- 改名 / 删除走 `viewlist/buttonEvent`，报文里 `viewType:"cardView"`（台账是 `nListView`，行为不变）。
+- 改名 / 删除按**视图族**路由：只有 `formView` 走 `layout/rename|delete`；cardView / 台账 / 看板 / 日历 / 思维导图 / 多维等**全部**走 `viewlist/buttonEvent`。`viewType` 的取值注意两套词汇：台账在 `getViewlist` 里是 `NList`，但 `buttonEvent` 只认 `nListView`（命令会自动归一）；其余视图族原样透传真实类型（日历、看板传成 `nListView` 会 500）。
+- 删除后回读会做有限次重试：平台删除是异步的，第一次读仍在不算失败。
 - 卡片视图**没有表单布局**：`form view populate` 会明确拒绝，不要拿它填字段。
-- 创建走 `viewlist/createView` + `viewType:"cardView"`，创建后必须在 `cardView.detail` 里回读到。
+- **卡片视图不能挂设计器组件**（数字面板、图表等）：它的 `pageId` 不是设计器页面，`designer layout/page/info` 会报 500。需要「卡片样式 + 数字面板」时，载体应是 **EB 页面**，或台账的**列表式/卡片布局**（`config.mode="12"`，走 `form nlist`），不是 `--type cardView`。
+- 创建走 `viewlist/createView` + `viewType:"cardView"`，**不能带 `terminalType`**（实测会 500），创建后必须在 `cardView.detail` 里回读到。
   若平台拒绝，命令会停下并提示「抓一次设计器新建卡片视图的 createView 报文」，不要改参数硬试。
 
 ## 显示字段落在哪一层（重要）
@@ -466,11 +523,18 @@ e10-cli form view delete <objId> <appId> <cardViewId>   # ⚠ 不可逆
 
 | 视图形态 | 显示字段所在层 | 用什么命令 |
 |---|---|---|
-| 表格式（nListView 默认） | `config.tableField` | `form list-columns` |
-| 列表式 / 卡片视图（NList） | `config.listField` + `config.cardLayout` | `form nlist add-field / remove-field / apply` |
+| 表格式 / 可编辑表格（`tableField` 非空） | `config.tableField` | `form list-columns` |
+| 列表式 / 卡片布局（`listField` 非空） | `config.listField` + `config.cardLayout` | `form nlist add-field / remove-field / apply` |
+
+层判定规则：**非空 `listField` 优先**；否则 `tableField` 非空就是表格式；两边都空时按 `mode` 兜底（`2` 列表式 / `12` 卡片布局 → `listField`，其余含可编辑表格 8/9/11 → `tableField`）。注意 `type:"NList"` 不能单独作为“列表式”的判据——可编辑表格同样是 `NList`，但显示列在 `tableField`。
 
 在列表式视图上执行 `form list-columns --add` 会**直接报错并给指引**（不会再写进不生效的 tableField，这是 2026-11 清单里「切列表式后加字段异常」的根因）。
 
+另有两层容易混淆：
+
+- `form list-columns` 读的是 **`getNListConfig.tableField`**（显示列清单）；
+- `form list-columns attr` 读的是 **`getListFields.pc[]`**（列属性，宽度/对齐/冻结等）。两者是**两层**：平台建表自动铺的列可能只有前者，`pc[]` 为空。这种情况下 `attr show` 会明确提示 0 条，`attr set` 会报错并说明“本命令只改列属性层，不会重建显示列”，不会静默把列清空。
+
 ```bash
 # 增量追加 / 移除列表式显示字段（只动点名字段，已有卡片布局原样保留）
 e10-cli form nlist add-field <objId> <appId> <listId> <fieldId1> <fieldId2>