weaver-e10-builder 1.6.12 → 1.6.13

package/skill-docs/actionflows/references/components/ebuilder/DateTrigger.md

@@ -1,32 +1,32 @@
-# 按日期字段触发（`DateTrigger`）
-
-## 何时使用
-
-根据 e-builder 数据中的日期/日期时间字段，在指定时机触发。
-
-## 先查询
-
-查询数据源、日期字段、可输出字段和操作人。
-
-## 不可猜测
-
-日期字段必须属于当前数据源；操作人必须是当前租户真实人员对象。
-
-## 最小计划
-
-`dataSource`、`dateField`、`operator`；其余时间规则按需求指定。未明确限制 `queryFields` 时不要传它（或传空数组），CLI 会默认全选主表和系统字段，包含后续链接/赋值需要的“数据ID”。
-
-## 重复周期
-
-`repeatType` 使用平台真实编码：
-
-| 值 | 含义 |
-|---|---|
-| `1` | 一次（不重复） |
-| `2` | 每天 |
-| `3` | 工作日（周一至周五） |
-| `4` | 每周 |
-| `5` | 每月 |
-| `6` | 每年 |
-
-不指定时默认为 `1`，即只触发一次。不要把 `1` 当成每日。
+# 按日期字段触发（`DateTrigger`）
+
+## 何时使用
+
+根据 e-builder 数据中的日期/日期时间字段，在指定时机触发。
+
+## 先查询
+
+查询数据源、日期字段、可输出字段和操作人。
+
+## 不可猜测
+
+日期字段必须属于当前数据源；操作人必须是当前租户真实人员对象。
+
+## 最小计划
+
+`dataSource`、`dateField`、`operator`；其余时间规则按需求指定。未明确限制 `queryFields` 时不要传它（或传空数组），预检会全选当前数据源字段选择器实际返回的字段，无法获取时停止生成。
+
+## 重复周期
+
+`repeatType` 使用平台真实编码：
+
+| 值 | 含义 |
+|---|---|
+| `1` | 一次（不重复） |
+| `2` | 每天 |
+| `3` | 工作日（周一至周五） |
+| `4` | 每周 |
+| `5` | 每月 |
+| `6` | 每年 |
+
+不指定时默认为 `1`，即只触发一次。不要把 `1` 当成每日。

package/skill-docs/actionflows/references/components/ebuilder/EnquiryForm.md

@@ -14,7 +14,9 @@
 
 ## 最小计划
 
-`dataSource`、`person`；按 `opType` 补充查询字段和筛选条件。未明确限制 `queryFields` 时不要传它（或传空数组），CLI 会默认全选主表和系统字段，包含“数据ID”。未指定 `filter` 时，CLI 会生成平台必填的中性条件“数据ID不为空”，不改变业务筛选范围；只有明确指定 `filter` 时才使用业务条件。
+`dataSource`、`person`；按 `opType` 补充查询字段，必须提供 `filter` 或 `conditionFormula`。未给出条件时应向用户确认具体筛选条件；即使需要查询全部数据，也不能臆造中性条件，应先确认并使用 `ds/fields` 返回的真实字段及支持的运算符。未明确限制 `queryFields` 时不要传它（或传空数组），CLI 会默认全选实时可选字段。
+
+业务模块数据源使用 `dataSourceKind:"business_module"`，可用平台实时分类名 `groupName` 或分类 ID `groupId` 缩小范围（例如 HRM）；未指定时逐分类查找，存在多个候选时须明确选择。字段查询沿用选中数据源返回的服务组。
 
 ## 动态分页和条件
 

package/skill-docs/actionflows/references/components/ebuilder/TimeBatchTrigger.md

@@ -1,19 +1,19 @@
-# 定时批量触发（`TimeBatchTrigger`）
-
-## 何时使用
-
-按一次、按小时、按日、按周、按月或 Quartz Cron 表达式扫描 e-builder 表单中满足条件的数据，并逐条触发后续动作。
-
-## 先查询
-
-查询数据源、查询/筛选字段与操作人。
-
-## 不可猜测
-
-批量筛选只能使用数据源真实字段；操作人不能使用文本或不存在的系统别名。
-
-`rate` 使用平台原生频率编码：`1` 一次、`2` 按小时、`3` 按日、`4` 按周、`5` 按月、`6` Cron。图形化频率需要 `startTime`；按小时/日/周用 `cycle` 或指定列表，按月用 `day`、`atWeek` 或 `lastWeek`。`orderFields` 支持查询排序；`endTime` 支持定时窗口；`openRetryFlag` 支持失败补偿。
-
-## 最小计划
-
-`dataSource`、`rate`、`startTime`、`operator`；按需求补充频率子项、查询字段、筛选条件、`orderFields`、`endTime` 和 `openRetryFlag`。未明确限制 `queryFields` 时不要传它（或传空数组），CLI 会默认全选主表和系统字段，包含后续链接/赋值需要的“数据ID”。Cron 模式使用 `rate=6` + `cornString`，例如每天 10:00：`0 0 10 * * ?`。
+# 定时批量触发（`TimeBatchTrigger`）
+
+## 何时使用
+
+按一次、按小时、按日、按周、按月或 Quartz Cron 表达式扫描 e-builder 表单中满足条件的数据，并逐条触发后续动作。
+
+## 先查询
+
+查询数据源、查询/筛选字段与操作人。
+
+## 不可猜测
+
+批量筛选只能使用数据源真实字段；操作人不能使用文本或不存在的系统别名。
+
+`rate` 使用平台原生频率编码：`1` 一次、`2` 按小时、`3` 按日、`4` 按周、`5` 按月、`6` Cron。图形化频率需要 `startTime`；按小时/日/周用 `cycle` 或指定列表，按月用 `day`、`atWeek` 或 `lastWeek`。`orderFields` 支持查询排序；`endTime` 支持定时窗口；`openRetryFlag` 支持失败补偿。
+
+## 最小计划
+
+`dataSource`、`rate`、`startTime`、`operator`；按需求补充频率子项、查询字段、筛选条件、`orderFields`、`endTime` 和 `openRetryFlag`。未明确限制 `queryFields` 时不要传它（或传空数组），预检会全选当前数据源字段选择器实际返回的字段，无法获取时停止生成。Cron 模式使用 `rate=6` + `cornString`，例如每天 10:00：`0 0 10 * * ?`。

package/skill-docs/references/common/ref-cli-commands.md

@@ -108,7 +108,11 @@
 | `e10-cli form permission archive <list\|add\|remove\|card> <objId> <appId> --workflow <workflowId>` | **流程归档权限**（归档后数据对谁可见/可改/可删，**按流程各一套**，与共享权限不同）。`add --target <general/creator/field/matrix>`：`general` 通用对象配 `--org-type`+`--org-id`；`creator` 创建人相关配 `--creator-related 0~7`；`field` 字段相关配 `--field <字段id或名>`（`--sub-form-id` 支持明细字段，未收录的字段类型需 `--org-type field_xxx` 显式指定）；`matrix` 矩阵相关配 `--matrix`（真矩阵）或 `--eb-form`（e-Builder 表单）+ `--matrix-value`（e-Builder 表单按名取它自己的人员字段/创建者，人员字段 valueType=resource），另可加**矩阵条件**（e-Builder 表单的条件列自动取该表单主表字段） `--matrix-condition '<json>'`（可重复 / `@文件` 给数组；右值三选一 `value` 固定值 / `field` 引本表单字段 / `fieldRef` 直给字段描述符）+ `--matrix-condition-relation and\|or`。权限码 `5/view` 归档查看、`6/edit` 归档编辑、`7/delete` 归档删除（**归档查看是系统默认必选，界面不可取消；`--rights` 没传 view 会自动并入**）；归档附件另算 `501/view`、`502/download`、`503/edit`（**不是**共享权限的 401/402；**归档附件查看 501 同属系统必选，不给 `--file-rights` 也会带上**）。保存后按 ID 回读逐项核对；`card <workflowId> <appId> [--set 0\|1]` 读写归档卡片开关。详见 `form/guide-form-archive-permission.md` |
 | `e10-cli form permission <list\|add\|remove\|rebuild> <objId> <appId>` | 权限通用管理及兼容入口。新建权限与数据权限分开；旧 `add --right-type` 保留兼容。`list` 查看全部分类；`remove --right-id <id[,id...]>` 删除一条或多条权限；添加后提示 `isShowRebuild=2` 时执行 `rebuild` |
 | `e10-cli form list-view <objId> <appId>` | 查看台账/数据列表（获取 viewId 用于菜单配置） |
-| `e10-cli form list-columns <objId> <appId> <listId> [--add <fieldId...>] [--remove <fieldId...>] [--set @columns.json] [--terminal pc/mobile] [--pc-only]` | 查看/批量设置台账显示列。增量追加、移除或整组指定顺序/列宽/格式；整组模式与增删互斥。支持主表和明细子字段，保留已有列未指定属性、事件及数据主键；一次保存并回读核对目标列和另一终端。详见 `references/form/guide-list-columns.md` |
+| `e10-cli form list-columns <objId> <appId> <listId> [--add <fieldId...>] [--remove <fieldId...>] [--set @columns.json] [--terminal pc/mobile] [--pc-only]` | 查看/批量设置台账显示列。增量追加、移除或整组指定顺序/列宽/格式；整组模式与增删互斥。支持主表和明细子字段，保留已有列未指定属性、事件及数据主键；一次保存并回读核对目标列和另一终端。**只作用于表格式 `tableField`**：列表式/卡片视图（NList）会直接报错并指向 `form nlist`。详见 `references/form/guide-list-columns.md` |
+| `e10-cli form list-columns attr show\|set <objId> <appId> <listId> --field <fieldId> [--align left\|center\|right] [--fixed on\|off] [--width N] [--width-unit px\|%] [--editable 0\|1] [--rich-editor on\|off] [--show-name <名>] [--conversion '<json>'] [--terminal pc/mobile]` | 列属性层（`getListFields`/`saveListFields`）：对齐、冻结、列宽、显示名、可编辑、富文本、显示转换。只改目标列，另一端与其它列原样回传，保存后回读目标列断言 |
+| `e10-cli form list-filter sql get\|set <objId> <appId> <listId> [--sql @sql.json] [--base-sql <sql>] [--dialect "mysql=<sql>"] [--dataset-id <id>]` | **SQL 条件**（`filter.type=sql_where`）：SQL 正文写进独立的 `sqlfragments` 数据集，视图只记数据集 ID。`sql.json` 键：`base` + `mysql/oracle/sqlserver/pg/dm/kingbase/st/oceanbase`（对应平台 `mysqlSql/oracleSql/sqlserverSql/pgSql/dmSql/kingBaseSql/stSql/oceanbaseMysql`）。主表别名 `t1`、明细 `d1`、`{参数}` 为运行时占位；保存后回读视图条件与数据集正文。`--dataset-id` 只切绑定不新建；`--ignore-empty on|off` 写「变量值为空时不参与过滤」（`filterIsNull`：on→false，off→true）。详见 `form/guide-form-view.md` |
+| `e10-cli form list-filter http get\|set <objId> <appId> <listId> --url <url> [--method GET\|POST] [--param name=value] [--header name=value] [--form name=value] [--payload '<json>'] [--ignore-empty on\|off]` | **自定义接口条件**（`filter.type=http`）：URL + 方法 + Params/Headers/Body(form-data 或 JSON)。落库 `data.{method,contentType,url,urlParams[],headers[],formData[],payload}`，`rootStr="自定义接口"`，PC/移动端同写；保存后回读 URL 与方法。详见 `form/guide-form-view.md` |
+| `e10-cli form list-config get\|set <objId> <appId> <listId> [--head-merge on\|off] [--hide-checkbox on\|off] [--page-size N] [--set-top 1\|0] [--set-top-type <s>] [--set-top-rule '<json>'] [--batch-edit-value on\|off] [--batch-add-fields '<json>'] [--batch-edit-fields '<json>'] [--can-delete on\|off] [--terminal pc/mobile] [--pc-only]` | 视图基础开关（`getNListConfig` 顶层键）：表头合并、隐藏 check 框、分页条数、数据置顶、批量、允许删除。只改点名键、其余原样回写，保存后只回读被改的键；`get` 额外展示操作按钮摘要（只读，本版不写 `buttonConfig`）。`headMerge`/`setTop` 的 UI 文案与极性待真机核对 |
 | `e10-cli form list-unit <objId> <appId> <listId> <fieldId> <后缀> [--prefix <前缀>] [--clear] [--pc-only]` | 设置台账列显示**单位**（后缀/前缀）。平台无字段级单位属性，靠列表列配置 `showTrans.ruleConfig.suffix/prefix` 实现。如 `form list-unit ... <fieldId> "（元）"` 让列显示单位；`--clear` 清除 |
 | `e10-cli form list-format <objId> <appId> <listId> <fieldId> [--thousandths] [--no-thousandths] [--decimal <n>] [--clear] [--pc-only]` | 查看/设置台账列**千分位/小数位**（Number/Money 列）。不加参数显示当前；`--thousandths` 开千分位（列 `format:"THOUSANDS"`）、`--no-thousandths` 关、`--decimal <n>` 小数位数（`decimalLength`）、`--clear` 清除恢复默认。与 `list-unit`（单位，走 `showTrans`）是两套不同机制。**自动保留移动端配置** |
 | `e10-cli form list-click <objId> <appId> <listId> <fieldId> [--target <formObjId>] [--open-mode <模式>] [--win-size <尺寸>] [--clear] [--pc-only]` | 设置台账列**点击跳转**。`--open-mode` 支持当前页面/新窗口/弹出窗口/右侧滑出/右侧推出；`--win-size` 仅用于滑出/推出，具体数值按需求填写：百分比使用 `%`（0～100），像素使用 `px`，两种单位不可混用。缺省 `800px` |
@@ -135,10 +139,11 @@
 | `e10-cli form list-permission <objId> <appId> <listId> [--add-all] [--add-user <userId> --name <name>] [--add-role <roleId> [--name <name>]] [--add-matrix <矩阵id> --name <name>] [--share-level <n>] [--seclevel <min>-<max>] [--add-raw '<json>'] [--remove <id>] [--remove-all] [--clear]` | 查看/配置**台账视图权限**（谁能查看这个台账）。`--add-all` 所有人（自动把空 dataid 与 0 视为同一主体，避免重复）、`--add-user` 人员、`--add-role` 角色、`--add-matrix` 矩阵（同 `form permission archive` 的矩阵条件参数：`--matrix-condition` / `--matrix-condition-relation` / `--matrix-condition-comp-type` / `--matrix-condition-raw`）。`--remove <id>` 删除指定权限；`--remove-all` 删除全部“所有人”，与 `--add-all` 同用可清理重复后只保留一条；`--clear` 清空全部。保存走 `list/permission/save` 全量覆盖并回读。另支持共享级别和安全级别范围 |
 | `e10-cli form list-search-group <objId> <appId> <listId> [--add <字段名或fieldId>] [--add-custom <名称>] [--custom @配置.json] [--archive on\|off] [--position 0\|1] [--display 平铺\|下拉] [--show-archive on\|off] [--option-order default\|field] [--no-show-count] [--count-update] [--only-with-data] [--date-granularity <列表>] [--default-group <粒度> --default-value <起,止>] [--options <列表>] [--default-options <列表>] [--remove <fieldId>] [--clear] [--pc-only]` | 查看/配置**分类搜索**（台账顶部/下拉的分类筛选）。`--add` 收**字段名或 fieldId**，已在里面则按本次参数**重建那条**（改配置走它）—— 本次没给的选项一律回到缺省，所以只改一项时要把想留着的一起给全。支持四类：**选项类**(Select/RadioBox/CheckBox)、**浏览框类**(Ebuilder/Browser/Employee/Department)、**日期类**(DateComponent)、**系统字段**(创建者/数据ID 这类)。`--position` **0=顶部(缺省)/1=左侧(下拉样式)**（平台枚举 Top="0"、Left/DropDown="1"）；`--display` 是「显示方式」：`平铺` 写 `tabStyle="tab"`、`下拉` 写 `"select"`（缺省下拉）；`--show-archive on|off` 控制「显示封存的选项」`showArchiveOption`（缺省 on）。`--add-custom <名称>` 添加**自定义分类**（`componentKey=GroupCustom`）：id 由前端生成 18 位数字、`fieldId=GroupCustom_<id>`（平台没有创建接口），分类值 `listGroupSets` 初始为空、之后在设计器里配置；同名分类再执行即更新（保留原 id），可用 `--remove <名称|id|fieldId>` 删除；`--option-order` 浏览框的选项排序（default 默认排序 / field 按字段属性设置）；`--no-show-count` 关掉统计数字，`--count-update` 让统计数字**随搜索结果更新**（选项/浏览框/日期可用，缺省只在进入台账时统计一次）；`--only-with-data` **仅显示有数据的选项**（**只有**选项/浏览框类有这个键，日期与系统字段用不了；这个键**勾上才出现**，不勾整个键都没有）；`--date-granularity` 日期粒度（全年/半年/季度/月，缺省全要）；`--options` / `--default-options` 控制选项类**哪些选项出现 / 哪些默认选中**。日期类的**默认值**用 `--default-group <粒度>` + `--default-value "起,止"`（两个**必须一起给**；平台存的是一条 `{value,group}` 的默认值，并把它对应的粒度标成默认勾上）。**仅主表字段，不支持明细（产品边界，传明细报错）**。走 saveNListConfig `config.searchConditions.groupFilters`（视图级明文） |
 | `e10-cli form nlist apply <objId> <appId> <listId> <template>` | 配置**列表式视图**（台账）的显示列：模板是二维数组（行 → 列），列项可绑表单字段（`fieldId`）或做**自定义文本**列（不给 `fieldId`、给 `html`，里面用 `{{字段名}}` 插入表单字段）。自动读移动端槽位一并写入。`show` 查看当前配置。⚠ 仅对列表式(NList)生效，表格式用 `form table-view`。详见 `form/guide-list-custom-text.md` |
+| `e10-cli form nlist add-field\|remove-field <objId> <appId> <listId> <fieldId...> [--form-id <id>]` | **增量**改列表式/卡片视图显示字段：追加的字段各占一行，移除时同时清 `listField` 与 `cardLayout.grid`；已有布局原样保留（不重建模板）。隐藏主键 `id=5` 恒保留。PC 与移动端一次提交，两端回读 |
 | `e10-cli form view list <objId> <appId> [--with-comps]` | 列出表单全部视图。`--with-comps` 额外拉每个视图布局 comps 数、标出空视图（NList 数据视图会显示「读取失败」，正常） |
-| `e10-cli form view rename <objId> <appId> <viewId> <新名称>` | 修改视图名称并回读。**表单视图与台账各走一条接口**（台账走 `viewlist/buttonEvent` 的编辑动作，其余视图走 `layout/rename`），命令按类型自动选。保留原视图 ID 和配置。需求名称与默认名称不一致时统一用此命令，不新建重复视图 |
-| `e10-cli form view delete <objId> <appId> <viewId>` | 删除视图（表单视图 / 台账 / 看板等，按类型自动选接口）。⚠ **不可逆、无回收站**。先回读定位目标，删完**再回读确认确实没了**才算成功 |
-| `e10-cli form view create <objId> <appId> <视图名> [--type formView\|kanbanView\|calendarView\|mindMapView\|multiView] [--terminal PC\|MOBILE] [--layout-type FLOW\|EXCEL] [--detail <明细名>] [--sub-form-id <明细subFormId>]` | 给**已有表单**添加视图。`formView` 创建后是空布局，需续跑 `form view populate` 填字段；`kanbanView`/`calendarView`/`mindMapView`/`multiView` 建视图实体。**multiView 数据维度**：缺省主表；明细表维度用 `--detail <明细名>`（按名解析）或 `--sub-form-id <明细subFormId>`（直传），传值即明细维度（`subFormMain:true`）。**台账(NList)视图**用 `form table-view create`，不在此命令 |
+| `e10-cli form view rename <objId> <appId> <viewId> <新名称>` | 修改视图名称并回读。**表单视图与台账各走一条接口**（台账与卡片视图走 `viewlist/buttonEvent` 的编辑动作，报文 `viewType` 分别为 `nListView`/`cardView`；其余视图走 `layout/rename`），命令按类型自动选。保留原视图 ID 和配置。需求名称与默认名称不一致时统一用此命令，不新建重复视图 |
+| `e10-cli form view delete <objId> <appId> <viewId>` | 删除视图（表单视图 / 台账 / **卡片视图** / 看板等，按类型自动选接口；台账与卡片视图走 `viewlist/buttonEvent`）。⚠ **不可逆、无回收站**。先回读定位目标，删完**再回读确认确实没了**才算成功 |
+| `e10-cli form view create <objId> <appId> <视图名> [--type formView\|cardView\|kanbanView\|calendarView\|mindMapView\|multiView] [--terminal PC\|MOBILE] [--layout-type FLOW\|EXCEL] [--detail <明细名>] [--sub-form-id <明细subFormId>]` | 给**已有表单**添加视图。`formView` 创建后是空布局，需续跑 `form view populate` 填字段；`cardView` 走精简 body（不带 layoutType），创建后必须在 `cardView.detail` 回读到，否则报错提示抓 createView 报文；`kanbanView`/`calendarView`/`mindMapView`/`multiView` 建视图实体。**multiView 数据维度**：缺省主表；明细表维度用 `--detail <明细名>`（按名解析）或 `--sub-form-id <明细subFormId>`（直传），传值即明细维度（`subFormMain:true`）。**台账(NList)视图**用 `form table-view create`，不在此命令 |
 | `e10-cli form view populate <objId> <appId> <viewId>` | 把已有字段按布局类型填入 formView。视图为空则整份填；**视图已有字段时只补缺**——只补视图里还没有的字段，已有组件的排版与属性一个不动（重跑幂等）。表单新增字段后要让它出现在某个视图里，也走这条 |
 | `e10-cli form message list <appId> [--obj-id <objId>] [--keyword <kw>] [--page-size <n>] [--page-index <n>]` | 列出**消息提醒**（表单数据变动时提醒人）。不传 `--obj-id` 列出整个应用的；传了**在本地按表单收口**（平台那条过滤参数不生效）。详见 `references/form/guide-form-message.md` |
 | `e10-cli form message get <appId> <triggerId> [--obj-id <objId>]` | 查看单条消息提醒，含**推送渠道**与提醒对象。渠道不在列表与详情返回里，命令额外读一次补上 |

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

@@ -413,6 +413,207 @@ e10-cli --json form view populate <objId> <appId> <viewId>
 
 服务器验证通过后仍需用户确认前端不是空画布、字段名称和特殊配置正确。
 
+## 视图基础开关（表头 / check 框 / 分页 / 置顶 / 批量 / 删除）
+
+`form list-config` 读写 `getNListConfig` 顶层的开关键。键名来自平台真实保存报文，**只改点名的键**，其余原样回写；另一端（PC / 移动）原样保留；保存后只回读被改的键。
+
+```bash
+# 读当前值（含操作按钮摘要：按钮 key / 启用值 / 位置，只读）
+e10-cli form list-config get <objId> <appId> <listId> --json
+
+# 改开关；不指定 --terminal 默认改 PC
+e10-cli form list-config set <objId> <appId> <listId> --hide-checkbox on --page-size 20
+e10-cli form list-config set <objId> <appId> <listId> --set-top 1 --set-top-rule @rule.json
+```
+
+| 选项 | 落库键 | 取值 |
+|---|---|---|
+| `--head-merge` | `headMerge` | on/off（UI 文案待真机核对） |
+| `--hide-checkbox` | `hideCheckbox` | on/off |
+| `--page-size` | `pageSize` | 数字，落库为字符串 |
+| `--set-top` | `setTop` | 1/0（1=开，极性待真机核对） |
+| `--set-top-type` / `--set-top-rule` | `setTopType` / `setTopRule` | 字符串 / JSON |
+| `--batch-edit-value` | `batchEditValue` | on/off |
+| `--batch-add-fields` / `--batch-edit-fields` | `batchAddFields` / `batchEditFields` | JSON 数组 |
+| `--can-delete` | `canDelete` | on/off |
+
+- `buttonConfig`（操作按钮的启用/位置）本版**只读展示、不提供写入**：样本里 `enable:0` 的极性未确认，避免写反。
+- 已是目标值时零写入；值没变不发保存请求。
+
+## 卡片视图（cardView）
+
+卡片视图在 `getViewlist` 里是独立的一族（`data.cardView.detail`），**不是布局视图**：
+
+```bash
+e10-cli --json form view create <objId> <appId> "卡片视图名" --type cardView
+e10-cli form view rename <objId> <appId> <cardViewId> "新名称"
+e10-cli form view delete <objId> <appId> <cardViewId>   # ⚠ 不可逆
+```
+
+- 改名 / 删除走 `viewlist/buttonEvent`，报文里 `viewType:"cardView"`（台账是 `nListView`，行为不变）。
+- 卡片视图**没有表单布局**：`form view populate` 会明确拒绝，不要拿它填字段。
+- 创建走 `viewlist/createView` + `viewType:"cardView"`，创建后必须在 `cardView.detail` 里回读到。
+  若平台拒绝，命令会停下并提示「抓一次设计器新建卡片视图的 createView 报文」，不要改参数硬试。
+
+## 显示字段落在哪一层（重要）
+
+显示字段有两层，`form list-columns` 只改**表格式**的 `config.tableField`：
+
+| 视图形态 | 显示字段所在层 | 用什么命令 |
+|---|---|---|
+| 表格式（nListView 默认） | `config.tableField` | `form list-columns` |
+| 列表式 / 卡片视图（NList） | `config.listField` + `config.cardLayout` | `form nlist add-field / remove-field / apply` |
+
+在列表式视图上执行 `form list-columns --add` 会**直接报错并给指引**（不会再写进不生效的 tableField，这是 2026-11 清单里「切列表式后加字段异常」的根因）。
+
+```bash
+# 增量追加 / 移除列表式显示字段（只动点名字段，已有卡片布局原样保留）
+e10-cli form nlist add-field <objId> <appId> <listId> <fieldId1> <fieldId2>
+e10-cli form nlist remove-field <objId> <appId> <listId> <fieldId>
+
+# 整份模板重排（会重建 cardLayout）
+e10-cli form nlist apply <objId> <appId> <listId> @template.json
+```
+
+- 新字段各占一行；隐藏主键 `id=5` 始终保留，不能增删。
+- PC 与移动端一次提交；移动端不是 NList 时只改 PC 并给出提示。
+
+## 列属性（对齐 / 冻结 / 宽度 / 显示名）
+
+列属性存在 `getListFields` / `saveListFields` 层（不是 `tableField`）：
+
+```bash
+e10-cli form list-columns attr show <objId> <appId> <listId>
+e10-cli form list-columns attr set  <objId> <appId> <listId> --field <fieldId> --align center --fixed on
+e10-cli form list-columns attr set  <objId> <appId> <listId> --field <fieldId> --width 200 --width-unit px
+e10-cli form list-columns attr set  <objId> <appId> <listId> --field <fieldId> --show-name "合同金额"
+```
+
+| 选项 | 落库键 | 取值 |
+|---|---|---|
+| `--align` | `alignment` | left / center / right |
+| `--fixed` | `fixed` | on→`"1"` / off→`"0"`（1 的语义待真机核对） |
+| `--width` / `--width-unit` | `width` / `widthUnit` | 正数 / px / % |
+| `--editable` | `isEditField` | 0 / 1 |
+| `--rich-editor` | `richEditor` | on / off |
+| `--show-name` | `showName` | 非空字符串 |
+| `--conversion` | `conversionSet` | JSON 字符串（如 `"[]"`） |
+
+- 只改目标列；另一端与其它列原样回传；保存后回读目标列断言。
+- 表头换行、列注释、列头筛选、拓展区域目前**没有**对应命令（本地无真实报文），需要时先抓一份保存报文。
+
+## SQL 条件（多数据库，2026-11-04 真机验证）
+
+视图数据条件除了常规条件树，还可以用 **SQL 条件**。平台不是把 SQL 存在视图里，而是：
+
+1. `POST /api/dw/directConn/addDataset` 建一个 `sqlfragments` 数据集——每种数据库一条 SQL；
+2. 视图 `config.filter` 只记数据集 ID：
+   ```json
+   {"type":"sql_where","isNewFilter":true,"version":1,
+    "data":{"condition":"<数据集ID>","formDw":true,"sourceId":"<表单objId>"}}
+   ```
+   同时 `config.rootStr = "SQL"`，PC 与移动端都写。
+
+```bash
+# 读：视图 filter + 数据集里的基础SQL/各库 SQL
+e10-cli form list-filter sql get <objId> <appId> <listId> --json
+
+# 写：建数据集并绑定（文件形式，避免命令行引号被 shell 改形）
+e10-cli form list-filter sql set <objId> <appId> <listId> --sql @sql.json
+
+# 或按库逐条给
+e10-cli form list-filter sql set <objId> <appId> <listId> \
+  --base-sql "t1.a = '{参数}'" \
+  --dialect "mysql=t1.a = '{参数}'" \
+  --dialect "oracle=t1.a = '{参数}'"
+
+# 切回之前那份条件（不新建数据集）
+e10-cli form list-filter sql set <objId> <appId> <listId> --dataset-id <旧数据集ID>
+```
+
+`sql.json` 的键（与平台 `sourceSql` 一致，别名大小写不敏感）：
+
+| 写法 | 落库键 | UI |
+|---|---|---|
+| `mysql` | `mysqlSql` | Mysql |
+| `oracle` | `oracleSql` | Oracle |
+| `sqlserver` | `sqlserverSql` | Sqlserver |
+| `pg` / `postgresql` | `pgSql` | PostgreSQL |
+| `dm` / `dameng` | `dmSql` | 达梦数据库 |
+| `kingbase` | `kingBaseSql` | 人大金仓数据库 |
+| `st` / `shentong` | `stSql` | 神通数据库 |
+| `oceanbase` | `oceanbaseMysql` | oceanbaseMysql |
+
+```json
+{
+  "base": "t1.a = '{参数}' and d1.b = '3'",
+  "mysql": "t1.a = '{参数}'",
+  "oracle": "t1.a = '{参数}'",
+  "pg": "t1.a = '{参数}'"
+}
+```
+
+- 主表别名 `t1`、明细表别名 `d1`；`{参数}` 是运行时参数占位。CLI 会告警花括号不配对、以及完全没出现 `t1./d1.` 的 SQL（只是提醒，以后端执行结果为准）。
+- `base` 是平台的「基础SQL」；不给时取第一条库 SQL。
+- 每次 `set` 都会新建一个数据集，**旧数据集不会自动删**；只是切换用 `--dataset-id`。
+- SQL 以明文提交即可（平台自己加密存储），回读也是明文。
+- **「变量值为空时不参与过滤」= `config.filterIsNull`**（2026-11-04 开/关两次保存对照，其余字段逐字节相同）：
+
+  | 开关 | `filterIsNull` |
+  |---|---|
+  | 打开（空值不参与过滤） | `false` |
+  | 关闭 | `true` |
+
+  两个命令都支持 `--ignore-empty on|off`；不给则沿用视图现有值：
+  ```bash
+  e10-cli form list-filter sql set <objId> <appId> <listId> --sql @sql.json --ignore-empty on
+  e10-cli form list-filter <objId> <appId> <listId> --ignore-empty on   # 常规条件同样可设
+  ```
+
+## 自定义接口条件（filter.type = http，2026-11-04 真机验证）
+
+视图条件的第三种形态：请求一个外部接口，用返回结果过滤数据。落库结构（真机保存报文）：
+
+```json
+{"type":"http","isNewFilter":true,"version":1,
+ "data":{"method":"GET","contentType":"multipart/form-data",
+         "url":"https://…",
+         "urlParams":[{"name":"a","value":"1"}],
+         "headers":[{"name":"x-test","value":"hello"}],
+         "payload":"{\"\"}",
+         "formData":[{"name":"body","value":"bbooddyy"}],
+         "condition":"","formDw":true,"sourceId":"<objId>","sqlContent":""}}
+```
+
+同时 `config.rootStr = "自定义接口"`，PC 与移动端写同一份。
+
+```bash
+e10-cli form list-filter http get <objId> <appId> <listId> --json
+
+e10-cli form list-filter http set <objId> <appId> <listId> \
+  --method GET \
+  --url "https://example.com/api?x=1" \
+  --param a=1 \
+  --header "x-test=hello" \
+  --form body=bbooddyy \
+  --ignore-empty on
+```
+
+| 选项 | 落库键 | 说明 |
+|---|---|---|
+| `--method` | `data.method` | GET / POST / PUT / DELETE / PATCH（默认 GET） |
+| `--url` | `data.url` | 接口地址，可带查询串 |
+| `--content-type` | `data.contentType` | 默认 `multipart/form-data` |
+| `--param` | `data.urlParams[]` | Params 页签一行，可重复 |
+| `--header` | `data.headers[]` | Headers 页签一行，可重复 |
+| `--form` | `data.formData[]` | Body(form-data) 一行，可重复 |
+| `--payload` | `data.payload` | Body(JSON) 原始字符串；不给则写平台默认 `{"":""}` |
+| `--ignore-empty` | `config.filterIsNull` | 开→false / 关→true，与 SQL 条件一致 |
+
+- 参数名禁止为空、禁止重复；URL 首尾有空格或不是 http(s) 开头会告警（仍按原样写入，平台不帮你去空格）。
+- 抓包里 `condition` 是切模式前残留的数据集 ID；http 模式不读它，CLI 写空串，回读只断言 URL/方法等实际写入的键。
+- 三种条件（常规条件树 / SQL / 自定义接口）共用同一个 `config.filter`，**互相覆盖**；切换前先 `get` 确认当前是哪一种。
+
 ## 执行与验收
 
 1. 计划中写明表单 objId、视图名称、类型和终端；用户确认后再写入。