weaver-e10-builder 1.6.15 → 1.6.16

package/skill-docs/references/report/report-help-guide.md

@@ -1,304 +1,304 @@
-# E-Builder 报表功能帮助指南（精简版）
-
-> **冷启动禁止通读**：见 `api-report-build-fast-path.md`。仅帮助手册问答时按需打开。
-> 本文档基于 e-builder 报表功能帮助文档整理，保留核心功能说明和配置要点。
-
-## 一、功能概述
-
-e-Builder 可视化报表功能帮助用户完成各种常见汇总报表的设计、展现和导出。基于浏览器所见即所得地快速完成报表制作，无需安装插件。
-
-核心能力：
-- 拖拽绑定字段方式制作分组汇总表或交叉表
-- 支持 Excel 运算公式
-- 支持多数据集关联
-- 支持条件格式、查询条件、填报字段
-- 支持主题样式、打印设置、分页设置
-
-## 二、报表设计器布局
-
-三栏布局：
-- **左侧**：数据集添加展示区，支持添加多个数据集
-- **中间**：设计展示区（SpreadJS 电子表格引擎）
-- **右侧**：单元格基本信息设置区
-
-## 三、数据集管理
-
-### 3.1 数据集类型
-
-| 类型 | 说明 |
-|------|------|
-| e-builder | e-builder 表单数据 |
-| 数据加工 | SQL 视图等加工数据 |
-| 外部数据源 | 外部数据库数据 |
-| 业务模块 | 系统业务模块数据 |
-| 数据集 | 已有数据集 |
-
-### 3.2 数据集核心功能
-
-- 数据获取与整合：连接多种数据源
-- 数据处理与转换：去重、汇总计算
-- 数据聚合和分组：分组聚合统计
-- 数据安全控制：基于人员的数据访问权限
-- 性能优化：数据缓存、查询优化
-
-### 3.3 数据集操作
-
-- **添加**：左上角"+"按钮，支持多选
-- **预览**：查看数据（展示10条）
-- **筛选**：支持 or/and 组合筛选
-- **聚合**：提前分组汇总
-- **排序**：多字段排序，前面的优先级高
-- **替换**：快速替换数据集和字段
-- **删除**：需先移除报表中引用的字段
-
-## 四、单元格设置
-
-### 4.0 事件 Tab（PC/H5 链接与传参）
-
-> **完整规则**：`event-hreflink-guide.md`（帮助手册 §传参 + 源码占位符）。
-
-| 配置项 | 说明 |
-|--------|------|
-| PC链接地址 | 落库 `pcHreflink` |
-| H5链接地址 | 落库 `h5Hreflink`（移动端优先） |
-| 打开方式 | **弹出页**=`blank`（默认）· **当前页**=`self` · **执行js代码**=`jsscript` |
-
-**传单元格值**（手册）：支持当前格值、父格值、父格的父格；链接中写 `{L4}` / `{A1}`，或如 `/sp/ebdfpage/list/xxx?ry=B5&kssj=E3`。
-**传查询条件值**：写 `{searchfield001}`（与条件 `asNameIndex` 对应）；区间可用 `_start`/`_end`。
-**超链接文本格**：左父格须指向提供 `{坐标}` 的数据格（见自检指南）。
-
-CLI：`e10-cli report validate href --map "弹出页"` / `--file cell.json`
-
-### 4.1 单元格类型
-
-| 类型 | 说明 |
-|------|------|
-| 文本字段 | 自定义文本内容 |
-| 数据字段 | 数据集选取的字段 |
-| 公式字段 | 公式计算 |
-| 序号字段 | 自动生成序号 |
-| 全选字段 | 全选框字段 |
-| 数据更新时间字段 | ETL 数据更新时间 |
-| 控件字段 | 多级填报字段 |
-
-### 4.2 扩展方向
-
-- **纵向扩展**：从上至下，不同单元格展示
-- **横向扩展**：从左至右，不同单元格展示
-- **不扩展**：所有数据在一个单元格
-
-### 4.3 显示方式
-
-- **分组**：相同数据合并为一组
-- **排列**：逐条排列展示
-- **汇总**：求和/最大值/最小值/平均数/个数/去重个数
-- **树形**：上下级层级展示
-
-### 4.4 父格设置
-
-- **左父格**：纵向扩展时，其他单元格以此单元格为基准纵向扩展
-- **上父格**：横向扩展时，其他单元格以此单元格为基准横向扩展
-- 左父格和上父格一起设置则交叉扩展
-
-注意事项：
-1. 父格设置不当会导致数据错乱或重复
-2. 复杂的父子关系可能影响报表性能
-3. 注意父子格扩展方向的协调一致
-
-### 4.5 分组方式
-
-日期字段分组方式：年份、年月、月份、年月日
-
-### 4.6 字段格式
-
-支持格式：常规、数值、货币、会计专用、短日期、长日期、时间、百分比、分数、科学计数法、文本
-
-> 注意：数值类型字段未设置格式时默认为"常规"，导出 excel 会被识别为文本导致公式计算为 0。参与计算的单元格需设置为数值格式。
-
-## 五、字段转换
-
-| 转换类型 | 说明 |
-|----------|------|
-| 人员 | 显示人员卡片，可点击查看 |
-| 部门 | 超链接形式，可点击查看部门详情 |
-| Checkbox | 转换为选择框，默认全选 |
-| 选择框 | id 值映射显示名称 |
-| 颜色选择框 | 选项值映射颜色 |
-| 分值图标 | 五星数据展示 |
-| 斜线文字 | 多维交叉表头（最多3个文本） |
-| 关联类型 | 人力/项目/任务/文档/流程/日程/表单/CRM/报告/绩效 |
-| 图片 | 附件/图片字段转换（仅 eb 表单） |
-| HTML | 富文本/标签值 HTML 转换 |
-| 前后缀 | 字段值前后拼接 |
-| 条码/二维码 | 数值字段转换为条码/二维码 |
-
-## 六、筛选设置
-
-### 6.1 父格筛选
-
-当单元格字段与其父格字段不属于同一数据集时，通过父格筛选关联数据集。
-
-- **左父格筛选**：当前单元格数据集与左父格数据集的筛选关系
-- **上父格筛选**：当前单元格数据集与上父格数据集的筛选关系
-- **从属关系（subordination）**：与左父格筛选配套，VLOOKUP 式字段映射
-- **字段引用格式**：fieldKey = `{dataSetId}.{sourceId}.{fieldName}`；`id` 必须等于 `currentField`
-
-详见 `cross-dataset-filter-guide.md`。
-
-### 6.2 自定义筛选
-
-当前单元格数据集的自定义筛选条件，支持多个 and/or 组合。配置时 `currentField`/`id` 用 fieldKey，type 用平台枚举。
-
-### 6.3 结果筛选
-
-- 前多少个 / 后多少个
-- 奇数 / 偶数
-- 特定：指定条数索引，如 "1,3" 或 "3-16,"
-
-## 七、条件格式
-
-### 7.1 突出显示
-
-支持条件：大于、小于、等于、介于、文本包含、发生日期、重复值
-
-可设置：字体、字号、字形、背景色、字体颜色
-
-### 7.2 数据条
-
-渐变填充 / 实心填充，最大值填满单元格
-
-### 7.3 图标集
-
-4类图标：方向、形状、标记、等级
-
-### 7.4 清除规则
-
-可清除所选单元格规则或整个工作表规则
-
-## 八、高级功能
-
-### 8.1 冻结单元格
-
-点击单元格设置冻结，冻结该单元格左侧和上方区域。
-
-### 8.2 解析优化
-
-- **行式加载**：列表展示时优化解析速度（仅单数据集简单列表）
-- **数据预聚合**：默认开启，按分组聚合逻辑解析
-
-### 8.3 分页设置
-
-- 默认每页200条，最大1000条（私有化260201基线后最大2000条）
-- 动态 Sheet 页：按字段值分不同 Sheet 页展示
-
-### 8.4 打印设置
-
-- 打印区域：起始行/列/结束行/列
-- 打印重复区域：表头重复
-- 打印网格线/外框线
-- 所有行/列打印在一页
-- 打印顺序：自动/先行后列/先列后行
-- 页边距/页眉页脚/纸张大小方向
-
-### 8.5 报表分栏
-
-- 按行/列数分栏：每N行/列自动为一栏
-- 按栏数分栏：整体分为N栏
-- 分栏模式：垂直/水平/卡片
-- 复制标题或表头
-
-### 8.6 按钮控制
-
-支持隐藏预览页面按钮，支持权限控制
-
-### 8.7 启用编辑/工具栏
-
-- 启用编辑：预览页面可双击编辑数据
-- 工具栏：调整字体样式、插入公式、设置打印
-
-## 九、公式功能
-
-### 9.1 公式分类
-
-| 分类 | 常用公式 |
-|------|----------|
-| 文本 | LEFT, RIGHT, MID, LEN, CONCAT, UPPER, LOWER |
-| 日期和时间 | YEAR, MONTH, DAY, DATE, DAYS, DATEDIF |
-| 数学 | SUM, AVERAGE, COUNT, MAX, MIN, ABS, ROUND |
-| 逻辑计算 | IF, IFERROR, AND, OR, NOT |
-| 信息 | ISERROR, ISBLANK, ISNUMBER |
-| 组合公式 | 多公式组合 |
-
-### 9.2 使用方式
-
-- 在单元格直接输入 `=sum` 联想公式
-- 公式 tab 选取公式插入
-
-### 9.3 注意事项
-
-- 求和字段需按特定父格分组时，公式资源也需指定自定义父格
-- iferror 包裹避免错误值导致计算失败
-- DAYS 函数结束日期在前，开始日期在后
-
-## 十、填报字段
-
-### 10.1 字段类型
-
-单行文本、多行文本、整数、浮点数、日期、人力资源、部门、分部、关联浏览、下拉框、check 框
-
-### 10.2 显示方式
-
-| 显示方式 | 适用字段类型 |
-|----------|-------------|
-| 输入框 | 单行文本、多行文本、整数、浮点数 |
-| 关联浏览 | 日期、人力资源、部门、分部、关联浏览 |
-| 选择框 | 下拉框 |
-| check框 | check 框 |
-
-### 10.3 关键属性
-
-- 控件名称：必填，可自定义
-- 表字段名：自动生成字母缩写，只读
-- 数据集名称：报表名+Sheet页名，只读
-- 数据库名：edc_uf_tb 开头，保存后生成
-- 字段属性：只读/编辑/必填
-- 显示字段：默认开启，关闭后不展示
-
-## 十一、数据分析
-
-- 默认分析页：开启数据分析后自动开启
-- 引用已有页面：选取有权限的 e-builder 页面
-- 新建分析：可新建多个分析，每个支持添加多个图表
-- 参数配置：自定义传参或系统参数
-- 展示宽度：像素或百分比，默认 280px
-- 打开方式：仅支持右侧滑出
-
-## 十二、版本管理
-
-- 存为新版本：保存当前配置为新版本
-- 历史版本：查看、预览、还原
-- 版本命名：报表名称-{date}-{time}，支持自定义
-
-## 十三、报表快速构建
-
-> **API / CLI（列表页新建）**：见 **`report-create-modes-guide.md`** — `e10-cli report create quick` · `quicklyParam`。
-
-### 13.1 列表式快速构建
-
-入口：后台管理中心 -> 报表 -> **新建报表** -> **快速构建-列表式**
-
-- 选取数据源（支持多选）
-- 设置显示字段（支持搜索）
-- 主题设置
-- 基础属性：列名称、列宽、对齐方式、分组、隐藏列、冻结单元格、自动换行
-- 落库：`POST baseInfo` + `quicklyParam`（非设计器手工拖格）
-
-### 13.2 报表设计页快速构建
-
-入口：报表设计器 -> 添加数据集后 -> 更多按钮
-
-生成简单列表式报表，默认开启行式加载。载荷为设计保存时的 `quicklyParamList`（与列表页新建 `quicklyParam` 不同入口）。
-
-### 13.3 模版创建（同对话框另一卡片）
-
-入口：新建报表 -> **模版创建** → `GET getReportModels` → `POST baseInfo` 且 `reportModel={模板ID}`。详见 `report-create-modes-guide.md`。
+# E-Builder 报表功能帮助指南（精简版）
+
+> **冷启动禁止通读**：见 `api-report-build-fast-path.md`。仅帮助手册问答时按需打开。
+> 本文档基于 e-builder 报表功能帮助文档整理，保留核心功能说明和配置要点。
+
+## 一、功能概述
+
+e-Builder 可视化报表功能帮助用户完成各种常见汇总报表的设计、展现和导出。基于浏览器所见即所得地快速完成报表制作，无需安装插件。
+
+核心能力：
+- 拖拽绑定字段方式制作分组汇总表或交叉表
+- 支持 Excel 运算公式
+- 支持多数据集关联
+- 支持条件格式、查询条件、填报字段
+- 支持主题样式、打印设置、分页设置
+
+## 二、报表设计器布局
+
+三栏布局：
+- **左侧**：数据集添加展示区，支持添加多个数据集
+- **中间**：设计展示区（SpreadJS 电子表格引擎）
+- **右侧**：单元格基本信息设置区
+
+## 三、数据集管理
+
+### 3.1 数据集类型
+
+| 类型 | 说明 |
+|------|------|
+| e-builder | e-builder 表单数据 |
+| 数据加工 | SQL 视图等加工数据 |
+| 外部数据源 | 外部数据库数据 |
+| 业务模块 | 系统业务模块数据 |
+| 数据集 | 已有数据集 |
+
+### 3.2 数据集核心功能
+
+- 数据获取与整合：连接多种数据源
+- 数据处理与转换：去重、汇总计算
+- 数据聚合和分组：分组聚合统计
+- 数据安全控制：基于人员的数据访问权限
+- 性能优化：数据缓存、查询优化
+
+### 3.3 数据集操作
+
+- **添加**：左上角"+"按钮，支持多选
+- **预览**：查看数据（展示10条）
+- **筛选**：支持 or/and 组合筛选
+- **聚合**：提前分组汇总
+- **排序**：多字段排序，前面的优先级高
+- **替换**：快速替换数据集和字段
+- **删除**：需先移除报表中引用的字段
+
+## 四、单元格设置
+
+### 4.0 事件 Tab（PC/H5 链接与传参）
+
+> **完整规则**：`event-hreflink-guide.md`（帮助手册 §传参 + 源码占位符）。
+
+| 配置项 | 说明 |
+|--------|------|
+| PC链接地址 | 落库 `pcHreflink` |
+| H5链接地址 | 落库 `h5Hreflink`（移动端优先） |
+| 打开方式 | **弹出页**=`blank`（默认）· **当前页**=`self` · **执行js代码**=`jsscript` |
+
+**传单元格值**（手册）：支持当前格值、父格值、父格的父格；链接中写 `{L4}` / `{A1}`，或如 `/sp/ebdfpage/list/xxx?ry=B5&kssj=E3`。
+**传查询条件值**：写 `{searchfield001}`（与条件 `asNameIndex` 对应）；区间可用 `_start`/`_end`。
+**超链接文本格**：左父格须指向提供 `{坐标}` 的数据格（见自检指南）。
+
+CLI：`e10-cli report validate href --map "弹出页"` / `--file cell.json`
+
+### 4.1 单元格类型
+
+| 类型 | 说明 |
+|------|------|
+| 文本字段 | 自定义文本内容 |
+| 数据字段 | 数据集选取的字段 |
+| 公式字段 | 公式计算 |
+| 序号字段 | 自动生成序号 |
+| 全选字段 | 全选框字段 |
+| 数据更新时间字段 | ETL 数据更新时间 |
+| 控件字段 | 多级填报字段 |
+
+### 4.2 扩展方向
+
+- **纵向扩展**：从上至下，不同单元格展示
+- **横向扩展**：从左至右，不同单元格展示
+- **不扩展**：所有数据在一个单元格
+
+### 4.3 显示方式
+
+- **分组**：相同数据合并为一组
+- **排列**：逐条排列展示
+- **汇总**：求和/最大值/最小值/平均数/个数/去重个数
+- **树形**：上下级层级展示
+
+### 4.4 父格设置
+
+- **左父格**：纵向扩展时，其他单元格以此单元格为基准纵向扩展
+- **上父格**：横向扩展时，其他单元格以此单元格为基准横向扩展
+- 左父格和上父格一起设置则交叉扩展
+
+注意事项：
+1. 父格设置不当会导致数据错乱或重复
+2. 复杂的父子关系可能影响报表性能
+3. 注意父子格扩展方向的协调一致
+
+### 4.5 分组方式
+
+日期字段分组方式：年份、年月、月份、年月日
+
+### 4.6 字段格式
+
+支持格式：常规、数值、货币、会计专用、短日期、长日期、时间、百分比、分数、科学计数法、文本
+
+> 注意：数值类型字段未设置格式时默认为"常规"，导出 excel 会被识别为文本导致公式计算为 0。参与计算的单元格需设置为数值格式。
+
+## 五、字段转换
+
+| 转换类型 | 说明 |
+|----------|------|
+| 人员 | 显示人员卡片，可点击查看 |
+| 部门 | 超链接形式，可点击查看部门详情 |
+| Checkbox | 转换为选择框，默认全选 |
+| 选择框 | id 值映射显示名称 |
+| 颜色选择框 | 选项值映射颜色 |
+| 分值图标 | 五星数据展示 |
+| 斜线文字 | 多维交叉表头（最多3个文本） |
+| 关联类型 | 人力/项目/任务/文档/流程/日程/表单/CRM/报告/绩效 |
+| 图片 | 附件/图片字段转换（仅 eb 表单） |
+| HTML | 富文本/标签值 HTML 转换 |
+| 前后缀 | 字段值前后拼接 |
+| 条码/二维码 | 数值字段转换为条码/二维码 |
+
+## 六、筛选设置
+
+### 6.1 父格筛选
+
+当单元格字段与其父格字段不属于同一数据集时，通过父格筛选关联数据集。
+
+- **左父格筛选**：当前单元格数据集与左父格数据集的筛选关系
+- **上父格筛选**：当前单元格数据集与上父格数据集的筛选关系
+- **从属关系（subordination）**：与左父格筛选配套，VLOOKUP 式字段映射
+- **字段引用格式**：fieldKey = `{dataSetId}.{sourceId}.{fieldName}`；`id` 必须等于 `currentField`
+
+详见 `cross-dataset-filter-guide.md`。
+
+### 6.2 自定义筛选
+
+当前单元格数据集的自定义筛选条件，支持多个 and/or 组合。配置时 `currentField`/`id` 用 fieldKey，type 用平台枚举。
+
+### 6.3 结果筛选
+
+- 前多少个 / 后多少个
+- 奇数 / 偶数
+- 特定：指定条数索引，如 "1,3" 或 "3-16,"
+
+## 七、条件格式
+
+### 7.1 突出显示
+
+支持条件：大于、小于、等于、介于、文本包含、发生日期、重复值
+
+可设置：字体、字号、字形、背景色、字体颜色
+
+### 7.2 数据条
+
+渐变填充 / 实心填充，最大值填满单元格
+
+### 7.3 图标集
+
+4类图标：方向、形状、标记、等级
+
+### 7.4 清除规则
+
+可清除所选单元格规则或整个工作表规则
+
+## 八、高级功能
+
+### 8.1 冻结单元格
+
+点击单元格设置冻结，冻结该单元格左侧和上方区域。
+
+### 8.2 解析优化
+
+- **行式加载**：列表展示时优化解析速度（仅单数据集简单列表）
+- **数据预聚合**：默认开启，按分组聚合逻辑解析
+
+### 8.3 分页设置
+
+- 默认每页200条，最大1000条（私有化260201基线后最大2000条）
+- 动态 Sheet 页：按字段值分不同 Sheet 页展示
+
+### 8.4 打印设置
+
+- 打印区域：起始行/列/结束行/列
+- 打印重复区域：表头重复
+- 打印网格线/外框线
+- 所有行/列打印在一页
+- 打印顺序：自动/先行后列/先列后行
+- 页边距/页眉页脚/纸张大小方向
+
+### 8.5 报表分栏
+
+- 按行/列数分栏：每N行/列自动为一栏
+- 按栏数分栏：整体分为N栏
+- 分栏模式：垂直/水平/卡片
+- 复制标题或表头
+
+### 8.6 按钮控制
+
+支持隐藏预览页面按钮，支持权限控制
+
+### 8.7 启用编辑/工具栏
+
+- 启用编辑：预览页面可双击编辑数据
+- 工具栏：调整字体样式、插入公式、设置打印
+
+## 九、公式功能
+
+### 9.1 公式分类
+
+| 分类 | 常用公式 |
+|------|----------|
+| 文本 | LEFT, RIGHT, MID, LEN, CONCAT, UPPER, LOWER |
+| 日期和时间 | YEAR, MONTH, DAY, DATE, DAYS, DATEDIF |
+| 数学 | SUM, AVERAGE, COUNT, MAX, MIN, ABS, ROUND |
+| 逻辑计算 | IF, IFERROR, AND, OR, NOT |
+| 信息 | ISERROR, ISBLANK, ISNUMBER |
+| 组合公式 | 多公式组合 |
+
+### 9.2 使用方式
+
+- 在单元格直接输入 `=sum` 联想公式
+- 公式 tab 选取公式插入
+
+### 9.3 注意事项
+
+- 求和字段需按特定父格分组时，公式资源也需指定自定义父格
+- iferror 包裹避免错误值导致计算失败
+- DAYS 函数结束日期在前，开始日期在后
+
+## 十、填报字段
+
+### 10.1 字段类型
+
+单行文本、多行文本、整数、浮点数、日期、人力资源、部门、分部、关联浏览、下拉框、check 框
+
+### 10.2 显示方式
+
+| 显示方式 | 适用字段类型 |
+|----------|-------------|
+| 输入框 | 单行文本、多行文本、整数、浮点数 |
+| 关联浏览 | 日期、人力资源、部门、分部、关联浏览 |
+| 选择框 | 下拉框 |
+| check框 | check 框 |
+
+### 10.3 关键属性
+
+- 控件名称：必填，可自定义
+- 表字段名：自动生成字母缩写，只读
+- 数据集名称：报表名+Sheet页名，只读
+- 数据库名：edc_uf_tb 开头，保存后生成
+- 字段属性：只读/编辑/必填
+- 显示字段：默认开启，关闭后不展示
+
+## 十一、数据分析
+
+- 默认分析页：开启数据分析后自动开启
+- 引用已有页面：选取有权限的 e-builder 页面
+- 新建分析：可新建多个分析，每个支持添加多个图表
+- 参数配置：自定义传参或系统参数
+- 展示宽度：像素或百分比，默认 280px
+- 打开方式：仅支持右侧滑出
+
+## 十二、版本管理
+
+- 存为新版本：保存当前配置为新版本
+- 历史版本：查看、预览、还原
+- 版本命名：报表名称-{date}-{time}，支持自定义
+
+## 十三、报表快速构建
+
+> **API / CLI（列表页新建）**：见 **`report-create-modes-guide.md`** — `e10-cli report create quick` · `quicklyParam`。
+
+### 13.1 列表式快速构建
+
+入口：后台管理中心 -> 报表 -> **新建报表** -> **快速构建-列表式**
+
+- 选取数据源（支持多选）
+- 设置显示字段（支持搜索）
+- 主题设置
+- 基础属性：列名称、列宽、对齐方式、分组、隐藏列、冻结单元格、自动换行
+- 落库：`POST baseInfo` + `quicklyParam`（非设计器手工拖格）
+
+### 13.2 报表设计页快速构建
+
+入口：报表设计器 -> 添加数据集后 -> 更多按钮
+
+生成简单列表式报表，默认开启行式加载。载荷为设计保存时的 `quicklyParamList`（与列表页新建 `quicklyParam` 不同入口）。
+
+### 13.3 模版创建（同对话框另一卡片）
+
+入口：新建报表 -> **模版创建** → `GET getReportModels` → `POST baseInfo` 且 `reportModel={模板ID}`。详见 `report-create-modes-guide.md`。