weaver-e10-builder 1.6.16 → 1.7.0

package/skill-docs/references/report/paged-group-report-guide.md

@@ -1,68 +1,68 @@
-# 分页分组报表 · 案例解析（SKILL A0.15 · 场景 E）
-
-> 案例（官方 demo「产品信息统计_标题重复/页内合计/条件预警」）五个特性 → 机制 → CLI 落点全解析。
-> 固化：2026-10-29。已固化项走 `build spec` / 场景 B；待验证项如实标注，不冒充已验证。
-
-## 一、案例结构（截图解析）
-
-- **表头行**：序号 | 产品名称 | 单价 | 库存量 | 订购量 | 订购金额（整行 Const）
-- **分组标题带**：`产品类别：` + 类别名称字段（如「饮料」）—— 该行**随类别扩展动态重复**（特性①）
-- **明细带**：序号（分组式编号）+ 产品名称/单价/库存量/订购量/订购金额 —— 每类别下展开其产品（特性②）
-- **页内合计带**：每页底部「页内合计：」+ 金额汇总（8287.5）（特性④）
-- 每页固定 10 行明细（特性③）；条件预警两处（特性⑤）
-
-## 二、特性 → 机制 → CLI 落点
-
-| # | 特性 | 机制（workbook 层） | CLI 落点 | 状态 |
-|---|---|---|---|---|
-| ① | 动态重复标题行 | 分组标题带整行（Const「产品类别：」+ 类别 Field 格）左父格绑**类别字段格** → 随类别扩展整块复制（= 段落块机制的多带版） | 多带结构走 `buildWorkbookFromFields` 重建路径（rebuild）；声明式待固化 | ✅ 机制已验证（场景A 同源） |
-| ② | 分组式编号（类别→产品两层） | 类别 Field 格 = 扩展根（`isActiveParent:true`）；明细带全部格左父格**跨带绑类别格**；序号列 = `SequenceNumber`（场景 B，**禁公式生号**） | `columns[].cellType:"seq"`（明细带）+ 跨带父格链 | ✅ |
-| ③ | 页内固定行数 | `pageSetting.pagination:true` + `pageRowCount:N`（每页行数） | **`build spec` 的 `layout.pageRowCount:N`**（本次固化，saveReportWithCacheConfig 通道） | ✅ 已固化 |
-| ④ | 页内汇总统计 | 每页底部合计带 Formula（=SUM(明细带)）；**「页内」语义**（随分页逐页汇总）依赖平台渲染 | 公式四件套（BUILD-46/49）落 Formula 格可做；**页内逐页汇总是否原生支持待设计器确认** | ⚠️ 待验证 |
-| ⑤ | 条件预警（单元格级） | `conditionRule.highlightDatas`（greater + foreColor 红） | **`columns[].rule:{"highlight":{"op":">","value1":"1000","foreColor":"#FF0000"}}`** | ✅ 已有 |
-
-**条件预警边界**：demo 中「库存量<订购量 → 整行白底高亮」是**跨格对比 + 行级**条件格式；
-现 CLI `rule` 只支持**格级**（当前格 vs 常量）。跨格/行级 `conditionType` 待设计器确认后固化（同页内合计）。
-
-## 三、已固化用法
-
-### 3.1 每页固定行数（build spec）
-
-```json
-{
-  "appId": "...", "name": "产品信息统计", "form": "产品信息",
-  "layout": { "title": "产品信息统计表", "freezeRows": 1, "pageRowCount": 10 },
-  "columns": [
-    { "title": "序号", "cellType": "seq", "width": 60 },
-    { "title": "产品名称", "field": "产品名称", "width": 140 },
-    { "title": "单价", "field": "单价", "format": "value" },
-    { "title": "库存量", "field": "库存量", "format": "int" },
-    { "title": "订购量", "field": "订购量", "format": "int" },
-    { "title": "订购金额", "field": "订购金额", "format": "value",
-      "rule": { "highlight": { "op": ">", "value1": "1000", "foreColor": "#FF0000", "bold": true } } }
-  ]
-}
-```
-
-- `pageRowCount>0` → 落库自动追加 `saveReportWithCacheConfig`（`pagination:true` + `pageRowCount`）；
-  失败 exitCode=2 并打 `saveReportWithCacheConfig FAIL`。
-- 回读：`GET allPageSetting` 或设计器「页面 → 打印与分页」核对每页行数。
-- 「不足 10 行补空白行」是平台渲染行为，**验证项**（与 cell-limit 渲染守卫无冲突，pageRowCount 仅分页尺寸）。
-
-### 3.2 分组式编号
-
-明细带序号列一律 `cellType:"seq"`（场景 B）；类别格为扩展根；**禁止公式生号**。
-
-## 四、搭建提示语句（用户照此提需求）
-
-> 搭一张分页分组报表（appId <appId>，数据源 <表名>）：分组标题带「产品类别：+类别」（随类别动态重复）；
-> 明细带：序号（分组式编号 seq）+ 产品名称/单价/库存量/订购量/订购金额；每页固定 <N> 行（layout.pageRowCount）；
-> 订购金额 >1000 红色高亮（rule highlight）；库存量<订购量整行预警与页内合计属设计器确认项，先按格级高亮+合计带公式落库。
-> 用 `e10-cli report build spec` 落库，回读验收格数/父格链/条件格式/pageSetting。
-
-## 五、关联
-
-- 场景 B（自增序号）/ 场景 A（多带父格）`branch-scene-guide.md` · `expansion-block-parent-config-guide.md`
-- 公式格四件套 `formula-cell-api-guide.md`（合计带 Formula 必读）
-- 条件格式 `condition-format-guide.md` · 分页 `designer-blank-prevention-guide.md`（scrollPage/pageRowCount）
-- 卡片段落版式 `card-report-guide.md` §3.1（标题行随块复制同源机制）
+# 分页分组报表 · 案例解析（SKILL A0.15 · 场景 E）
+
+> 案例（官方 demo「产品信息统计_标题重复/页内合计/条件预警」）五个特性 → 机制 → CLI 落点全解析。
+> 固化：2026-10-29。已固化项走 `build spec` / 场景 B；待验证项如实标注，不冒充已验证。
+
+## 一、案例结构（截图解析）
+
+- **表头行**：序号 | 产品名称 | 单价 | 库存量 | 订购量 | 订购金额（整行 Const）
+- **分组标题带**：`产品类别：` + 类别名称字段（如「饮料」）—— 该行**随类别扩展动态重复**（特性①）
+- **明细带**：序号（分组式编号）+ 产品名称/单价/库存量/订购量/订购金额 —— 每类别下展开其产品（特性②）
+- **页内合计带**：每页底部「页内合计：」+ 金额汇总（8287.5）（特性④）
+- 每页固定 10 行明细（特性③）；条件预警两处（特性⑤）
+
+## 二、特性 → 机制 → CLI 落点
+
+| # | 特性 | 机制（workbook 层） | CLI 落点 | 状态 |
+|---|---|---|---|---|
+| ① | 动态重复标题行 | 分组标题带整行（Const「产品类别：」+ 类别 Field 格）左父格绑**类别字段格** → 随类别扩展整块复制（= 段落块机制的多带版） | 多带结构走 `buildWorkbookFromFields` 重建路径（rebuild）；声明式待固化 | ✅ 机制已验证（场景A 同源） |
+| ② | 分组式编号（类别→产品两层） | 类别 Field 格 = 扩展根（`isActiveParent:true`）；明细带全部格左父格**跨带绑类别格**；序号列 = `SequenceNumber`（场景 B，**禁公式生号**） | `columns[].cellType:"seq"`（明细带）+ 跨带父格链 | ✅ |
+| ③ | 页内固定行数 | `pageSetting.pagination:true` + `pageRowCount:N`（每页行数） | **`build spec` 的 `layout.pageRowCount:N`**（本次固化，saveReportWithCacheConfig 通道） | ✅ 已固化 |
+| ④ | 页内汇总统计 | 每页底部合计带 Formula（=SUM(明细带)）；**「页内」语义**（随分页逐页汇总）依赖平台渲染 | 公式四件套（BUILD-46/49）落 Formula 格可做；**页内逐页汇总是否原生支持待设计器确认** | ⚠️ 待验证 |
+| ⑤ | 条件预警（单元格级） | `conditionRule.highlightDatas`（greater + foreColor 红） | **`columns[].rule:{"highlight":{"op":">","value1":"1000","foreColor":"#FF0000"}}`** | ✅ 已有 |
+
+**条件预警边界**：demo 中「库存量<订购量 → 整行白底高亮」是**跨格对比 + 行级**条件格式；
+现 CLI `rule` 只支持**格级**（当前格 vs 常量）。跨格/行级 `conditionType` 待设计器确认后固化（同页内合计）。
+
+## 三、已固化用法
+
+### 3.1 每页固定行数（build spec）
+
+```json
+{
+  "appId": "...", "name": "产品信息统计", "form": "产品信息",
+  "layout": { "title": "产品信息统计表", "freezeRows": 1, "pageRowCount": 10 },
+  "columns": [
+    { "title": "序号", "cellType": "seq", "width": 60 },
+    { "title": "产品名称", "field": "产品名称", "width": 140 },
+    { "title": "单价", "field": "单价", "format": "value" },
+    { "title": "库存量", "field": "库存量", "format": "int" },
+    { "title": "订购量", "field": "订购量", "format": "int" },
+    { "title": "订购金额", "field": "订购金额", "format": "value",
+      "rule": { "highlight": { "op": ">", "value1": "1000", "foreColor": "#FF0000", "bold": true } } }
+  ]
+}
+```
+
+- `pageRowCount>0` → 落库自动追加 `saveReportWithCacheConfig`（`pagination:true` + `pageRowCount`）；
+  失败 exitCode=2 并打 `saveReportWithCacheConfig FAIL`。
+- 回读：`GET allPageSetting` 或设计器「页面 → 打印与分页」核对每页行数。
+- 「不足 10 行补空白行」是平台渲染行为，**验证项**（与 cell-limit 渲染守卫无冲突，pageRowCount 仅分页尺寸）。
+
+### 3.2 分组式编号
+
+明细带序号列一律 `cellType:"seq"`（场景 B）；类别格为扩展根；**禁止公式生号**。
+
+## 四、搭建提示语句（用户照此提需求）
+
+> 搭一张分页分组报表（appId <appId>，数据源 <表名>）：分组标题带「产品类别：+类别」（随类别动态重复）；
+> 明细带：序号（分组式编号 seq）+ 产品名称/单价/库存量/订购量/订购金额；每页固定 <N> 行（layout.pageRowCount）；
+> 订购金额 >1000 红色高亮（rule highlight）；库存量<订购量整行预警与页内合计属设计器确认项，先按格级高亮+合计带公式落库。
+> 用 `e10-cli report build spec` 落库，回读验收格数/父格链/条件格式/pageSetting。
+
+## 五、关联
+
+- 场景 B（自增序号）/ 场景 A（多带父格）`branch-scene-guide.md` · `expansion-block-parent-config-guide.md`
+- 公式格四件套 `formula-cell-api-guide.md`（合计带 Formula 必读）
+- 条件格式 `condition-format-guide.md` · 分页 `designer-blank-prevention-guide.md`（scrollPage/pageRowCount）
+- 卡片段落版式 `card-report-guide.md` §3.1（标题行随块复制同源机制）

package/skill-docs/references/report/preaggregate-auto-disable-guide.md

@@ -1,118 +1,118 @@
-# 数据预聚合自动关闭指南
-
-> **解析优化 · 数据预聚合**（设计器「页面 → 报表展示 · 解析优化」）对应 `sheetConfig.dataPreAgg`（默认 `true`）。
-> 当数据源字段或报表布局不满足引擎预聚合条件时，**必须自动关闭**，避免预览/解析异常或静默降级。
-> **勿混淆**：左侧数据集菜单「**数据聚合**」是 `aggregationSave`（见 `dataset-sidebar-ops-guide.md`），不是本指南的 `dataPreAgg`。
-
----
-
-## 一、源码依据
-
-| 来源 | 规则 |
-|------|------|
-| `SheetServiceImpl.existNotAllAllowAggregate` | 数据集字段 `gdBySelf=true` → 不支持预聚合 |
-| 同上 | 字段 `usage == "list"` → 不支持（仅 `""`/`all`/`char`/`aggregate` 支持分组） |
-| `BaseEngine.initDataSetByGroup` | `sheetConfig.dataPreAgg=false` → 全局跳过 |
-| 同上 | 单元格存在 `customFilterField` 或 `dataFilterField` → 该 dataset 不参与预聚合 |
-| 同上 | 存在 `displayType=List`（排列）字段 → 该 dataset 不参与 |
-| `GCONST.NO_GROUP_COMP_TYPE` | 分组字段 `compType` 为 `TextArea` / `RichText` → 不可预分组 |
-
----
-
-## 二、检测时机（Agent 必做）
-
-在 **addDataset 后、saveReportWithCacheConfig 前**：
-
-1. 调用 `GET /api/bs/edc/dataset/fieldsAndOriginFields?datasetId={id}&hasField=true&isFront=true`
-2. 读取 `data.fieldsKey` 或 `data.originFields` 中每个字段的 `usage`、`originField.compType`、`gdBySelf`（若在 dataset 级）
-3. 结合已规划的报表字段（displayType、customFilterField）运行检测脚本
-
-```bash
-e10-cli report py preagg --fields-json <fields.json> [--layout-json <report_fields.json>]
-```
-
----
-
-## 三、判定逻辑（摘要）
-
-**以下任一成立 → `dataPreAgg: false`**
-
-### 3.1 字段元数据（数据源）
-
-- 任一绑定字段 `usage == "list"`
-- 任一作为**分组**使用的字段 `originField.compType ∈ {TextArea, RichText}`
-- 数据集级标记 `gdBySelf == true`
-
-### 3.2 报表布局
-
-- 任一字段 `displayType == "List"`（排列）
-- 任一字段 `customFilterField` 或 `dataFilterField` 非空
-- 多数据集且存在跨表 `leftFilterField`（父格筛选参与取数，引擎对涉及 dataset 跳过预聚合）
-
----
-
-## 四、写入方式
-
-### 4.1 pageSetting / sheetConfig
-
-双保存时 `pageSetting` 或 sheet props 中写入：
-
-```json
-{
-  "0": {
-    "rowHeader": 0,
-    "colHeader": 0,
-    "gridLine": 0,
-    "sheetConfig": "{\"dataPreAgg\":false,\"simpleList\":false}"
-  }
-}
-```
-
-> **注意**：`rowHeader` / `colHeader` / `gridLine` 保持 **0**（默认关闭）。勿为写 `sheetConfig` 而顺带把网格线/行号列头写成 `1`；见 `report-designer-feature-map.md` §4.6.1。
-
-### 4.2 ReportProps JSON
-
-```json
-"sheetProps": {
-  "sheetConfig": "{\"dataPreAgg\":false,\"simpleList\":false}"
-}
-```
-
-### 4.3 脚本辅助
-
-`e10-cli report py preagg` 输出：
-
-```json
-{
-  "dataPreAgg": false,
-  "reasons": ["字段[备注] usage=list 不支持预聚合", "…"],
-  "sheetConfig": "{\"dataPreAgg\":false,\"simpleList\":false}"
-}
-```
-
----
-
-### 4.4 已验证写入路径（★ 2026-09-15 验证 · 交叉表/含公式格报表适用）
-
-`sheetConfig` 实际落点是 **workbook 的 `sheet.tag.sheetConfig`**（服务端 `sheetProps.sheetConfig` 回读）。对已有报表（尤其含 Formula 格）：
-
-1. `getReportDevInfo` 取 `fields[]`（全键）+ `sheetProps[0]`
-2. 反向重建 workbook：格子用构建态完整结构（typeName/editorType/subordination，Formula 格 cell 级带 `formula` 键），sheet 骨架按 `e10-cli report fix table-name` 的 18 键形态（theme/selections/colHeaderData/rowHeaderData 等一个不少），`tag.sheetConfig = {dataPreAgg:false, simpleList:false}`
-3. 保存走与 build spec 同通道：`saveReportDevInfo` form（`designKey:''` + gzip base64）——勿走 fix 门禁授权路径
-4. 回读确认：fields 数不变、Formula 格数不变、`sheetProps.sheetConfig` 含 `"dataPreAgg":false`
-
-验证：23 格（Formula 10）692ms 落库全存活，合并/父格不变，verify self 0 错 0 警。
-
-## 五、Agent 流程嵌入
-
-1. 获取字段元数据 → 运行 `e10-cli report py preagg`
-2. 若 `dataPreAgg=false`，在 save 载荷中写入 `sheetConfig`，并在 HTML 手册 `tips` 中注明「已关闭数据预聚合：原因…」
-3. 保存后 `getReportDevInfo` / 设计器「页面 → 解析优化」确认开关状态
-
----
-
-## 六、相关文档
-
-- `report-designer-feature-map.md` — 解析优化入口
-- `report-knowledge-base.md` §1.2 — 预聚合概念
-- `report-delivery-contract.md` — 交付自检含预聚合项
+# 数据预聚合自动关闭指南
+
+> **解析优化 · 数据预聚合**（设计器「页面 → 报表展示 · 解析优化」）对应 `sheetConfig.dataPreAgg`（默认 `true`）。
+> 当数据源字段或报表布局不满足引擎预聚合条件时，**必须自动关闭**，避免预览/解析异常或静默降级。
+> **勿混淆**：左侧数据集菜单「**数据聚合**」是 `aggregationSave`（见 `dataset-sidebar-ops-guide.md`），不是本指南的 `dataPreAgg`。
+
+---
+
+## 一、源码依据
+
+| 来源 | 规则 |
+|------|------|
+| `SheetServiceImpl.existNotAllAllowAggregate` | 数据集字段 `gdBySelf=true` → 不支持预聚合 |
+| 同上 | 字段 `usage == "list"` → 不支持（仅 `""`/`all`/`char`/`aggregate` 支持分组） |
+| `BaseEngine.initDataSetByGroup` | `sheetConfig.dataPreAgg=false` → 全局跳过 |
+| 同上 | 单元格存在 `customFilterField` 或 `dataFilterField` → 该 dataset 不参与预聚合 |
+| 同上 | 存在 `displayType=List`（排列）字段 → 该 dataset 不参与 |
+| `GCONST.NO_GROUP_COMP_TYPE` | 分组字段 `compType` 为 `TextArea` / `RichText` → 不可预分组 |
+
+---
+
+## 二、检测时机（Agent 必做）
+
+在 **addDataset 后、saveReportWithCacheConfig 前**：
+
+1. 调用 `GET /api/bs/edc/dataset/fieldsAndOriginFields?datasetId={id}&hasField=true&isFront=true`
+2. 读取 `data.fieldsKey` 或 `data.originFields` 中每个字段的 `usage`、`originField.compType`、`gdBySelf`（若在 dataset 级）
+3. 结合已规划的报表字段（displayType、customFilterField）运行检测脚本
+
+```bash
+e10-cli report py preagg --fields-json <fields.json> [--layout-json <report_fields.json>]
+```
+
+---
+
+## 三、判定逻辑（摘要）
+
+**以下任一成立 → `dataPreAgg: false`**
+
+### 3.1 字段元数据（数据源）
+
+- 任一绑定字段 `usage == "list"`
+- 任一作为**分组**使用的字段 `originField.compType ∈ {TextArea, RichText}`
+- 数据集级标记 `gdBySelf == true`
+
+### 3.2 报表布局
+
+- 任一字段 `displayType == "List"`（排列）
+- 任一字段 `customFilterField` 或 `dataFilterField` 非空
+- 多数据集且存在跨表 `leftFilterField`（父格筛选参与取数，引擎对涉及 dataset 跳过预聚合）
+
+---
+
+## 四、写入方式
+
+### 4.1 pageSetting / sheetConfig
+
+双保存时 `pageSetting` 或 sheet props 中写入：
+
+```json
+{
+  "0": {
+    "rowHeader": 0,
+    "colHeader": 0,
+    "gridLine": 0,
+    "sheetConfig": "{\"dataPreAgg\":false,\"simpleList\":false}"
+  }
+}
+```
+
+> **注意**：`rowHeader` / `colHeader` / `gridLine` 保持 **0**（默认关闭）。勿为写 `sheetConfig` 而顺带把网格线/行号列头写成 `1`；见 `report-designer-feature-map.md` §4.6.1。
+
+### 4.2 ReportProps JSON
+
+```json
+"sheetProps": {
+  "sheetConfig": "{\"dataPreAgg\":false,\"simpleList\":false}"
+}
+```
+
+### 4.3 脚本辅助
+
+`e10-cli report py preagg` 输出：
+
+```json
+{
+  "dataPreAgg": false,
+  "reasons": ["字段[备注] usage=list 不支持预聚合", "…"],
+  "sheetConfig": "{\"dataPreAgg\":false,\"simpleList\":false}"
+}
+```
+
+---
+
+### 4.4 已验证写入路径（★ 2026-09-15 验证 · 交叉表/含公式格报表适用）
+
+`sheetConfig` 实际落点是 **workbook 的 `sheet.tag.sheetConfig`**（服务端 `sheetProps.sheetConfig` 回读）。对已有报表（尤其含 Formula 格）：
+
+1. `getReportDevInfo` 取 `fields[]`（全键）+ `sheetProps[0]`
+2. 反向重建 workbook：格子用构建态完整结构（typeName/editorType/subordination，Formula 格 cell 级带 `formula` 键），sheet 骨架按 `e10-cli report fix table-name` 的 18 键形态（theme/selections/colHeaderData/rowHeaderData 等一个不少），`tag.sheetConfig = {dataPreAgg:false, simpleList:false}`
+3. 保存走与 build spec 同通道：`saveReportDevInfo` form（`designKey:''` + gzip base64）——勿走 fix 门禁授权路径
+4. 回读确认：fields 数不变、Formula 格数不变、`sheetProps.sheetConfig` 含 `"dataPreAgg":false`
+
+验证：23 格（Formula 10）692ms 落库全存活，合并/父格不变，verify self 0 错 0 警。
+
+## 五、Agent 流程嵌入
+
+1. 获取字段元数据 → 运行 `e10-cli report py preagg`
+2. 若 `dataPreAgg=false`，在 save 载荷中写入 `sheetConfig`，并在 HTML 手册 `tips` 中注明「已关闭数据预聚合：原因…」
+3. 保存后 `getReportDevInfo` / 设计器「页面 → 解析优化」确认开关状态
+
+---
+
+## 六、相关文档
+
+- `report-designer-feature-map.md` — 解析优化入口
+- `report-knowledge-base.md` §1.2 — 预聚合概念
+- `report-delivery-contract.md` — 交付自检含预聚合项