weaver-e10-builder 1.6.16 → 1.7.0

package/skill-docs/references/report/report-requirement-analysis-template.md

@@ -1,266 +1,266 @@
-# 报表需求分析交付规范（仅用户要「分析」时必做）
-
-> **冷启动禁止通读（纯搭表）**：见 `api-report-build-fast-path.md`。
-> **适用范围**：凡用户**明确要求**「需求分析」「报表需求分析」「根据效果图/截图分析」「报表搭建指导 / 图示」时，按本规范输出完整分析 + **报表搭建图示**。
-> **不适用**：用户只要「搭建 / 创建报表 / 生成报表」—— **跳过本模板**，直接走 `api-report-build-fast-path.md` + `report-delivery-contract.md` **模式 A**（交设计器地址即结束）。
-> **HTML 手册**：非强制；仅用户点名要 HTML/指导文档时才 `build_guide_html.py`。
->
-> **与能力一/二关系**：本规范是能力二（搭建配置指导）在「分析」意图下的输出格式；**禁止**在纯搭表任务中先强制跑本规范再落库。
-
----
-
-## 〇、场景识别（**先判定，再套配置** · SKILL A0.13）
-
-> 本节规则**优先级高于原有报表规则**，但**仅在识别命中时启用**；
-> **不满足识别条件的普通需求 → 完全沿用原有报表逻辑**，不执行任何特殊配置。
-
-**识别方式**：解析需求文件**内容结构**（**不依赖关键词**）—— `e10-cli report scene detect --req <需求文件>`。
-
-| 场景 | 识别条件（结构特征） | 命中后的强制配置（分析报告必须写明） |
-|------|---------------------|-----------------------------------|
-| **A · 同 sheet 多报表** | 同一个 sheet 存在**多行数据源字段单元格** → 上下放置多个独立报表 | ① Sheet 左上角**公共父格**（自定义文本 + `isActiveParent`）；② 各独立报表的**扩展父格**左父格**统一绑定**它；③ 其余格父格**维持不变** |
-| **B · 自增序号** | 单元格标注**【自增序号单元格】** | 统一用系统序号 `{seq}`（`SequenceNumber` · **纵向扩展**）；**禁止**公式生成序号 |
-| **C · 单元格跳转 Sheet 页** | 需求描述含「**点击跳转sheetX / 点击可跳转到sheetX**」 | 当前格加**点击跳转事件**：`pcHreflink` = 报表预览页 `/sp/edc/report/view/<reportId>` + **`sheetIndex=<N-1>`**（sheet1→0，**从 0 起**）；打开方式默认**弹出页** `openType="blank"` |
-
-**识别边界（防过度触发）**：① 仅**同一 sheet 多组独立数据源字段**才算多报表，**单报表单数据源 sheet 不加公共父格**；
-② 公共父格**只**做本 sheet 多报表的父格归集，**不改**单报表内部原有左父格；③ 只有**明确标注**「自增序号单元格」才用 `{seq}`，
-**普通序号 / 手工编号不触发**；④ 跳转 Sheet **仅当**出现「点击跳转sheetX」这类描述才触发，`sheetIndex` **从 0 起**计数。
-
-**判据纪律**：交叉表的「列维表头」(`Horizontal`) 与「行维入口」(`Vertical`) 属**同一矩阵**，
-**不是**两个独立报表 —— 场景 A 只认**纵向扩展根**，且必须**分布在不同行**。
-
-> 分析报告请**单独列出「场景识别」小节**：命中场景 / 结构证据（数据区数、标注位置、跳转描述）/ 对应强制配置 / 未命中则写明「沿用原有规则」。
-> 细则：`branch-scene-guide.md` · `expansion-block-parent-config-guide.md`（场景 A 细化：三类单元格口径/泛化禁令）；注意点 `BUILD-43` / `BUILD-44` / `BUILD-45` / `BUILD-46` / `BUILD-47` / `BUILD-48`。
-
----
-
-## 一、交付清单（缺一不可）
-
-每次报表需求分析必须包含以下 **8 个章节**（顺序固定）：
-
-| # | 章节 | 必含要素 |
-|---|------|----------|
-| 1 | 报表定位 | 名称、业务目的、报表类型（LIST/GROUP/COUNT…）、行基格说明 |
-| 2 | 查询条件 | 条件名、字段类型、默认值、关系运算符、绑定数据集 |
-| 3 | 数据集与数据集过滤 | 物理表/逻辑源、datasetFilter（queryInfoSave）规则 |
-| 4 | 页面与网格布局图示 | ASCII 或 Mermaid：R1 分组行、R2 列名、R3 配置基格 |
-| 5 | 父格与扩展方向图示 | 行基格、左父格链、公式格「不扩展」 |
-| 6 | **列级配置总表** | 见 §二（每列 8 项） |
-| 7 | 公式列说明 | 公式、除零规则、显示格式（百分比等） |
-| 8 | 待业务确认项 | 口径歧义、缺字段、同比/累计定义 |
-
-**禁止**：只写业务口径文字、不给搭建图示；只给列名列表、不写父格/筛选/汇总。
-
----
-
-## 二、列级配置总表（核心）
-
-对 **每一个数据列/公式列**（含行基格 A 列），必须填下表一行：
-
-| 列 | 列名 | 字段/公式 | **字段类型** | **数据集** | **父格** | **扩展方向** | **显示方式** | **汇总方式** | **父格筛选** | **自定义筛选** |
-|:--:|---|---|:---:|:---:|---|:---:|:---:|:---:|---|---|
-| A | 大区/专项 | 大区/专项 | Text/Select | 合同表 | **无（行基格）** | 纵向 | 列表/分组 | — | — | — |
-| B | 当月新客户合同数 | 合同号 | Text | 合同表 | A3 | 纵向 | 汇总 | COUNT DISTINCT | — | 业绩年月=当月 AND 合同种类=新签 |
-| E | 当月伙伴签占比 | `IF(B3=0,"--",D3/B3)` | Formula | — | A3 | **不扩展** | 百分比 | — | — | — |
-
-**字段类型** 枚举（写清物理类型 + 平台 componentKey 如有）：
-
-`Text` · `Number` · `Money` · `Date`/`yearmonth` · `Select` · `Employee` · `Department` · `EBuilder` · `Formula` · `Const`
-
-**父格**：单数据集且无指定计算时填 **默认**（见 `datasource-selection-and-parent-filter-guide.md` §〇）；勿臆造自定义坐标链。
-
-**显示方式**：`列表` · `分组` · `排列` · `汇总` · `隐藏`
-
-**汇总方式**：`—` · `sum` · `count` · `distinctcount` · `avg` · `max` · `min`
-
-**父格筛选**（leftFilterField / 左父格筛选）：跨数据集时**仅连续同源区域的入口列**必填，同区域其余列填 `-`（见 `datasource-selection-and-parent-filter-guide.md` §二）。格式示例：
-
-`合同.销售经理 = EBU团队.责任人`（fieldKey 见 cross-dataset-filter-guide.md）
-
-**数据集选用**：先核主表是否已有用户/部门等展示字段；有则**不要**为显示再挂人员表/部门表（`datasource-selection-and-parent-filter-guide.md` §一）。
-**自定义筛选**（customFilterField / 单元格级）：列口径差异写在此，示例：
-
-`业绩年月=当月` · `合同种类=新签合同` · `签约渠道=伙伴签` · `客户名称 非空`
-
----
-
-## 三、数据集过滤（datasetFilter）专表
-
-与「列级自定义筛选」区分：**datasetFilter** 作用于整个数据集实例（设计器左侧数据集 → 筛选条件 / queryInfoSave）。
-
-| 数据集 | 逻辑关系 | 字段 | 运算符(func) | 值 | 说明 |
-|---|---|---|:---:|---|---|
-| 直销合同业绩表 | AND | 核算机构 | NotContain/uncontains | 亘岩 | 剔除专项机构 |
-| 直销合同业绩表 | AND | 核算机构 | NotContain | 契约锁 | … |
-| EBU团队 | AND | 负责人 | eq | `{userid}` | 行级权限（若需要） |
-
-> API 写入见 `dataset-query-filter-guide.md`；**禁止**与 saveQueryItem（高级搜索）混用。
-
----
-
-## 四、查询条件专表
-
-| 显示名 | 绑定字段 | **字段类型** | 关系 | 默认值 | **显示方式**（必填） | 备注 |
-|---|---|:---:|:---:|---|:---:|---|
-| 年份 | 业绩年月.年 | Number/Select | Equals | `{thisyear}` | **高级搜索**（默认） | 驱动 R1 动态标题 |
-| 月份 | 业绩年月.月 | Select | Equals | `{thismonth}` | **高级搜索**（默认） | 01–12 |
-
-> **显示方式**：设计器必填；默认「高级搜索」（`showWhere: advancedSearch`）；用户指定「筛选」时写筛选（`filter`）。**不可留空**。见 `query-condition-api-guide.md` §2.1。
-> 日期区间 21 项、asNameIndex 等见同文档。
-
----
-
-## 五、搭建布局图示（必须输出 ≥4 张）
-
-### 5.1 页面整体布局
-
-```text
-┌─────────────────────────────────────────────────────────────┐
-│  {报表名称}                                                  │
-├─────────────────────────────────────────────────────────────┤
-│  [查询条件区]  [搜索] [重置]              [导出] [打印] [更多] │
-├─────────────────────────────────────────────────────────────┤
-│                    报表 Sheet 工作区                          │
-└─────────────────────────────────────────────────────────────┘
-```
-
-### 5.2 网格与表头合并（R1/R2/R3）
-
-```text
-        A          B        C        …
-R1  ┌─────────┬──────────────── 分组标题1 ────────────────┬──────── 分组标题2 ────────┐
-R2  │ 列名A   │ 列名B   │ 列名C   │ …
-R3  │ ★行基格 │ 指标B   │ 指标C   │ …   ← 数据区起点，行基格纵向扩展
-    │ 维度值1 │  …      │  …      │
-    │ 维度值2 │  …      │  …      │
-```
-
-- 标注 **★ 行基格** 坐标（如 A3）
-- 标注 R1 合并范围与背景色（若效果图有分区色）
-- R1 动态标题规则：`{查询年}-{查询月}` + 固定后缀
-
-### 5.3 父格与扩展方向（Mermaid 或 ASCII）
-
-```mermaid
-flowchart TB
-    A3["A3 行基格<br/>纵向扩展"]
-    B3["B3 指标列<br/>左父格→A3<br/>纵向+汇总"]
-    E3["E3 公式列<br/>左父格→A3<br/>不扩展"]
-    A3 --> B3
-    A3 --> E3
-```
-
-### 5.4 数据集挂载关系
-
-```mermaid
-flowchart LR
-    Q[查询条件] --> DS1[(数据集1)]
-    Q --> DS2[(数据集2)]
-    DS1 --> C1[列 B~J]
-    DS2 --> C2[列 K~S]
-    DS2 -.leftFilterField.-> DS1
-```
-
-### 5.5 列级筛选叠加示意（可选，多口径报表建议画）
-
-```text
-  [datasetFilter 全局]  +  [列 customFilter 时间/新客/伙伴]  +  [父格筛选 跨表关联]
-```
-
-### 5.6 Sheet1 式单元格配置示例（R3 任选一列展示 6 项）
-
-```text
-┌──────────────────────────────────────────┐
-│ D3 当前月份新客户伙伴签合同数量            │
-├──────────────────────────────────────────┤
-│ 字段：     合同业绩表.合同号               │
-│ 父格：     A3（大区/专项）                 │
-│ 显示方式： 汇总                            │
-│ 扩展方向： 纵向扩展                        │
-│ 父格筛选： -（同数据集无）                 │
-│ 自定义筛选：业绩年月=当月 AND 新客 AND 伙伴签 │
-└──────────────────────────────────────────┘
-```
-
----
-
-## 六、三类筛选分工（必须在分析中写清）
-
-| 类型 | 配置位置 | API | 典型用途 |
-|---|---|---|---|
-| **查询条件** | 报表顶部高级搜索 | saveQueryItem | 年月、大区、负责人 |
-| **数据集过滤** | 左侧数据集筛选 | queryInfoSave | 核算机构剔除、行级权限 |
-| **自定义筛选** | 单元格属性 | customFilterField | 新客/伙伴签/当月/年累计/去年同期 |
-| **父格筛选** | 跨数据集单元格 | leftFilterField | 销售经理=责任人 |
-
-**禁止重复**：已在 datasetFilter 的全局规则（如核算机构 NotContain ×7）**不要**再写入每个单元格 customFilter。
-
----
-
-## 七、公式列规范（分析阶段即写明）
-
-| 列 | 公式 | 除零 | 父格 | 扩展 |
-|---|---|---|---|---|
-| E | `IF(B3=0,"--",D3/B3)` | 显示 `--` | A3 | 不扩展 |
-
-API 写入约束见 `formula-cell-api-guide.md`（cellText 无前导 `=`）。
-
----
-
-## 八、完整示例索引
-
-- **新客户伙伴签约 19 列**：对话示例「2026-06 新客户伙伴签约统计报表」需求分析（A~S 列、双分组表头）
-
----
-
-## 九、自检清单（交付前必过）
-
-- [ ] 是否包含 **§一 全部 8 章节**？
-- [ ] **列级配置总表**是否每列都有：字段类型、父格、扩展方向、汇总、父格筛选、自定义筛选？
-- [ ] 是否单独给出 **数据集过滤表** 和 **查询条件表**？
-- [ ] 是否至少有 **网格布局图 + 父格扩展图**？
-- [ ] 行基格坐标是否明确（如 A3 / F3）？
-- [ ] 公式列是否标注「不扩展」与除零规则？
-- [ ] 三类筛选是否分工清晰、无重复？
-- [ ] 是否列出 **待业务确认项**？
-
----
-
-## 十、需求文件解析（Excel 合并单元格 · 逐格勾稽）
-
-> **报表结构以需求文件为准逐格还原**：标题跨度、纵向/横向合并、行列数——**禁止凭目测**。
-
-### 10.1 xlrd `merged_cells` 为**半开区间**
-
-用 `xlrd` 解析 `.xls`（`formatting_info=True` 才带合并信息）：
-
-```python
-import xlrd
-wb = xlrd.open_workbook(path, formatting_info=True)   # ★ 必须 formatting_info=True，否则 merged_cells 为空
-sh = wb.sheet_by_index(0)
-for (r1, r2, c1, c2) in sh.merged_cells:              # ★ 半开区间 [r1,r2) × [c1,c2)
-    rows = r2 - r1          # 跨行数 = r2 − r1（不是 r2 − r1 + 1）
-    cols = c2 - c1          # 跨列数 = c2 − c1
-    # 合并左上角 = (r1, c1)
-```
-
-| 易错点 | 正解 |
-|--------|------|
-| 跨行/跨列数 | **`r2 − r1`** / **`c2 − c1`**（半开区间，**不要 +1**） |
-| 不开 `formatting_info` | `merged_cells` **恒为空** → 表头合并全丢 |
-| 行列基准 | xlrd 行列均 **0 基**；落到报表 `style.cellType.x/y` 也 0 基 |
-
-### 10.2 逐格严格比对 + 回读勾稽
-
-1. **搭之前**：把需求文件的**每一处合并区间**（含表头逐格）记录成清单（标题跨度、纵向/横向合并、行列数）。
-2. **搭之后**：用 `getReportDevInfo` 回读，把 `xCount/yCount`（合并跨度）与需求清单**逐条勾稽**，
-   任何一处不一致即视为未还原（`dump cells` 可回看每格 `xCount/yCount`）。
-
----
-
-## 十一、多独立扩展块（统计块）需求识别（SKILL A0.13 场景 A 细化）
-
-需求文件里**多行数据源字段单元格**、上下放置多个独立统计块时 → 命中 **场景 A**（见 §〇）。
-分析报告须写明：**公共父格 + 三类单元格口径**（入口格/标题·表头行整行 Const 绑公共父格；数据格保持默认链）、
-**合计行按维度合计 / 总计行独立链**、**扩展带公式格父格**。
-> 细则：`expansion-block-parent-config-guide.md`；注意点 `BUILD-46/47/48`。
+# 报表需求分析交付规范（仅用户要「分析」时必做）
+
+> **冷启动禁止通读（纯搭表）**：见 `api-report-build-fast-path.md`。
+> **适用范围**：凡用户**明确要求**「需求分析」「报表需求分析」「根据效果图/截图分析」「报表搭建指导 / 图示」时，按本规范输出完整分析 + **报表搭建图示**。
+> **不适用**：用户只要「搭建 / 创建报表 / 生成报表」—— **跳过本模板**，直接走 `api-report-build-fast-path.md` + `report-delivery-contract.md` **模式 A**（交设计器地址即结束）。
+> **HTML 手册**：非强制；仅用户点名要 HTML/指导文档时才 `build_guide_html.py`。
+>
+> **与能力一/二关系**：本规范是能力二（搭建配置指导）在「分析」意图下的输出格式；**禁止**在纯搭表任务中先强制跑本规范再落库。
+
+---
+
+## 〇、场景识别（**先判定，再套配置** · SKILL A0.13）
+
+> 本节规则**优先级高于原有报表规则**，但**仅在识别命中时启用**；
+> **不满足识别条件的普通需求 → 完全沿用原有报表逻辑**，不执行任何特殊配置。
+
+**识别方式**：解析需求文件**内容结构**（**不依赖关键词**）—— `e10-cli report scene detect --req <需求文件>`。
+
+| 场景 | 识别条件（结构特征） | 命中后的强制配置（分析报告必须写明） |
+|------|---------------------|-----------------------------------|
+| **A · 同 sheet 多报表** | 同一个 sheet 存在**多行数据源字段单元格** → 上下放置多个独立报表 | ① Sheet 左上角**公共父格**（自定义文本 + `isActiveParent`）；② 各独立报表的**扩展父格**左父格**统一绑定**它；③ 其余格父格**维持不变** |
+| **B · 自增序号** | 单元格标注**【自增序号单元格】** | 统一用系统序号 `{seq}`（`SequenceNumber` · **纵向扩展**）；**禁止**公式生成序号 |
+| **C · 单元格跳转 Sheet 页** | 需求描述含「**点击跳转sheetX / 点击可跳转到sheetX**」 | 当前格加**点击跳转事件**：`pcHreflink` = 报表预览页 `/sp/edc/report/view/<reportId>` + **`sheetIndex=<N-1>`**（sheet1→0，**从 0 起**）；打开方式默认**弹出页** `openType="blank"` |
+
+**识别边界（防过度触发）**：① 仅**同一 sheet 多组独立数据源字段**才算多报表，**单报表单数据源 sheet 不加公共父格**；
+② 公共父格**只**做本 sheet 多报表的父格归集，**不改**单报表内部原有左父格；③ 只有**明确标注**「自增序号单元格」才用 `{seq}`，
+**普通序号 / 手工编号不触发**；④ 跳转 Sheet **仅当**出现「点击跳转sheetX」这类描述才触发，`sheetIndex` **从 0 起**计数。
+
+**判据纪律**：交叉表的「列维表头」(`Horizontal`) 与「行维入口」(`Vertical`) 属**同一矩阵**，
+**不是**两个独立报表 —— 场景 A 只认**纵向扩展根**，且必须**分布在不同行**。
+
+> 分析报告请**单独列出「场景识别」小节**：命中场景 / 结构证据（数据区数、标注位置、跳转描述）/ 对应强制配置 / 未命中则写明「沿用原有规则」。
+> 细则：`branch-scene-guide.md` · `expansion-block-parent-config-guide.md`（场景 A 细化：三类单元格口径/泛化禁令）；注意点 `BUILD-43` / `BUILD-44` / `BUILD-45` / `BUILD-46` / `BUILD-47` / `BUILD-48`。
+
+---
+
+## 一、交付清单（缺一不可）
+
+每次报表需求分析必须包含以下 **8 个章节**（顺序固定）：
+
+| # | 章节 | 必含要素 |
+|---|------|----------|
+| 1 | 报表定位 | 名称、业务目的、报表类型（LIST/GROUP/COUNT…）、行基格说明 |
+| 2 | 查询条件 | 条件名、字段类型、默认值、关系运算符、绑定数据集 |
+| 3 | 数据集与数据集过滤 | 物理表/逻辑源、datasetFilter（queryInfoSave）规则 |
+| 4 | 页面与网格布局图示 | ASCII 或 Mermaid：R1 分组行、R2 列名、R3 配置基格 |
+| 5 | 父格与扩展方向图示 | 行基格、左父格链、公式格「不扩展」 |
+| 6 | **列级配置总表** | 见 §二（每列 8 项） |
+| 7 | 公式列说明 | 公式、除零规则、显示格式（百分比等） |
+| 8 | 待业务确认项 | 口径歧义、缺字段、同比/累计定义 |
+
+**禁止**：只写业务口径文字、不给搭建图示；只给列名列表、不写父格/筛选/汇总。
+
+---
+
+## 二、列级配置总表（核心）
+
+对 **每一个数据列/公式列**（含行基格 A 列），必须填下表一行：
+
+| 列 | 列名 | 字段/公式 | **字段类型** | **数据集** | **父格** | **扩展方向** | **显示方式** | **汇总方式** | **父格筛选** | **自定义筛选** |
+|:--:|---|---|:---:|:---:|---|:---:|:---:|:---:|---|---|
+| A | 大区/专项 | 大区/专项 | Text/Select | 合同表 | **无（行基格）** | 纵向 | 列表/分组 | — | — | — |
+| B | 当月新客户合同数 | 合同号 | Text | 合同表 | A3 | 纵向 | 汇总 | COUNT DISTINCT | — | 业绩年月=当月 AND 合同种类=新签 |
+| E | 当月伙伴签占比 | `IF(B3=0,"--",D3/B3)` | Formula | — | A3 | **不扩展** | 百分比 | — | — | — |
+
+**字段类型** 枚举（写清物理类型 + 平台 componentKey 如有）：
+
+`Text` · `Number` · `Money` · `Date`/`yearmonth` · `Select` · `Employee` · `Department` · `EBuilder` · `Formula` · `Const`
+
+**父格**：单数据集且无指定计算时填 **默认**（见 `datasource-selection-and-parent-filter-guide.md` §〇）；勿臆造自定义坐标链。
+
+**显示方式**：`列表` · `分组` · `排列` · `汇总` · `隐藏`
+
+**汇总方式**：`—` · `sum` · `count` · `distinctcount` · `avg` · `max` · `min`
+
+**父格筛选**（leftFilterField / 左父格筛选）：跨数据集时**仅连续同源区域的入口列**必填，同区域其余列填 `-`（见 `datasource-selection-and-parent-filter-guide.md` §二）。格式示例：
+
+`合同.销售经理 = EBU团队.责任人`（fieldKey 见 cross-dataset-filter-guide.md）
+
+**数据集选用**：先核主表是否已有用户/部门等展示字段；有则**不要**为显示再挂人员表/部门表（`datasource-selection-and-parent-filter-guide.md` §一）。
+**自定义筛选**（customFilterField / 单元格级）：列口径差异写在此，示例：
+
+`业绩年月=当月` · `合同种类=新签合同` · `签约渠道=伙伴签` · `客户名称 非空`
+
+---
+
+## 三、数据集过滤（datasetFilter）专表
+
+与「列级自定义筛选」区分：**datasetFilter** 作用于整个数据集实例（设计器左侧数据集 → 筛选条件 / queryInfoSave）。
+
+| 数据集 | 逻辑关系 | 字段 | 运算符(func) | 值 | 说明 |
+|---|---|---|:---:|---|---|
+| 直销合同业绩表 | AND | 核算机构 | NotContain/uncontains | 亘岩 | 剔除专项机构 |
+| 直销合同业绩表 | AND | 核算机构 | NotContain | 契约锁 | … |
+| EBU团队 | AND | 负责人 | eq | `{userid}` | 行级权限（若需要） |
+
+> API 写入见 `dataset-query-filter-guide.md`；**禁止**与 saveQueryItem（高级搜索）混用。
+
+---
+
+## 四、查询条件专表
+
+| 显示名 | 绑定字段 | **字段类型** | 关系 | 默认值 | **显示方式**（必填） | 备注 |
+|---|---|:---:|:---:|---|:---:|---|
+| 年份 | 业绩年月.年 | Number/Select | Equals | `{thisyear}` | **高级搜索**（默认） | 驱动 R1 动态标题 |
+| 月份 | 业绩年月.月 | Select | Equals | `{thismonth}` | **高级搜索**（默认） | 01–12 |
+
+> **显示方式**：设计器必填；默认「高级搜索」（`showWhere: advancedSearch`）；用户指定「筛选」时写筛选（`filter`）。**不可留空**。见 `query-condition-api-guide.md` §2.1。
+> 日期区间 21 项、asNameIndex 等见同文档。
+
+---
+
+## 五、搭建布局图示（必须输出 ≥4 张）
+
+### 5.1 页面整体布局
+
+```text
+┌─────────────────────────────────────────────────────────────┐
+│  {报表名称}                                                  │
+├─────────────────────────────────────────────────────────────┤
+│  [查询条件区]  [搜索] [重置]              [导出] [打印] [更多] │
+├─────────────────────────────────────────────────────────────┤
+│                    报表 Sheet 工作区                          │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### 5.2 网格与表头合并（R1/R2/R3）
+
+```text
+        A          B        C        …
+R1  ┌─────────┬──────────────── 分组标题1 ────────────────┬──────── 分组标题2 ────────┐
+R2  │ 列名A   │ 列名B   │ 列名C   │ …
+R3  │ ★行基格 │ 指标B   │ 指标C   │ …   ← 数据区起点，行基格纵向扩展
+    │ 维度值1 │  …      │  …      │
+    │ 维度值2 │  …      │  …      │
+```
+
+- 标注 **★ 行基格** 坐标（如 A3）
+- 标注 R1 合并范围与背景色（若效果图有分区色）
+- R1 动态标题规则：`{查询年}-{查询月}` + 固定后缀
+
+### 5.3 父格与扩展方向（Mermaid 或 ASCII）
+
+```mermaid
+flowchart TB
+    A3["A3 行基格<br/>纵向扩展"]
+    B3["B3 指标列<br/>左父格→A3<br/>纵向+汇总"]
+    E3["E3 公式列<br/>左父格→A3<br/>不扩展"]
+    A3 --> B3
+    A3 --> E3
+```
+
+### 5.4 数据集挂载关系
+
+```mermaid
+flowchart LR
+    Q[查询条件] --> DS1[(数据集1)]
+    Q --> DS2[(数据集2)]
+    DS1 --> C1[列 B~J]
+    DS2 --> C2[列 K~S]
+    DS2 -.leftFilterField.-> DS1
+```
+
+### 5.5 列级筛选叠加示意（可选，多口径报表建议画）
+
+```text
+  [datasetFilter 全局]  +  [列 customFilter 时间/新客/伙伴]  +  [父格筛选 跨表关联]
+```
+
+### 5.6 Sheet1 式单元格配置示例（R3 任选一列展示 6 项）
+
+```text
+┌──────────────────────────────────────────┐
+│ D3 当前月份新客户伙伴签合同数量            │
+├──────────────────────────────────────────┤
+│ 字段：     合同业绩表.合同号               │
+│ 父格：     A3（大区/专项）                 │
+│ 显示方式： 汇总                            │
+│ 扩展方向： 纵向扩展                        │
+│ 父格筛选： -（同数据集无）                 │
+│ 自定义筛选：业绩年月=当月 AND 新客 AND 伙伴签 │
+└──────────────────────────────────────────┘
+```
+
+---
+
+## 六、三类筛选分工（必须在分析中写清）
+
+| 类型 | 配置位置 | API | 典型用途 |
+|---|---|---|---|
+| **查询条件** | 报表顶部高级搜索 | saveQueryItem | 年月、大区、负责人 |
+| **数据集过滤** | 左侧数据集筛选 | queryInfoSave | 核算机构剔除、行级权限 |
+| **自定义筛选** | 单元格属性 | customFilterField | 新客/伙伴签/当月/年累计/去年同期 |
+| **父格筛选** | 跨数据集单元格 | leftFilterField | 销售经理=责任人 |
+
+**禁止重复**：已在 datasetFilter 的全局规则（如核算机构 NotContain ×7）**不要**再写入每个单元格 customFilter。
+
+---
+
+## 七、公式列规范（分析阶段即写明）
+
+| 列 | 公式 | 除零 | 父格 | 扩展 |
+|---|---|---|---|---|
+| E | `IF(B3=0,"--",D3/B3)` | 显示 `--` | A3 | 不扩展 |
+
+API 写入约束见 `formula-cell-api-guide.md`（cellText 无前导 `=`）。
+
+---
+
+## 八、完整示例索引
+
+- **新客户伙伴签约 19 列**：对话示例「2026-06 新客户伙伴签约统计报表」需求分析（A~S 列、双分组表头）
+
+---
+
+## 九、自检清单（交付前必过）
+
+- [ ] 是否包含 **§一 全部 8 章节**？
+- [ ] **列级配置总表**是否每列都有：字段类型、父格、扩展方向、汇总、父格筛选、自定义筛选？
+- [ ] 是否单独给出 **数据集过滤表** 和 **查询条件表**？
+- [ ] 是否至少有 **网格布局图 + 父格扩展图**？
+- [ ] 行基格坐标是否明确（如 A3 / F3）？
+- [ ] 公式列是否标注「不扩展」与除零规则？
+- [ ] 三类筛选是否分工清晰、无重复？
+- [ ] 是否列出 **待业务确认项**？
+
+---
+
+## 十、需求文件解析（Excel 合并单元格 · 逐格勾稽）
+
+> **报表结构以需求文件为准逐格还原**：标题跨度、纵向/横向合并、行列数——**禁止凭目测**。
+
+### 10.1 xlrd `merged_cells` 为**半开区间**
+
+用 `xlrd` 解析 `.xls`（`formatting_info=True` 才带合并信息）：
+
+```python
+import xlrd
+wb = xlrd.open_workbook(path, formatting_info=True)   # ★ 必须 formatting_info=True，否则 merged_cells 为空
+sh = wb.sheet_by_index(0)
+for (r1, r2, c1, c2) in sh.merged_cells:              # ★ 半开区间 [r1,r2) × [c1,c2)
+    rows = r2 - r1          # 跨行数 = r2 − r1（不是 r2 − r1 + 1）
+    cols = c2 - c1          # 跨列数 = c2 − c1
+    # 合并左上角 = (r1, c1)
+```
+
+| 易错点 | 正解 |
+|--------|------|
+| 跨行/跨列数 | **`r2 − r1`** / **`c2 − c1`**（半开区间，**不要 +1**） |
+| 不开 `formatting_info` | `merged_cells` **恒为空** → 表头合并全丢 |
+| 行列基准 | xlrd 行列均 **0 基**；落到报表 `style.cellType.x/y` 也 0 基 |
+
+### 10.2 逐格严格比对 + 回读勾稽
+
+1. **搭之前**：把需求文件的**每一处合并区间**（含表头逐格）记录成清单（标题跨度、纵向/横向合并、行列数）。
+2. **搭之后**：用 `getReportDevInfo` 回读，把 `xCount/yCount`（合并跨度）与需求清单**逐条勾稽**，
+   任何一处不一致即视为未还原（`dump cells` 可回看每格 `xCount/yCount`）。
+
+---
+
+## 十一、多独立扩展块（统计块）需求识别（SKILL A0.13 场景 A 细化）
+
+需求文件里**多行数据源字段单元格**、上下放置多个独立统计块时 → 命中 **场景 A**（见 §〇）。
+分析报告须写明：**公共父格 + 三类单元格口径**（入口格/标题·表头行整行 Const 绑公共父格；数据格保持默认链）、
+**合计行按维度合计 / 总计行独立链**、**扩展带公式格父格**。
+> 细则：`expansion-block-parent-config-guide.md`；注意点 `BUILD-46/47/48`。