weaver-e10-builder 1.6.14 → 1.6.16

package/skill-docs/references/report/branch-scene-guide.md

@@ -1,293 +1,293 @@
-# 分支场景规则 —— 同 sheet 多报表 / 自增序号 / 单元格跳转 Sheet（SKILL A0.13）
-
-> **优先级**：本节规则**优先级高于原有报表规则**，但**仅在识别命中时启用**。
-> **不满足识别条件的普通报表需求 → 完全沿用原有全部报表逻辑**，不执行任何特殊配置。
->
-> **CLI**：`e10-cli report scene rules | detect | check | apply`
-> **脚本**：`e10-cli report scene` · 规则常量 `SCENE_RULES`（与 SKILL A0.13 同源）
-> **声明式**：`build spec` 的 spec 支持 `columns[].cellType:"seq"｜"jump"`、
-> `scene.publicParent + scene.anchorCells`、`scene.jumpCells`
-
----
-
-## 一、识别纪律（**不依赖关键词**）
-
-> ⚠ **禁止**用「多报表」「序号」「自增」这类**业务关键词**去猜场景 —— 那正是本规则要避免的做法。
-> 判定**只看内容结构**：`e10-cli report scene detect --req <需求文件>`。
-
-支持的输入：`.json`（spec / `cells[]` / `blocks[]`）、`.md` / `.txt` / `.csv`（文本网格）。
-`.xlsx` 需先另存为 `.csv` / `.md`（本工具不直接解析二进制表格）。
-
-「数据源字段单元格」的结构特征（任一命中即为字段单元格）：
-
-| 形态 | 示例 |
-|------|------|
-| 三段式 `fieldKey` | `1324295304156717057.1162255789527552000.sort` |
-| 结构化键值 | `字段：学院号` / `fieldKey: …` |
-| 表格「字段」列 | 表头含 `字段` / `字段名` / `field` 列，该列有值 |
-
-**分组规则**：连续的字段行归为一个**数据区**；空行 / 标题行 / 段落行 = **硬边界**（分隔符行 `|---|` 不断组）。
-
-```jsonc
-// 输出（--json）
-{
-  "scenes": ["A", "C"],                 // 命中场景（可同时 A+B / A+C / B+C / A+B+C）
-  "scene": "A+C",
-  "evidence": {
-    "dataAreas": 2,                     // ★ 场景 A 判据：数据区数量
-    "fieldRows": [7, 8, 9, 15, 16],
-    "seqMarked": ["【自增序号单元格】"],   // ★ 场景 B 判据：标注
-    "jumpMarked": ["sheet2: 点击跳转sheet2"], // ★ 场景 C 判据：动作描述
-    "criteria": { "A": ["…"], "B": [], "C": ["识别到「点击跳转 sheetN」描述 1 处"] }
-  },
-  "action": "enable_scene_rules",       // 未命中时 = "keep_default_rules"
-  "rules": { "A": { "mandatory": ["…"] } }
-}
-```
-
-**退出码**：detect 恒 0（识别结果本身不是错误）；`check` 不合规 = **3**。
-
-### 1.1 识别边界说明（防过度触发 · 必须遵守）
-
-| # | 边界 | 说明 |
-|---|------|------|
-| ① | **多报表只认「多组独立数据源字段」** | 仅当**同一个 sheet 内出现多组独立数据源字段（多行数据源）**才判定为多报表场景；**单报表单数据源 sheet，不新增公共父格**。 |
-| ② | **公共父格只做归集，不改内部** | 公共父格**只**用于当前 sheet 内多个报表的**父格归集**，**不修改单报表内部原有单元格的左父格关系**。 |
-| ③ | **`{seq}` 只认显式标注** | 只有需求里**明确标注**「自增序号单元格」才启用 `{seq}`；**普通序号 / 手工编号不触发**此规则。 |
-| ④ | **跳转只认「点击跳转」描述** | 跳转 Sheet **仅当**需求描述包含「点击跳转sheetX / 点击可跳转到sheetX」这类描述才触发跳转事件；URL 参数严格遵循 `sheetIndex` **从 0 开始计数**。 |
-
----
-
-## 二、场景 A · 同 sheet 多报表（公共父格）
-
-### 2.1 识别条件
-
-**同一个 sheet 页存在多行数据源字段单元格** → 判定为「同页面上下放置多个独立报表」。
-
-### 2.2 强制配置（命中后必做）
-
-> **细化指南**：`expansion-block-parent-config-guide.md`（三类单元格口径 / 泛化禁令 / 合计·总计行 / 扩展带公式格）。
-> 凡同 sheet 存在「**主区 + 多个独立扩展块（统计块）**」时，按**三类单元格口径**处理：
-
-| 类 | 单元格 | 配置 |
-|---|--------|------|
-| ① **公共父格** | Sheet **左上角** `Const`（自定义文本，如「统计区」） | `left=(-1,-1)` + **`isActiveParent=true`** |
-| ② **入口格 + 标题/表头行整行 Const** | 每带**入口格**（数据带第一格、合计带第一格 = 纵向扩展根）；每块**标题行 / 表头行整行 Const** | 左父格**统一绑定**公共父格 |
-| ③ **数据格** | 入口格**右侧**的普通 Field 格 | **保持默认链**（同行前一列），**不动** |
-
-> ⚠ **泛化禁令**：**不得**把公共父格配置**泛化**到「入口格以右的数据格」—— 数据跟随入口格扩展，
-> **父格链**与**公共父格**是**两层机制**。
-
-**合计行 / 总计行**：**合计行（按维度合计，如按学年/按部门）** 该行**整行所有格**（标签 + Field + Formula）左父格**统一 = 维度字段所在格**；
-**总计行**保持**独立链**（挂自己行标签），公式**引用合计行**，不跟随维度扩展。
-
-### 2.3 配置形态
-
-```jsonc
-// 公共父格（落库形态）
-{ "x": 0, "y": 0, "cellType": "Const", "cellText": "报表区",
-  "leftX": -1, "leftY": -1, "expandType": "NoExpand",
-  "isActiveParent": true, "displayType": "Group" }
-
-// 各独立报表的行维入口格（=「扩展父格」）
-{ "x": 1, "y": 1, "cellType": "Field", "name": "zxmc", "text": "中心名称",
-  "expandType": "Vertical", "leftX": 0, "leftY": 0 }   // ← 绑到公共父格
-```
-
-> 公共父格若**已占用**该坐标 → **复用**它并置 `isActiveParent=true`（不新建）。
-
-### 2.4 判据纪律（★ 防交叉表误报）
-
-**一个交叉表**的「列维表头」是 `Horizontal` 扩展、「行维入口」是 `Vertical` 扩展 ——
-二者同属**同一个矩阵**，**不是**两个独立报表。
-
-| 判据 | 规则 |
-|------|------|
-| 只认**纵向入口** | `Vertical` 且「是根（`left=-1,-1`）**或**已绑公共父格」（`entryLikeCells()`）—— 幂等：绑过公共父格的入口格重复 check 不漏判 |
-| 且必须**分布在不同行** | 行号去重后 ≥2（`looksMultiReport()`）→ 才是「上下多个独立报表」 |
-| 纵向入口 ≤1 或全在同一行 | **不适用**场景 A，检查直接 PASS |
-
-**反例（会误报的情形）**：chl测试1010 这类行列交叉表 —— 列头 `(0,3) 年级` 是 `Horizontal`、
-行头 `(1,1) 学院名称` 是 `Vertical`，粗按「扩展根≥2」会误判成多报表。**按上述判据即正确排除。**
-
-### 2.5 正例 / 反例
-
-```text
-✅ 正例：上下两个独立报表
-   A1「中心名称」  Vertical  left=(-1,-1)  ┐
-   A5「专业名称」  Vertical  left=(-1,-1)  ┘ 两个纵向根、行号不同 → 场景 A
-   → 修法：(0,0) 建公共父格，A1/A5 的 leftX/leftY 都改成 0,0
-
-❌ 反例：单块交叉表（不适用场景 A）
-   D1「年级」      Horizontal left=(-1,-1)
-   B2「学院名称」  Vertical   left=(-1,-1)
-   → 只有 1 个纵向根 → 场景 A **不适用**，勿加公共父格
-```
-
----
-
-## 三、场景 B · 自增序号（系统 `{seq}`）
-
-### 3.1 识别条件
-
-需求文件单元格标注 **【自增序号单元格】**（也接受 `[自增序号单元格]`）。
-
-> ⚠ 边界③：**普通序号 / 手工编号不触发**本规则。
-
-### 3.2 强制配置
-
-| # | 配置 | 说明 |
-|---|------|------|
-| ① | 统一使用系统标准序号字段 **`{seq}`** | `cellType='SequenceNumber'`，`cellText='{seq}'` |
-| ② | **纵向扩展** | `expandType='Vertical'` |
-| ③ | **禁止**用自定义公式生成序号 | 不得写 `=ROW()-2` / `=SUBTOTAL(...)` 之类 |
-
-### 3.3 配置形态
-
-```jsonc
-{ "cellType": "SequenceNumber", "typeName": "SequenceNumberCellType",
-  "cellText": "{seq}", "expandType": "Vertical", "displayType": "Group",
-  "leftX": 1, "leftY": 1 }        // 左父格 = 所在块的入口格，随块纵向扩展
-```
-
-> **反例**：`{"cellType":"Formula","cellText":"ROW()-2"}` —— 导出/分页后错位、跨块串号，**禁止**。
-
----
-
-## 四、场景 C · 单元格跳转 Sheet 页
-
-### 4.1 识别条件
-
-需求描述包含「**点击跳转sheetX** / **点击可跳转到sheetX**」这类描述
-（正则 `/(?:点击|单击|点按)\s*(?:可|即|能)?\s*跳转\s*(?:到|至)?\s*sheet\s*(?:页)?\s*([0-9]+)/i`）。
-
-> ⚠ 边界④：**仅**这类「点击跳转」描述才触发；`sheetIndex` **严格从 0 开始计数**。
-
-### 4.2 强制配置（命中后必做）
-
-| # | 配置 | 说明 |
-|---|------|------|
-| ① | 在**当前单元格**添加**点击跳转事件** | 落 `pcHreflink`（PC 端）；移动端另配 `h5Hreflink`（别名 `mbhreflink`） |
-| ② | 基础地址取**当前报表预览页 URL** | `/sp/edc/report/view/<reportId>` |
-| ③ | URL 参数 **`sheetIndex=<N-1>`** | sheet1→`0`，sheet2→`1`，sheetN→`N-1`（**严格从 0 起**） |
-| ④ | **打开方式**默认「**弹出页**」 | `openType="blank"`（与设计器右侧配置一致） |
-
-### 4.3 链接形态
-
-```text
-报表预览页：/sp/edc/report/view/1325388137101516800
-转到 sheet2 的完整链接：/sp/edc/report/view/1325388137101516800?sheetIndex=1
-```
-
-```jsonc
-// 落库形态（fields[] + workbook style.cellType）
-{ "x": 2, "y": 1, "cellType": "Const", "cellText": "查看明细",
-  "pcHreflink": "/sp/edc/report/view/1325388137101516800?sheetIndex=1",
-  "h5Hreflink": "", "openType": "blank" }
-```
-
-> **映射表（sheet 序号 → sheetIndex）**：`sheet1→0` · `sheet2→1` · `sheet3→2` … `sheetN→N-1`。
-> 链接字符 `?` / `&` 必须是 **ASCII**（禁用全角 `？`），见 `event-hreflink-guide.md` §二。
-
-### 4.4 反例 / 常见错
-
-| 错法 | 后果 |
-|------|------|
-| `sheet2 → sheetIndex=2`（off-by-one） | 跳到 sheet3，或越界无效 |
-| 基础地址非 `/sp/edc/report/view/…` | 跳到无关页面 |
-| `openType="popup"` / `"window"` | 非法值，平台不认（只认 `blank`/`self`/`jsscript`） |
-| 链接用了全角 `？` / `&` | 预览点击**无反应** |
-
----
-
-## 五、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|B|C] \
-  [--seq-cells "x,y;x,y"] [--jump-cells "x,y=N"] [--open-type blank] [--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 "1,1;5,1"] [--apply]
-e10-cli report scene apply --report-id <rid> --app-id <appId> --scene B \
-  --seq-cells "1,0" [--apply]
-e10-cli report scene apply --report-id <rid> --app-id <appId> --scene C \
-  --jump-cells "2,1=2" [--base /sp/edc/report/view/<rid>] [--open-type blank] [--apply]
-```
-
-**落库通道保障**：`scene apply` 一律走 `buildWorkbookFromFields`（**A0.8 定点补丁**，禁止整表重建）
-+ `saveReportDevInfoAuto`（**BUILD-39** 载荷自适应）+ `assertNoStaleDatasetIds`（**BUILD-42** 数据集 id 硬门禁），
-`--apply` 后**自动回读校验**（场景 A：公共父格 `isActiveParent` + 锚点是否都绑上；场景 B：序号格 `SequenceNumber`+`Vertical`；
-场景 C：跳转格 `pcHreflink` 含 `/sp/edc/report/view/` 且 `sheetIndex` = N-1、`openType` 正确）。
-校验不过 → exit 2 且提示复查。
-
-`--jump-cells` 语法：`"x,y=N"`，多个用 `;` 分隔（如 `"2,1=2;5,1=3"`）；**N = 目标 sheet 序号，从 1 起**。
-
----
-
-## 六、声明式（`build spec` 的 spec 字段）
-
-```jsonc
-{
-  "appId": "…", "name": "预算执行(多报表同页)", "form": "…",
-  "columns": [
-    { "title": "序号", "cellType": "seq" },                      // ★ 场景 B：系统序号 {seq}
-    { "title": "查看明细", "cellType": "jump", "jumpSheet": 2 },  // ★ 场景 C：跳转 sheet2
-    { "title": "中心名称", "field": "中心名称" }
-  ],
-  "scene": {                                                      // ★ 场景 A + C
-    "publicParent": { "x": 0, "y": 0, "text": "报表区" },
-    "anchorCells": ["1,1", "5,1"],                                // 各独立报表的扩展父格坐标
-    "jumpCells": [ { "cell": "2,1", "sheet": 2 }, "5,1=3" ],      // 落库期给指定格写跳转链接
-    "base": "/sp/edc/report/view/<rid>",                          // 可选；缺省用搭建期 reportId 自动拼
-    "openType": "blank"                                           // 可选；默认「弹出页」
-  }
-}
-```
-
-- `columns[].cellType:"seq"` → 生成 `SequenceNumber` **纵向**格；该列**不参与字段绑定匹配**（不会因无字段而 exit 4）。
-- `columns[].cellType:"jump" + jumpSheet:N` → 生成 Const 文本 + 跳转链接；同样**不参与字段绑定匹配**。
-- `scene.publicParent` → 落库前在指定坐标插入（或复用）公共父格并置 `isActiveParent`；
-  `scene.anchorCells` 列出的入口格左父格统一改到该坐标；**未列出的格一律不动**。
-- `scene.jumpCells` → 落库前给每个 `{cell,sheet}`（或 `"x,y=N"`）写 `pcHreflink = <base>?sheetIndex=<N-1>` + `openType`。
-- 不写 `scene` 段（或只写空对象）→ **完全不介入**（`applySceneDecl` 返回 null），原单块路径零影响。
-
-> **多块内容**：`build spec` 当前为**单块模型**。多块（上下多个报表）内容可分别构建 /
-> 在其上继续铺块后，统一用 `scene apply --scene A` 做「建公共父格 + 重绑入口格」这一步。
-
----
-
-## 七、自检清单（交付前必过）
-
-- [ ] 是否先跑了 `scene detect`？**不命中就不加任何特殊配置**（不要「顺手也加上」）。
-- [ ] 场景 A 的公共父格是否在 **Sheet 左上角**、`isActiveParent=true`、有自定义文本？
-- [ ] 场景 A 是否**只**改了「各独立报表的扩展父格」的左父格，其余格父格**未动**？（边界②）
-- [ ] 是否确认这些纵向根**分布在不同行**（而非交叉表的列维/行维）？单报表单数据源**未**加公共父格？（边界①）
-- [ ] 场景 B 的序号格是否 `SequenceNumber` + `Vertical` + `{seq}`，且**没有**残留公式？**普通序号未被误改**？（边界③）
-- [ ] 场景 C 的跳转链接基础地址是否 `/sp/edc/report/view/<reportId>`、`sheetIndex` = **N-1（从 0 起）**、`openType=blank`？（边界④）
-- [ ] 跳转链接是否用了 **ASCII** `?` / `&`（非全角）？
-- [ ] `scene check` 是否 **PASS**（exit 0）？`check-ids` 是否同步合规（BUILD-42）？
-
----
-
-## 八、相关文档
-
-| 文档 | 关系 |
-|------|------|
-| `SKILL.md` A0.13 / 执行优先级 0.46 | 硬规则正文 |
-| `expansion-block-parent-config-guide.md` | ★ 场景 A **细化**：三类单元格口径 / 泛化禁令 / 合计·总计行 / 扩展带公式格（BUILD-46/47/48） |
-| `pitfalls BUILD-43` | 多报表未绑公共父格（各块扩展互串） |
-| `pitfalls BUILD-44` | 序号用自定义公式生成（导出/分页错位） |
-| `pitfalls BUILD-45` | 跳转 Sheet 的 `sheetIndex` 错位 / 基础地址非预览页 / 打开方式非法 |
-| `pitfalls BUILD-48` | 公共父格泛化到数据格 / 合计行·总计行父格错配 |
-| `event-hreflink-guide.md` | 超链接落库键 `pcHreflink`/`h5Hreflink`/`openType`、ASCII `?`/`&`、父格链传参 |
-| `datasource-selection-and-parent-filter-guide.md` §2.0 | 既有父格链铁律（A0.7），本规则**不替代**它 |
-| `formula-cell-api-guide.md` | Formula 格 API（场景 B 明令**不用**公式生号） |
-| `report-requirement-analysis-template.md` §〇 | 需求分析阶段的场景识别章节 |
-| `crosstab-raw-workbook-guide.md` §六 | 数据集 id 隔离（BUILD-42） |
+# 分支场景规则 —— 同 sheet 多报表 / 自增序号 / 单元格跳转 Sheet（SKILL A0.13）
+
+> **优先级**：本节规则**优先级高于原有报表规则**，但**仅在识别命中时启用**。
+> **不满足识别条件的普通报表需求 → 完全沿用原有全部报表逻辑**，不执行任何特殊配置。
+>
+> **CLI**：`e10-cli report scene rules | detect | check | apply`
+> **脚本**：`e10-cli report scene` · 规则常量 `SCENE_RULES`（与 SKILL A0.13 同源）
+> **声明式**：`build spec` 的 spec 支持 `columns[].cellType:"seq"｜"jump"`、
+> `scene.publicParent + scene.anchorCells`、`scene.jumpCells`
+
+---
+
+## 一、识别纪律（**不依赖关键词**）
+
+> ⚠ **禁止**用「多报表」「序号」「自增」这类**业务关键词**去猜场景 —— 那正是本规则要避免的做法。
+> 判定**只看内容结构**：`e10-cli report scene detect --req <需求文件>`。
+
+支持的输入：`.json`（spec / `cells[]` / `blocks[]`）、`.md` / `.txt` / `.csv`（文本网格）。
+`.xlsx` 需先另存为 `.csv` / `.md`（本工具不直接解析二进制表格）。
+
+「数据源字段单元格」的结构特征（任一命中即为字段单元格）：
+
+| 形态 | 示例 |
+|------|------|
+| 三段式 `fieldKey` | `1324295304156717057.1162255789527552000.sort` |
+| 结构化键值 | `字段：学院号` / `fieldKey: …` |
+| 表格「字段」列 | 表头含 `字段` / `字段名` / `field` 列，该列有值 |
+
+**分组规则**：连续的字段行归为一个**数据区**；空行 / 标题行 / 段落行 = **硬边界**（分隔符行 `|---|` 不断组）。
+
+```jsonc
+// 输出（--json）
+{
+  "scenes": ["A", "C"],                 // 命中场景（可同时 A+B / A+C / B+C / A+B+C）
+  "scene": "A+C",
+  "evidence": {
+    "dataAreas": 2,                     // ★ 场景 A 判据：数据区数量
+    "fieldRows": [7, 8, 9, 15, 16],
+    "seqMarked": ["【自增序号单元格】"],   // ★ 场景 B 判据：标注
+    "jumpMarked": ["sheet2: 点击跳转sheet2"], // ★ 场景 C 判据：动作描述
+    "criteria": { "A": ["…"], "B": [], "C": ["识别到「点击跳转 sheetN」描述 1 处"] }
+  },
+  "action": "enable_scene_rules",       // 未命中时 = "keep_default_rules"
+  "rules": { "A": { "mandatory": ["…"] } }
+}
+```
+
+**退出码**：detect 恒 0（识别结果本身不是错误）；`check` 不合规 = **3**。
+
+### 1.1 识别边界说明（防过度触发 · 必须遵守）
+
+| # | 边界 | 说明 |
+|---|------|------|
+| ① | **多报表只认「多组独立数据源字段」** | 仅当**同一个 sheet 内出现多组独立数据源字段（多行数据源）**才判定为多报表场景；**单报表单数据源 sheet，不新增公共父格**。 |
+| ② | **公共父格只做归集，不改内部** | 公共父格**只**用于当前 sheet 内多个报表的**父格归集**，**不修改单报表内部原有单元格的左父格关系**。 |
+| ③ | **`{seq}` 只认显式标注** | 只有需求里**明确标注**「自增序号单元格」才启用 `{seq}`；**普通序号 / 手工编号不触发**此规则。 |
+| ④ | **跳转只认「点击跳转」描述** | 跳转 Sheet **仅当**需求描述包含「点击跳转sheetX / 点击可跳转到sheetX」这类描述才触发跳转事件；URL 参数严格遵循 `sheetIndex` **从 0 开始计数**。 |
+
+---
+
+## 二、场景 A · 同 sheet 多报表（公共父格）
+
+### 2.1 识别条件
+
+**同一个 sheet 页存在多行数据源字段单元格** → 判定为「同页面上下放置多个独立报表」。
+
+### 2.2 强制配置（命中后必做）
+
+> **细化指南**：`expansion-block-parent-config-guide.md`（三类单元格口径 / 泛化禁令 / 合计·总计行 / 扩展带公式格）。
+> 凡同 sheet 存在「**主区 + 多个独立扩展块（统计块）**」时，按**三类单元格口径**处理：
+
+| 类 | 单元格 | 配置 |
+|---|--------|------|
+| ① **公共父格** | Sheet **左上角** `Const`（自定义文本，如「统计区」） | `left=(-1,-1)` + **`isActiveParent=true`** |
+| ② **入口格 + 标题/表头行整行 Const** | 每带**入口格**（数据带第一格、合计带第一格 = 纵向扩展根）；每块**标题行 / 表头行整行 Const** | 左父格**统一绑定**公共父格 |
+| ③ **数据格** | 入口格**右侧**的普通 Field 格 | **保持默认链**（同行前一列），**不动** |
+
+> ⚠ **泛化禁令**：**不得**把公共父格配置**泛化**到「入口格以右的数据格」—— 数据跟随入口格扩展，
+> **父格链**与**公共父格**是**两层机制**。
+
+**合计行 / 总计行**：**合计行（按维度合计，如按学年/按部门）** 该行**整行所有格**（标签 + Field + Formula）左父格**统一 = 维度字段所在格**；
+**总计行**保持**独立链**（挂自己行标签），公式**引用合计行**，不跟随维度扩展。
+
+### 2.3 配置形态
+
+```jsonc
+// 公共父格（落库形态）
+{ "x": 0, "y": 0, "cellType": "Const", "cellText": "报表区",
+  "leftX": -1, "leftY": -1, "expandType": "NoExpand",
+  "isActiveParent": true, "displayType": "Group" }
+
+// 各独立报表的行维入口格（=「扩展父格」）
+{ "x": 1, "y": 1, "cellType": "Field", "name": "zxmc", "text": "中心名称",
+  "expandType": "Vertical", "leftX": 0, "leftY": 0 }   // ← 绑到公共父格
+```
+
+> 公共父格若**已占用**该坐标 → **复用**它并置 `isActiveParent=true`（不新建）。
+
+### 2.4 判据纪律（★ 防交叉表误报）
+
+**一个交叉表**的「列维表头」是 `Horizontal` 扩展、「行维入口」是 `Vertical` 扩展 ——
+二者同属**同一个矩阵**，**不是**两个独立报表。
+
+| 判据 | 规则 |
+|------|------|
+| 只认**纵向入口** | `Vertical` 且「是根（`left=-1,-1`）**或**已绑公共父格」（`entryLikeCells()`）—— 幂等：绑过公共父格的入口格重复 check 不漏判 |
+| 且必须**分布在不同行** | 行号去重后 ≥2（`looksMultiReport()`）→ 才是「上下多个独立报表」 |
+| 纵向入口 ≤1 或全在同一行 | **不适用**场景 A，检查直接 PASS |
+
+**反例（会误报的情形）**：chl测试1010 这类行列交叉表 —— 列头 `(0,3) 年级` 是 `Horizontal`、
+行头 `(1,1) 学院名称` 是 `Vertical`，粗按「扩展根≥2」会误判成多报表。**按上述判据即正确排除。**
+
+### 2.5 正例 / 反例
+
+```text
+✅ 正例：上下两个独立报表
+   A1「中心名称」  Vertical  left=(-1,-1)  ┐
+   A5「专业名称」  Vertical  left=(-1,-1)  ┘ 两个纵向根、行号不同 → 场景 A
+   → 修法：(0,0) 建公共父格，A1/A5 的 leftX/leftY 都改成 0,0
+
+❌ 反例：单块交叉表（不适用场景 A）
+   D1「年级」      Horizontal left=(-1,-1)
+   B2「学院名称」  Vertical   left=(-1,-1)
+   → 只有 1 个纵向根 → 场景 A **不适用**，勿加公共父格
+```
+
+---
+
+## 三、场景 B · 自增序号（系统 `{seq}`）
+
+### 3.1 识别条件
+
+需求文件单元格标注 **【自增序号单元格】**（也接受 `[自增序号单元格]`）。
+
+> ⚠ 边界③：**普通序号 / 手工编号不触发**本规则。
+
+### 3.2 强制配置
+
+| # | 配置 | 说明 |
+|---|------|------|
+| ① | 统一使用系统标准序号字段 **`{seq}`** | `cellType='SequenceNumber'`，`cellText='{seq}'` |
+| ② | **纵向扩展** | `expandType='Vertical'` |
+| ③ | **禁止**用自定义公式生成序号 | 不得写 `=ROW()-2` / `=SUBTOTAL(...)` 之类 |
+
+### 3.3 配置形态
+
+```jsonc
+{ "cellType": "SequenceNumber", "typeName": "SequenceNumberCellType",
+  "cellText": "{seq}", "expandType": "Vertical", "displayType": "Group",
+  "leftX": 1, "leftY": 1 }        // 左父格 = 所在块的入口格，随块纵向扩展
+```
+
+> **反例**：`{"cellType":"Formula","cellText":"ROW()-2"}` —— 导出/分页后错位、跨块串号，**禁止**。
+
+---
+
+## 四、场景 C · 单元格跳转 Sheet 页
+
+### 4.1 识别条件
+
+需求描述包含「**点击跳转sheetX** / **点击可跳转到sheetX**」这类描述
+（正则 `/(?:点击|单击|点按)\s*(?:可|即|能)?\s*跳转\s*(?:到|至)?\s*sheet\s*(?:页)?\s*([0-9]+)/i`）。
+
+> ⚠ 边界④：**仅**这类「点击跳转」描述才触发；`sheetIndex` **严格从 0 开始计数**。
+
+### 4.2 强制配置（命中后必做）
+
+| # | 配置 | 说明 |
+|---|------|------|
+| ① | 在**当前单元格**添加**点击跳转事件** | 落 `pcHreflink`（PC 端）；移动端另配 `h5Hreflink`（别名 `mbhreflink`） |
+| ② | 基础地址取**当前报表预览页 URL** | `/sp/edc/report/view/<reportId>` |
+| ③ | URL 参数 **`sheetIndex=<N-1>`** | sheet1→`0`，sheet2→`1`，sheetN→`N-1`（**严格从 0 起**） |
+| ④ | **打开方式**默认「**弹出页**」 | `openType="blank"`（与设计器右侧配置一致） |
+
+### 4.3 链接形态
+
+```text
+报表预览页：/sp/edc/report/view/1325388137101516800
+转到 sheet2 的完整链接：/sp/edc/report/view/1325388137101516800?sheetIndex=1
+```
+
+```jsonc
+// 落库形态（fields[] + workbook style.cellType）
+{ "x": 2, "y": 1, "cellType": "Const", "cellText": "查看明细",
+  "pcHreflink": "/sp/edc/report/view/1325388137101516800?sheetIndex=1",
+  "h5Hreflink": "", "openType": "blank" }
+```
+
+> **映射表（sheet 序号 → sheetIndex）**：`sheet1→0` · `sheet2→1` · `sheet3→2` … `sheetN→N-1`。
+> 链接字符 `?` / `&` 必须是 **ASCII**（禁用全角 `？`），见 `event-hreflink-guide.md` §二。
+
+### 4.4 反例 / 常见错
+
+| 错法 | 后果 |
+|------|------|
+| `sheet2 → sheetIndex=2`（off-by-one） | 跳到 sheet3，或越界无效 |
+| 基础地址非 `/sp/edc/report/view/…` | 跳到无关页面 |
+| `openType="popup"` / `"window"` | 非法值，平台不认（只认 `blank`/`self`/`jsscript`） |
+| 链接用了全角 `？` / `&` | 预览点击**无反应** |
+
+---
+
+## 五、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|B|C] \
+  [--seq-cells "x,y;x,y"] [--jump-cells "x,y=N"] [--open-type blank] [--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 "1,1;5,1"] [--apply]
+e10-cli report scene apply --report-id <rid> --app-id <appId> --scene B \
+  --seq-cells "1,0" [--apply]
+e10-cli report scene apply --report-id <rid> --app-id <appId> --scene C \
+  --jump-cells "2,1=2" [--base /sp/edc/report/view/<rid>] [--open-type blank] [--apply]
+```
+
+**落库通道保障**：`scene apply` 一律走 `buildWorkbookFromFields`（**A0.8 定点补丁**，禁止整表重建）
++ `saveReportDevInfoAuto`（**BUILD-39** 载荷自适应）+ `assertNoStaleDatasetIds`（**BUILD-42** 数据集 id 硬门禁），
+`--apply` 后**自动回读校验**（场景 A：公共父格 `isActiveParent` + 锚点是否都绑上；场景 B：序号格 `SequenceNumber`+`Vertical`；
+场景 C：跳转格 `pcHreflink` 含 `/sp/edc/report/view/` 且 `sheetIndex` = N-1、`openType` 正确）。
+校验不过 → exit 2 且提示复查。
+
+`--jump-cells` 语法：`"x,y=N"`，多个用 `;` 分隔（如 `"2,1=2;5,1=3"`）；**N = 目标 sheet 序号，从 1 起**。
+
+---
+
+## 六、声明式（`build spec` 的 spec 字段）
+
+```jsonc
+{
+  "appId": "…", "name": "预算执行(多报表同页)", "form": "…",
+  "columns": [
+    { "title": "序号", "cellType": "seq" },                      // ★ 场景 B：系统序号 {seq}
+    { "title": "查看明细", "cellType": "jump", "jumpSheet": 2 },  // ★ 场景 C：跳转 sheet2
+    { "title": "中心名称", "field": "中心名称" }
+  ],
+  "scene": {                                                      // ★ 场景 A + C
+    "publicParent": { "x": 0, "y": 0, "text": "报表区" },
+    "anchorCells": ["1,1", "5,1"],                                // 各独立报表的扩展父格坐标
+    "jumpCells": [ { "cell": "2,1", "sheet": 2 }, "5,1=3" ],      // 落库期给指定格写跳转链接
+    "base": "/sp/edc/report/view/<rid>",                          // 可选；缺省用搭建期 reportId 自动拼
+    "openType": "blank"                                           // 可选；默认「弹出页」
+  }
+}
+```
+
+- `columns[].cellType:"seq"` → 生成 `SequenceNumber` **纵向**格；该列**不参与字段绑定匹配**（不会因无字段而 exit 4）。
+- `columns[].cellType:"jump" + jumpSheet:N` → 生成 Const 文本 + 跳转链接；同样**不参与字段绑定匹配**。
+- `scene.publicParent` → 落库前在指定坐标插入（或复用）公共父格并置 `isActiveParent`；
+  `scene.anchorCells` 列出的入口格左父格统一改到该坐标；**未列出的格一律不动**。
+- `scene.jumpCells` → 落库前给每个 `{cell,sheet}`（或 `"x,y=N"`）写 `pcHreflink = <base>?sheetIndex=<N-1>` + `openType`。
+- 不写 `scene` 段（或只写空对象）→ **完全不介入**（`applySceneDecl` 返回 null），原单块路径零影响。
+
+> **多块内容**：`build spec` 当前为**单块模型**。多块（上下多个报表）内容可分别构建 /
+> 在其上继续铺块后，统一用 `scene apply --scene A` 做「建公共父格 + 重绑入口格」这一步。
+
+---
+
+## 七、自检清单（交付前必过）
+
+- [ ] 是否先跑了 `scene detect`？**不命中就不加任何特殊配置**（不要「顺手也加上」）。
+- [ ] 场景 A 的公共父格是否在 **Sheet 左上角**、`isActiveParent=true`、有自定义文本？
+- [ ] 场景 A 是否**只**改了「各独立报表的扩展父格」的左父格，其余格父格**未动**？（边界②）
+- [ ] 是否确认这些纵向根**分布在不同行**（而非交叉表的列维/行维）？单报表单数据源**未**加公共父格？（边界①）
+- [ ] 场景 B 的序号格是否 `SequenceNumber` + `Vertical` + `{seq}`，且**没有**残留公式？**普通序号未被误改**？（边界③）
+- [ ] 场景 C 的跳转链接基础地址是否 `/sp/edc/report/view/<reportId>`、`sheetIndex` = **N-1（从 0 起）**、`openType=blank`？（边界④）
+- [ ] 跳转链接是否用了 **ASCII** `?` / `&`（非全角）？
+- [ ] `scene check` 是否 **PASS**（exit 0）？`check-ids` 是否同步合规（BUILD-42）？
+
+---
+
+## 八、相关文档
+
+| 文档 | 关系 |
+|------|------|
+| `SKILL.md` A0.13 / 执行优先级 0.46 | 硬规则正文 |
+| `expansion-block-parent-config-guide.md` | ★ 场景 A **细化**：三类单元格口径 / 泛化禁令 / 合计·总计行 / 扩展带公式格（BUILD-46/47/48） |
+| `pitfalls BUILD-43` | 多报表未绑公共父格（各块扩展互串） |
+| `pitfalls BUILD-44` | 序号用自定义公式生成（导出/分页错位） |
+| `pitfalls BUILD-45` | 跳转 Sheet 的 `sheetIndex` 错位 / 基础地址非预览页 / 打开方式非法 |
+| `pitfalls BUILD-48` | 公共父格泛化到数据格 / 合计行·总计行父格错配 |
+| `event-hreflink-guide.md` | 超链接落库键 `pcHreflink`/`h5Hreflink`/`openType`、ASCII `?`/`&`、父格链传参 |
+| `datasource-selection-and-parent-filter-guide.md` §2.0 | 既有父格链铁律（A0.7），本规则**不替代**它 |
+| `formula-cell-api-guide.md` | Formula 格 API（场景 B 明令**不用**公式生号） |
+| `report-requirement-analysis-template.md` §〇 | 需求分析阶段的场景识别章节 |
+| `crosstab-raw-workbook-guide.md` §六 | 数据集 id 隔离（BUILD-42） |