weaver-e10-builder 1.6.10 → 1.6.12

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

@@ -0,0 +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（标题行随块复制同源机制）

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

@@ -28,7 +28,7 @@
 3. 结合已规划的报表字段（displayType、customFilterField）运行检测脚本
 
 ```bash
-python e10-cli report py preagg --fields-json <fields.json> [--layout-json <report_fields.json>]
+e10-cli report py preagg --fields-json <fields.json> [--layout-json <report_fields.json>]
 ```
 
 ---
@@ -59,12 +59,12 @@ python e10-cli report py preagg --fields-json <fields.json> [--layout-json <repo
 
 ```json
 {
- "0": {
- "rowHeader": 0,
- "colHeader": 0,
- "gridLine": 0,
- "sheetConfig": "{\"dataPreAgg\":false,\"simpleList\":false}"
- }
+  "0": {
+    "rowHeader": 0,
+    "colHeader": 0,
+    "gridLine": 0,
+    "sheetConfig": "{\"dataPreAgg\":false,\"simpleList\":false}"
+  }
 }
 ```
 
@@ -74,27 +74,38 @@ python e10-cli report py preagg --fields-json <fields.json> [--layout-json <repo
 
 ```json
 "sheetProps": {
- "sheetConfig": "{\"dataPreAgg\":false,\"simpleList\":false}"
+  "sheetConfig": "{\"dataPreAgg\":false,\"simpleList\":false}"
 }
 ```
 
 ### 4.3 脚本辅助
 
-`check_preaggregate_support.py` 输出：
+`e10-cli report py preagg` 输出：
 
 ```json
 {
- "dataPreAgg": false,
- "reasons": ["字段[备注] usage=list 不支持预聚合", "…"],
- "sheetConfig": "{\"dataPreAgg\":false,\"simpleList\":false}"
+  "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. 获取字段元数据 → 运行 `check_preaggregate_support.py`
+1. 获取字段元数据 → 运行 `e10-cli report py preagg`
 2. 若 `dataPreAgg=false`，在 save 载荷中写入 `sheetConfig`，并在 HTML 手册 `tips` 中注明「已关闭数据预聚合：原因…」
 3. 保存后 `getReportDevInfo` / 设计器「页面 → 解析优化」确认开关状态