weaver-e10-builder 1.6.15 → 1.6.16

package/skill-docs/references/report/ai-report-workflow.md

@@ -1,412 +1,412 @@
-# AI 报表生成工作流程
-
-> **冷启动禁止通读**：见 `api-report-build-fast-path.md`。纯搭表走 `api-report-build-fast-path.md`，勿开场读本文。
-
-## 一、整体流程概览
-
-```
-用户输入（文本描述 / 图片效果 / 需求文件）
-        |
-        v
-  1. 需求解析：理解报表类型、数据维度、指标、样式需求
-        |
-        v
-  2. 字段分类：将需求中的字段映射为三类
-     - groupFields（分组/维度字段）
-     - listFields（列表/展示字段）
-     - targetFields（指标/度量字段）
-        |
-        v
-  3. 报表类型判定：根据字段组合判断报表类型
-     - 简单列表（LIST）
-     - 分组表（GROUP）
-     - 交叉表/统计表（COUNT）
-        |
-        v
-  4. 布局规划：确定单元格位置、扩展方向、父格关系
-        |
-        v
-  5. 样式配置：主题选择、条件格式、字体样式
-        |
-        v
-  6. 高级配置：查询条件、分页、打印、解析优化
-        |
-        v
-  7. 输出配置：生成完整的 ReportProps JSON 配置
-```
-
-## 二、需求解析规则
-
-### 2.1 从文本描述解析
-
-识别以下关键信息：
-- **报表名称**：用户提到的报表名称，如"客户信息报表"、"销售统计表"
-- **数据源**：用户提到的数据表/表单名称，如"客户信息表"、"销售合同表"
-- **分组维度**：用户提到"按...分组"、"按...统计"中的字段
-- **指标度量**：用户提到"统计...数量"、"求和...金额"中的字段和聚合方式
-- **列表字段**：用户提到"显示...信息"、"展示...详情"中的字段
-- **查询条件**：用户提到"按...筛选"、"按...查询"中的字段
-- **排序要求**：用户提到"按...排序"中的字段和方向
-- **样式要求**：用户提到的主题颜色、条件格式等
-
-### 2.2 从图片效果解析
-
-分析报表截图中的以下要素：
-- **报表布局**：表头结构、数据排列方式（分组/交叉/列表）
-- **字段位置**：行维度字段、列维度字段、指标字段的位置
-- **样式特征**：背景色、字体样式、交替行颜色
-- **条件格式**：数据条、图标集、高亮规则
-- **功能区域**：查询条件区域、工具栏按钮
-
-### 2.3 从需求文件解析
-
-支持的需求文件格式：
-- **Word/Excel**：提取表格结构、字段列表、统计要求
-- **JSON/YAML**：直接映射为报表配置
-- **Markdown**：提取结构化的报表需求描述
-- **图片**：同图片效果解析流程
-
-## 三、字段分类规则
-
-### 3.1 groupFields（分组/维度字段）
-
-判定条件：
-- 用户提到"按...分组"、"按...分类"、"按...维度"
-- 日期类字段且用户提到时间粒度（年/月/日）
-- 报表中需要横向或纵向展开的分类字段
-
-配置示例：
-```json
-{
-    "fieldName": "创建日期",
-    "groupType": "yearmonth"    // 按年月分组
-}
-```
-
-groupType 中文到系统值映射：
-- "年份" → `year`
-- "年月" → `yearmonth`
-- "月份" → `month`
-- "年月日" → `yearmonthday`
-- 无时间分组 → `none`
-
-### 3.2 listFields（列表/展示字段）
-
-判定条件：
-- 用户提到"显示...信息"、"展示...字段"
-- 不需要分组、不需要聚合的普通展示字段
-- 报表中的明细数据列
-
-配置示例：
-```json
-{
-    "fieldName": "客户名称",
-    "groupType": "none"
-}
-```
-
-### 3.3 targetFields（指标/度量字段）
-
-判定条件：
-- 用户提到"统计...数量"、"求和...金额"、"平均...值"
-- 需要聚合计算的数字类型字段
-- 报表中的数据值区域
-
-配置示例：
-```json
-{
-    "fieldName": "合同金额",
-    "countType": "sum"     // 求和
-}
-```
-
-countType 中文到系统值映射：
-- "求和" → `sum`
-- "最大值" → `max`
-- "最小值" → `min`
-- "平均值" → `avg`
-- "计数" → `count`
-- "去重计数" → `distinctcount`
-- 默认 → `sum`
-
-## 四、报表类型判定与布局规则
-
-### 4.1 简单列表（LIST）
-
-**触发条件**：只有 listFields 和/或 targetFields，没有 groupFields
-
-**布局规则**：
-- 所有字段纵向扩展（expandType = Vertical）
-- 显示方式为排列（displayType = List）
-- 左父格均为默认（leftParent = ["default", 0, 0]）
-- 无上父格（topParent = ["empty", 0, 0]）
-
-**单元格布局示例**：
-```
-A1: 标题行（常量）
-A2: 字段1(纵向扩展,排列)  B2: 字段2(纵向扩展,排列)  C2: 字段3(纵向扩展,排列)
-```
-
-### 4.2 分组表（GROUP）
-
-**触发条件**：有 groupFields 但数量 < 2，或没有 targetFields
-
-**布局规则**：
-- 分组字段纵向扩展（expandType = Vertical），显示方式为分组（displayType = Group）
-- 指标字段纵向扩展（expandType = Vertical），显示方式为汇总（displayType = Count）
-- 左父格关系：指标字段的左父格默认依赖相邻的分组字段
-- 无上父格
-
-**单元格布局示例**：
-```
-A1: 标题行（常量）
-A2: 分组字段(纵向扩展,分组)  B2: 指标字段(纵向扩展,汇总,求和)
-```
-
-### 4.3 交叉表/统计表（COUNT）
-
-**触发条件**：groupFields >= 2 且有 targetFields
-
-**布局规则**：
-- 行维度 = groupFields 的最后一个（纵向扩展，分组）
-- 列维度 = groupFields 的前 N-1 个（横向扩展，分组）
-- 指标字段在交叉位置（纵向扩展，汇总）
-- 指标字段的左父格自定义指向行维度单元格
-- 指标字段的上父格自定义指向列维度单元格
-- 必须设置父格筛选关联多数据集
-
-**单元格布局示例**（2个分组字段+1个指标）：
-```
-A1: 标题行（常量）
-A2: 行维度字段(纵向扩展,分组)  B2: 列维度字段(横向扩展,分组)
-                              B3: 指标字段(纵向扩展,汇总,求和)
-                                  左父格=自定义(A2), 上父格=自定义(B2)
-```
-
-### 4.4 交叉表父格筛选配置
-
-当使用多个数据集时，必须同时配置 **subordination**（从属关系）和 **leftFilterField**（左父格筛选）。
-字段引用必须使用 **fieldKey**：`{dataSetId}.{sourceId}.{fieldName}`，且 `id` 等于 `currentField`。
-
-> 完整说明、自定义筛选、双保存与定位见 `cross-dataset-filter-guide.md`。
-
-```json
-{
-    "subordination": [
-        "1304979556231593994.1299763447342276611.field_1299763447342276617",
-        "1304979560546713602.1299789221321891842.field_1299789221321891843"
-    ],
-    "leftFilterField": [{
-        "parentField": "1304979556231593994.1299763447342276611.field_1299763447342276617",
-        "currentField": "1304979560546713602.1299789221321891842.field_1299789221321891843",
-        "type": "Equals",
-        "id": "1304979560546713602.1299789221321891842.field_1299789221321891843"
-    }],
-    "customFilterField": [{
-        "currentField": "1304979560546713602.1299789221321891842.field_1299789221321891844",
-        "type": "NotContain",
-        "value": "排除机构",
-        "id": "1304979560546713602.1299789221321891842.field_1299789221321891844"
-    }]
-}
-```
-
-**常见错误**：使用显示名「团队」「销售经理」或裸 `field_xxx` → 设计器筛选下拉空白。
-
-## 五、单元格坐标规划规则
-
-### 5.1 基本布局原则
-
-- 第1行（y=0）：报表标题行，使用常量字段（cellType=Const）
-- 第2行（y=1）：表头/字段名称行
-- 第3行及以后（y>=2）：数据区域
-
-### 5.2 坐标系
-
-- x = 行号（从0开始，向下递增）
-- y = 列号（从0开始，向右递增）
-- 父格坐标：[type, x, y]
-  - `["default", 0, 0]` = 默认（依赖相邻单元格）
-  - `["custom", x, y]` = 自定义（指向坐标 x,y 的单元格）
-  - `["empty", 0, 0]` = 无父格
-
-### 5.3 多数据集布局
-
-当报表使用多个数据集时：
-1. 维度字段通常来自主数据集
-2. 指标字段可能来自不同数据集
-3. 跨数据集字段必须设置父格筛选关联
-
-## 六、公式配置规则
-
-> **API / 脚本保存含 Formula 时，完整规范见 `formula-cell-api-guide.md`。** 本节为工作流摘要。
-
-### 6.1 公式类型
-
-| 分类 | 常用公式 |
-|------|----------|
-| 数学 | SUM, AVERAGE, COUNT, MAX, MIN, ABS, ROUND, CEILING, FLOOR |
-| 文本 | LEFT, RIGHT, MID, LEN, CONCAT, UPPER, LOWER |
-| 日期 | YEAR, MONTH, DAY, DATE, DATEDIF, NOW, TODAY |
-| 逻辑 | IF, IFERROR, AND, OR, NOT |
-| 信息 | ISERROR, ISBLANK, ISNUMBER |
-
-### 6.2 公式配置方式（ReportProps / getReportDevInfo）
-
-公式单元格 `cellType` 为 `Formula`，**cellText 为公式表达式且不带前导 `=`**：
-
-```json
-{
-    "cellType": "Formula",
-    "cellText": "IF(J3=0,0,L3/J3)",
-    "displayType": "Group",
-    "countType": "count",
-    "groupType": null,
-    "expandType": "NoExpand"
-}
-```
-
-**错误示例（会导致设计器空白）**：
-
-```json
-{
-    "cellType": "Formula",
-    "cellText": "=IF(J3=0,0,L3/J3)",
-    "displayType": "List",
-    "countType": "none"
-}
-```
-
-### 6.3 workbook 写入（saveReportWithCacheConfig）
-
-workbook `dataTable` 中 Formula 格需同时设置：
-
-- 顶层 `"formula": "IF(...)"`（无前导 `=`）
-- `style.cellType.cellText` 与顶层 `formula` 内容一致
-- `style.formatter` 为空字符串
-
-参考 `make_formula()` 见 `formula-cell-api-guide.md` §四。
-
-### 6.4 公式与父格关系
-
-若公式需要按特定分组计算，公式单元格也需设置自定义左父格或上父格（`leftX`/`leftY` 指向根格）。
-
-公式格通常 `subordination: ["", ""]`，引用同表内 Field 汇总格而非数据集字段名。
-
-### 6.5 占比 / 除法推荐写法
-
-| 场景 | 设计器输入 | API 存储 |
-|------|-----------|----------|
-| 达成率 | `=IF(J3=0,0,L3/J3)` | `IF(J3=0,0,L3/J3)` |
-| 占比 | `=IF(L3=0,0,M3/L3)` | `IF(L3=0,0,M3/L3)` |
-| 安全除法 | `=IFERROR(G5/F5,"--")` | `IFERROR(G5/F5,"--")` |
-
-### 6.6 保存与验证
-
-1. 双保存：`saveReportWithCacheConfig` + `saveReportDevInfo`
-2. `getReportDevInfo` 回读：确认 `cellText` 不以 `=` 开头
-3. 运行 `e10-cli report py validate` 预检 Formula 格式
-
-## 七、高级功能配置
-
-### 7.1 查询条件配置
-
-> **API/脚本写入完整规范**见 `query-condition-api-guide.md`（条件字段形态、asNameIndex、21 项日期选项、系统参数默认值）。以下为 ReportProps 摘要，**不可直接等同于 saveQueryItem  payload**。
-
-```json
-{
-    "queryFields": [{
-        "uuid": "query-1",
-        "id": "field-001",
-        "text": "日期范围",
-        "displayType": "date",
-        "conditions": [{
-            "dataSetId": "ds-001",
-            "fieldId": "createdate",
-            "relation": "between"
-        }],
-        "showOrder": 1
-    }]
-}
-```
-
-### 7.2 分页配置
-
-```json
-{
-    "pageNum": 1,
-    "pageRowCount": 200,        // 每页行数
-    "dynamicField": "",        // 动态Sheet页字段
-    "scrollPage": false        // 滚动分页
-}
-```
-
-### 7.3 解析优化配置
-
-```json
-{
-    "rowMode": false,          // 行式加载（仅单数据集简单列表）
-    "preAggregate": true       // 数据预聚合（默认开启）
-}
-```
-
-### 7.4 打印配置
-
-```json
-{
-    "printInfo": {
-        "area": { "startRow": -1, "endRow": -1, "startCol": -1, "endCol": -1 },
-        "repeatArea": { "startRow": -1, "endRow": -1, "startCol": -1, "endCol": -1 },
-        "printGridLine": false,
-        "printOuterBorder": false,
-        "allRowsInOnePage": false,
-        "allColsInOnePage": false,
-        "printOrder": "auto"
-    },
-    "pageMargin": { "top": -1, "bottom": -1, "left": -1, "right": -1, "header": -1, "footer": -1 },
-    "paperSize": "A4",
-    "paperOrientation": "portrait"
-}
-```
-
-## 八、确认信息生成规则
-
-生成报表配置后，应向用户展示确认信息：
-
-```
-报表创建确认：
-
-名称：{reportName}
-数据源：{formName}
-报表类型：{列表|分组表|交叉表}
-
-行维度字段：{字段名}（{分组类型}）
-列维度字段：{字段名}（{分组类型}）
-列表字段：{字段名}
-指标字段：{字段名}（{聚合方式}）
-
-查询条件：{条件名}（{条件类型}）
-主题样式：主题{编号}
-
-请确认是否创建此报表。
-```
-
-## 九、错误处理与校验
-
-### 9.1 必须校验项
-
-1. **报表名称**：不能为空，不能与已有报表重名
-2. **数据源**：必须指定有效的数据源
-3. **字段配置**：至少需要一个字段
-4. **字段有效性**：指定的字段名必须在数据集可用字段中
-5. **父格一致性**：多数据集时必须设置父格筛选
-
-### 9.2 常见错误及处理
-
-| 错误 | 原因 | 处理方式 |
-|------|------|----------|
-| 字段不存在 | AI 指定的字段名不在数据集中 | 列出可用字段，提示用户修正 |
-| 数据源未找到 | formId 无效 | 提示用户选择有效数据源 |
-| 名称重复 | 报表名已存在 | 提示用户更换名称 |
-| 父格循环引用 | 父格设置形成环 | 检查并修正父格关系 |
-| 聚合字段非数字 | 对文本字段使用求和 | 检查字段类型，使用计数替代 |
+# AI 报表生成工作流程
+
+> **冷启动禁止通读**：见 `api-report-build-fast-path.md`。纯搭表走 `api-report-build-fast-path.md`，勿开场读本文。
+
+## 一、整体流程概览
+
+```
+用户输入（文本描述 / 图片效果 / 需求文件）
+        |
+        v
+  1. 需求解析：理解报表类型、数据维度、指标、样式需求
+        |
+        v
+  2. 字段分类：将需求中的字段映射为三类
+     - groupFields（分组/维度字段）
+     - listFields（列表/展示字段）
+     - targetFields（指标/度量字段）
+        |
+        v
+  3. 报表类型判定：根据字段组合判断报表类型
+     - 简单列表（LIST）
+     - 分组表（GROUP）
+     - 交叉表/统计表（COUNT）
+        |
+        v
+  4. 布局规划：确定单元格位置、扩展方向、父格关系
+        |
+        v
+  5. 样式配置：主题选择、条件格式、字体样式
+        |
+        v
+  6. 高级配置：查询条件、分页、打印、解析优化
+        |
+        v
+  7. 输出配置：生成完整的 ReportProps JSON 配置
+```
+
+## 二、需求解析规则
+
+### 2.1 从文本描述解析
+
+识别以下关键信息：
+- **报表名称**：用户提到的报表名称，如"客户信息报表"、"销售统计表"
+- **数据源**：用户提到的数据表/表单名称，如"客户信息表"、"销售合同表"
+- **分组维度**：用户提到"按...分组"、"按...统计"中的字段
+- **指标度量**：用户提到"统计...数量"、"求和...金额"中的字段和聚合方式
+- **列表字段**：用户提到"显示...信息"、"展示...详情"中的字段
+- **查询条件**：用户提到"按...筛选"、"按...查询"中的字段
+- **排序要求**：用户提到"按...排序"中的字段和方向
+- **样式要求**：用户提到的主题颜色、条件格式等
+
+### 2.2 从图片效果解析
+
+分析报表截图中的以下要素：
+- **报表布局**：表头结构、数据排列方式（分组/交叉/列表）
+- **字段位置**：行维度字段、列维度字段、指标字段的位置
+- **样式特征**：背景色、字体样式、交替行颜色
+- **条件格式**：数据条、图标集、高亮规则
+- **功能区域**：查询条件区域、工具栏按钮
+
+### 2.3 从需求文件解析
+
+支持的需求文件格式：
+- **Word/Excel**：提取表格结构、字段列表、统计要求
+- **JSON/YAML**：直接映射为报表配置
+- **Markdown**：提取结构化的报表需求描述
+- **图片**：同图片效果解析流程
+
+## 三、字段分类规则
+
+### 3.1 groupFields（分组/维度字段）
+
+判定条件：
+- 用户提到"按...分组"、"按...分类"、"按...维度"
+- 日期类字段且用户提到时间粒度（年/月/日）
+- 报表中需要横向或纵向展开的分类字段
+
+配置示例：
+```json
+{
+    "fieldName": "创建日期",
+    "groupType": "yearmonth"    // 按年月分组
+}
+```
+
+groupType 中文到系统值映射：
+- "年份" → `year`
+- "年月" → `yearmonth`
+- "月份" → `month`
+- "年月日" → `yearmonthday`
+- 无时间分组 → `none`
+
+### 3.2 listFields（列表/展示字段）
+
+判定条件：
+- 用户提到"显示...信息"、"展示...字段"
+- 不需要分组、不需要聚合的普通展示字段
+- 报表中的明细数据列
+
+配置示例：
+```json
+{
+    "fieldName": "客户名称",
+    "groupType": "none"
+}
+```
+
+### 3.3 targetFields（指标/度量字段）
+
+判定条件：
+- 用户提到"统计...数量"、"求和...金额"、"平均...值"
+- 需要聚合计算的数字类型字段
+- 报表中的数据值区域
+
+配置示例：
+```json
+{
+    "fieldName": "合同金额",
+    "countType": "sum"     // 求和
+}
+```
+
+countType 中文到系统值映射：
+- "求和" → `sum`
+- "最大值" → `max`
+- "最小值" → `min`
+- "平均值" → `avg`
+- "计数" → `count`
+- "去重计数" → `distinctcount`
+- 默认 → `sum`
+
+## 四、报表类型判定与布局规则
+
+### 4.1 简单列表（LIST）
+
+**触发条件**：只有 listFields 和/或 targetFields，没有 groupFields
+
+**布局规则**：
+- 所有字段纵向扩展（expandType = Vertical）
+- 显示方式为排列（displayType = List）
+- 左父格均为默认（leftParent = ["default", 0, 0]）
+- 无上父格（topParent = ["empty", 0, 0]）
+
+**单元格布局示例**：
+```
+A1: 标题行（常量）
+A2: 字段1(纵向扩展,排列)  B2: 字段2(纵向扩展,排列)  C2: 字段3(纵向扩展,排列)
+```
+
+### 4.2 分组表（GROUP）
+
+**触发条件**：有 groupFields 但数量 < 2，或没有 targetFields
+
+**布局规则**：
+- 分组字段纵向扩展（expandType = Vertical），显示方式为分组（displayType = Group）
+- 指标字段纵向扩展（expandType = Vertical），显示方式为汇总（displayType = Count）
+- 左父格关系：指标字段的左父格默认依赖相邻的分组字段
+- 无上父格
+
+**单元格布局示例**：
+```
+A1: 标题行（常量）
+A2: 分组字段(纵向扩展,分组)  B2: 指标字段(纵向扩展,汇总,求和)
+```
+
+### 4.3 交叉表/统计表（COUNT）
+
+**触发条件**：groupFields >= 2 且有 targetFields
+
+**布局规则**：
+- 行维度 = groupFields 的最后一个（纵向扩展，分组）
+- 列维度 = groupFields 的前 N-1 个（横向扩展，分组）
+- 指标字段在交叉位置（纵向扩展，汇总）
+- 指标字段的左父格自定义指向行维度单元格
+- 指标字段的上父格自定义指向列维度单元格
+- 必须设置父格筛选关联多数据集
+
+**单元格布局示例**（2个分组字段+1个指标）：
+```
+A1: 标题行（常量）
+A2: 行维度字段(纵向扩展,分组)  B2: 列维度字段(横向扩展,分组)
+                              B3: 指标字段(纵向扩展,汇总,求和)
+                                  左父格=自定义(A2), 上父格=自定义(B2)
+```
+
+### 4.4 交叉表父格筛选配置
+
+当使用多个数据集时，必须同时配置 **subordination**（从属关系）和 **leftFilterField**（左父格筛选）。
+字段引用必须使用 **fieldKey**：`{dataSetId}.{sourceId}.{fieldName}`，且 `id` 等于 `currentField`。
+
+> 完整说明、自定义筛选、双保存与定位见 `cross-dataset-filter-guide.md`。
+
+```json
+{
+    "subordination": [
+        "1304979556231593994.1299763447342276611.field_1299763447342276617",
+        "1304979560546713602.1299789221321891842.field_1299789221321891843"
+    ],
+    "leftFilterField": [{
+        "parentField": "1304979556231593994.1299763447342276611.field_1299763447342276617",
+        "currentField": "1304979560546713602.1299789221321891842.field_1299789221321891843",
+        "type": "Equals",
+        "id": "1304979560546713602.1299789221321891842.field_1299789221321891843"
+    }],
+    "customFilterField": [{
+        "currentField": "1304979560546713602.1299789221321891842.field_1299789221321891844",
+        "type": "NotContain",
+        "value": "排除机构",
+        "id": "1304979560546713602.1299789221321891842.field_1299789221321891844"
+    }]
+}
+```
+
+**常见错误**：使用显示名「团队」「销售经理」或裸 `field_xxx` → 设计器筛选下拉空白。
+
+## 五、单元格坐标规划规则
+
+### 5.1 基本布局原则
+
+- 第1行（y=0）：报表标题行，使用常量字段（cellType=Const）
+- 第2行（y=1）：表头/字段名称行
+- 第3行及以后（y>=2）：数据区域
+
+### 5.2 坐标系
+
+- x = 行号（从0开始，向下递增）
+- y = 列号（从0开始，向右递增）
+- 父格坐标：[type, x, y]
+  - `["default", 0, 0]` = 默认（依赖相邻单元格）
+  - `["custom", x, y]` = 自定义（指向坐标 x,y 的单元格）
+  - `["empty", 0, 0]` = 无父格
+
+### 5.3 多数据集布局
+
+当报表使用多个数据集时：
+1. 维度字段通常来自主数据集
+2. 指标字段可能来自不同数据集
+3. 跨数据集字段必须设置父格筛选关联
+
+## 六、公式配置规则
+
+> **API / 脚本保存含 Formula 时，完整规范见 `formula-cell-api-guide.md`。** 本节为工作流摘要。
+
+### 6.1 公式类型
+
+| 分类 | 常用公式 |
+|------|----------|
+| 数学 | SUM, AVERAGE, COUNT, MAX, MIN, ABS, ROUND, CEILING, FLOOR |
+| 文本 | LEFT, RIGHT, MID, LEN, CONCAT, UPPER, LOWER |
+| 日期 | YEAR, MONTH, DAY, DATE, DATEDIF, NOW, TODAY |
+| 逻辑 | IF, IFERROR, AND, OR, NOT |
+| 信息 | ISERROR, ISBLANK, ISNUMBER |
+
+### 6.2 公式配置方式（ReportProps / getReportDevInfo）
+
+公式单元格 `cellType` 为 `Formula`，**cellText 为公式表达式且不带前导 `=`**：
+
+```json
+{
+    "cellType": "Formula",
+    "cellText": "IF(J3=0,0,L3/J3)",
+    "displayType": "Group",
+    "countType": "count",
+    "groupType": null,
+    "expandType": "NoExpand"
+}
+```
+
+**错误示例（会导致设计器空白）**：
+
+```json
+{
+    "cellType": "Formula",
+    "cellText": "=IF(J3=0,0,L3/J3)",
+    "displayType": "List",
+    "countType": "none"
+}
+```
+
+### 6.3 workbook 写入（saveReportWithCacheConfig）
+
+workbook `dataTable` 中 Formula 格需同时设置：
+
+- 顶层 `"formula": "IF(...)"`（无前导 `=`）
+- `style.cellType.cellText` 与顶层 `formula` 内容一致
+- `style.formatter` 为空字符串
+
+参考 `make_formula()` 见 `formula-cell-api-guide.md` §四。
+
+### 6.4 公式与父格关系
+
+若公式需要按特定分组计算，公式单元格也需设置自定义左父格或上父格（`leftX`/`leftY` 指向根格）。
+
+公式格通常 `subordination: ["", ""]`，引用同表内 Field 汇总格而非数据集字段名。
+
+### 6.5 占比 / 除法推荐写法
+
+| 场景 | 设计器输入 | API 存储 |
+|------|-----------|----------|
+| 达成率 | `=IF(J3=0,0,L3/J3)` | `IF(J3=0,0,L3/J3)` |
+| 占比 | `=IF(L3=0,0,M3/L3)` | `IF(L3=0,0,M3/L3)` |
+| 安全除法 | `=IFERROR(G5/F5,"--")` | `IFERROR(G5/F5,"--")` |
+
+### 6.6 保存与验证
+
+1. 双保存：`saveReportWithCacheConfig` + `saveReportDevInfo`
+2. `getReportDevInfo` 回读：确认 `cellText` 不以 `=` 开头
+3. 运行 `e10-cli report py validate` 预检 Formula 格式
+
+## 七、高级功能配置
+
+### 7.1 查询条件配置
+
+> **API/脚本写入完整规范**见 `query-condition-api-guide.md`（条件字段形态、asNameIndex、21 项日期选项、系统参数默认值）。以下为 ReportProps 摘要，**不可直接等同于 saveQueryItem  payload**。
+
+```json
+{
+    "queryFields": [{
+        "uuid": "query-1",
+        "id": "field-001",
+        "text": "日期范围",
+        "displayType": "date",
+        "conditions": [{
+            "dataSetId": "ds-001",
+            "fieldId": "createdate",
+            "relation": "between"
+        }],
+        "showOrder": 1
+    }]
+}
+```
+
+### 7.2 分页配置
+
+```json
+{
+    "pageNum": 1,
+    "pageRowCount": 200,        // 每页行数
+    "dynamicField": "",        // 动态Sheet页字段
+    "scrollPage": false        // 滚动分页
+}
+```
+
+### 7.3 解析优化配置
+
+```json
+{
+    "rowMode": false,          // 行式加载（仅单数据集简单列表）
+    "preAggregate": true       // 数据预聚合（默认开启）
+}
+```
+
+### 7.4 打印配置
+
+```json
+{
+    "printInfo": {
+        "area": { "startRow": -1, "endRow": -1, "startCol": -1, "endCol": -1 },
+        "repeatArea": { "startRow": -1, "endRow": -1, "startCol": -1, "endCol": -1 },
+        "printGridLine": false,
+        "printOuterBorder": false,
+        "allRowsInOnePage": false,
+        "allColsInOnePage": false,
+        "printOrder": "auto"
+    },
+    "pageMargin": { "top": -1, "bottom": -1, "left": -1, "right": -1, "header": -1, "footer": -1 },
+    "paperSize": "A4",
+    "paperOrientation": "portrait"
+}
+```
+
+## 八、确认信息生成规则
+
+生成报表配置后，应向用户展示确认信息：
+
+```
+报表创建确认：
+
+名称：{reportName}
+数据源：{formName}
+报表类型：{列表|分组表|交叉表}
+
+行维度字段：{字段名}（{分组类型}）
+列维度字段：{字段名}（{分组类型}）
+列表字段：{字段名}
+指标字段：{字段名}（{聚合方式}）
+
+查询条件：{条件名}（{条件类型}）
+主题样式：主题{编号}
+
+请确认是否创建此报表。
+```
+
+## 九、错误处理与校验
+
+### 9.1 必须校验项
+
+1. **报表名称**：不能为空，不能与已有报表重名
+2. **数据源**：必须指定有效的数据源
+3. **字段配置**：至少需要一个字段
+4. **字段有效性**：指定的字段名必须在数据集可用字段中
+5. **父格一致性**：多数据集时必须设置父格筛选
+
+### 9.2 常见错误及处理
+
+| 错误 | 原因 | 处理方式 |
+|------|------|----------|
+| 字段不存在 | AI 指定的字段名不在数据集中 | 列出可用字段，提示用户修正 |
+| 数据源未找到 | formId 无效 | 提示用户选择有效数据源 |
+| 名称重复 | 报表名已存在 | 提示用户更换名称 |
+| 父格循环引用 | 父格设置形成环 | 检查并修正父格关系 |
+| 聚合字段非数字 | 对文本字段使用求和 | 检查字段类型，使用计数替代 |