weaver-e10-builder 1.6.14 → 1.6.16

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

@@ -1,263 +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
-}
-```
-
+# 多报表交叉表搭建实战案例集（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
+}
+```
+