weaver-e10-builder 1.6.15 → 1.6.16

package/skill-docs/references/report/datasource-selection-and-parent-filter-guide.md

@@ -1,183 +1,183 @@
-# 数据源选用与多源父格（强制）
-
-> **适用**：需求分析、配置生成、API 建表。
-> **目标**：少挂数据源、少配父格筛选、控制找表空耗。
-
----
-
-## 〇、左父格默认优先（强制 · 单数据集）
-
-> **事故对照**：同一需求文件生成的「供应商信息管理」`866766714447126529` 与「供应商-1」`1312703681350901760` 均为**单数据集**，却一个把字段左父格串成「逐列自定义链」，一个把明细列都自定义挂到分组列 —— 设计器里大量显示「自定义」，与常规「默认」不一致。
-
-**原则**：无多数据集、且需求**未指定**特殊计算/交叉/合计挂靠时，**Field / 普通 Const** 左父格一律默认（`leftX=-1, leftY=-1` / `["default",0,0]`）。
-
-> **例外（强制）**：**超链接 Const**（`pcHreflink` 含 `{L4}` 等）**不适用**「左父格默认」。上父格仍为 `-1`；左父格须指向占位依赖的数据格。见 `report-self-check-guide.md` §2.2。
-> **已有报表**：用户未点名时**禁止**批量改父格。
-
-| 场景 | 左父格 | 说明 |
-|------|--------|------|
-| **单数据集**列表 / 简单分组 | **默认** | 引擎按相邻扩展自动解析；**禁止**为「看起来整齐」逐格写 custom |
-| 单数据集但需求写明合计行挂某分组、交叉表行列挂靠、公式指定父格 | **自定义**（仅涉及的格） | 见 building-guide / formula-cell-api-guide |
-| **多数据集**跨源关联 | 连续同源区**仅入口格**自定义 + 父格筛选 | 见 §二（**最高优先**）；区域内**其余字段左父格指「入口格」** |
-
-**硬约束**
-
-1. 报表内有效 `dataSetId` 只有 **1 个**（忽略 `-1`）→ **新建/从需求生成时** Field 左父格用 default；**禁止**链式 `左父格=上一列`、也**禁止**无必要地把所有 List 列挂到同一 Group 列。
-2. 同数据集 **禁止**配 `leftFilterField` / `subordination`（那是跨源用的）。
-3. 只有用户/需求明确「按 XX 分组计算」「合计挂在 A3」「交叉维」时才对该格设自定义父格。
-4. 需求分析列级表：单数据集时「父格」列填 **默认**，勿臆造自定义坐标。
-5. **禁止擅自改已有报表父格**：用户仅强调「规则上默认即可」时，**只更新 Skill/新建逻辑**；**不得**对线上已有报表批量把自定义左/上父格改成 default，除非用户**明确要求修改该报表**。
-6. **上父格**：无交叉/横向扩展需求时保持默认/无；勿给普通列表单元格（如 M4 链接文案）乱设上父格。
-
----
-
-## 一、尽可能少用数据源（强制）
-
-**原则**：主业务表上**已有**可展示字段时，**禁止**仅为「好看/完整」再挂关联表。
-
-| 场景 | 正确做法 | 错误做法 |
-|------|----------|----------|
-| 考勤表已有用户 ID / 姓名 / 工号 | 直接绑考勤表字段 | 再关联人员表只为显示人员 |
-| 人员表已有部门名称 / 部门 ID | 直接绑人员表部门字段 | 再关联部门表只为显示部门 |
-| 合同表已有供应商名称 | 直接绑合同表字段 | 再挂供应商主数据表只为回显名称 |
-| 需求明确要「主数据维度扩展」（如按部门树下钻、人员多属性）且主表无该字段 | 才允许加第二数据源 | — |
-
-**判定顺序**
-
-1. 先读主表 `fieldsAndOriginFields` / `form read`，列出需求列能否在**同一 sourceId** 上取到。
-2. 能取到 → **只 add 这一张表**（或需求点名的最少表集合）。
-3. 取不到且业务必须跨表关联 → 再加第二源，并走 §二 父格规则。
-
-**禁止**：按「业务实体清单」机械每人/每部门/每组织各挂一张表；禁止未核对字段就先 `addDataset` 多张。
-
----
-
-## 二、多数据源 · 连续区域父格链（★★ 最高优先 · 强制）
-
-> **本节是父格配置的第一优先规则**：先认「入口格」，其余同源字段**全部跟随入口格**。
-> 跨数据集关联的 fieldKey 写法仍遵守 `cross-dataset-filter-guide.md`（`id=currentField` 等）；本节约束 **父格链怎么连、筛选配在哪几格**。
-
-### 2.0 一句话铁律（先记这句）
-
-> **父格筛选只配在该区域的「入口格」上；同区域内的后续字段只要是同一个数据集，一律以这个入口字段为父格。**
-
-### 2.1 规则
-
-同一布局里，若**连续一片区域**（同行连续列 / 同列连续行）的字段**全部来自同一数据源 B**，且整个区域需挂到另一数据源 A 上：
-
-| 角色 | 单元格 | 左父格 `leftX/leftY` | `subordination` + `leftFilterField`（父格筛选） |
-|------|--------|----------------------|--------------------------------------------------|
-| **入口格** | 该连续区域的**第一个**字段（最左 / 最上） | 指向 **A 侧关联键字段所在格**（自定义父格） | **必须配置**（A.key = B.fk） |
-| **后续格** | 同区域其余**同源**字段 | **必须显式指向「本区域入口格」的坐标** | **必须为空**（继承入口格的筛选） |
-
-四条硬约束：
-
-1. **筛选唯一**：一个连续同源区域**有且仅有 1 个入口格**，只有它能配 `subordination` / `leftFilterField`；任何后续格再配一遍 = 违规（重复筛选）。
-2. **父格跟随**：后续同源字段的左父格**必须**是「本区域入口格」坐标；**禁止**指向异源格（典型误配：指到 A 区的某个格）。指了异源格又没带筛选 → 该列**跨源却无筛选**，脱离入口格的关联约束 → **数据串源、结果对不上**。
-3. **显式写坐标**：多数据集报表里**不要**依赖引擎自动解析扩展链（`-1,-1` / 设计器「默认」）。入口格与后续格一律显式写 `leftX/leftY`，落库后可直接回读校验。
-4. **区域被打断就分段**：连续区域被公式列 / 常量列 / 异源列打断 → **每一段各自**认定入口格（段内规则不变，段首配筛选、段内其余跟随段首）。
-
-> **与 §〇 的边界（勿混）**：本节只适用**多数据集**报表的跨源区域。
-> **单数据集**报表的 Field 左父格仍按 §〇 用默认 `-1,-1`，**不要**套用本节。
-
-### 2.2 示意
-
-```
-A 区（数据源 A）… 〔关联键格〕
-B 区连续（数据源 B，例：第 3 行 E~G 列）：
-  E3  左父格 → 〔A 区关联键格〕      + 父格筛选（A.key = B.fk）   ← 入口格：唯一配筛选的格
-  F3  左父格 → E3（本区域入口格）    · 父格筛选 空
-  G3  左父格 → E3（本区域入口格）    · 父格筛选 空
-  …
-```
-
-### 2.3 反例（验证踩过）
-
-1. **后续格指向异源格**（真实事故）：连续同源区域 E3/F3/G3，入口格 E3 的筛选配好了，但 F3/G3 的 `leftX/leftY` 指到了 A 区的 A3、且没带筛选 → 这两列**跨源却无筛选**，脱离入口格约束、数据串源；设计器里的表现就是用户问的「G3 为啥没有配置父格筛选」。
-   - 报表 `1315015331503456271` 验证：F3/G3 的 `leftY` 由 `0`（A 列）改为 `4`（E 列）后恢复正常。
-2. **每格都配一遍**：对 B1、B2、B3 **每个**都设左父格指向 A 区，并各写一遍 `leftFilterField` → 冗余、易错、预览异常风险高。
-3. **把被打断的区域当一整块**：连续区域被公式列 / 常量列打断后仍只配一个入口筛选 → 关联失效。
-
-### 2.4 与需求分析表的填法
-
-列级配置总表中：
-
-- **连续同源区域**：**仅入口列**「父格筛选」写关联；其余列父格筛选填 `-`，**父格填「本区域入口列」**（不是 `default`、更不是异源格）。见 §2.1。
-- **关联键来源**（见 §2.5）：需求已写明 → 直接填；推断得到 → 父格筛选列标注「推断·待确认」，并在待确认项列出。
-
-### 2.5 多表关联键：需求优先 · 推断须确认（强制）
-
-> 报表挂 **≥2 个数据集** 且需跨源父格筛选时适用。配置写法仍见 `cross-dataset-filter-guide.md`。
-
-#### 2.5.1 关联键如何确定
-
-| 优先级 | 来源 | Agent 行为 |
-|--------|------|------------|
-| **1** | 需求/用户**明确**写出两表关联（如「销售单.客户ID = 客户.ID」「按供应商名称关联」） | **直接**按该对字段配入口格 `subordination` + `leftFilterField`；**不必**再问 |
-| **2** | 需求**未写**关联字段 | 用两表字段元数据**检索匹配**（见下）→ 选出候选 → **必须提示用户确认** 后再落库；用户未回时可用置信度最高的一对**先配**，但交付时注明「推断关联·请确认」 |
-| **3** | 无法推断或候选冲突 | **打断询问**关联关系；**禁止**瞎配；可先交单表/已确认部分，关联筛选标待补（非阻塞，见 `failure-cleanup-and-nonblocking-guide.md`） |
-
-#### 2.5.2 字段值/元数据匹配（需求未写明时）
-
-对父表 A、子表 B 的字段列表（优先 `fieldsAndOriginFields` / `e10-cli report join suggest`）：
-
-1. **显示名全等**（如双方都有「供应商名称」）→ 高置信
-2. **系统名/业务键同构**（同 `field_*` 后缀模式、`xxxId`↔`xxx`、外键命名含对方表名）→ 中高置信
-3. **名称近似**（去后缀「编号/名称/ID」后相同、一方「客户」一方「客户名称」）→ 中置信
-4. **多候选同分** → 全部列出，**禁止**静默任选一个不告知
-
-**禁止**：仅凭表名臆造 fieldKey；禁止用显示名当 `parentField`/`currentField`（必须三段式 fieldKey）。
-
-#### 2.5.3 必须给用户的确认话术（推断时强制）
-
-推断关联后，交付/询问中**至少**说明：
-
-```
-【关联待确认】表 A「…」与表 B「…」未在需求中写明关联字段。
-已按字段匹配推断：A.{显示名/系统名}  Equals  B.{显示名/系统名}
-请确认是否正确；若不正确请给出正确关联（A.字段 = B.字段）。
-```
-
-用户确认或纠正后，再改入口格筛选（定点改，见 `targeted-fix-guide.md`）。
-
-#### 2.5.4 CLI（优先）
-
-```bash
-e10-cli report join suggest --app-id <appId> --parent-source <sourceIdA> --child-source <sourceIdB>
-# 或按表名：
-e10-cli report join suggest --app-id <appId> --parent-form "销售单" --child-form "销售明细"
-```
-
-输出候选对 + `needConfirm=true`；Agent **优先调 CLI**，勿手写比对脚本。
-
----
-
-### 2.6 自检判据（落库前后各跑一次 · 可机械执行）
-
-对**每个 Field 格**取四件事：① 本格 `dataSetId`；② 本格左父格坐标 → ③ 左父格格 `dataSetId`；④ 本格 `leftFilterField` 是否非空。逐条比对：
-
-| 级别 | 判据 | 结论 / 处置 |
-|------|------|-------------|
-| 🔴 | ①≠③ 且 ④ 空 | **跨源却无筛选**：本格若是入口格 → 补筛选；否则 → 左父格改指入口格 |
-| 🔴 | ①≠③ 且本格**不是**区域入口格 | **后续格指了异源**：改指入口格坐标，并清空筛选 |
-| 🔴 | ①=③ 但 ④ 非空 | **同源却配了跨源筛选**：只保留入口格那一份，其余清空 |
-| 🔴 | 同一连续同源区域内 ④ 非空的格 **> 1** | **重复配筛选**：只留入口格 |
-| 🟡 | 多数据集报表里，同源后续格左父格为 `-1,-1` | 扩展链不明：显式改为入口格坐标 |
-
-**回读校验（强制）**：改完父格必须重新读一次（`getReportDevInfo`）确认 `leftX/leftY` 真的生效——服务端可能**静默忽略**。
-CLI：`e10-cli report fix parent --report-id <id> --set-parent "x,y=leftX,leftY" [--apply]`（可重复；内置落库后回读，未生效即 exit 2）。
-坐标口径：`x` = 行（0 基）、`y` = 列（0 基）。
-
----
-
-## 三、与找表耗时控制的关系
-
-少挂源 = 少次 `addDataset` / `fields`。找不准表时的打断规则见 **`app-datasource-lookup-guide.md` §七**。
-
-| 文档 | 关系 |
-|------|------|
-| `app-datasource-lookup-guide.md` | 应用内找表 + 多轮打断询问 |
-| `cross-dataset-filter-guide.md` | 入口格筛选的 fieldKey 写法 |
-| `e10-cli report-cli.md` | **CLI 优先**：找表 / join suggest / verify / 删壳 |
-| `api-report-build-fast-path.md` | 建表流程引用本节 |
-| `report-requirement-analysis-template.md` | 列级表父格筛选填法 |
+# 数据源选用与多源父格（强制）
+
+> **适用**：需求分析、配置生成、API 建表。
+> **目标**：少挂数据源、少配父格筛选、控制找表空耗。
+
+---
+
+## 〇、左父格默认优先（强制 · 单数据集）
+
+> **事故对照**：同一需求文件生成的「供应商信息管理」`866766714447126529` 与「供应商-1」`1312703681350901760` 均为**单数据集**，却一个把字段左父格串成「逐列自定义链」，一个把明细列都自定义挂到分组列 —— 设计器里大量显示「自定义」，与常规「默认」不一致。
+
+**原则**：无多数据集、且需求**未指定**特殊计算/交叉/合计挂靠时，**Field / 普通 Const** 左父格一律默认（`leftX=-1, leftY=-1` / `["default",0,0]`）。
+
+> **例外（强制）**：**超链接 Const**（`pcHreflink` 含 `{L4}` 等）**不适用**「左父格默认」。上父格仍为 `-1`；左父格须指向占位依赖的数据格。见 `report-self-check-guide.md` §2.2。
+> **已有报表**：用户未点名时**禁止**批量改父格。
+
+| 场景 | 左父格 | 说明 |
+|------|--------|------|
+| **单数据集**列表 / 简单分组 | **默认** | 引擎按相邻扩展自动解析；**禁止**为「看起来整齐」逐格写 custom |
+| 单数据集但需求写明合计行挂某分组、交叉表行列挂靠、公式指定父格 | **自定义**（仅涉及的格） | 见 building-guide / formula-cell-api-guide |
+| **多数据集**跨源关联 | 连续同源区**仅入口格**自定义 + 父格筛选 | 见 §二（**最高优先**）；区域内**其余字段左父格指「入口格」** |
+
+**硬约束**
+
+1. 报表内有效 `dataSetId` 只有 **1 个**（忽略 `-1`）→ **新建/从需求生成时** Field 左父格用 default；**禁止**链式 `左父格=上一列`、也**禁止**无必要地把所有 List 列挂到同一 Group 列。
+2. 同数据集 **禁止**配 `leftFilterField` / `subordination`（那是跨源用的）。
+3. 只有用户/需求明确「按 XX 分组计算」「合计挂在 A3」「交叉维」时才对该格设自定义父格。
+4. 需求分析列级表：单数据集时「父格」列填 **默认**，勿臆造自定义坐标。
+5. **禁止擅自改已有报表父格**：用户仅强调「规则上默认即可」时，**只更新 Skill/新建逻辑**；**不得**对线上已有报表批量把自定义左/上父格改成 default，除非用户**明确要求修改该报表**。
+6. **上父格**：无交叉/横向扩展需求时保持默认/无；勿给普通列表单元格（如 M4 链接文案）乱设上父格。
+
+---
+
+## 一、尽可能少用数据源（强制）
+
+**原则**：主业务表上**已有**可展示字段时，**禁止**仅为「好看/完整」再挂关联表。
+
+| 场景 | 正确做法 | 错误做法 |
+|------|----------|----------|
+| 考勤表已有用户 ID / 姓名 / 工号 | 直接绑考勤表字段 | 再关联人员表只为显示人员 |
+| 人员表已有部门名称 / 部门 ID | 直接绑人员表部门字段 | 再关联部门表只为显示部门 |
+| 合同表已有供应商名称 | 直接绑合同表字段 | 再挂供应商主数据表只为回显名称 |
+| 需求明确要「主数据维度扩展」（如按部门树下钻、人员多属性）且主表无该字段 | 才允许加第二数据源 | — |
+
+**判定顺序**
+
+1. 先读主表 `fieldsAndOriginFields` / `form read`，列出需求列能否在**同一 sourceId** 上取到。
+2. 能取到 → **只 add 这一张表**（或需求点名的最少表集合）。
+3. 取不到且业务必须跨表关联 → 再加第二源，并走 §二 父格规则。
+
+**禁止**：按「业务实体清单」机械每人/每部门/每组织各挂一张表；禁止未核对字段就先 `addDataset` 多张。
+
+---
+
+## 二、多数据源 · 连续区域父格链（★★ 最高优先 · 强制）
+
+> **本节是父格配置的第一优先规则**：先认「入口格」，其余同源字段**全部跟随入口格**。
+> 跨数据集关联的 fieldKey 写法仍遵守 `cross-dataset-filter-guide.md`（`id=currentField` 等）；本节约束 **父格链怎么连、筛选配在哪几格**。
+
+### 2.0 一句话铁律（先记这句）
+
+> **父格筛选只配在该区域的「入口格」上；同区域内的后续字段只要是同一个数据集，一律以这个入口字段为父格。**
+
+### 2.1 规则
+
+同一布局里，若**连续一片区域**（同行连续列 / 同列连续行）的字段**全部来自同一数据源 B**，且整个区域需挂到另一数据源 A 上：
+
+| 角色 | 单元格 | 左父格 `leftX/leftY` | `subordination` + `leftFilterField`（父格筛选） |
+|------|--------|----------------------|--------------------------------------------------|
+| **入口格** | 该连续区域的**第一个**字段（最左 / 最上） | 指向 **A 侧关联键字段所在格**（自定义父格） | **必须配置**（A.key = B.fk） |
+| **后续格** | 同区域其余**同源**字段 | **必须显式指向「本区域入口格」的坐标** | **必须为空**（继承入口格的筛选） |
+
+四条硬约束：
+
+1. **筛选唯一**：一个连续同源区域**有且仅有 1 个入口格**，只有它能配 `subordination` / `leftFilterField`；任何后续格再配一遍 = 违规（重复筛选）。
+2. **父格跟随**：后续同源字段的左父格**必须**是「本区域入口格」坐标；**禁止**指向异源格（典型误配：指到 A 区的某个格）。指了异源格又没带筛选 → 该列**跨源却无筛选**，脱离入口格的关联约束 → **数据串源、结果对不上**。
+3. **显式写坐标**：多数据集报表里**不要**依赖引擎自动解析扩展链（`-1,-1` / 设计器「默认」）。入口格与后续格一律显式写 `leftX/leftY`，落库后可直接回读校验。
+4. **区域被打断就分段**：连续区域被公式列 / 常量列 / 异源列打断 → **每一段各自**认定入口格（段内规则不变，段首配筛选、段内其余跟随段首）。
+
+> **与 §〇 的边界（勿混）**：本节只适用**多数据集**报表的跨源区域。
+> **单数据集**报表的 Field 左父格仍按 §〇 用默认 `-1,-1`，**不要**套用本节。
+
+### 2.2 示意
+
+```
+A 区（数据源 A）… 〔关联键格〕
+B 区连续（数据源 B，例：第 3 行 E~G 列）：
+  E3  左父格 → 〔A 区关联键格〕      + 父格筛选（A.key = B.fk）   ← 入口格：唯一配筛选的格
+  F3  左父格 → E3（本区域入口格）    · 父格筛选 空
+  G3  左父格 → E3（本区域入口格）    · 父格筛选 空
+  …
+```
+
+### 2.3 反例（验证踩过）
+
+1. **后续格指向异源格**（真实事故）：连续同源区域 E3/F3/G3，入口格 E3 的筛选配好了，但 F3/G3 的 `leftX/leftY` 指到了 A 区的 A3、且没带筛选 → 这两列**跨源却无筛选**，脱离入口格约束、数据串源；设计器里的表现就是用户问的「G3 为啥没有配置父格筛选」。
+   - 报表 `1315015331503456271` 验证：F3/G3 的 `leftY` 由 `0`（A 列）改为 `4`（E 列）后恢复正常。
+2. **每格都配一遍**：对 B1、B2、B3 **每个**都设左父格指向 A 区，并各写一遍 `leftFilterField` → 冗余、易错、预览异常风险高。
+3. **把被打断的区域当一整块**：连续区域被公式列 / 常量列打断后仍只配一个入口筛选 → 关联失效。
+
+### 2.4 与需求分析表的填法
+
+列级配置总表中：
+
+- **连续同源区域**：**仅入口列**「父格筛选」写关联；其余列父格筛选填 `-`，**父格填「本区域入口列」**（不是 `default`、更不是异源格）。见 §2.1。
+- **关联键来源**（见 §2.5）：需求已写明 → 直接填；推断得到 → 父格筛选列标注「推断·待确认」，并在待确认项列出。
+
+### 2.5 多表关联键：需求优先 · 推断须确认（强制）
+
+> 报表挂 **≥2 个数据集** 且需跨源父格筛选时适用。配置写法仍见 `cross-dataset-filter-guide.md`。
+
+#### 2.5.1 关联键如何确定
+
+| 优先级 | 来源 | Agent 行为 |
+|--------|------|------------|
+| **1** | 需求/用户**明确**写出两表关联（如「销售单.客户ID = 客户.ID」「按供应商名称关联」） | **直接**按该对字段配入口格 `subordination` + `leftFilterField`；**不必**再问 |
+| **2** | 需求**未写**关联字段 | 用两表字段元数据**检索匹配**（见下）→ 选出候选 → **必须提示用户确认** 后再落库；用户未回时可用置信度最高的一对**先配**，但交付时注明「推断关联·请确认」 |
+| **3** | 无法推断或候选冲突 | **打断询问**关联关系；**禁止**瞎配；可先交单表/已确认部分，关联筛选标待补（非阻塞，见 `failure-cleanup-and-nonblocking-guide.md`） |
+
+#### 2.5.2 字段值/元数据匹配（需求未写明时）
+
+对父表 A、子表 B 的字段列表（优先 `fieldsAndOriginFields` / `e10-cli report join suggest`）：
+
+1. **显示名全等**（如双方都有「供应商名称」）→ 高置信
+2. **系统名/业务键同构**（同 `field_*` 后缀模式、`xxxId`↔`xxx`、外键命名含对方表名）→ 中高置信
+3. **名称近似**（去后缀「编号/名称/ID」后相同、一方「客户」一方「客户名称」）→ 中置信
+4. **多候选同分** → 全部列出，**禁止**静默任选一个不告知
+
+**禁止**：仅凭表名臆造 fieldKey；禁止用显示名当 `parentField`/`currentField`（必须三段式 fieldKey）。
+
+#### 2.5.3 必须给用户的确认话术（推断时强制）
+
+推断关联后，交付/询问中**至少**说明：
+
+```
+【关联待确认】表 A「…」与表 B「…」未在需求中写明关联字段。
+已按字段匹配推断：A.{显示名/系统名}  Equals  B.{显示名/系统名}
+请确认是否正确；若不正确请给出正确关联（A.字段 = B.字段）。
+```
+
+用户确认或纠正后，再改入口格筛选（定点改，见 `targeted-fix-guide.md`）。
+
+#### 2.5.4 CLI（优先）
+
+```bash
+e10-cli report join suggest --app-id <appId> --parent-source <sourceIdA> --child-source <sourceIdB>
+# 或按表名：
+e10-cli report join suggest --app-id <appId> --parent-form "销售单" --child-form "销售明细"
+```
+
+输出候选对 + `needConfirm=true`；Agent **优先调 CLI**，勿手写比对脚本。
+
+---
+
+### 2.6 自检判据（落库前后各跑一次 · 可机械执行）
+
+对**每个 Field 格**取四件事：① 本格 `dataSetId`；② 本格左父格坐标 → ③ 左父格格 `dataSetId`；④ 本格 `leftFilterField` 是否非空。逐条比对：
+
+| 级别 | 判据 | 结论 / 处置 |
+|------|------|-------------|
+| 🔴 | ①≠③ 且 ④ 空 | **跨源却无筛选**：本格若是入口格 → 补筛选；否则 → 左父格改指入口格 |
+| 🔴 | ①≠③ 且本格**不是**区域入口格 | **后续格指了异源**：改指入口格坐标，并清空筛选 |
+| 🔴 | ①=③ 但 ④ 非空 | **同源却配了跨源筛选**：只保留入口格那一份，其余清空 |
+| 🔴 | 同一连续同源区域内 ④ 非空的格 **> 1** | **重复配筛选**：只留入口格 |
+| 🟡 | 多数据集报表里，同源后续格左父格为 `-1,-1` | 扩展链不明：显式改为入口格坐标 |
+
+**回读校验（强制）**：改完父格必须重新读一次（`getReportDevInfo`）确认 `leftX/leftY` 真的生效——服务端可能**静默忽略**。
+CLI：`e10-cli report fix parent --report-id <id> --set-parent "x,y=leftX,leftY" [--apply]`（可重复；内置落库后回读，未生效即 exit 2）。
+坐标口径：`x` = 行（0 基）、`y` = 列（0 基）。
+
+---
+
+## 三、与找表耗时控制的关系
+
+少挂源 = 少次 `addDataset` / `fields`。找不准表时的打断规则见 **`app-datasource-lookup-guide.md` §七**。
+
+| 文档 | 关系 |
+|------|------|
+| `app-datasource-lookup-guide.md` | 应用内找表 + 多轮打断询问 |
+| `cross-dataset-filter-guide.md` | 入口格筛选的 fieldKey 写法 |
+| `e10-cli report-cli.md` | **CLI 优先**：找表 / join suggest / verify / 删壳 |
+| `api-report-build-fast-path.md` | 建表流程引用本节 |
+| `report-requirement-analysis-template.md` | 列级表父格筛选填法 |

package/skill-docs/references/report/date-range-query-reference.md

@@ -1,97 +1,97 @@
-# 日期区间查询条件选项参考（已验证样例）
-
-> **金标准来源**：报表 `1304979556231593985`（EBU 经营数据统计）· 查询条件「入职时间」
-> **完整规范**：`query-condition-api-guide.md`（条件字段形态、系统参数默认值、验证清单）
-
----
-
-## 一、快捷选项（filterParam.dataOptions · 21 项）
-
-设计器 save 后的正确形态：
-
-| 字段 | 正确值 |
-|------|--------|
-| `selectOptions` | **`[]`** |
-| `filterParam.enableOption` | `true` |
-| `filterParam.isTile` | `true` |
-| `filterParam.dataOptions` | **21 行**（下表） |
-| `filterParam.optionTile` | **`{}`** |
-| `filterParam.dateSelectDefaultValue` | **`""`** |
-
-**勿用旧格式**：15 项数字码（`"9"`、`"{yesterday}"`）+ 9 项 `selectOptions` + 填满 `optionTile` → 齿轮菜单常只剩「自定义」。
-
----
-
-## 二、dataOptions catalog（id = selectValue）
-
-| selectKey | selectValue / id |
-|-----------|------------------|
-| 近三天 | day3 |
-| 近五天 | day5 |
-| 近七天 | day7 |
-| 今天 | today |
-| 昨天 | yesterday |
-| 明天 | tomorrow |
-| 本周 | thisWeek |
-| 上一周 | lastWeek |
-| 下一周 | nextWeek |
-| 本月 | thisMonth |
-| 上一月 | lastMonth |
-| 下一月 | nextMonth |
-| 本季度 | thisSeason |
-| 上一季 | lastSeason |
-| 下一季 | nextSeason |
-| 今年 | thisYear |
-| 上半年 | firstHalfYear |
-| 下半年 | nextHalfYear |
-| 去年 | lastYear |
-| 明年 | nextYear |
-| 自定义 | custom |
-
----
-
-## 三、系统参数默认值（与快捷选项独立）
-
-默认值写在顶层 **`defaultValueType` + `defaultValue`**，不是 `dateSelectDefaultValue`。
-
-| 场景 | defaultValueType | defaultValue | handleDefaultValue 示例 |
-|------|------------------|--------------|-------------------------|
-| 本月 | `custom` | `["{thismonth}",""]` | `["2026-08-01,2026-08-31",""]` |
-| 今天 | `custom` | `["{date}","{date}"]` | `["2026-08-19","2026-08-19"]` |
-
-`displayType`：`yyyy-MM-dd` 字段 → `date.ymd`；`yyyy-MM` 字段 → `date.ym`。
-
----
-
-## 四、filterParam 完整示例
-
-```json
-{
-  "isTile": true,
-  "enableOption": true,
-  "showType": "tile",
-  "multiple": false,
-  "dataOptions": [ { "selectKey": "本月", "selectValue": "thisMonth", "id": "thisMonth" } ],
-  "optionTile": {},
-  "dateSelectDefaultValue": ""
-}
-```
-
-（`dataOptions` 须写满 21 项，此处省略。）
-
----
-
-## 五、Agent checklist
-
-1. 加载本文 + `query-condition-api-guide.md`
-2. `_default_date_filter_param()` + `defaultValueType: custom` + 系统参数
-3. 校验：21 项 dataOptions、`selectOptions=[]`、`handleDefaultValue` 非空
-4. 设计器：齿轮 21 项 + 默认筛选项生效
-
----
-
-## 六、相关文件
-
-| 文件 | 用途 |
-|------|------|
-| `query-condition-api-guide.md` | 查询条件总规范 |
+# 日期区间查询条件选项参考（已验证样例）
+
+> **金标准来源**：报表 `1304979556231593985`（EBU 经营数据统计）· 查询条件「入职时间」
+> **完整规范**：`query-condition-api-guide.md`（条件字段形态、系统参数默认值、验证清单）
+
+---
+
+## 一、快捷选项（filterParam.dataOptions · 21 项）
+
+设计器 save 后的正确形态：
+
+| 字段 | 正确值 |
+|------|--------|
+| `selectOptions` | **`[]`** |
+| `filterParam.enableOption` | `true` |
+| `filterParam.isTile` | `true` |
+| `filterParam.dataOptions` | **21 行**（下表） |
+| `filterParam.optionTile` | **`{}`** |
+| `filterParam.dateSelectDefaultValue` | **`""`** |
+
+**勿用旧格式**：15 项数字码（`"9"`、`"{yesterday}"`）+ 9 项 `selectOptions` + 填满 `optionTile` → 齿轮菜单常只剩「自定义」。
+
+---
+
+## 二、dataOptions catalog（id = selectValue）
+
+| selectKey | selectValue / id |
+|-----------|------------------|
+| 近三天 | day3 |
+| 近五天 | day5 |
+| 近七天 | day7 |
+| 今天 | today |
+| 昨天 | yesterday |
+| 明天 | tomorrow |
+| 本周 | thisWeek |
+| 上一周 | lastWeek |
+| 下一周 | nextWeek |
+| 本月 | thisMonth |
+| 上一月 | lastMonth |
+| 下一月 | nextMonth |
+| 本季度 | thisSeason |
+| 上一季 | lastSeason |
+| 下一季 | nextSeason |
+| 今年 | thisYear |
+| 上半年 | firstHalfYear |
+| 下半年 | nextHalfYear |
+| 去年 | lastYear |
+| 明年 | nextYear |
+| 自定义 | custom |
+
+---
+
+## 三、系统参数默认值（与快捷选项独立）
+
+默认值写在顶层 **`defaultValueType` + `defaultValue`**，不是 `dateSelectDefaultValue`。
+
+| 场景 | defaultValueType | defaultValue | handleDefaultValue 示例 |
+|------|------------------|--------------|-------------------------|
+| 本月 | `custom` | `["{thismonth}",""]` | `["2026-08-01,2026-08-31",""]` |
+| 今天 | `custom` | `["{date}","{date}"]` | `["2026-08-19","2026-08-19"]` |
+
+`displayType`：`yyyy-MM-dd` 字段 → `date.ymd`；`yyyy-MM` 字段 → `date.ym`。
+
+---
+
+## 四、filterParam 完整示例
+
+```json
+{
+  "isTile": true,
+  "enableOption": true,
+  "showType": "tile",
+  "multiple": false,
+  "dataOptions": [ { "selectKey": "本月", "selectValue": "thisMonth", "id": "thisMonth" } ],
+  "optionTile": {},
+  "dateSelectDefaultValue": ""
+}
+```
+
+（`dataOptions` 须写满 21 项，此处省略。）
+
+---
+
+## 五、Agent checklist
+
+1. 加载本文 + `query-condition-api-guide.md`
+2. `_default_date_filter_param()` + `defaultValueType: custom` + 系统参数
+3. 校验：21 项 dataOptions、`selectOptions=[]`、`handleDefaultValue` 非空
+4. 设计器：齿轮 21 项 + 默认筛选项生效
+
+---
+
+## 六、相关文件
+
+| 文件 | 用途 |
+|------|------|
+| `query-condition-api-guide.md` | 查询条件总规范 |