weaver-e10-builder 1.6.15 → 1.6.16

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

@@ -1,200 +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 逐格体检脚本
-
+# 金标准案例 · 明细数据页 + 核心摘要页（业务专项统计报表）
+
+> 来源：报表 `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 逐格体检脚本
+