weaver-e10-builder 1.6.9 → 1.6.11

package/skill-docs/references/report/golden-case-summary-sheet.md

@@ -0,0 +1,200 @@
+# 金标准案例 · 明细数据页 + 核心摘要页（业务专项统计报表）
+
+> 来源：报表 `1332025742762827883`（app `878284317729439749`），需求文件《业务专项统计报表-需求描述-优化版.xlsx》。
+> 用户 2026-10-30 明确认可「明细数据页配置完全正确」，本文件即该页的**逐格范式**，新建同类统计报表照此复刻。
+> 配套注意点：BUILD-113 / BUILD-114 / BUILD-115 / BUILD-116 / BUILD-117。
+
+---
+
+## 0. 页面命名铁律（BUILD-116）
+
+**sheet 名必须与需求文件的 sheet 页名 1:1 一致，不得自造 `Sheet0 / Sheet1 / Sheet2`。**
+
+| 场景 | 正确 | 错误 |
+|------|------|------|
+| 需求文件有「明细数据」「核心摘要」两页 | `sheets[i].name = '明细数据'` / `'核心摘要'` | `Sheet0` / `Sheet1` / `Sheet2` |
+| 需求文件未给页名 | 用业务含义命名（「明细数据」「汇总」），仍不得用 Sheet+序号 | 按 idx 机械命名 |
+
+蓝图里 `sheets[].name` 会被 `rebuild from-blueprint` 直写 `sheetProps[].name`，落库后用
+`getReportDevInfo` 的 `sheetProps` 回读核对（`dump cells` 标题行也会打印 `sheetIndex=N <页名>`）。
+
+```js
+// 一次性改多页命名
+bp.sheets[0].name = '明细数据';
+bp.sheets[1].name = '核心摘要';
+```
+
+> 已知事故：曾把第一页由 `Sheet1` 写成 `Sheet0`，用户当场指出「这种要莫就按照需求文件 sheet 页的名称命名，其他情况不要乱改」。
+
+---
+
+## 1. 明细数据页金标准（8 设计列 / 三模块 / 77 格）
+
+### 1.1 列骨架
+
+| 列 | 内容 | 类型 | 说明 |
+|----|------|------|------|
+| A | 专项负责人 | Field | `Vertical` 纵向根，`L(-1,-1)`，`top=本模块条` |
+| B | 专项名称 | Field | `L(x,0)`，跟随 A |
+| C | 所属大区/城市 | Field | `L(x,1)`，跟随 B |
+| D | 负责人拼接串 | Formula | `A{rn}&"（"&B{rn}&"/"&C{rn}&"）"`，`L(x,0)`，`NoExpand` |
+| E | 金额（年份锚） | Field `htzje` | `Horizontal` + `Group` + `groupType:'year'`，`top=本模块条` |
+| F | 合计金额 | Const | `top=本模块条`（与 E 同 top，否则 CROSS_TOP_MISSING） |
+| G | 数量（年份锚） | Field `id` | 同 E，第二组锚 |
+| H | 合计数量 | Const | 同 F |
+
+- 横向锚只占 **1 物理列**，按年份自动展开，**禁止**按年数预留空列（BUILD-66/67）。
+- 指标格 `displayType:'Count'` + `countType:'sum'`（金额）/ `'count'`（数量）。
+- 维度格 `displayType:'Group'` + `countType:'none'`。
+- 拼接公式行号 = **Excel 行号 = x+1**（同行引用），不是上一行（BUILD-71）。
+
+### 1.2 行骨架（每模块 4 行）
+
+```
+x=模块条行   【模块N】…            Const，yCount=列数（横向合并）
+x=表头行     负责人|专项名称|…|合计数量   Const ×8
+x=数据行     A..H 八格             数据区只写 1 行，人数由 A 列 Vertical 自动展开
+x=合计行     合计 | SUM(E{x})+…    A 列 Const「合计」+ 各指标 SUM
+```
+
+### 1.3 模块1：两组维度行（关键）
+
+「本区域」类指标必须**拆两组数据行**，因为 `所属大区/城市` 字段存两种粒度：
+
+| 组 | A 格 `customFilterField` | 指标格左父格筛选 | 覆盖的人 |
+|----|--------------------------|------------------|----------|
+| 组1 | `isDq Equals "1"` | `jgs Equals ← C` + `cplx Include ← B` | 所属填大区名（陕西大区/上海大区） |
+| 组2 | `isDq Equals "0"` | `dq Equals ← C` + `cplx Include ← B` | 所属填城市名（苏州/青岛） |
+
+源数据实证（`专项区域业务` 表单）：
+
+```
+令信通 | 王栋（西安） | 陕西大区 | isDq=是     → 需要 dq 匹配
+业票通 | 邓果成      | 苏州     | isDq=否     → 需要 jgs 匹配
+资管家 | 郭衍敏      | 青岛     | isDq=否     → 需要 jgs 匹配
+```
+
+⚠ 只配一组 ⇒ 另一半人金额恒 0（本次事故现象：摘要页「本区域纯专项金额」14 人里 12 人为 0）。
+
+两组共用一个合计行：`SUM(E{a})+SUM(E{b})`。
+
+### 1.4 模块2 / 模块3
+
+| 模块 | 数据源 | 指标格筛选 |
+|------|--------|-----------|
+| 模块2 纯专项（全量） | SQL 视图 | 仅 `cplx Include ← B`（专项名称），全国全量，不带区域条件 |
+| 模块3 混合合同（仅专项部分） | 专项方案表单 | `专项方案字段 Include ← B`，金额取 `专项方案金额` 字段 |
+
+### 1.5 指标格左父格（BUILD-115 铁律）
+
+```
+指标格 leftX = 本行 x，leftY = 2   ← 指向 C 列「所属大区/城市」真实 Field 格
+```
+
+**禁止指向 D 列拼接 Formula**：Formula 没有字段身份，`subordination[0]` / `filter.parentField` 解析不到父字段值 ⇒ **整列 0**。
+
+`subordination` = `[第一条条件的 parentField, 本格字段 fieldKey]`；两条条件时取第一条（区域维度）。
+
+### 1.5b 公式格左父格口径（BUILD-118，2026-10-30 用户截图点名）
+
+**数据行里的 Formula 格（拼接串 / 金额 SUM / 占比）左父格也必须指「具体的表单字段格」，不能挂 Const 自定义文本，也不能跨行指父**：
+
+| 公式格 | 左父格正确写法 | 用户截图实证 |
+|---|---|---|
+| D 列拼接 `A6&"（"&B6&"/"&C6&"）"` | 同行维度 Field（A 列负责人） | — |
+| F 列金额 `SUM(E6)` | 本行维度 Field 或本列块字段锚 | 明细数据 → 本列块字段锚 |
+| H/I 占比 `IFERROR(IF(G5=0,"-",F5/G5),"-")` | **分母字段格**（语义配对） | 核心摘要 H5 → G5 混合专项金额 |
+
+- 禁止：数据行公式 left 挂行首 Const（「合计」等自定义文本）→ 关联关系取不到父字段。
+- 禁止：跨行指父（如 H6 曾错指下一行 C7）→ 方向校验 `DIR_WRONG` 阻断 + 扩展上下文错乱。
+- **例外放行**：合计/总计行（本行无 Field 格）左父格挂行首 Const 是平台验收形态（V10.7 同构），不改——
+  把合计行公式父格改指数据行 Field 有被卷进纵向扩展的风险。
+- 门禁：`e10-cli report verify all` 第 ⑧ 组 `FORMULA_PARENT_CONST` / `FORMULA_PARENT_ROW_MISMATCH`（提示级 WARN）。
+
+### 1.6 筛选条件写法
+
+```json
+// leftFilterField
+[
+  {"index":27,"currentField":"<DS_S>.<SRC_S>.jgs","type":"Equals","parentField":"<DS_R>.<SRC_R>.field_…6055"},
+  {"index":31,"currentField":"<DS_S>.<SRC_S>.cplx","type":"Include","parentField":"<DS_R>.<SRC_R>.field_…6053"}
+]
+// customFilterField（入口格分支条件）
+[{"index":101,"currentField":"<DS_R>.<SRC_R>.field_…5939","type":"Equals","value":"1"}]
+```
+
+- `currentField` / `parentField` 三段式 `datasetId.nameIndex.field`（BUILD-94）。
+- 条件标识用 **`index`（全表唯一递增）**，不要写 `id`（BUILD-115）。
+- 文本包含匹配用 **`Include`**，不是 `Contain`。
+
+---
+
+## 2. 核心摘要页范式（6 可见列 + 3 零宽载体列）
+
+需求只要 6 列，但「负责人」列要求是**三字段拼接串** ⇒ 拼接格不能同时承担字段身份。
+解法：把三个维度字段放 **A/B/C 零宽列**，可见区从 D 开始。
+
+| 列 | 内容 | 宽 | 说明 |
+|----|------|----|------|
+| A | 专项负责人 | **0** | Field Vertical 根，父格筛选锚 |
+| B | 专项名称 | **0** | Field Vertical |
+| C | 所属大区/城市 | **0** | Field Vertical，指标格左父格指它 |
+| D | 负责人（拼接串） | 190 | `A{rn}&"（"&B{rn}&"/"&C{rn}&"）"` |
+| E | 本区域纯专项金额 | 150 | `htzje` sum |
+| F | 纯专项总金额 | 150 | `htzje` sum |
+| G | 混合专项金额 | 150 | `专项方案金额` sum |
+| H | 纯专项/混合占比 | 120 | `IFERROR(IF(G{rn}=0,"-",F{rn}/G{rn}),"-")` |
+| I | 本区/总纯专项占比 | 130 | `IFERROR(IF(F{rn}=0,"-",E{rn}/F{rn}),"-")` |
+
+```js
+// 隐藏列：cell.width = 0（BUILD-16，columns[].size=0）
+{ x:4, y:0, width:0 } ...
+```
+
+### 2.1 行骨架
+
+```
+x=0  标题   Const yCount=6，从 D 列起（y=3）
+x=1  副标题 Const yCount=6
+x=3  表头   Const ×6（A/B/C 也补表头，宽 0）
+x=4  数据组1  isDq=1 → E 用 jgs Equals
+x=5  数据组2  isDq=0 → E 用 dq Equals
+x=6  总计    E=SUM(E5)+SUM(E6) … H/I 按总计行本行重算
+```
+
+- 两组 root 格（A 列 `L(-1,-1)`）平台会**纵向串联成一段**，视觉上仍是一个连续人员清单。
+- 占比格左父格 = D（拼接，逐人扩展），与 SUM 公式指拼接列同理（Formula 作**公式格**左父格合法）。
+- 总计行「总计」标签放 D 列（可见首列），**不要**横向合并盖住 B/C/D（会丢指标）。
+
+### 2.2 验收数值（本报表验证）
+
+修复前后对比：
+
+| 项 | 修复前 | 修复后 |
+|----|--------|--------|
+| 可见列 | 9 列（表头 6 个，指标错位到「占比」表头下） | 6 列（D..I 对齐表头） |
+| 本区域纯专项金额 | 14 人里 12 人为 0 | 15 人全部有值 |
+| 占比公式 | 引 C5/D5（维度文本） | 引 F/G、E/F |
+| E5/F5 | 两格配置完全相同 | 口径分离（本区域 / 全量） |
+
+---
+
+## 3. 门禁与验收
+
+```bash
+BP="E:/.../bp.json"
+e10-cli report verify all --blueprint "$BP"     # 含 DIR_WRONG / FILTER_ID_DUP / FILTER_SEGMENT
+e10-cli report verify self --blueprint "$BP"
+e10-cli report verify self --blueprint "$BP"
+e10-cli report rebuild from-blueprint --blueprint "$BP"          # dry-run
+e10-cli report rebuild from-blueprint --blueprint "$BP" --apply
+# 按页渲染取数（2026-10-30 新增 --sheet）
+EB_ALLOW_RENDER=1 e10-cli report render values <reportId> <appId> 60 --sheet=1 --max-cols=10
+```
+
+- `DIR_WRONG` 会拦「左父格在右方」——零宽载体列必须放**左侧**，不能放右侧。
+- 渲染出来的 Formula 格 `value` 为 `null`、只带 `formula` 字符串属**正常**（服务端不算公式，前端 SpreadJS 计算）；判读标准是 Field 格有没有值。
+- Field 格全 0 ⇒ 先查左父格是否指到 Formula 列、筛选是否缺 `parentField`。
+
+### 3.1 逐格体检脚本
+

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

@@ -42,7 +42,12 @@ e10-cli report build --spec spec.json --dry-run # 只看定源与字段绑定，
 | `layout` | `{ title, freezeRows, showLocation }` |
 | `style` / `titleStyle` / `headerStyle` / `bodyStyle` | 分层样式；不给就是默认表头样式 |
 
-列的可选项：`width`、`format`（`货币`/`短日期`/`百分比`…，见 `cell-config-echo-guide.md`）、`formula`（公式列不参与字段绑定）、`groupType`（日期分组）、`rule`（条件格式，见 `condition-format-guide.md`）、`field` / `fieldName`（显式指定字段）。
+列的可选项：`width`、`format`（`货币`/`短日期`/`百分比`…，见 `cell-config-echo-guide.md`）、`formula`（公式列不参与字段绑定）、`groupType`（日期分组）、`rule`（条件格式，见 `condition-format-guide.md`）、`field` / `fieldName`（显式指定字段）、`aggregate`（汇总方式，见下）、`display: "tree"`（折叠树形）、`sort`（`asc` / `desc`）。
+
+**汇总列**：`"aggregate": "sum"`（或 `count`/`max`/`min`/`avg`）。同一行维度下聚合成一行，不会被子记录撑开。
+汇总格的左父格会自动锚到**行维度入口列**（最左边那列普通字段），不需要手写父格。
+配 `layout.totalRow: true` 追加合计行；合计列是 `SUM(整列)` 的公式格，行首是 Const「合计」。
+回读时显示方式会被规范化成「分组」，属正常现象；`e10-cli report verify anchors` 可复检。
 
 ---
 

package/skill-docs/references/report/hidden-row-and-header-merge-guide.md

@@ -29,8 +29,8 @@ Excel 里 `ht="0" hidden="1"` 的行（常见用途：表头与数据之间的**
 
 ```js
 spans = [
- { row: 2, col: 0, rowCount: 2, colCount: 1 }, // 固定列表头纵向合并（Excel B3:B4）
- { row: 2, col: 45, rowCount: 1, colCount: 3 }, // 日期区横向合并（Excel AU3:AW3）
+  { row: 2, col: 0,  rowCount: 2, colCount: 1 },   // 固定列表头纵向合并（Excel B3:B4）
+  { row: 2, col: 45, rowCount: 1, colCount: 3 },   // 日期区横向合并（Excel AU3:AW3）
 ]
 ```
 
@@ -44,7 +44,7 @@ spans = [
 
 1. **`row`/`col` 是 0-based**，而 Excel 的 `mergeCells` 是 1-based → 换算 `row = excelRow - 1`、`col = excelColNum - 1`。
 2. 日期/交叉维度区块本就必须 `colCount = 块宽`（本包默认日期块 3 列），**不要再叠加一次**，否则块宽翻倍。
-3. **只写 `spans` 即可生效**，可不写 cell 级 `rowCount`/`colCount`（服务端统一按 spans 回写 `xCount`/`yCount`）。
+3. 验证：**只写 `spans` 即可生效**，可不写 cell 级 `rowCount`/`colCount`（服务端统一按 spans 回写 `xCount`/`yCount`）。
 4. 合并区内的非左上角单元格**不要放内容**（Excel 同理），否则合并语义混乱。
 
 ### 从 Excel 提取 mergeCells（本环境 xlsx 常被 openpyxl 拒读）
@@ -56,7 +56,7 @@ import zipfile, xml.etree.ElementTree as ET
 NS = "{http://schemas.openxmlformats.org/spreadsheetml/2006/main}"
 sh = ET.fromstring(zipfile.ZipFile(path).read("xl/worksheets/sheet1.xml"))
 mc = sh.find(f"{NS}mergeCells")
-refs = [m.attrib["ref"] for m in mc.findall(f"{NS}mergeCell")] # ["B3:B4", "AU3:AW3", ...]
+refs = [m.attrib["ref"] for m in mc.findall(f"{NS}mergeCell")]   # ["B3:B4", "AU3:AW3", ...]
 ```
 
 映射规律（常见表头）：
@@ -74,18 +74,18 @@ refs = [m.attrib["ref"] for m in mc.findall(f"{NS}mergeCell")] # ["B3:B4", "AU3:
 只能看 `fields`（含 `xCount`/`yCount`）——**不能证明渲染效果**。要看用户到底看见什么，必须走渲染链：
 
 ```
-POST /api/edc/report/view/analysis (multipart；sheetId=reportId、pageFilter、pageNum…)
- → data.json[0] = sessionKey
-GET /api/edc/report/view/getJsonStr?sessionKey=<key>
- → gunzip → workbook（含展开后的 dataTable / rows / spans）
+POST /api/edc/report/view/analysis   (multipart；sheetId=reportId、pageFilter、pageNum…)
+   → data.json[0] = sessionKey
+GET  /api/edc/report/view/getJsonStr?sessionKey=<key>
+   → gunzip → workbook（含展开后的 dataTable / rows / spans）
 ```
 
 判据：
 
 - **无多余空行**：下一行（0-based = `数据行 index`）应已是非空数据行。
- 例：表头 r2、星期 r3 → r4 必须是数据（此前 r4 全空 = 事故）。
+  例：表头 r2、星期 r3 → r4 必须是数据（此前 r4 全空 = 事故）。
 - **表头合并生效**：渲染 `spans` 中应存在 `{row:表头行, rowCount:2, colCount:1}` 共 N 条（N=固定列数）、
- 以及 `{row:表头行, col:日期起始列, colCount:块宽}`。
+  以及 `{row:表头行, col:日期起始列, colCount:块宽}`。
 
 ⚠️ 渲染有 **50000 单元格上限**（超限 `code:555`）。估算：`渲染行数 × 列数`。
 本例 `1004 × 48 ≈ 48192` 勉强过关；列维度一展开就会超，需靠默认查询条件收敛。

package/skill-docs/references/report/layout-showlocation-freeze-guide.md

@@ -7,7 +7,7 @@
 
 ## 一、报表显示位置 `showLocation`
 
-### 1.1 UI → 存储枚举（前端 ）
+### 1.1 UI → 存储枚举（前端验证）
 
 设计器「页面 → 页面布局 → 报表显示位置」写入：
 
@@ -38,6 +38,35 @@
 
 宽表（列宽×列数 ≥ 视口）时居左/居中视觉差可能不明显；仍须按枚举正确落库，不得因「看起来一样」改回错误值。
 
+### 1.5 ⚠️⚠️ 血案：手写 workbook 漏 `tag` → 显示位置被静默改成居中（2026-09-14）
+
+**症状**：修完 `tableName` 后用户反馈「报表上还是显示的不对」，定位 `fields[]`/`verify bind`/
+`listWithPageReport` **全部正常**，最终定位 `sheetProps.showLocation` 从 `1` 变成了 `2`。
+
+**根因**：用**手写临时脚本**构造 workbook 落库时，sheet 里**没有 `tag` 字段**（`tag: null`）。
+按 §1.2：**tag 为 null 时服务端默认写 `2`** → 居左被静默改成居中。
+
+**对比证据**：
+
+| 构建方式 | sheet 键数 | `tag` | showLocation 结果 |
+|---|---|---|---|
+| CLI 正规路径（`e10-cli report fix table-name` → `buildWorkbook`） | **18** | 完整对象 | ✅ 保留原值 `1` |
+| 手写临时脚本 | 7 | `null` | ❌ 被改成 `2` |
+
+CLI 正规路径的 `tag` 含：
+`childMerge` / `showLocation` / `filterSheet` / `tableNameSuffix` / `columnConfig` / `sheetConfig`；
+sheet 还含 `theme` / `names` / `__rowColHeaderVisible` / `__gridline` / `__printLineVisible` /
+`selections` / `colHeaderData` / `rowHeaderData` —— **这些都影响设计器渲染，一个都不能少**。
+
+**★ 铁律：禁止用「手写临时 workbook」直接落库生产报表。**
+服务端对缺失的非必填键**静默回落默认值**（不报错、不提示、无 diff 可查）。
+必须走 CLI 正规构建路径。
+
+**已加的护栏**：
+- `e10-cli report fix table-name` 新增 `--show-location 1|2`（显式修正）
+- dry-run 汇报打印 `显示位置 showLocation: live=X → 重建=Y (居左/居中)`
+- 落库后回读校验 `showLocation`，不一致计入失败判定
+
 ---
 
 ## 二、冻结单元格 / 冻结表头
@@ -108,18 +137,18 @@
 ```java
 Optional<AnalysisField> obj = this.fields.stream().filter(d -> d.getFixed() == 1).findFirst();
 OffSet cell = obj.get().getMinCell();
-setFrozenRowCount(cell.getX()); // 冻结锚点上方各行
-setFrozenColumnCount(cell.getY()); // 冻结锚点左侧各列
+setFrozenRowCount(cell.getX());      // 冻结锚点上方各行
+setFrozenColumnCount(cell.getY());   // 冻结锚点左侧各列
 ```
 
 **推论（三条）**
 
 1. **锚点格不必是空格**。设计器 `setFixedCellByTarget` 只在锚点格 `cellType.typeName` 为假（空格）时才补写
- `cellText="fixed-cell-tag"` + 透明样式；**占用格（数据字段所在格）它什么都不写**，只更新内存里的 `tag.fixedCell`。
- 所以「用 API 把锚点设在数据格上」是**唯一可行**的做法 —— 只置 `tag.fixed` 即可，预览照样冻结。
+   `cellText="fixed-cell-tag"` + 透明样式；**占用格（数据字段所在格）它什么都不写**，只更新内存里的 `tag.fixedCell`。
+   所以「用 API 把锚点设在数据格上」是**唯一可行**的做法 —— 只置 `tag.fixed` 即可，预览照样冻结。
 2. **禁止**顺手给锚点格写 `cellText="fixed-cell-tag"`：服务端会据此把该格**边框 4 边 + 底色清空**
- （`CustomEngine`/`SimpleListEngine` 的 `field.getFixed()==1 && "fixed-cell-tag".equals(cellText)` 分支），
- 属于改动未点名格的样式。
+   （`CustomEngine`/`SimpleListEngine` 的 `field.getFixed()==1 && "fixed-cell-tag".equals(cellText)` 分支），
+   属于改动未点名格的样式。
 3. **`fixed=1` 的字段必须唯一**。`findFirst()` 取的是字段列表里第一个 `fixed==1`，多个会以第一个为准（顺序 = x 升序、同 x 按 y）→ 落库前先清掉所有旧 `fixed`。
 
 **锚点坐标怎么选**
@@ -135,8 +164,8 @@ CLI：`e10-cli report fix freeze --report-id <id> --app-id <aid> --anchor 4,3 [-
 
 1. **重建保真度不足**（除冻结点外与线上 `fields[]` 有差异）→ 拒绝，避免误伤；
 2. **重复坐标**（同一 `(x,y)` 在 `fields[]` 里有 ≥2 条记录）→ 报 `exit 3` 并列出各条 `id/createTime`。
- 典型成因：**在设计器里把字段拖到某个表头格上**，旧 Const 未被清掉 → 该格"表头 + 字段"两条记录并存。
- 此时 workbook 一个坐标只能放一格，重建必然丢一条 → 必须先由用户确认取舍（或先去设计器清理）。
+   典型成因：**在设计器里把字段拖到某个表头格上**，旧 Const 未被清掉 → 该格"表头 + 字段"两条记录并存。
+   此时 workbook 一个坐标只能放一格，重建必然丢一条 → 必须先由用户确认取舍（或先去设计器清理）。
 
 ---
 
@@ -164,4 +193,4 @@ CLI：`e10-cli report fix freeze --report-id <id> --app-id <aid> --anchor 4,3 [-
 | `targeted-fix-guide.md` | 定点范围；样式禁碰 |
 | `report-designer-feature-map.md` §4.2 / §4.6 | UI 入口索引 |
 | `safe-partial-save-guide.md` | 完整 workbook 写回 |
-| `safe_report_save.js` → `fieldToCell` | 须把 `fixed` 写入 `cell.tag.fixed` |
+| `` → `fieldToCell` | 须把 `fixed` 写入 `cell.tag.fixed` |

package/skill-docs/references/report/multi-report-crosstab-casebook.md

@@ -0,0 +1,263 @@
+# 多报表交叉表搭建实战案例集（2026-10-29 ~ 10-30 · 业务专项统计报表）
+
+> 本文件是**实战复盘 + 可复用蓝图模板**，配套 `SKILL.md` A0.13 / A0.13.1 强制规则。
+> 案例报表：`1331872953607685192`「业务专项统计报表chl202610300310」（应用 `878284317729439749`）。
+> 参考报表（已验收基准）：`1331796692140359741`「chl测试专项业务202610292211」。
+
+---
+
+## 一、本案例的结构画像
+
+| 项 | 值 |
+|---|---|
+| sheet 数 | 2（`明细数据` / `核心摘要`） |
+| 明细数据格数 | **79**（合并标题后从 163 降下来） |
+| 核心摘要格数 | **30** |
+| 报表块数 | 明细 3 块（模块1 / 模块2 / 模块3）+ 摘要 1 块 |
+| 是否交叉表 | 是（4 个横向锚：`E4/G4`、`E10/G10`） |
+| 列布局 | 8 列：`A 负责人 / B 专项名称 / C 所属大区城市 / D 拼接公式 / E 年份金额 / F 合计金额 / G 年份数量 / H 合计数量` |
+| 数据集 | `xz=`专项区域业务(业务模块) `ht=`专项统计-直销合同-商务(数据加工) |
+
+---
+
+## 二、★ 血案一：所有字段被绑到同一个数据集（最高频 · 必看）
+
+### 症状
+- 设计器右侧「数据集合」显示的是**同一个表**，跟字段实际该取的表不符；
+- 字段回显空白 / 显示 `field_13xxxxxxxx` 原始 key；
+- 报表预览取不到值，全 0 或全空。
+
+### 根因（`e10-cli report rebuild from-blueprint` 第 236 行）
+```js
+const ds = idx.byKey[c.datasetKey || 'default'] || (c.datasetKey ? undefined : idx.all[0]);
+```
+**没写 `datasetKey` 的 Field 格 → 一律回退到 `idx.all[0]`（蓝图 `datasets[]` 的第一个）。**
+而且 `buildCell()` 第 124-126 行会用解析出的 `ds` **重算覆盖** `dataSetId / nameIndex / fieldKey`：
+```js
+cell.dataSetId = String(ds.id);
+cell.nameIndex = String(ds.nameIndex || '');
+cell.fieldKey = `${ds.id}.${cell.nameIndex}.${bp.name}`;
+```
+→ 蓝图里 `dataSetId` 写得再对，**只要漏了 `datasetKey`，落库就是错的**，且回读校验「fieldKey 三段自洽」照样 PASS（因为它自洽地绑错了）。
+
+### 铁律
+**每个 Field 格必须同时给 4 个键，缺一不可**：
+
+| 键 | 值 | 说明 |
+|---|---|---|
+| `datasetKey` | `'xz'` / `'ht'` | ★★ 落库脚本按它选数据集，漏了必错 |
+| `dataSetId` | 数据集 id | 蓝图自检用 |
+| `nameIndex` | 数据集 sourceId | 三段 key 的第二段 |
+| `fieldKey` | `${id}.${sourceId}.${fieldName}` | 三段自洽 |
+
+生成器里封装成工厂函数，并内置自检：
+```js
+function FD(x, y, fieldName, text, dsObj, opt = {}) {
+  const o = {
+    x, y, cellType: 'Field', sheetIndex: opt.sheetIndex || 0,
+    name: fieldName,
+    text: text || fieldName,                 // 数据显示名，设计器拿它当回显
+    tableName: TBL[opt.dsKey || 'xz'],       // 面板显示名（带添加类型后缀）
+    datasetKey: opt.dsKey || 'xz',           // ★★ 必须落进蓝图
+    dataSetId: dsObj.id,
+    nameIndex: dsObj.src,
+    fieldKey: `${dsObj.id}.${dsObj.src}.${fieldName}`,
+    ...
+  };
+  cells.push(o); return o;
+}
+
+// 自检：任一 Field 缺 datasetKey / text / fieldKey 即中止
+const badField = cells.filter(c => c.cellType === 'Field' &&
+  (!c.text || !c.fieldKey || c.fieldKey.split('.')[0] !== c.dataSetId || !c.datasetKey));
+if (badField.length) { console.error('!! Field 格不合规', badField.length); process.exit(1); }
+```
+
+### 验伪方法（落库后必做）
+```bash
+# 看横向锚那一格：
+#   dataSetId / nameIndex / fieldKey / tableName 必须同时指向**正确的那张表**
+```
+
+---
+
+## 三、★ 血案二：标题行没合并
+
+### 症状
+大标题 / 副标题 / 模块条文字挤在 A 列，右侧留白一大片，与参考报表不一致。
+
+### 根因
+上一版写成「1 个实格 + N-1 个空 `Const` 占位格」——视觉上**不是合并**。
+参考报表的做法是**单格横向合并**：`xCount=1, yCount=列数`。
+
+### 正确写法
+```js
+function BAR(x, text, si, st, n) {
+  guard(x, 0, si);
+  cells.push({
+    x, y: 0, cellType: 'Const', sheetIndex: si,
+    cellText: text,
+    xCount: 1, yCount: n || NCOL,      // ★ 横向合并列数
+    topX: x === 0 ? -1 : 0, topY: x === 0 ? -1 : 0,
+    width: 150, style: st,
+  });
+}
+```
+参考报表验证（`1331796692140359741`）：
+```
+x=0 y=0 Const xCount=1 yCount=8 "业务专项统计报表"
+x=1 y=0 Const xCount=1 yCount=8 "统计周期 2023-2026 · 单位：元"
+x=2 y=0 Const xCount=1 yCount=8 "本区域纯专项"
+x=8 y=0 Const xCount=1 yCount=8 "纯专项（全量）"
+```
+**注意**：合并后不再需要那 N-1 个空格，格数会明显下降（本例 163 → 109），这是正常的。
+
+---
+
+## 四、★ 血案三：横向锚的上父格挂错（A0.13.1 的由来）
+
+### 症状
+- 年份列展开后，模块标题条不跟着撑宽，右侧留白；
+- 或合计列（合计金额 / 合计数量）被横向锚带着逐列重复。
+
+### 强制规则（A0.13.1）
+多块 + 交叉表 + 有独立标题行的块内：
+**横向扩展字段本身 + 它右侧所有单元格，上父格一律显式设为「本块标题行」，不写公共父格 `0,0`、不留 `-1,-1`。**
+
+```js
+// 模块块渲染：headX 是表头行，barX 是块标题条行
+FD(headX, Y_AMT, 'qdnf', 'qdnf', DS.ht, {
+  dsKey: 'ht', sheetIndex: si, expandType: 'Horizontal', orderType: 'asc',
+  topX: barX, topY: 0,          // ★★ 上父格 = 本块标题行（不是 0,0）
+  width: W[4], style: ST.head,
+});
+```
+
+### 与之配套的判定宽容（否则死循环）
+平台每次保存会把 `left=-1,-1` 归一成公共父格，所以 `scene check` 必须接受两跳链：
+**表头格 `top=标题行` → 标题条 `top=公共父格`**，视为合规（`boundToPublicParentChained()`）。
+详见 `SKILL.md` BUILD-60 / BUILD-62。
+
+---
+
+## 五、勾稽规则速查（父格该挂谁）
+
+| 单元格类型 | 左父格（`leftX/leftY`） | 上父格（`topX/topY`） |
+|---|---|---|
+| 块标题条（合并 `yCount>1`） | `-1,-1` | 首块 `-1,-1`；非首块 `0,0` |
+| 表头行 Const（行内非空 Const ≥2） | `-1,-1` | `0,0`（或经标题条两跳） |
+| 行维入口格（首个 `Vertical` 字段） | `-1,-1` | `0,0` |
+| 入口格右侧数据格 | `left=入口格坐标` | **`-1,-1`**（绑了 `top=0,0` 会判泛化禁令违规） |
+| 横向扩展锚 | 跟随块内逻辑 | **本块标题行**（A0.13.1） |
+| 横向锚右侧的合计列表头 | `-1,-1` | **本块标题行** |
+| 数据行的合计列公式 | `left=同行入口格` | 本块标题行 |
+| 合计行 | `left=合计行标签格` | 本块标题行 |
+| 待接占位表头行（字段未接入） | `-1,-1` | `0,0`（整行都要归集） |
+
+> `scene apply` **只补 `isActiveParent`，不修父格归属** —— 父格必须在蓝图里一次写对。
+
+---
+
+## 六、样式配色规范（8 种样式族 · 抄参考报表）
+
+| 用途 | `backColor` | `foreColor` |
+|---|---|---|
+| 大标题 | `#2E5E9E` | `#FFFFFF` |
+| 副标题 | `#EAF1F9` | `#44546A` |
+| 模块条 | `#2E75B6` | `#FFFFFF` |
+| 表头行 | `#E6E6E6` | `#333333` |
+| 数据行 | `#fff` | `#333333` |
+| 合计行 | `#FFF2CC` | `#333333` |
+| 待接模块条 | `#7F7F7F` | `#FFFFFF` |
+| 待接表头 | `#F2F2F2` | `#595959` |
+
+```js
+function style(bg, fg, opts = {}) {
+  return JSON.stringify({
+    backColor: bg, backgroundImageLayout: 0,
+    borderBottom: { color: '#999', style: 1 }, borderLeft: { color: '#999', style: 1 },
+    borderRight: { color: '#999', style: 1 }, borderTop: { color: '#999', style: 1 },
+    font: opts.font || '12px 微软雅黑', foreColor: fg,
+    formatter: '',                              // 「常规」= '' 或 'General'，禁 'common'
+    hAlign: opts.hAlign === undefined ? 1 : opts.hAlign,
+    textDecoration: 0, textIndent: 0.0, themeColor: true, vAlign: 1, wordWrap: true,
+  });
+}
+```
+
+---
+
+## 七、跨表关联筛选标准写法
+
+```js
+// 左边的 parentField 是本行维度字段，右边 currentField 是要取数的表的字段
+const fFzr  = { parentField: fk(DS.xz, 'field_…6054'), currentField: fk(DS.ht, 'zxfzr'), type: 'Equals',  id: fk(DS.ht, 'zxfzr') };
+const fCplx = { parentField: fk(DS.xz, 'field_…6053'), currentField: fk(DS.ht, 'cplx'),  type: 'Contain', id: fk(DS.ht, 'cplx') };
+const fDq   = { parentField: fk(DS.xz, 'field_…6055'), currentField: fk(DS.ht, 'dq'),    type: 'Equals',  id: fk(DS.ht, 'dq') };
+const fJgs  = { parentField: fk(DS.xz, 'field_…6055'), currentField: fk(DS.ht, 'jgs'),   type: 'Contain', id: fk(DS.ht, 'jgs') };
+```
+
+**约定**：
+- `id` **必须等于** `currentField`（否则设计器筛选项回显不出来）；
+- 同一个「所属大区城市」字段，在 A 模块用 `Equals dq`、在 B 模块用 `Contain jgs` ——
+  这就是「同一字段两套筛选」的标准表达，**写在不同的行**，各配各的 `customFilterField`；
+- 本行自定义筛选（拆两行那种）：
+```js
+[{ currentField: fk(DS.xz, 'field_…5939'), id: fk(DS.xz, 'field_…5939'), type: 'Equals', value: '1' }]
+// 下拉字段 value 填 '1' / '0'，不是「是」「否」文字
+```
+
+---
+
+## 八、命令速查（本案例全程用到的）
+
+```bash
+export EB_ETEAMSID="<取本机凭证>"
+export EB_HOST="https://www.e-cology.com.cn"
+
+# ★ 蓝图路径必须写盘符 E:/...，不能写 /e/...（会拼成 E:\e\...）
+e10-cli report rebuild from-blueprint --blueprint "E:/.../bp-v14.json" --apply
+
+# 场景校验 + 定点补丁
+e10-cli report scene apply --report-id <rid> --app-id <appId> --scene A --apply
+e10-cli report scene check --report-id <rid> --app-id <appId> --scene A
+e10-cli report preflight --report-id <rid> --app-id <appId>
+e10-cli report dataset id-check --report-id <rid> --app-id <appId>
+
+# 回读验伪
+```
+
+---
+
+## 九、本次会话注意清单（补充进 pitfalls 索引）
+
+| 编号 | 坑 | 后果 | 规避 |
+|---|---|---|---|
+| **BUILD-65** | Field 格漏写 `datasetKey` | **全部字段被绑到 datasets[0]**，取不到值、回显空白 | FD 工厂强制 4 键 + 自检 |
+| **BUILD-66** | 标题用「1 实格 + N-1 空格」 | 标题不合并，右侧留白 | 单格 `yCount=列数` |
+| **BUILD-67** | 横向锚及其右侧上父格写 `0,0` | 标题不撑宽 / 合计列随锚复制 | A0.13.1：上父格 = 本块标题行 |
+| **BUILD-68** | 数据格（入口右侧）写 `top=0,0` | `scene check` 判「泛化禁令」违规 | 数据格只 `left=入口格`，`top` 留 `-1,-1` |
+| **BUILD-69** | 待接占位表头行 Const 留 `-1,-1` | 判「表头行未按方向统一到公共父格」 | 整行 Const 都写 `0,0` |
+| **BUILD-70** | `--blueprint` 传 `/e/...` | `ENOENT E:\e\...` | 传 `E:/...` 盘符路径 |
+| **BUILD-71** | 误以为 `scene apply` 能修父格 | 它只补 `isActiveParent`，白跑一轮 | 父格在蓝图里写对 |
+
+---
+
+## 十、可复用蓝图骨架
+
+```js
+const DS = {
+  xz: { id: '<dataset1>', src: '<sourceId1>', name: '表A' },
+  ht: { id: '<dataset2>', src: '<sourceId2>', name: '表B' },
+};
+const TBL = { xz: '表A(业务模块)', ht: '表B(数据加工)' };
+
+// 块渲染：barX 标题条 / headX 表头行 / rows 数据行 / footX 合计行
+function renderBlock(barX, headX, rows, footX, si, modes) {
+  // 表头：行维标题 Const → 写 top=0,0
+  // 横向锚 ×2：expandType=Horizontal, orderType=asc, topX=barX  ← A0.13.1
+  // 横向锚右侧合计标题 Const：topX=barX, leftX=-1  ← A0.13.1 + 断左父格
+  // 数据行：入口格 top=0,0；右侧数据格 left=入口格 + top=-1,-1
+}
+```
+