weaver-e10-builder 1.6.10 → 1.6.12

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

@@ -0,0 +1,69 @@
+# 档案式报表 · 场景 G（SKILL A0.17）
+
+> 典型案例：FineReport「帆软集团基本档案」—— 一个实体一份档案，纵向多区块：
+> ①基本信息（左右两组标签/值网格）②教育经历（标题条+表头行+多行明细）
+> ③工作经历（同上）④职称资格（单行带）⑤培训记录；**保持 A4 自然分页**（第1页/共3页）。
+
+---
+
+## 一、案例解析（特性 → 机制 → CLI 落点）
+
+| # | 特性 | 机制 | CLI 落点 |
+|---|---|---|---|
+| ① | 一个实体一份档案（基本信息区） | 标签 Const + 值 Field 链式跟随（卡片机制同源），**不扩展或随实体锚点扩展** | 单源：`card build` cells 网格直写（label/value） |
+| ② | 多个一对多明细带（教育/工作/培训） | **每个带 = 独立扩展块**：带锚点 = 带内首格 Field（Vertical 扩展），带标题条+表头行 Const 左父格挂**公共父格或带锚点**（场景 A 三类口径：入口格/标题行/表头行整行 Const），带内数据格默认链 | 多源走 `rebuild from-blueprint`（`datasets[]` + 格上 `datasetKey`）；带结构同场景 A 多扩展块 |
+| ③ | 多数据源（主表 + N 个子表） | 主表一个数据集，每个子表单/明细各自 addDataset，格按 `dataSetId` 归片 | **datasetId 隔离铁律照常**：`check-ids` / `assertNoStaleDatasetIds` |
+| ④ | A4 自然分页（第N页/共M页） | 分页**开着**（默认）—— 与段落/卡片式（不分页）**相反** | card spec **不要写** `pageSetting.pagination:false`；要显式则 `pagination:true`。跨页时区块/明细带是否断行 = 平台渲染（验证项） |
+
+## 二、与相近场景的边界
+
+| 场景 | 数据形态 | 分页 | 通道 |
+|---|---|---|---|
+| 卡片式（发票） | 一条记录=一张卡片，块内 label/value | 不分页 | `card build`（单源） |
+| 段落明细表 | 同上，块内多信息区 | 不分页 | `card example paragraph` |
+| **档案式（本节）** | **一个实体 + N 个一对多明细带**（通常多数据集） | **分页开** | 单源 `card build` / 多源 `rebuild from-blueprint` |
+| 分页分组报表（E） | 平铺列表 + 分组 + 每页 N 行 | 固定行数分页 | `build spec` |
+
+## 三、多源档案 spec 骨架（rebuild from-blueprint）
+
+```json
+{
+  "datasets": [
+    { "key": "main",  "sourceId": "<主表sid>",  "sourceName": "<主表>" },
+    { "key": "edu",   "sourceId": "<教育子表sid>", "sourceName": "<教育经历>" },
+    { "key": "work",  "sourceId": "<工作子表sid>", "sourceName": "<工作经历>" }
+  ],
+  "cells": [
+    { "r": 0, "c": 0, "text": "基本信息", "span": 4, "style": { "back": "#BDD7EE", "bold": true } },
+    { "r": 1, "c": 0, "text": "编号" },  { "r": 1, "c": 1, "datasetKey": "main", "field": "编号" },
+    { "r": 1, "c": 2, "text": "姓名" },  { "r": 1, "c": 3, "datasetKey": "main", "field": "姓名" },
+    { "r": 3, "c": 0, "text": "教育经历", "span": 5, "style": { "back": "#BDD7EE", "bold": true } },
+    { "r": 4, "c": 0, "text": "学习时间" }, { "r": 4, "c": 1, "text": "性质" }, { "r": 4, "c": 2, "text": "学历" }, { "r": 4, "c": 3, "text": "学校" }, { "r": 4, "c": 4, "text": "专业" },
+    { "r": 5, "c": 0, "datasetKey": "edu", "field": "学习时间", "expand": "Vertical", "isActiveParent": true },
+    { "r": 5, "c": 1, "datasetKey": "edu", "field": "性质", "left": [5, 0] },
+    { "r": 5, "c": 2, "datasetKey": "edu", "field": "学历", "left": [5, 0] },
+    { "r": 5, "c": 3, "datasetKey": "edu", "field": "学校", "left": [5, 0] },
+    { "r": 5, "c": 4, "datasetKey": "edu", "field": "专业", "left": [5, 0] }
+  ]
+}
+```
+
+- 带标题条/表头行：整行 Const 左父格挂**公共父格**（场景 A）或带锚点；不可悬空（悬空 = 随机扩展事故）。
+- 每带锚点 `isActiveParent:true` 且**各带锚点独立**；带间用空行/标题条隔开。
+
+## 四、搭建提示语句（用户照此说即可）
+
+> 按档案式报表搭一张「XX基本档案」：一个实体一份档案，纵向分区块——
+> 「基本信息」（标签/值网格，字段 A/B/C/D…）＋「教育经历」（表头：时间/性质/学历/学校/专业，一对多明细）
+> ＋「工作经历」（表头：…）＋「培训记录」（表头：…）；
+> 主表 sourceId `<sid0>`，各明细子表 sourceId `<sid1/sid2/…>`（appId `<appId>`）；
+> 保持 A4 自然分页；多源走 `rebuild from-blueprint`（datasets[]+datasetKey），
+> 落库后回读验收：各带锚点独立扩展、带标题/表头行父格齐全、check-ids 无外来 datasetId。
+
+## 五、验证清单
+
+1. 回读：每个明细带锚点 `expandType=Vertical` 且各带独立；带内数据格左父格→带锚点
+2. 带标题条/表头行 Const 的左父格指向公共父格/带锚点（非悬空）
+3. 多源：`e10-cli report check-ids` exit 0；各格 `fieldKey` 首段 == 本格 `dataSetId`
+4. 分页：`allPageSetting` pagination=true（或未写 false）
+5. 单实体/多实体表现（整份档案是否随实体复制）以设计器确认为准；验证后回填本指南

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

@@ -0,0 +1,75 @@
+# 数据钻取类报表 · 指南（SKILL A0.14 · 场景 D）
+
+> 形态：**列表报表 + 行级钻取**（官方 demo「订单信息列表」类）：
+> ① **多维度钻取** —— 点击订单号钻取订单明细 / 物流信息（跳其他报表并按当前行值过滤）；
+> ② **列排序** —— 点击订购日期按升/降序查看；
+> ③ **行级导出/打印明细** —— 每行「导出」链接（详见 §三能力边界）。
+> 固化：2026-10-29 · 落地点 = `build spec` 的 `columns[].link` / `columns[].sort`（通用建表器内置，禁止临时脚本）。
+
+## 一、能力 → 落库键映射
+
+| 需求 | 落库键 | 语法 | 规则来源 |
+|---|---|---|---|
+| 钻取链接 | `style.cellType.pcHreflink` + `openType` | 见 §二 | `event-hreflink-guide.md` §二/§三 |
+| 列排序 | Field 格 `style.cellType.orderType` = `asc`/`desc` | `columns[].sort` | 预览点击排序表现**以设计器确认为准** |
+| 跳同表其他 Sheet | 同上（pcHreflink + `sheetIndex=N-1`） | `columns[].cellType:"jump"` + `jumpSheet:N` | 场景 C（branch-scene-guide.md） |
+
+## 二、columns[].link 声明（build spec spec.json）
+
+```json
+"columns": [
+  { "title": "订单号", "field": "订单号", "width": 100,
+    "link": { "type": "report", "reportId": "<明细报表id>", "params": { "ddhh": "SELF" }, "openType": "blank" } },
+  { "title": "订购日期", "field": "订购日期", "width": 120, "sort": "asc" },
+  { "title": "客户名称", "field": "客户名称", "width": 140 },
+  { "title": "导出明细", "cellType": "jump", "href": "<custom 或见 §三>", "width": 90 }
+]
+```
+
+| type | 生成的 URL | 传参方式 |
+|---|---|---|
+| `report` | `/sp/edc/report/view/<reportId>` | 查询串 `参数名=坐标`（无花括号）；参数名须与**目标报表查询条件标识**对应 |
+| `list` | `/sp/ebdfpage/list/<formId>` | 同上 |
+| `card` | `/sp/ebdfpage/card/0/<formId>` | **路径占位** `{坐标}`（带花括号，§3.2），第一个参数进路径、其余进查询串 |
+| `custom` | 原样 `url`（可预置 `{坐标}` 占位） | params 仍拼查询串 |
+
+- `params` 值：`"SELF"` = 当前格；或**列标题** → 该列数据格坐标（自动转 Excel 引用，如 `D3`）。
+- `openType`：`blank`（默认弹出页）/ `self` / `jsscript`，禁止自造别名。
+- 参数名**避免** `id`/`name` 等系统关键字；`?`/`&` 必须 ASCII（禁全角 `？`）。
+
+**★ 逆引用硬门禁（A0.11）**：列表数据带左父格链（引用列 ≤ 链接列）。引用右侧列 → 构建**直接抛错不落库**
+（静默失效无报错，历史血案）。要传行内任意列 → 把链接列放**最右**（demo 的「导出明细」列即最右）。
+
+### 接收端：目标报表的查询条件（强制 · 2026-11-03 实测）
+
+链接参数**不会**自动过滤目标报表。目标报表里必须有对应条件，且默认值写成「自定义 + `{参数名}`」：
+
+| 键 | 值 |
+|---|---|
+| `defaultValueType` | `"custom"` |
+| `defaultValue` / `type2DefaultValue` | `'["{searchfield002}",""]'` |
+
+- URL 的参数名 = `{…}` 里的名字（通常与条件标识 `searchfield00x` 相同）。
+- 设计器「默认值」框显示为 `(searchfield002)`，圆括号只是 UI 渲染，落库是花括号。
+- 保持「常规 / 空」→ 参数被**静默忽略**：页面能打开、不报错、数据一条不少。
+- 不带参数打开目标报表时，占位会被清空，不会残留字面量。
+- 落地后跑 `e10-cli report verify drill <来源报表> --app-id <id>` 验收；缺绑定会失败并给出修法。
+
+## 三、能力边界（如实告知用户）
+
+| 效果 | 结论 |
+|---|---|
+| 每行「导出」**不预览直接导出**该行明细 | **无已验证 API**。已固化替代：导出列 = Const 链接钻取到明细报表（预览态）。真·直接导出/打印须在设计器或预览页验证官方事件（`openType:"jsscript"` 路线），验证通过后再固化进 CLI |
+| 点击列头升降序切换 | `orderType` 落库即生效配置；预览是否可点击切换以平台版本验证为准 |
+| 无限层次钻取（订单→明细→产品） | 逐层建报表、每层 `link.type:"report"` 指向下一层即可，机制相同无层数限制 |
+
+## 四、搭建提示语句（用户照此提需求）
+
+> 搭一张数据钻取列表报表（appId <appId>，数据源 <表名/sourceId>）：
+> 列：订单号/订购日期/客户名称/…（列级 `sort` 按需升序）；点击订单号钻取到明细报表 <reportId> 并按订单号过滤
+> （`link.type:"report"`，参数名=目标报表查询条件标识）；末列「导出明细」钻取到 <明细报表/单据卡片>；
+> 无限层次（订单→明细→产品）逐层建表互联。用 `e10-cli report build spec` 一次落库，回读验收 pcHreflink/orderType。
+
+**验证**：回读 `dump cells` 或 `getReportDevInfo`，核对 `pcHreflink`（占位/坐标/ASCII ?）与 `orderType`；
+渲染验证占位已替换为真实值（event-hreflink-guide §3.0，配置层正常 ≠ 运行时穿透）；
+接收端跑 `e10-cli report verify drill <来源报表> --app-id <id>`，确认每个 URL 参数都被目标条件的自定义默认值接住。

package/skill-docs/references/report/event-hreflink-guide.md

@@ -26,8 +26,8 @@
 1. **事件动作可传递单元格值**（当前格及其父格值；**父格的父格也支持**）。
 2. **可传递查询条件值**（查询条件标识形如 `{searchfield001}`）。
 3. **跳转列表示例**：在链接中拼接单元格坐标参数，如
- `/sp/ebdfpage/list/xxx?ry=B5&kssj=E3`
- （`B5`/`E3` 表示取该格展开后的实际值）。
+   `/sp/ebdfpage/list/xxx?ry=B5&kssj=E3`
+   （`B5`/`E3` 表示取该格展开后的实际值）。
 4. 打开方式 UI：**弹出页 / 当前页 / 执行js代码**。
 
 ---
@@ -47,7 +47,7 @@
 ```bash
 e10-cli report validate href --map "弹出页"
 e10-cli report validate href --map "执行js代码"
-e10-cli report validate href --file cell.json --fix # 全角？→ASCII ?
+e10-cli report validate href --file cell.json --fix   # 全角？→ASCII ?
 ```
 
 ---
@@ -56,6 +56,40 @@ e10-cli report validate href --file cell.json --fix # 全角？→ASCII ?
 
 > **范围**：仅当前格 + 设置链接字段的**左/上父格**（父格的父格也支持）。超出父格链的坐标**不能**取值。
 
+### 3.0 ★★ 逆引用会「静默失效」（A0.11 · 2026-09-15 血案）
+
+> 供应商绩效看板 `1315297716934582273`：A3 写 `pcHreflink="…/{M3}"`，而 **M3 是 A3 的子格**（M3 左父格 = A3）。
+> 配置回读正常、设计器正常、预览不报错 —— 渲染后 `{M3}` **原样保留从未替换**，穿透 100% 失效。
+
+| 引用目标 | 结果 |
+|---|---|
+| 当前格 / 左父格 / 上父格（含父格的父格） | ✅ 运行时替换为展开后的真实值 |
+| **子格 / 旁系格**（如 A3 引 `{M3}`，而 M3 左父格=A3） | ❌ **静默失效**：占位符原样输出，无任何报错 |
+| `$datasetId.fieldName$`（同行数据集字段） | ❌ 本环境超链接中**验证不生效**（原样保留） |
+
+**唯一验证方法（不看配置层、不看设计器）**：渲染后读 `cell.style.cellType.hreflink`（`BlankHerflinkCellType`），
+确认占位已变成**真实值**：
+
+```
+期望  /sp/ebdfpage/card/0/864399547574140928/866754615609884673
+而非  /sp/ebdfpage/card/0/864399547574140928/{M3}
+```
+
+**修法（最小改动）**：让**承载目标值的格**成为链接格的**父格**：
+
+```bash
+# A3 需要引用 M3 的 id → 把 M3 变成 A3 的左父格（M3 设为根格避免环）
+e10-cli report fix table-name --report-id <id> \
+  --set-parent "2,0=2,12" --set-parent "2,12=-1,-1" \
+  --set-json '2,0:pcHreflink:"…/{M3}"' --apply
+```
+
+**标准形态**（参考实现 `_ref_m4_full.json`）：链接格在**右**、承 id 列在**左** ——
+`M4`（Const「点击查看」）的 `leftX/leftY = L4`，`pcHreflink="…/{L4}"`，引的正是自己的左父格。
+想「点击**某字段列**」穿透，就让承 id 的**隐藏列位于该字段列左侧**。
+
+> ⚠️ **禁止**为了「父格方向顺眼」而重排列（违反 A0.8 + 用户「不顺手改其他」偏好）；确需重排属**结构性变更**，须先获用户同意。
+
 ### 3.1 查询串传参（台账过滤 / 外链最常用）
 
 格式：`参数名=字段坐标`（坐标**不加** `{}`）。
@@ -123,6 +157,7 @@ https://www.baidu.com/s?zclb=D7&zcmc=E7&cx={searchfield001}
 2. 链接中写 `{searchfield00x}`，预览时替换为用户当前查询值。
 3. 也可在表头 Const 的 `cellText` 中引用同一标识显示查询值。
 4. 系统参数（如 `{userid}`、`{date}`、`{year}`）亦可出现在链接中（`DynamicParamsBuilder`）。
+5. **报表跳报表时，接收端要配条件**：目标报表的查询条件必须用「自定义」默认值 `'["{searchfield00x}",""]'` 声明同名参数，否则 URL 参数被静默忽略（页面正常、数据不过滤）。参数名以 `{…}` 里为准，链接 key 必须与之一致。详见 `query-condition-api-guide.md` §5.3，落地后用 `report verify drill` 验收。
 
 示例：
 
@@ -138,12 +173,12 @@ https://www.baidu.com/s?zclb=D7&zcmc=E7&cx={searchfield001}
 
 ```json
 {
- "cellType": "Field",
- "name": "3506271460832878820",
- "text": "资产名称",
- "pcHreflink": "https://www.baidu.com/s?zclb=D7&zcmc=E7&cx={searchfield001}",
- "h5Hreflink": "",
- "openType": "blank"
+  "cellType": "Field",
+  "name": "3506271460832878820",
+  "text": "资产名称",
+  "pcHreflink": "https://www.baidu.com/s?zclb=D7&zcmc=E7&cx={searchfield001}",
+  "h5Hreflink": "",
+  "openType": "blank"
 }
 ```
 
@@ -151,54 +186,27 @@ https://www.baidu.com/s?zclb=D7&zcmc=E7&cx={searchfield001}
 
 ```json
 {
- "cellType": "Const",
- "cellText": "点击查看",
- "pcHreflink": "/sp/ebdfpage/card/0/1123053786772799489/{C4}",
- "openType": "blank",
- "leftX": 3,
- "leftY": 2,
- "topX": -1,
- "topY": -1
+  "cellType": "Const",
+  "cellText": "点击查看",
+  "pcHreflink": "/sp/ebdfpage/card/0/1123053786772799489/{C4}",
+  "openType": "blank",
+  "leftX": 3,
+  "leftY": 2,
+  "topX": -1,
+  "topY": -1
 }
 ```
 
-### 用 CLI 写入（推荐）
-
-```bash
-# 弹出页（新窗口）
-e10-cli report cell-event set <reportId> --app-id <appId> \
-  --cell 1,0 --pc "https://www.baidu.com/s?zclb=D7&zcmc=E7" --open 弹出页
-
-# 当前页（同页跳转）
-e10-cli report cell-event set <reportId> --app-id <appId> \
-  --cell 1,0 --pc "/sp/ebdfpage/list/xxx?dept=B5" --open 当前页
-
-# 执行 js 代码
-e10-cli report cell-event set <reportId> --app-id <appId> \
-  --cell 1,0 --pc "window.open('/sp/ebdfpage/list/xxx')" --open 执行js代码
-
-# 读回 / 清除
-e10-cli report cell-event list <reportId> --app-id <appId>
-e10-cli report cell-event clear <reportId> --app-id <appId> --cell 1,0
-```
-
-命令会改 `fields[]` + workbook `style.cellType`、双保存并回读比对。两条硬规则：
-
-- **全角 `？＆＝` 直接报错** —— 这类链接写进去设计器能显示，但预览点击无反应。
-- `saveReportDevInfo` 在 `designKey` 过期时返回 **code=200 + `data:"您当前的数据不是最新的…"`**。
-  手工调接口时看到 200 就收工会得到「链接写进去了但点了没反应」；命令已识别并自动重读重写。
-
-> 运行时平台会把带链接的格子换成 `BlankHerflinkCellType` / `SelfHerflinkCellType` /
-> `JSScriptHerflinkCellType`（分别对应 `blank|self|jsscript`）。若设计器里看得到链接、
-> 预览里单元格没有变成超链接样式，先确认 fields 与 workbook 两边是否都写到了。
-
 ---
 
 ## 六、Agent 检查清单
 
 - [ ] `openType` ∈ `blank|self|jsscript`，UI 文案已映射
 - [ ] 传单元格：查询串用 `参数名=坐标`（无 `{}`）；路径用 `{坐标}`；仅当前格+父格链
+- [ ] ★ **逆引用自检**：每个占位坐标都落在「该格自身 + 左/上父格链」内（引子格/旁系格 = 静默失效）
+- [ ] ★ **渲染验证**：渲染后读 `cellType.hreflink`，确认占位已替换为**真实值**（配置层看不出问题）
 - [ ] 传查询条件：`{searchfield00x}`，asNameIndex 已对齐
+- [ ] ★ 报表跳报表：目标条件的自定义默认值已声明 `{参数名}`（`report verify drill` 通过）
 - [ ] 参数名避免 `id`/`name` 等系统关键字
 - [ ] PC/H5 分端：移动需要时填 `h5Hreflink`
 - [ ] 双写 fields + workbook；`safe_report_save` / fieldToCell 不丢链接键

package/skill-docs/references/report/expansion-block-parent-config-guide.md

@@ -0,0 +1,208 @@
+# 多独立扩展块（统计块）父格配置指南（SKILL A0.13 场景 A 细化 · BUILD-46/47/48）
+
+> **适用范围**：同一个 sheet 内存在「**主区 + 多个独立扩展块（统计块）**」——
+> 即需求文件里**多行数据源字段单元格**、上下放置多个独立报表 / 统计块时（场景 A）。
+> **判据**：`e10-cli report scene detect --req <需求文件>`（**不依赖关键词**，只看结构）。
+>
+> **优先级**：本规则**优先级高于原有报表规则**，但**仅当识别命中时启用**；未命中 → **完全沿用原有报表逻辑**。
+>
+> **CLI**：`e10-cli report scene check|apply --scene A` · **注意点**：`BUILD-48`（父格口径）/ `BUILD-46`（扩展带公式格）/ `BUILD-47`（常规格式）
+
+---
+
+## 〇、一句话
+
+**公共父格只归集「块入口 + 标题/表头行」，数据格照旧跟随入口格 —— 父格链与公共父格是两层机制，禁止把公共父格泛化到数据格。**
+
+---
+
+## 一、两类概念别混淆
+
+| 机制 | 作用 | 绑定对象 |
+|------|------|----------|
+| **公共父格**（`isActiveParent`） | 把同 sheet 内**多个独立扩展块**归集到同一 sheet，避免各块扩展互相串行/错位 | **块入口格** + **标题行 / 表头行整行 Const** |
+| **父格链**（`leftX/leftY`） | 让**数据格**跟随所在块的**入口格**（同行前一列）一起扩展 | 入口格**右侧的普通 Field 数据格**（保持默认链） |
+
+> ⚠ **泛化禁令**：**不得**把公共父格配置**泛化**到「入口格以右的数据格」。
+
+---
+
+## 二、三类单元格口径（命中场景 A 后强制执行）
+
+凡同 sheet 存在「主区 + 多个独立扩展块」时，按**三类**处理：
+
+| 类 | 单元格 | 父格配置 | 形态 |
+|----|--------|----------|------|
+| ① **公共父格** | Sheet 左上角（如 `A1`），自定义文本（如「统计区」，文本可任意） | `left=(-1,-1)` + **`isActiveParent=true`** | `{ cellType:"Const", cellText:"统计区", leftX:-1, leftY:-1, isActiveParent:true }` |
+| ② **入口格 + 标题/表头行整行 Const** | 每带**入口格**（数据带第一格、合计带第一格 = 纵向扩展根）；每块**标题行 / 表头行整行 Const** | 左父格 = **公共父格** | `{ cellType:"Field", expandType:"Vertical", leftX:0, leftY:0 }`（绑 `(0,0)`） |
+| ③ **数据格** | 入口格**右侧**的普通 Field 格 | **保持默认链**（同行前一列），**不动** | `{ cellType:"Field", expandType:"NoExpand", leftX:<入口.x>, leftY:<入口前1列> }` |
+
+> 其余所有单元格的父格配置，**维持原有逻辑不变**（边界②）。
+
+### 2.1 判定纪律（★ 防交叉表误报）
+
+- 场景 A **只认纵向入口**：`Vertical` 且「是根（`left=-1,-1`）**或**已绑公共父格」。
+- **交叉表**的「列维表头」是 `Horizontal` —— **不算**独立报表入口（`entryLikeCells()`）。
+- 且**纵向入口必须分布在不同行**（`looksMultiReport()`）→ 才是「上下多个独立块」。
+- 幂等：入口格绑上公共父格后 `left` 不再是 `-1` → 判据同时接受「已绑公共父格的纵向格」，**重复 check 不会漏判**。
+
+---
+
+## 三、合计行 / 总计行口径（易错）
+
+| 行 | 口径 |
+|----|------|
+| **合计行（按维度合计，如按学年/按部门）** | 该行**整行所有格**（标签 + Field + Formula）左父格**统一 = 维度字段所在格**（跟随维度扩展） |
+| **总计行** | **保持独立链**（挂自己的行标签）；**不**跟随维度扩展；公式**引用合计行** |
+
+> 症状：把「按维度合计」的合计行挂成公共父格 / 挂到入口格右侧数据格 → 合计不随维度展开或与明细错位。
+
+---
+
+## 四、「常规」数字格式口径（BUILD-47）
+
+> **预览渲染吃 `style.formatter`，不是顶层 `formatterType`。**
+
+| 目标 | ✅ 正确 | ❌ 踩雷 |
+|------|--------|--------|
+| **常规** | `formatterType:["common"]` + **`style.formatter:"General"`** | `style.formatter:"common"` |
+| 货币 | `formatterType:["huobi"]` + `style.formatter:"\"￥\"#,##0.00_);[Red](\"￥\"#,##0.00)"` | `style.formatter:"huobi"` |
+
+- 构建器会把 `formatterType[0]`（短码）**透传**进 `style.formatter`；若 `style.formatter` 落成字面量 `common`，
+  SpreadJS 会把它**当数字格式串解释**（`m`=月份）→ 在 12 月预览显示成 **`co12on`**。
+- 写 `0.00` / `0.##` 功能正常，但设计器会归「**其他数字格式**」；用户要求「保持常规」时**一律用 `General` 口径**。
+- **格式调整范围以用户点名的单元格区域为准**，未点名区域**不顺手改**。
+
+```bash
+e10-cli report validate format --map "常规"                        # 自动纠正 + 告警
+e10-cli report validate format --inline '{"formatter":"common"}'   # 命中断码误写 → 纠正为 General/common
+```
+
+---
+
+## 五、扩展数据带内公式格（BUILD-46）
+
+**规则**：扩展数据带内**公式格（Formula）的左父格必须直接挂「块入口格」**，**禁止链到前一列公式格**；
+否则扩展实例**引用解析错位** —— **预览第一行正常（或 `#DIV/0!`）、后续行渲染乱码**。
+
+| 项 | 硬要求 |
+|----|--------|
+| 左父格 | **直接挂块入口格**（入口格 = 数据带第一格）；**禁止**链公式格 → 公式格 |
+| `refX` / `refY` | 必须 **`-1`**（服务端对这两个键的 int **默认补 0**，回读常见 `0,0`，重建会**原样复制** → 后续行乱码） |
+| 落库后处理路径 | `wb.sheets[*].data.dataTable[行][列].style.cellType`（`typeName=FormulaCellType`）—— **不是** `cells` |
+| 自动兜底 | `buildWorkbookFromFields` 出口 + `saveReportDevInfoAuto` 的 500 防御层 **R7** 已自动归 -1 |
+| **行号规则** | 引用**带自身行** = `x+1`；**跨带引用** = **目标带** `x+1` |
+
+### 5.1 蓝图 diff 方法论（渲染异常时）
+
+> **禁止猜测**：与「用户认可的正常报表」`getReportDevInfo` 回读做**逐字段 diff**
+> （`left` / `refX` / `refY` / `style.formatter`），**实证定位**差异，再定点补丁。
+
+```bash
+e10-cli report formula parent check --report-id <rid> --app-id <appId>     # 只读，exit 3 = 不一致/链公式格/ref≠-1
+e10-cli report formula parent align --report-id <rid> --app-id <appId> [--apply]   # 对齐 + 顺带把 refX/refY 归 -1
+`e10-cli report verify all`
+```
+
+---
+
+## 六、CLI
+
+```bash
+# 识别（恒 exit 0；不依赖关键词）
+e10-cli report scene rules
+e10-cli report scene detect --req <需求文件> [--json]
+
+# 体检（只读；exit 3 = 不合规）—— 三类口径 + 泛化禁令
+e10-cli report scene check --report-id <rid> --app-id <appId> --scene A [--json]
+# 离线定位：--dev-file <getReportDevInfo 的 data JSON>
+
+# 定点修复（默认 dry-run；--apply 才落库）
+e10-cli report scene apply --report-id <rid> --app-id <appId> --scene A \
+  [--at 0,0] [--text "统计区"] [--anchor "x,y;x,y"] [--header-cells "x,y;x,y"] [--apply]
+```
+
+- `--anchor` / `--header-cells`：
+  - `--anchor` 只接受**纵向入口格**（root 或已绑公共父格）与 **Const 标题/表头格**；
+    传**普通 Field 数据格**会被**拒绑**并告警（泛化禁令）；确需强绑加 `--force`。
+  - `--header-cells "x,y;x,y"`：一并把标题/表头行整行 Const 绑到公共父格。
+- 不给 `--anchor` → 自动取全部纵向入口格（幂等）。
+- 落库通道：`buildWorkbookFromFields`（A0.8 定点补丁）+ `saveReportDevInfoAuto`（BUILD-39/ENV-11 载荷自适应）+ BUILD-42 数据集 id 硬门禁；`--apply` 后自动回读校验。
+
+---
+
+## 七、声明式（`build spec` 的 spec）
+
+```jsonc
+{
+  "columns": [ { "title": "序号", "cellType": "seq" }, { "title": "学院", "field": "学院" } ],
+  "scene": {
+    "publicParent": { "x": 0, "y": 0, "text": "统计区" },
+    "anchorCells": ["1,1", "5,1"],                 // 各独立块的入口格坐标
+    "headerCells": ["0,1", "4,1"]                  // 可选：标题/表头行整行 Const
+  }
+}
+```
+
+- `scene.publicParent` → 落库前在指定坐标插入（或复用）公共父格并置 `isActiveParent`。
+- `scene.anchorCells` → 列出的**入口格**左父格统一改到该坐标；**未列出的格一律不动**。
+- 不写 `scene` 段 → **完全不介入**（`applySceneDecl` 返回 null），原单块路径零影响。
+
+---
+
+## 八、自检清单（交付前必过）
+
+- [ ] 是否先跑 `scene detect`？**不命中就不加任何特殊配置**（不要「顺手也加上」）。
+- [ ] 公共父格是否在 **Sheet 左上角**、`isActiveParent=true`、有自定义文本、`left=(-1,-1)`？
+- [ ] **入口格 + 标题/表头行整行 Const** 是否都绑了公共父格？
+- [ ] **入口格右侧的普通 Field 数据格**是否**保持默认链**（未被泛化绑公共父格）？（泛化禁令）
+- [ ] 纵向入口是否**分布在不同行**（非交叉表列维/行维）？单报表单数据源**未**加公共父格？
+- [ ] 合计行（按维度合计）是否整行挂**维度字段格**？总计行是否**独立链**、公式引用合计行？
+- [ ] 扩展带内 Formula 格左父格是否**直接挂块入口格**（非公式格）？`refX/refY` 是否 = `-1`？
+- [ ] 「常规」格式是否用 `style.formatter:"General"` + `formatterType:["common"]`（**未**写短码 `common`）？
+- [ ] 格式/父格调整是否**只动点名区域**？（未点名不顺手改）
+- [ ] `scene check --scene A` 是否 **PASS**（exit 0）？`formula parent check` 是否 PASS？`check-ids` 是否合规？
+
+---
+
+## 九、相关文档
+
+| 文档 | 关系 |
+|------|------|
+| `SKILL.md` A0.13 / 执行优先级 0.46 | 硬规则正文 |
+| `branch-scene-guide.md` §二 | 场景 A 识别 + 判据纪律（本文是其**细化**） |
+| `formula-cell-api-guide.md` §七 | 公式格父格 / 上父格 / `refX·refY` |
+| `cell-config-echo-guide.md` §二 | 数字格式目录（「常规」= `General`/`common`） |
+| `pitfalls BUILD-46 / 47 / 48` | 扩展带公式格 / 常规格式 / 公共父格泛化 |
+| `datasource-selection-and-parent-filter-guide.md` §2.0 | 既有父格链铁律（A0.7），本规则**不替代**它 |
+
+---
+
+## 十、环境归一化兼容 + 行首格自动归集（2026-10-29 · 验证 www.e-cology.com.cn）
+
+### 10.1 环境行为（保存后服务端自动做两件事）
+
+| 行为 | 表现 | 影响 |
+|------|------|------|
+| **坐标整体 +1,+1** | 蓝图 (x,y) → 回读 (x+1,y+1)；服务端在 (0,0) 自动插入一个 `Const "1"`（left=-1,-1） | 回读坐标 ≠ 搭建坐标，**父格绑定一律以回读坐标为准** |
+| **纵向根左父格归一化** | 锚点 `left=(-1,-1)` 被改为 `left=(0,0)`（指向自动插入的「1」格）；回读**不带 `isActiveParent` 键** | 旧判据 `entryLikeCells` 只认 `-1,-1` 或「已绑公共父格」→ 误判「0 入口格 → 场景 A 不适用」 |
+
+### 10.2 e10-cli report scene 三处补丁（本节 = 修复记录）
+
+1. **`findPublicParent` 放宽**：`(0,0)` 处 `Const` 且非纵向扩展即可当公共父格（键存在才要求 `isActiveParent`）；
+2. **`entryLikeCells` 追加一类入口**：纵向格 `left=(0,0)` 且 (0,0) 是 Const 非扩展格 → 视为「已绑」（幂等；**限定 (0,0)** 防误伤块内普通 Const 标签）；
+3. **`blockFirstConsts()` 新增（口径②自动归集）**：所有**行首格**（同行 y 最小）中 `left=(-1,-1)` 的 Const → apply 时统一绑公共父格。覆盖表头行首/合计带首/总计行首/摘要表头首/各块标题条（合并整行也是行首）；行内其余格已有默认链，不绑（泛化禁令不变）。Const 不扩展，绑公共父格只归集扩展上下文、不改变渲染。
+
+### 10.3 命令（幂等，可反复执行）
+
+```bash
+e10-cli report scene check --report-id <rid> --app-id <appId> --scene A   # exit 3 = 有行首格未归集
+e10-cli report scene apply --report-id <rid> --app-id <appId> --scene A --apply
+# 公共父格文本默认「1」（用户口径）；可用 --text "统计区" 覆盖；--header-cells "x,y;x,y" 手工追加
+```
+
+### 10.4 验证留证（chl业务专项统计 1331753785429704735）
+
+- 公共父格 (0,0)「1」+ 4 个块锚点（模块1行①/行②、模块2、摘要）已绑；
+- 13 个行首/标题条 Const（副题、4 条标题条、4 个表头首格、2 个合计行首、1 个总计行首、1 个口径条）统一绑 (0,0)；
+- apply 回读校验 unbound=[]；逐格核对 13/13 OK。