weaver-work-cli 0.1.24 → 0.1.25

package/skills/weaver-e10-builder/references/report/report-building-guide.md

@@ -0,0 +1,511 @@
+# e-Builder 报表搭建实战指导手册
+
+> **冷启动禁止通读**：见 `cold-start-scan-guide.md`。仅需要界面逐步操作指导时再读。
+> **设计器 UI 全景（开始/页面/公式 全菜单 + API 对照）**：见同目录 **`report-designer-feature-map.md`**。
+
+## 文档定位
+
+本手册面向**完全不了解 e-Builder 报表功能配置的用户**和**需要根据需求案例快速生成搭建指导的 AI 助手**。内容基于 e-Builder 报表设计器的真实界面截图（左侧数据集面板、中间 Excel 画布、右侧属性面板、顶部「开始 / 页面 / 公式」菜单），将用户描述的需求或上传的报表截图 / Excel 案例，转化为可直接操作的搭建步骤。
+
+阅读本手册时，请配套参考 `report-knowledge-base.md` 中的核心概念（父格、扩展方向、显示方式等）。
+
+---
+
+## 一、拿到需求后，先回答 5 个问题
+
+用户给出一个需求报表时（文字描述、截图或 Excel 案例），先按以下 5 个问题拆解，再进入具体配置：
+
+| 问题 | 作用 | 示例 |
+|------|------|------|
+| 1. 报表要展示什么数据？ | 确定数据集来源和字段 | 合同签约金额、已付款金额、已付款比例 |
+| 2. 按什么维度分组/展开？ | 确定父格和扩展方向 | 按大区 → 机构 → 团队层级展开 |
+| 3. 需要算什么指标？ | 确定汇总方式和公式 | 金额求和、比例 = 已付款 / 签约金额 |
+| 4. 是否需要筛选？ | 确定查询条件 | 按日期区间、部门、负责人筛选 |
+| 5. 最终展示形态是什么？ | 确定报表类型 | 分组汇总表、交叉表、简单列表 |
+
+**判断报表类型的快速规则**：
+- 只是一条条数据平铺 → 简单列表
+- 按某几个维度分类，每类下面有明细和合计 → 分组报表
+- 行是一个维度、列是另一个维度（如人员 × 月份） → 交叉报表
+- 需要录入数据 → 填报报表
+- 数据按层级树状展开 → 树形报表
+
+---
+
+## 二、e-Builder 报表设计器界面速览
+
+### 2.1 整体布局
+
+设计器分为三大区域：
+
+- **左侧：数据集面板**
+ - 显示已添加的数据集（如「分组报表数据源(内置)」）
+ - 展开可看到字段列表
+ - 右键数据集可执行：自定义名称、数据预览、筛选条件、数据聚合、数据排序、替换数据集、移除
+ - 把字段拖到中间画布即可生成数据单元格
+
+- **中间：报表设计画布**
+ - 类似 Excel 的网格区域
+ - 选中单元格后，右侧属性面板会显示该单元格的属性
+ - 顶部有「开始」「页面」「公式」三个主 Tab
+
+- **右侧：属性面板**
+ - 「单元格」Tab：单元格类型、数据集合、字段、父格、扩展方向、显示方式、分组排序等
+ - 「事件」Tab：配置 PC 链接地址、H5 链接地址、打开方式（弹出页 / 当前页 / 执行 JS 代码）
+ - 「样式」Tab：主题模板、背景色、配色交替方式、文本样式
+
+### 2.2 顶部菜单关键入口
+
+| 入口 | 路径 | 用途 |
+|------|------|------|
+| 保存 / 预览 | 右上角 | 保存报表、预览效果 |
+| 查询设置 | 页面 → 查询设置 | 设置查询条件是「高级搜索」还是「筛选」展示 |
+| 添加查询条件 | 页面 → + 添加查询条件 | 新增筛选字段 |
+| 冻结单元格 | 页面 → 单元格 → 冻结单元格 | 冻结表头 |
+| 打印与分页 | 页面 → 打印与分页 | 设置打印、分页、EXCEL 标签 |
+| 报表展示 | 页面 → 报表展示 | 列排序筛选、子格合并、解析优化、报表分栏、按钮控制、工具栏 |
+| 页面布局 | 页面 → 页面布局 | 显示网格线、行号列头、无限滚动条、数据展开、报表显示位置 |
+| 快照设置 | 页面 → 快照设置 | 生成快照相关配置 |
+| 公式 | 公式 → 插入函数 | 写 Excel 公式 / 逻辑函数 |
+
+### 2.3 右侧「单元格」属性面板关键字段
+
+| 属性 | 含义 | 常用值 |
+|------|------|--------|
+| 单元格类型 | 数据字段 / 文本字段 | 数据字段 = 绑定数据集字段；文本字段 = 自定义文字或公式 |
+| 数据集合 | 选择数据集 | 例如「分组报表数据源(内置)」 |
+| 字段 | 选择具体字段 | 例如「大区」「签约金额」 |
+| 左父格 | 纵向参照的单元格 | 默认 / 无 / 自定义某个单元格 |
+| 上父格 | 横向参照的单元格 | 默认 / 无 / 自定义某个单元格 |
+| 扩展方向 | 数据展开方向 | 纵向扩展 / 横向扩展 / 不扩展 |
+| 显示方式 | 数据展示模式 | 分组 / 排列 / 汇总 / 树形 |
+| 日期分组 | 日期字段按年/年月聚合 | 不设置 / 按年份 / 按年月 |
+| 分组排序 | 分组后排序 | 不排序 / 升序 / 降序 |
+| 筛选 | 父格筛选 / 自定义筛选 | 用于多数据集关联或按条件过滤 |
+
+---
+
+## 三、通用搭建流程（按顺序执行）
+
+### 步骤 1：新建报表并进入设计器
+
+操作路径：
+
+```
+后台管理中心 → e-builder 低代码平台 → EB 应用后台管理 → 报表 → 新建报表 → 进入报表设计器
+```
+
+进入后先**保存一个空报表**，避免后续配置丢失。
+
+### 步骤 2：添加数据集
+
+1. 点击左侧数据集面板上方的「+」或「添加数据集」
+2. 选择数据集类型（e-builder 表单 / 数据加工 / 外部数据源 / 业务模块 / ESB 中心）
+3. 选择具体的数据源后点击确定
+4. （可选）右键数据集 → 数据预览，确认字段和数据
+5. （可选）右键数据集 → 筛选条件 / 数据聚合 / 排序，提前处理数据
+
+> 如果报表需要多个数据源，重复添加即可。多数据集关联通过「父格筛选」实现，详见 `report-knowledge-base.md` 2.1 节。
+
+### 步骤 3：拖拽字段搭建表头与数据行
+
+把左侧字段拖到画布中：
+
+1. **先放维度字段**（如大区、机构、团队、负责人）
+2. **再放指标字段**（如签约金额、已付款金额）
+3. **最后放计算字段**（如已付款比例 = 已付款金额 / 签约金额）
+
+放置后，选中单元格，在右侧「单元格」面板确认：
+
+- 单元格类型 = 数据字段
+- 数据集合 = 正确数据集
+- 字段 = 你拖入的字段
+
+### 步骤 4：配置父格与扩展方向
+
+这是报表搭建最关键的一步。按以下规则设置：
+
+#### 维度字段（如大区、机构、团队）
+
+- **左父格**：默认（通常取左侧相邻单元格）
+- **上父格**：无
+- **扩展方向**：纵向扩展
+- **显示方式**：分组（相同值合并）
+
+#### 指标字段（如签约金额）
+
+- **左父格**：默认
+- **上父格**：无
+- **扩展方向**：纵向扩展
+- **显示方式**：汇总 → 求和
+
+#### 表头 / 标题 / 合计文本
+
+- **左父格**：无
+- **上父格**：无
+- **扩展方向**：不扩展
+
+#### 交叉报表的横向维度
+
+- **左父格**：无
+- **上父格**：无
+- **扩展方向**：横向扩展
+- **显示方式**：分组
+
+> 更复杂的父格规则（如交叉区域、多横向维度、一个 sheet 多报表等）请参考 `report-knowledge-base.md` 第二节和第四节。
+
+### 步骤 5：添加合计行 / 总计行
+
+#### 分组合计（如「大区合计」）
+
+1. 在分组字段下方插入一行
+2. 合并左侧维度列单元格，输入文字「大区合计」
+3. 在指标列输入公式，例如 `=SUM(F5)`（F5 为该组指标字段单元格）
+4. 选中「大区合计」文字单元格：
+ - 左父格 = 自定义为分组字段单元格（如 B5）
+ - 上父格 = 无
+ - 扩展方向 = 不扩展
+5. 选中指标合计单元格：
+ - 左父格 = 自定义为分组字段单元格（如 B5）
+ - 上父格 = 无
+ - 扩展方向 = 不扩展
+
+#### 总计行（报表最底部）
+
+1. 在报表最下方插入一行，输入「合计」
+2. 指标列输入公式，例如 `=SUM(F5)` 或 `=SUM(指标字段区域)`
+3. 选中「合计」文字单元格和指标合计单元格：
+ - 左父格 = 无
+ - 上父格 = 无
+ - 扩展方向 = 不扩展
+
+### 步骤 6：添加查询条件
+
+#### 6.1 先设置查询条件的展示形式
+
+入口：**页面 → 查询设置**
+
+弹窗中可配置：
+
+- **高级搜索显示形式**：默认样式 / 展开条件
+ - 默认样式：预览页右上角显示搜索图标，点击后展开筛选条件
+ - 展开条件：预览页顶部直接展示搜索栏
+- **启用所有条件任一条件切换**：开启后查询条件之间从「and」变成「or」
+- **筛选下拉框无字段时不显示**：仅对筛选生效
+- **仅在查询时获取数据**：减少初始加载
+- **手动触发筛选**：仅对筛选生效，点击查询按钮后才刷新数据
+
+配置完成后点击「保存」。
+
+#### 6.2 添加具体查询条件
+
+入口：**页面 → + 添加查询条件**
+
+在弹窗中填写：
+
+| 字段 | 说明 |
+|------|------|
+| 显示方式 | **必填**：高级搜索（默认）/ 筛选；对应 `showWhere`，不可不选 | `query-condition-api-guide.md` §2.1 |
+| 显示名称 | 查询条件在页面上显示的名字，支持多语言 |
+| 字段类型 | 文本 / 数字 / 日期区间 / 日期 / 下拉框 / 关联 e-builder / 关联类型 / 自定义分类 |
+| 默认值类型 | 常规 / 自定义 |
+| 默认值 | 默认条件值，可引用系统参数 |
+| 快捷搜索 | 开启后作为快捷搜索条件 |
+| 显示位置 | 平铺 / 下拉 |
+| 条件必填 | 开启后筛选条件必填 |
+
+**以「日期区间」为例**：
+
+1. 显示名称填「签约日期」
+2. 字段类型选「日期区间」
+3. 默认值类型选「自定义」，默认值可填 `{thisweek}` 或留空
+4. 显示位置选「平铺」或「下拉」
+5. 点击「添加条件」，在下方的查询条件行中选择：
+ - **选择类型**：默认选 **条件字段**（仅需求明确写 SQL 时才选 SQL）
+ - 数据集 = 对应数据集合
+ - 数据集字段 = 目标字段（fieldKey：`{dataSetId}.{sourceId}.{fieldName}`）
+ - 条件 = 等于 / 区间等（与字段类型匹配）
+6. **日期区间**：设计器「选项」默认全部勾选（全部/今天/本周/本月/…/自定义）；API 写入见下文
+7. 点击「确定」保存
+
+> **API/脚本写入**：见 `query-condition-api-guide.md`。条件字段：`filterType: default`，`conditions` 勿写 `filterType: field`，顶层 `dataSetId`/`name` 为 null，附带 `fieldOptions`。日期区间：`filterParam.dataOptions` 21 项、`selectOptions=[]`、`optionTile={}`。默认值：`defaultValueType: custom` + 系统参数（本月 `{thismonth}`、今天 `{date}`）。
+
+> **重要提示**：日期区间的「自定义」选项（用户可手动选择起止日期）仅在「高级搜索」展示形式下出现；若选择「筛选」展示形式，只显示固定选项（今天、本周、本月等）。
+
+### 步骤 7：美化样式
+
+1. **选中表头行** → 设置背景色、字体加粗、文字居中
+2. **选中数据区域** → 设置数字格式（千分位、小数位、货币符号）
+3. **设置交替行颜色**：页面 → 样式 → 配色交替方式
+4. **设置主题模板**：页面 → 样式 → 主题模板
+5. **调整列宽行高**：右键列号 / 行号 → 设置行高列宽
+
+### 步骤 8：冻结表头
+
+如果报表行数较多，需要冻结表头：
+
+1. 选中**表头下方第一行、第 A 列**（或数据区左上角单元格）作为锚点
+2. 页面 → 单元格 → 冻结单元格
+3. 冻结后，该单元格**上方**的行和**左侧**的列在预览时会固定（不含锚点格本身）
+4. API 落库须同时写：`fixed-cell-tag` Const + `tag.fixed` + `sheet.tag.fixedCell`；详见 `layout-showlocation-freeze-guide.md`（**禁止只写 `frozenRowCount`**）
+
+### 步骤 9：预览与保存
+
+1. 点击右上角「预览」查看效果
+2. 检查数据、分组、合计、查询条件是否正常
+3. 返回设计器调整
+4. 点击「保存」或「存为新版本」
+
+---
+
+## 四、典型场景配置示例
+
+### 场景 1：分组统计年度报表（与大区 / 机构 / 团队结构一致）
+
+这是截图中的示例报表：按大区 → 机构 → 团队展示签约金额、已付款金额、已付款比例，并带大区合计和总计。
+
+#### 数据结构
+
+- 维度：大区、机构、团队、负责人
+- 指标：签约金额、已付款金额
+- 计算：已付款比例 = 已付款金额 / 签约金额
+
+#### 单元格配置
+
+| 单元格 | 内容 | 左父格 | 上父格 | 扩展方向 | 显示方式 |
+|--------|------|--------|--------|----------|----------|
+| B4 | 大区 | 默认 | 无 | 纵向扩展 | 分组 |
+| C4 | 机构 | 默认（B4） | 无 | 纵向扩展 | 分组 |
+| D4 | 团队 | 默认（C4） | 无 | 纵向扩展 | 分组 |
+| E4 | 负责人 | 默认（D4） | 无 | 纵向扩展 | 分组 |
+| F4 | 签约金额 | 默认（E4） | 无 | 纵向扩展 | 汇总-求和 |
+| G4 | 已付款金额 | 默认（E4） | 无 | 纵向扩展 | 汇总-求和 |
+| H4 | 已付款比例 | 默认（E4） | 无 | 纵向扩展 | 不扩展 |
+| B5:E5 合并 | 大区合计 | 自定义 B4 | 无 | 不扩展 | 文本 |
+| F5 | 大区签约金额合计 | 自定义 B4 | 无 | 不扩展 | 不扩展 |
+| G5 | 大区已付款金额合计 | 自定义 B4 | 无 | 不扩展 | 不扩展 |
+| H5 | 大区已付款比例 | 自定义 B4 | 无 | 不扩展 | 公式 `=IFERROR(G5/F5,"-")` |
+| B8:E8 合并 | 合计 | 无 | 无 | 不扩展 | 文本 |
+| F8 | 总计签约金额 | 无 | 无 | 不扩展 | 公式 `=SUM(F4)` |
+| G8 | 总计已付款金额 | 无 | 无 | 不扩展 | 公式 `=SUM(G4)` |
+| H8 | 总计已付款比例 | 无 | 无 | 不扩展 | 公式 `=IFERROR(G8/F8,"-")` |
+
+> 截图中 H4 公式示例为 `=IFERROR(G5/F5,"-")`，说明比例字段通常放在合计行同级，引用同行的汇总值。
+
+### 场景 2：按日期区间筛选签约数据
+
+需求：报表预览时，用户可以选择「签约日期」范围过滤数据。
+
+#### 配置步骤
+
+1. **页面 → 查询设置**
+ - 高级搜索显示形式：选择「默认样式」或「展开条件」
+ - 保存
+2. **页面 → + 添加查询条件**
+ - 显示名称：签约日期
+ - 字段类型：日期区间
+ - 显示位置：平铺
+ - 条件必填：根据需要开启
+ - 点击「添加条件」
+ - 在查询条件行中：
+ - 数据集字段 = 签约日期
+ - 条件类型会自动匹配为日期区间
+ - 点击「确定」
+3. **预览测试**
+ - 点击预览
+ - 若选择「默认样式」，在右上角搜索图标中打开筛选面板
+ - 若选择「展开条件」，筛选栏直接显示在顶部
+ - 选择日期区间后点击查询，确认数据被过滤
+
+> 若用户希望默认显示「本月」或「今天」数据：默认值类型选 **自定义**，填系统参数 `{thismonth}` 或 `{date}`（今天区间写 `["{date}","{date}"]`）。详见 `query-condition-api-guide.md` §五。
+
+### 场景 3：按部门下拉框筛选
+
+需求：用户通过下拉框选择部门，只展示该部门数据。
+
+#### 配置步骤
+
+1. **页面 → + 添加查询条件**
+ - 显示名称：所属部门
+ - 字段类型：下拉框
+ - 默认值类型：常规
+ - 显示位置：平铺
+2. 点击「添加条件」
+ - 数据集字段 = 部门字段
+ - 条件 = 等于
+3. 点击「确定」
+4. 预览时，下拉框会显示部门选项，选择后自动过滤
+
+### 场景 4：交叉报表（人员 × 月份展示金额）
+
+需求：行是人员，列是月份，交叉区域显示金额。
+
+#### 单元格配置
+
+| 单元格 | 内容 | 左父格 | 上父格 | 扩展方向 | 显示方式 |
+|--------|------|--------|--------|----------|----------|
+| B5 | 人员 | 默认 | 无 | 纵向扩展 | 分组 |
+| C5~E5 | 人员相关信息 | 默认（B5） | 无 | 纵向扩展 | 分组/排列 |
+| F3 | 月份 | 无 | 无 | 横向扩展 | 分组（按年月） |
+| F4~H4 | 月份表头文字 | 无 | 自定义 F3 | 不扩展 | 文本 |
+| F5~H5 | 金额 | 自定义 E5 | 自定义 F3 | 纵向扩展 | 汇总-求和 |
+| I5 | 人员小计 | 自定义 E5 | 默认 | 纵向扩展 | 汇总-求和 |
+| F6~H6 | 月份合计 | 无 | 自定义 F3 | 不扩展 | 公式 `=SUM(F5:H5)` |
+
+更详细的交叉表配置请参考 `report-knowledge-base.md` 4.3 节。
+
+---
+
+## 五、如何根据用户上传的截图或 Excel 生成搭建步骤
+
+> **强制规范**：输出「报表需求分析」时，必须同时遵守 `report-requirement-analysis-template.md`——除下列分析框架外，还须交付：**列级配置总表**（字段类型、父格、扩展方向、汇总、父格筛选、自定义筛选）、**数据集过滤表**、**查询条件表**、**≥4 张搭建布局图示**。详见该文档 §一～§九。
+
+当用户上传一个需求报表截图或 Excel 案例时，按以下分析框架输出配置指导：
+
+### 5.1 识别报表结构
+
+从截图 / Excel 中识别：
+
+1. **表头内容**：有哪些列？哪些是维度？哪些是指标？
+2. **分组层级**：是否有合并单元格表示层级？（如大区合并多行）
+3. **合计行**：是否有小计、合计、总计？
+4. **数据方向**：数据是纵向展开还是横向展开？
+5. **特殊元素**：是否有查询条件栏、按钮、图表、交叉表头？
+
+### 5.2 输出配置清单
+
+为每个数据单元格输出（**推荐直接使用 template §二列级配置总表**）：
+
+- 列 / 单元格坐标
+- 绑定字段及 **字段类型**（Text/Select/Employee/Formula…）
+- 左父格 / 行基格
+- 上父格（交叉表需要）
+- 扩展方向
+- 显示方式
+- **汇总方式**（sum / count / distinctcount）
+- **父格筛选**（跨数据集 leftFilterField，无则 `-`）
+- **自定义筛选**（customFilterField 口径）
+- 公式（如有）
+
+另附 **数据集过滤**（queryInfoSave，template §三）与 **查询条件**（saveQueryItem，template §四）专表。
+
+### 5.3 输出操作步骤
+
+按「通用搭建流程」的顺序，给出：
+
+1. 进入设计器的入口路径
+2. 添加哪个数据集
+3. 拖拽哪些字段到哪些单元格
+4. 每个单元格的父格、扩展方向、显示方式设置
+5. 查询条件如何添加
+6. 合计行 / 总计行公式
+7. 样式美化建议
+8. 预览验证要点
+
+### 5.4 示例输出格式
+
+以「按大区统计年度合同金额」为例：
+
+```markdown
+## 搭建步骤
+
+### 1. 进入报表设计器
+后台管理中心 → e-builder 低代码平台 → EB 应用后台管理 → 报表 → 新建报表 → 进入报表设计器
+
+### 2. 添加数据集
+- 点击左侧「+ 添加数据集」
+- 选择「合同数据」数据集
+- 右键 → 数据预览，确认包含字段：大区、签约金额、签约日期
+
+### 3. 拖拽字段
+- B4 拖入「大区」
+- C4 拖入「签约金额」
+
+### 4. 配置单元格属性
+| 单元格 | 字段 | 左父格 | 上父格 | 扩展方向 | 显示方式 |
+|--------|------|--------|--------|----------|----------|
+| B4 | 大区 | 默认 | 无 | 纵向扩展 | 分组 |
+| C4 | 签约金额 | 默认 | 无 | 纵向扩展 | 汇总-求和 |
+| B5 | 合计 | 无 | 无 | 不扩展 | 文本 |
+| C5 | =SUM(C4) | 无 | 无 | 不扩展 | 不扩展 |
+
+### 5. 添加查询条件
+- 页面 → 查询设置 → 高级搜索显示形式：默认样式 → 保存
+- 页面 → + 添加查询条件
+ - 显示名称：签约日期
+ - 字段类型：日期区间
+ - 显示位置：平铺
+ - 添加条件：数据集字段 = 签约日期
+ - 确定
+
+### 6. 预览保存
+- 点击右上角「预览」验证数据
+- 确认无误后保存
+```
+
+---
+
+## 六、常见问题速查
+
+| 现象 | 可能原因 | 解决方法 |
+|------|----------|----------|
+| 预览时数据重复出现 | 维度字段显示方式用了「排列」而非「分组」 | 将维度字段显示方式改为「分组」 |
+| 合计行不显示或数据不对 | 合计行左父格设置错误 | 合计行左父格应自定义为分组字段单元格 |
+| 交叉表数据错位 | 交叉区域字段左父格 / 上父格未自定义 | 参考 `report-knowledge-base.md` 4.3 节重新设置 |
+| 查询条件不生效 | 字段类型与数据集字段格式不匹配 | 检查字段类型和条件设置，日期字段用日期区间/日期类型 |
+| 日期区间没有自定义选项 | 查询条件展示形式为「筛选」 | 改为「高级搜索」展示形式 |
+| 预览页面没有查询条件 | 未添加查询条件或展示形式为「默认样式」 | 点击右上角搜索图标查看，或改为「展开条件」 |
+| 多数据集数据不关联 | 未配置 subordination + leftFilterField，或字段引用非 fieldKey | 见 `cross-dataset-filter-guide.md`：fieldKey 格式 + id=currentField |
+| 筛选下拉空白 | parentField/currentField 用了显示名或裸 field_xxx | 改为 `{dataSetId}.{sourceId}.{fieldName}` |
+| 数字显示为科学计数法 | 单元格数字格式未设置 | 右键 → 设置单元格格式 → 数值，设置小数位和千分位 |
+
+---
+
+## 七、配套文档说明
+
+- `report-knowledge-base.md`：核心概念、报表类型、数据集、查询条件、常见场景的详细说明
+- `report-requirement-analysis-template.md`：**报表需求分析交付规范**（需求分析必做的 8 章节、列级 8 项总表、搭建图示、自检清单）
+测试用例生成：**已删除，不随包分发**
+功能原型图输出：**已删除，不随包分发**
+
+本手册重点解决「**用户给了一个需求，如何一步步把它搭出来**」的问题，强调入口路径、操作顺序和真实界面元素对应。
+
+---
+
+## 八、源码级隐性规则对搭建的影响（基于 weaver-common-edc，文档冲突以代码为准）
+
+> 以下结论来自对 `D:\edc_source\weaver-common-edc` 源码的核查（详见 `report-knowledge-base.md` 第九节），此处给出"搭建时应如何操作"的落地提示。
+
+### 8.1 合计/小计必须手动放置，引擎不自动生成
+- 引擎（`GroupCrossEngine`/`SimpleListEngine`/`CustomEngine`）**不会自动插入合计行**。
+- 要在分组下显示小计：在分组字段旁放一个**显示方式=汇总**的单元格（其聚合值即渲染值）；或在分组行放置 `AnalysisDisplayType.Count` 单元格。
+- 总计：在报表最底部放一个汇总单元格并写 `=SUM(...)` 公式（`COMB_GRAND_TOTAL` 在后端仅转成 `SUM+原串`，算术在前端 SpreadJS 算）。
+- **搭建操作**：合计/总计行左父格需自定义为分组字段（同原手册步骤 5），不要指望系统"自动合计"。
+
+### 8.2 占比、同环比是前端公式，不是后端计算
+- 帮助文档里"占比""增长率"等，在后端只是生成 `IFERROR(...)` / `SUM(...)` 公式串；**具体百分比、同比/环比数值由前端 SpreadJS 计算引擎执行**。
+- **搭建操作**：配置占比列时直接写 Excel 公式（如 `=IFERROR(本期/合计,"-")` 或 `=IF(合计=0,0,本期/合计)`），不要假设后端会预计算出数值；预览时才能看到计算结果。
+- **API / 脚本保存**：设计器输入带 `=`，但持久化 `cellText` **不带**前导 `=`；须设 `countType=count`、`displayType=Group`。详见 `formula-cell-api-guide.md`。
+
+### 8.3 时区：不可配置、仅运行态、仅日期字段
+- 全仓库**没有时区配置项**，写死 `GMT+8`（北京时间）。时区转换只在结果映射阶段、且只对 `isDate()` 日期字段、且字符串为 29 位含 `T` 的 ISO 格式（如 `2018-02-01T15:42:37.000+00:00`）时才发生（UTC→北京 +8）。
+- **设计预览不做 +8 转换，运行预览才做**（代码分支不同）。
+- **搭建操作**：若用户要求"报表按某时区展示"，需指出源码当前**不支持配置时区**；日期字段建议统一存储为 `yyyy-MM-dd HH:mm:ss` 并在查询条件/筛选中保持格式一致（参考帮助文档 6.2 节日期类型格式一致规则）。
+
+### 8.4 多端：列/查询条件默认只给 PC，移动端需显式配置
+- 归属 `BelongAttr`：`PC("0")/MOBILE("1")/PCMOBILE("2")`，**默认 PC**。查询条件、列默认只在 PC 出现。
+- 移动端默认 `ListView`（列表/卡片），交叉表网格由前端按终端决定，后端不禁用。
+- **搭建操作**：若需求含"移动端/企微/小程序也要看"，必须将该列/查询条件的 `belong` 改为 `MOBILE` 或 `PCMOBILE`，否则移动端不渲染；超链接需同时配置移动端链接（`mbhreflink`）。
+
+### 8.5 合法枚举值（配置项下拉必须以这些为准）
+- 单元格类型 `AnalysisCellType`：`Const, Field, Formula, DateTime, AllCheck, SequenceNumber, SystemField, Control, TreeField, DateField`
+- 扩展方向 `AnalysisExpandType`：`NoExpand, Horizontal, Vertical`
+- 显示方式 `AnalysisDisplayType`：`Group, List, Count, Tree`（默认 `Group`）
+- 字段类型 `EtFieldType`：`String, Date, Number, Select, BusinessData`
+- 聚合方式：`SUM, MAX, MIN, AVG, COUNT`（含 `COUNT DISTINCT`）
+- 写入 DB 默认值：`expandType→"NoExpand"`、`cellType→"Const"`、`thumbnail→"NoDisplay"`、`displayType→"Group"`、`textDirection→"FromLeftToRight"`（非法枚举会回退这些默认，不会崩溃）。
+
+### 8.6 保存时的硬性校验（搭建后点保存会触发）
+- **父格循环依赖**：左父格=上父格（同一格）或形成环 → 保存抛异常「存在父格循环依赖或者左、上父格设置相同单元格的情况，请检查！」。**搭建操作**：交叉区域、多横向维度务必按手册 4.3/4.8 节正确设父格，避免左=上同格。
+- **乐观锁**：`designKey` 过期（别人已改过）→ "您当前的数据不是最新的，请重新打开获取最新的数据！"。**搭建操作**：长时间编辑后保存失败，重新打开设计器再保存。
+- **报表名/许可**：重名与许可数量校验在保存事务外（前端防御），后端保存不二次校验；但仍应保证名称唯一。