weaver-e10-builder 1.6.13 → 1.6.14

package/skill-docs/references/form/layout/detail-advanced.md

@@ -0,0 +1,124 @@
+# 明细表高级扩展
+
+适用 EB 表单、原生工作流程表单的 FLOW／EXCEL 布局。先读 [明细表基础设置](detail-settings.md)定位表单、布局和子表。命令仍为 `form layout detail get/set`，原生流程传 `--module workflow`，修改默认预览，加 `--apply` 保存并独立回读。
+
+`get` 的 `settings` 包含已存高级设置，`advancedCandidates` 列出明细字段、类型以及 `canTotal`／`canFilterSelected`。字段 ID 必须属于目标明细。候选中的其他字段只表示属于明细，并非各高级功能的完整平台白名单；分组、合并、排序、搜索和批量添加仍需结合字段特性选择，不能把保存成功当成所有字段类型均有相同运行效果。
+
+## 配置块和更新规则
+
+| 设置 | JSON 配置 | 语义 |
+|---|---|---|
+| 合计字段 | `totalLine:[字段ID]` | 数字、金额、运算控件；多列用数组 |
+| 过滤已选数据 | `duplicatedField:[字段ID]` | 同一明细列选择时过滤其他行已选对象；开放关联 EBuilder 和自定义关联浏览 |
+| 批量添加 | `batchAdd:{isOpen,fields}` | 字段 ID 数组，也可用 `{fieldId,name}`；命令从真实字段补名称 |
+| 合并显示 | `mergedFields:[字段ID]` | 选择要合并显示的字段 |
+| 分组 | `groupConfig:{enableGroup,groups}` | 多个规则，每组只能选择一个合计字段 |
+| 排序 | `sortConfig:{enableSort,sorts}` | 多个规则，数组顺序保留 |
+| 搜索 | `searchConfig:{enabled,quickSearchFields}` | 快捷搜索字段 ID 数组 |
+| 按钮 | `buttonConfig:{buttons:[按钮补丁]}` | 按按钮 ID 部分更新，保留其他按钮、顺序及属性 |
+
+未指定的配置块保留。指定块内的开关或字段列表只修改给出的项；字段数组、分组规则数组、排序规则数组整体替换。增删一条规则先读取原列表，再提交完整新列表。所有 JSON 布尔值必须是 true/false，不能用字符串。
+
+合计字段对应类型 `Number/NumberComponent`、`Money`、`Calculation`；不把任意带公式的文本字段当成运算控件。`duplicatedField` 不等于字段唯一性校验，也不承诺阻止接口或导入产生重复数据。其他关联浏览类型未开放时会报错，不应换成普通文本绕过限制。
+
+批量添加字段允许多种类型，不局限人员或选项。`batchAdd.relateId` 当前只支持空字符串；省略时保留现值，非空来源不猜测。开启时需至少一个字段。
+
+以下是选字段类设置的完整输入示例，保存为 JSON 文件后交给 `--config @文件路径`。占位名称须替换为 get 返回的真实字段 ID，不能把字段名称直接写进 ID 数组：
+
+```json
+{
+  "duplicatedField":["关联记录字段ID","自定义关联浏览字段ID"],
+  "mergedFields":["分类字段ID","名称字段ID"],
+  "batchAdd":{"isOpen":true,"fields":["人员字段ID","分类字段ID","数量字段ID"]},
+  "searchConfig":{"enabled":true,"quickSearchFields":["名称字段ID","人员字段ID"]}
+}
+```
+
+`fields` 的字符串数组是 CLI 输入简写，保存时转成 `[{fieldId,name}]`；其他示例中的字段 ID 数组直接保存。搜索开关为 enabled，批量添加开关为 isOpen，分组和排序分别为 enableGroup、enableSort，不能混用。
+
+## 分组与排序
+
+```json
+{
+  "totalLine":["数量字段ID"],
+  "groupConfig":{"enableGroup":true,"groups":[
+    {"name":"按分类","dimension":"分类字段ID","type":"value","order":"asc","collapsed":false,"total":"数量字段ID"},
+    {"name":"按备注是否为空","dimension":"备注字段ID","type":"empty","order":"desc","collapsed":true,"total":"数量字段ID"}
+  ]},
+  "sortConfig":{"enableSort":true,"sorts":[
+    {"name":"数量优先","dimension":"数量字段ID","order":"desc","orderBy":"content"},
+    {"name":"名称次序","dimension":"名称字段ID","order":"asc","orderBy":"content"}
+  ]}
+}
+```
+
+分组规则：`name` 名称，`dimension` 分组字段 ID，`type:value` 按实际值、`type:empty` 按是否为空，`order:asc/desc` 升序／降序，`collapsed` 默认折叠，`total` 单个合计字段 ID。不要给 total 传数组。多规则按原顺序提交；页面上的层级与组合效果需要按业务数据检查，不自行将它解释成多个独立统计报表。
+
+排序规则：名称、字段、方向，`orderBy` 只开放 `content`，省略时补该值。每一组内的规则名称不能空或重复。
+
+分组的 total 可以省略或传空字符串表示不选合计字段；有值时只能是一个本明细数值字段 ID。规则内不支持只传名称来修改局部字段，需要提交该规则的完整结构。
+
+## 表操作按钮和行操作按钮
+
+先 `get` 读取 `settings.buttonConfig.buttons`；只修改其中唯一存在的 ID。原生布局没有返回按钮配置时，CLI 不造一份固定模板；需补充该布局按钮初始化协议。`type:top` 表操作、`type:row` 行操作是原生类别，不作为补丁随意修改。
+
+| 表操作名称 | ID | 表操作名称 | ID |
+|---|---|---|---|
+| 添加 | `add` | 批量删除 | `batchDel` |
+| 批量复制 | `batchCopy` | 批量编辑 | `batchEdit` |
+| 批量添加 | `batchAdd` | 批量下载 | `batchDownload` |
+| 从票夹选择 | `invoiceSelect` | 上传发票添加 | `invoiceUpload` |
+| 发票手动录入 | `invoiceInput` | 导入 | `import` |
+| 导出 | `export` | 设置显示列 | `customColumns` |
+| 编辑 | `editSwitch` | 最大化 | `maximize` |
+| 收起／展开 | `collapse` | 收起／展开子明细 | `collapseAllSub` |
+
+| 行操作名称 | ID |
+|---|---|
+| 删除 | `delete` |
+| 复制 | `copy` |
+| 插入 | `insert` |
+| 上移 | `moveUp` |
+| 下移 | `moveDown` |
+| 弹出编辑 | `edit` |
+| 关联明细 | `subView` |
+
+```json
+{"buttonConfig":{"buttons":[
+  {"id":"add","enabled":true,"title":"添加记录","mode":"both","position":"caption",
+   "icon":{"path":"#icon-add-to01"},
+   "style":{"color":"#2255aa","fillType":"backgroundColor","backgroundColor":"#eaf2ff"}},
+  {"id":"delete","enabled":false}
+]}}
+```
+
+| 属性 | 码表／写法 |
+|---|---|
+| 启用／名称 | `enabled:boolean`、`title:string` |
+| 展示方式 | `mode:icon` 仅图标、`text` 仅文字、`both` 图标加文字 |
+| 表按钮位置 | `top` 默认、`header` 表头、`caption` 表格上方、`footer` 表格下方、`bottom` 底部居中 |
+| 行按钮位置 | `row`；不能套用表按钮的五种位置 |
+| 文字颜色 | `style.color` |
+| 填充方式 | `style.fillType:none/backgroundColor/borderColor` |
+| 背景／边框色 | `style.backgroundColor`／`style.borderColor` |
+| 图标 | `icon.path` 使用平台图标引用，`icon.style` 与按钮 style 分开 |
+
+修改 style 或 icon 时会合并已有子属性；取消背景用 `fillType:none`，不必清掉其他存储颜色。按钮补丁不接受未知 ID，也不允许改类别或 isSystem。票夹、发票、下载、子明细按钮还依赖相应业务能力；按钮 enabled 不覆盖 allowAdd/allowCopy/allowEdit/allowDelete 或服务端权限。`showInReadOnly`、展开标题和展开图标等原生属性保留，本入口暂不提供编辑参数。
+
+按钮名称不能为空；按钮颜色使用十六进制颜色字符串（例如 #2255aa）、transparent 或空字符串，当前不接受 rgb() 或颜色名称。icon.style 可使用 bgColor、color、fillType、borderColor、backgroundColor；不要把文字色写进图标颜色来代替 style.color。
+
+## 删除、关闭与恢复
+
+```json
+{
+  "totalLine":[],"duplicatedField":[],"mergedFields":[],
+  "batchAdd":{"isOpen":false,"fields":[]},
+  "groupConfig":{"enableGroup":false,"groups":[]},
+  "sortConfig":{"enableSort":false,"sorts":[]},
+  "searchConfig":{"enabled":false,"quickSearchFields":[]}
+}
+```
+
+清空分组规则但保留开启状态可传 `groupConfig:{"enableGroup":true,"groups":[]}`。只关开关而省略列表会保留已有规则。批量添加删除某字段用剩余字段列表。按钮关闭用 `enabled:false`；空按钮补丁数组表示不修改任何按钮，不是删除全部按钮。恢复时重新提交所需配置。
+
+运行检查包括合计值与小数精度、分组空值及默认折叠、多级排序的先后、快捷搜索、重复对象是否从弹窗候选中过滤，以及按钮与权限的组合效果。PC／移动端分别检查；配置写入和独立回读不代替这些运行检查。

package/skill-docs/references/form/layout/detail-settings.md

@@ -0,0 +1,106 @@
+# 明细表布局属性、行权限和操作者过滤
+
+这里设置整张明细表的布局组件。子字段的只读、必填等属性另走字段布局设置；明细定义和二级明细关系见 `../guide-form-sub-detail.md`。搜索词：显示、编辑、必填行数、允许新增、复制、修改、删除、根据操作者过滤。
+
+## 定位与命令
+
+EB 表单用 objId，原生工作流程表单用 formId 并传 `--module workflow`。两者均通过以下入口操作 FLOW 流式或 EXCEL 表格式布局：
+
+```bash
+e10-cli form layout detail get <objId> <subFormId> --view-id <布局ID>
+e10-cli form layout detail get <formId> <subFormId> --module workflow --view-id <布局ID>
+e10-cli form layout detail set <objId> <subFormId> --view-id <布局ID> --config @detail-settings.json
+e10-cli form layout detail set <objId> <subFormId> --view-id <布局ID> --config @detail-settings.json --apply
+```
+
+`get` 返回实际组件、页面、属性、可用于过滤的明细字段、各类型来源码及当前环境组织维度。`set` 默认只预览，`--apply` 保存并独立回读；未指定项保留。`--terminal PC|MOBILE` 指定终端，默认 PC；PC 和移动端分别维护。EB 查看布局需要时使用 `--target-kind view`；EB 直接传 formId 时加 `--id-type form`。不要凭表单名称判断模块，也不要把子表 ID 当作布局组件 ID。
+
+新建表单或追加明细后，先让明细进入目标布局，取得真实布局和子表 ID，再运行本命令。建后修改使用相同入口，不重建布局。新建、追加与修改不是三套属性协议。
+
+| 表单与布局 | 调用归属 |
+|---|---|
+| EB 流式 FLOW | objId + 布局 ID，module 默认 ebuilderform |
+| EB 表格式 EXCEL | 同上；不重排网格 |
+| 原生工作流程流式 FLOW | formId + 布局 ID，module 为 workflow |
+| 原生工作流程表格式 EXCEL | 同上；不重排网格 |
+
+“查看布局”与“表格式／流式”是不同维度；同一个名称的 PC、移动布局也不是同一目标。布局 ID 取 layout describe 返回的 multipleLayoutId，子表 ID 取明细定义或查询返回的 subFormId；页面 pageId、组件 componentId 均不能替代这两个参数。新建或追加完成后仍需单独执行 detail set，不会自动套用测试或默认高级配置。
+
+## 属性与联动
+
+| JSON 属性 | 页面含义 | 类型 |
+|---|---|---|
+| `display` | 显示 | boolean |
+| `readOnly` | 编辑的反向值：false 可编辑，true 只读 | boolean |
+| `required` | 必填 | boolean |
+| `requiredRows` | 必填行数 | 正整数 |
+| `hideDescribe` | 隐藏描述 | boolean |
+| `isHideTitle` | 隐藏标题 | boolean |
+| `allowAdd` | 允许新增明细行 | boolean |
+| `allowCopy` | 允许复制明细行 | boolean |
+| `allowEdit` | 允许修改已有明细 | boolean |
+| `allowDelete` | 允许删除已有明细 | boolean |
+
+开启编辑（`readOnly:false`）同时开启显示。开启必填时同时开启显示、编辑，且必须显式提供 `requiredRows`。设置项互相冲突时命令报错。隐藏时明确传 `display:false,readOnly:true,required:false`；只读时明确关闭必填。不推断设计器取消勾选的自动联动。`required:false` 不清除已存行数；再次开启必填仍需传行数。
+
+```json
+{"required":true,"requiredRows":2,"allowAdd":true,"allowCopy":false,"allowEdit":true,"allowDelete":false}
+```
+
+整体可编辑与已有行允许修改是两项设置；子字段本身还可能只读。行操作开关不替代服务端权限。操作效果应在新建、查看或编辑的对应场景检查。
+
+## 根据操作者过滤
+
+左侧只支持目标明细内的人员选择（Employee）、部门选择（Department）、分部选择（Subcompany，组件类型也可能写为 SubCompany）。不接受主表、其他明细、普通文本或其他浏览类型。先 `get` 读取候选字段与维度，再设置：
+
+```json
+{"filterCondition":{"relation":"or","condition":[
+  {"fieldId":"明细人员字段ID","operate":"contain","value":"self","dimension":""},
+  {"fieldId":"明细部门字段ID","operate":"contain","value":"self_department","dimension":"组织维度ID"}
+]}}
+```
+
+`relation` 为 `and`（全部满足）或 `or`（任一满足），`condition` 是平铺非空数组，不是任意嵌套树。`set` 中指定 `filterCondition` 会整体替换这一组过滤，省略则保留；增删一行时先读取、合并后完整提交该组。当前不开放空条件清除，空对象、null 和空数组均不能作为未经定义的清空协议。
+
+| 操作符 | 码值 |
+|---|---|
+| 包含 | `contain` |
+| 不包含 | `notContain` |
+| 属于 | `belong` |
+| 不属于 | `notBelong` |
+
+这些是操作者过滤自身的码表，与关联浏览数据范围的 aggregate 等码值不同。来源由左侧字段类型决定：
+
+| 类型 | 来源 | value |
+|---|---|---|
+| 人员 | 本人 | `self` |
+| 人员 | 直接下属 | `direct_subordinates` |
+| 人员 | 本人及直接下属 | `self_and_direct_subordinates` |
+| 人员 | 所有下属 | `all_subordinates` |
+| 人员 | 本人及所有下属 | `self_and_all_subordinates` |
+| 人员 | 直接上级 | `direct_superior` |
+| 人员 | 本人或直接上级 | `self_or_direct_superior` |
+| 人员 | 所有上级 | `all_superior` |
+| 人员 | 同分部人员 | `same_div` |
+| 部门 | 本部门 | `self_department` |
+| 部门 | 上级部门 | `org_allSuper_department` |
+| 部门 | 本部门或上级部门 | `self_or_org_allSuper_department` |
+| 部门 | 本部门及上级部门 | `self_and_org_allSuper_department` |
+| 部门 | 下级部门 | `org_all_child_department` |
+| 部门 | 本部门或下级部门 | `self_or_org_all_child_department` |
+| 部门 | 本部门及下级部门 | `self_and_org_all_child_department` |
+| 分部 | 本分部 | `self_subcompany` |
+| 分部 | 上级分部 | `org_allSuper_subcompany` |
+| 分部 | 本分部或上级分部 | `self_or_org_allSuper_subcompany` |
+| 分部 | 本分部及上级分部 | `self_and_org_allSuper_subcompany` |
+| 分部 | 下级分部 | `org_all_child_subcompany` |
+| 分部 | 本分部或下级分部 | `self_or_org_all_child_subcompany` |
+| 分部 | 本分部及下级分部 | `self_and_org_all_child_subcompany` |
+
+`self` 的 `dimension` 使用空字符串；其他来源使用当前环境返回的组织维度 ID。行政组织通常为 `1`，配置时以查询结果为准。不要把字段的 currentLevel 当作过滤维度。包含／属于与“或／及”来源含义分别由平台处理，不自行互换。
+
+## 范围与检查
+
+命令保存后核对整组明细设置，并比较其他字段及页面结构；平台返回成功但回读不一致仍报错。预览、配置回读和实际运行效果分别检查。过滤影响明细行展示，不能当作数据权限；已有行的修改、删除及复制行为在对应运行入口检查。
+
+合计、过滤已选、批量添加、合并显示、分组、按钮、排序和搜索见[明细表高级扩展](detail-advanced.md)，仍使用同一命令。它们与 JSSDK 的运行时明细操作分别维护。

package/skill-docs/references/form/layout/layout-overview.md

@@ -20,6 +20,8 @@
 | 复制布局、指定新建／显示／编辑用途、删除布局 | 按视图布局 ID 操作并回读结果 | [视图与布局管理](management.md) |
 | 给流程表单新增布局，或让某个流程节点使用独立布局 | 先管理表单布局，再按节点和终端绑定 | [流程表单与节点布局](workflow-layout.md) |
 | 看清字段、分组、明细及网格位置 | `form layout describe`；需要完整原生底稿时用 `read --raw` 或 `document export` | [布局查询与局部编辑](inspect-edit.md) |
+| 明细表整体显示／编辑／必填、行数、行操作权限及操作者过滤 | `form layout detail get/set`；EB 与工作流程、流式与表格式共用入口 | [明细表设置](detail-settings.md) |
+| 明细合计、过滤已选、批量添加、合并、分组、按钮、排序和搜索 | `form layout detail get/set` 的高级配置块 | [明细高级扩展](detail-advanced.md) |
 | 改少量表格式行高、列宽、已有单元格样式或同网格字段位置 | `layout diff` 预览，随后 `layout edit` 应用 | [布局查询与局部编辑](inspect-edit.md) |
 | 同时修改多个区域、组件、合并关系、页面样式等完整布局内容 | `layout document export` → 编辑草稿 → `diff` → `apply` | [完整布局文档编辑](document.md) |
 | 根据当前字段重建布局，或将样式模板应用到实际表单 | `layout init-reviewed` 先生成计划，再按同一配置执行 | [初始化与模板应用](initialization.md)、[模板总览](template/template-guide.md) |