weaver-e10-builder 1.6.16 → 1.7.1

package/skill-docs/references/report/cross-dataset-filter-guide.md

@@ -1,429 +1,429 @@
-# 跨数据集筛选配置指南（左父格筛选 & 自定义筛选）
-
-> **适用场景**：单元格字段与左/上父格字段来自不同数据集；或单元格需按固定条件过滤（如核算机构排除、年度参数）。
->
-> **已验证平台**：e-Builder EDC 报表设计器（2026-08，EBU 经营数据统计报表 `1304979556231593985`）。
->
-> **与「左侧数据集筛选」区分**：整表/行级预过滤走 **`queryInfoSave`**（`conditionData`），见 **`dataset-query-filter-guide.md`**。本文档面向 **subordination / leftFilterField / customFilterField / datasetFilter**（单元格与多实例副本级）。
-
-## 〇、前置门禁：跨源关联必须「先探后写」（强制 · A0.9）
-
-> 血案：供应商绩效看板 `1315297716934582273` 的跨源列定位，因**未先读子表样本数据**，
-> 靠「重建 → 渲染」试错跑了 **~9 轮**，是整次搭建最大的时间浪费。
-
-**在配置任何跨源筛选（`subordination` / `leftFilterField`）之前，必须先完成两步「探」**：
-
-1. **读子表样本数据** —— 要的是**真实取值**，不是字段元数据：
-   确认「子表哪一列真正指向主表记录」及其**取值形态**（记录 id？显示名？逗号串？）。
-2. **跑 `join suggest`** ——
-   `e10-cli report join suggest --app-id <appId> --parent-source <主表sourceId> --child-source <子表sourceId>`
-   取平台建议的关联键，再据此配父格。
-
-**禁止**：未读样本就靠「反复落库 + 渲染」猜关联键 / 猜 `Equals` 还是 `Contain` / 猜 `left` 指向。
-子列取值一旦不对，**先回读样本数据**定位，不要又重建一轮落库。
-（关联键真口径见 **§2.3.1**；子表 1:N 汇总见 **§2.3.2**；禁令总纲见 `targeted-fix-guide.md` §〇 · `pitfalls BUILD-18`。）
-
-## 一、核心结论（必读）
-
-设计器下拉框**按 `fieldKey` 匹配字段**，不是按显示名（`text`）或裸系统名（`field_xxx`）。
-
-**fieldKey 格式**（三段式，用 `.` 连接）：
-
-```
-{dataSetId}.{sourceId}.{fieldName}
-```
-
-| 段 | 含义 | 示例 |
-|----|------|------|
-| dataSetId | 报表内数据集 ID（`ds[].id`） | `1304979556231593994` |
-| sourceId | 数据源/逻辑表 ID（`ds[].sourceId`） | `1299763447342276611` |
-| fieldName | 字段系统名（`fields[].name`） | `field_1299763447342276617` |
-
-**症状对照**：
-
-| 现象 | 常见原因 |
-|------|----------|
-| API 保存成功，设计器筛选区下拉为空白 | `parentField`/`currentField` 用了显示名或裸 `field_xxx` |
-| 筛选条件不生效 | 未配置 `subordination` 或父格坐标错误 |
-| 类型选了但无效 | `type` 用了 `eq`/`uncontains` 而非平台枚举 |
-
----
-
-## 二、左父格筛选（leftFilterField）
-
-### 2.1 何时需要
-
-当前单元格 `dataSetId` ≠ 左父格单元格 `dataSetId` 时，必须同时配置：
-
-1. **subordination** — VLOOKUP 式字段映射（设计器「从属关系」）
-2. **leftFilterField** — 左父格筛选条件（设计器「左父格筛选」）
-
-两者字段引用**都必须使用 fieldKey**。
-
-### 2.1.1 连续同源区域：筛选只配入口格 · 后续字段以入口格为父格（★★ 最高优先 · 强制）
-
-> 完整规则见 **`datasource-selection-and-parent-filter-guide.md` §二**（含 **§2.5 关联键：需求优先 · 推断须用户确认**、**§2.6 自检判据**）。
-
-若连续一片单元格**全部来自同一数据源**，且整体挂在另一数据源父格下：
-
-- **入口格（区域第一个字段）**：自定义父格指向异源关联键格 + 配置 `subordination` / `leftFilterField`（**只有这一格配筛选**）
-- **同区域其余同源字段**：左父格**必须显式指向「本区域入口格」坐标**；`subordination` / `leftFilterField` **必须为空**
-- **禁止**：后续字段指异源格（**跨源却无筛选** → 数据串源）；也禁止逐格重复配一遍父格筛选
-- **关联字段**：需求已写明则按需求；未写明则字段匹配推断后 **必须提示用户确认**（CLI：`e10-cli report join suggest`）
-
-**铁律**：父格筛选只配在区域「入口格」上；同区域后续字段只要是同一个数据集，一律以这个入口字段为父格。
-
-> **⚠ 边界（A0.21 交叉区布局 · 2026-10-29 实证）**：本条「只配入口格」仅适用于**后续格以入口格为父格**的链式布局。
-> 交叉扩展区（横向日期 × 纵向维度）里每个数据格的左父格都直指**行维度扩展根**（异源）而非入口格
-> ⇒ 每个跨源 Field 数据格**各自**配 `subordination` + `leftFilterField`（细则 `crosstab-raw-workbook-guide.md §4.3.4`）。
-
-### 2.2 数据结构
-
-**workbook 内**（`style.cellType` 上）：
-
-```json
-{
-  "subordination": [
-    "1304979556231593994.1299763447342276611.field_1299763447342276617",
-    "1304979560546713602.1299789221321891842.field_1299789221321891843"
-  ],
-  "leftFilterField": [
-    {
-      "index": 27,
-      "currentField": "1304979560546713602.1299789221321891842.field_1299789221321891843",
-      "type": "Equals",
-      "parentField": "1304979556231593994.1299763447342276611.field_1299763447342276617"
-    }
-  ]
-}
-```
-
-| 字段 | 说明 |
-|------|------|
-| subordination[0] | 父格（左父格）字段 fieldKey |
-| subordination[1] | 当前单元格字段 fieldKey |
-| parentField | 同 subordination[0] |
-| currentField | 同 subordination[1] |
-| type | 匹配关系，跨数据集关联通常用 `Equals` |
-| index | **该条条件自身的唯一序号**（设计器原生形态）—— ⚠ 不是字段 fieldKey，见 §2.3 |
-
-**save 后 fields 表**（`getReportDevInfo`）：`leftFilterField`、`subordination` 出现在字段记录顶层（JSON 字符串或数组），不在 `style` 内。
-
-### 2.3 左父格筛选识别与写入（2026-09 eteams 验证 · 必遵）
-
-设计器 F2「左父格筛选」下拉按 **fieldKey 注册表** 解析标签；下列写法会导致回显 **`undefined`** 或下拉空白：
-
-| 错误写法 | 现象 | 正确写法 |
-|----------|------|----------|
-| `parentField: "...field_5"`（截断/臆造字段名） | 父格关联字段显示 undefined | 完整 `{dataSetId}.{sourceId}.field_4746632256695654785` |
-| `id`/`index` 写成字段 fieldKey | 多格共用同一标识 → 设计器把 N 条当同一条：**改一条全变、删一条全删**（BUILD-115） | **每条条件各自唯一 `index` 序号**，与 currentField 无关 |
-| `subordination: ["",""]` | 从属关系丢失 | `[parentField, currentField]` 与 leftFilter 同步 |
-| 仅改 fields 表、workbook 内 `style.cellType` 未同步 | 保存后字段绑定丢失 | workbook + fields **双保存**（见 §4.1） |
-
-> **🔴 条件标识语义更正（2026-10-30 用户两次点名，E6 金标准实证）**：本表旧版写「`id` 必须等于 `currentField`」是**错的**。
-> ① 平台/设计器认的是 **`index`（序号）**，不是 `id`。条件应写成 `{index, currentField, type, parentField}`；
-> 写 `id` 的条件在设计器里会退化成「按字段归并」，即使 id 全表唯一，UI 里**照样联动**。
-> ② 标识写成 fieldKey ⇒ 同字段的多条条件共享一个标识 ⇒ 设计器当成同一条：
-> **改一个条件另一个跟着变、点一个删除全都被删**（用户原话）。
-> 正解：`index` 全表唯一递增（`normalizeFilterCondIds()` 构建期自动补/改写），门禁第 ⑦ 组 `FILTER_ID_DUP` 兜底。
->
-> **🔴 指标格左父格口径（E6 金标准）**：Sheet0 指标格 `leftX/leftY` 必须指 **本行 C 列（真实 Field 格）**，
-> 不能指 D 拼接公式列 —— Formula 格没有字段身份，`subordination`/`parentField` 找不到父字段 ⇒ **取数整列 0**。
-> 判据：`(本行 x, 2)`；参考样板 `1331753785429704735` 与用户手调的 E6 完全一致。
-
-**父格坐标（leftX / leftY）**：须指向布局上**真实的左父格单元格**（0-based 列 x、行 y），不能机械套用 `leftY = col - 1`。
-
-**纵向堆叠多数据集示例**（进销存-供应商 + 采购进货单，同列 B）：
-
-- 供应商字段：y=0~4（供应商等级 → 联系方式），根格 y=0 左父格无
-- 采购字段：y=5~9，`leftX=1`, **`leftY=4`**（指向 E2「联系方式」所在行）
-- 关联：`parentField` = 供应商.供应商名称；`currentField` = 进货单.供应商
-
-**生成 helper**（Skill 内置）：
-
-```python
-from scripts.left_filter_builder import build_cross_dataset_filter
-
-lf, sub = build_cross_dataset_filter(
-    ds_supplier, src_supplier, "field_4746632256695654785",
-    ds_purchase, src_purchase, "field_4746633026496455388",
-)
-# lf[0]["id"] 是独立唯一雪花号，**不等于** currentField（BUILD-115）
-```
-
-**保存后验证**（`getReportDevInfo` 抽检首个跨表格，如进货单编号 y=5）：
-
-```bash
-# parentField / currentField 各含两个 '.' 段；subordination 与 leftFilterField 一致
-```
-
-### 2.3.1 🔴 关联键必须是「子表关联字段」，不是本列展示字段（2026-09 验证定论）
-
-> **血案**：报表 `1315297716934582273`（供应商绩效看板）跨源列**整列为空**，反复换 `Equals`/`Contain`、
-> 换 `left` 指向都无效。最后定位到 `currentField` 写错了字段。
-
-| 写作 | 结果 |
-|------|------|
-| `currentField` = 本格要展示的字段（如 评级.现供应商等级 / 风险.风险等级） | ❌ 整列空（拿等级去 Equals 供应商名，永不匹配） |
-| `currentField` = **子表侧参与关联的键字段**（评级.供应商名称 / 风险.关联供应商） | ✅ 正确 |
-
-**判定「哪个是关联键字段」**：子表里「指向主表记录」的那个字段（常常是 **Ebuilder 关联表单**控件），
-**不是**你要显示的那一列。入口格展示字段与关联键字段通常是**两个不同字段**。
-
-**关联键取值口径（同样致命）**：
-
-| 主表侧 parentField | 子表侧 currentField | 结果 |
-|---|---|---|
-| 主表.**数据ID**（Text，值=记录 id） | 子表.Ebuilder 关联字段（原始值=目标记录 id） | ✅ 命中 |
-| 主表.名称（Text 显示名） | 子表.Ebuilder 关联字段 | ❌ 不匹配（id vs 名称） |
-
-Ebuilder 关联字段的原始值是**目标记录 id**，所以父格必须拿「数据ID」去比。
-**并且入口格的左父格要指向承载该 id 的那一格**（无该列时新增一个隐藏列放 `id`），
-不要指向放显示名称的那一列。
-
-> ⚠️ 这个「隐藏列」的落库口径是 **列宽 = 0**（`columns[].size = 0`，Excel 隐藏列语义），
-> **不是** `visible:false`、也不是 cell 顶层 `colVisible=0` —— 后两者会被服务端丢弃/归一化成 `"1"`，
-> 结果是留下一条 1px 宽的**可见**细条。详见 ``ref-report-pitfalls.md``（BUILD-16）。
-
-```
-信息区：A3 供应商名称(根) … M3 数据ID(隐藏列，left→A3)
-评级入口格 I3：leftX/Y → (2,12)=M3   ← 承载关联 id 的格
-             parentField   = 信息.数据ID
-             currentField  = 评级.供应商名称(Ebuilder)
-```
-
-**回读校验**：`subordination` 两段与 `leftFilterField` 的 `parentField`/`currentField` 一致；
-`parentField` 指向主表 id 类字段、`currentField` 指向子表关联字段。
-
-可检索：``ref-report-pitfalls.md``（BUILD-12 / BUILD-13）。
-
-### 2.3.2 子表 1:N → 用「汇总格」收敛成一行（勿让它撑行）
-
-子表一个父记录对应多条时，明细格会**把整行撑开**（出现只有子列有值、主列空白的行）。看板类报表应改为汇总：
-
-| 需求 | 配置 |
-|------|------|
-| 条数 | `displayType:"Count"` + `countType:"count"` |
-| 取最大档（如风险等级） | `displayType:"Count"` + `countType:"max"` |
-| 取明细单值 | 无需汇总，`expandType:"NoExpand"`（多值会逗号拼接） |
-
-**汇总格三件套（缺一不可）**：`displayType:"Count"` + `expandType:"Vertical"` + `groupType:"none"`。
-⚠️ 服务端会把 `displayType=Count` **规范化回 `Group`**；用 `NoExpand` 配 Count 会被规范化掉、汇总失效
-（BUILD-14）。汇总按父格分组计算，不会撑行。
-
-⚠️ 汇总后的 **Select 值是裸 optionId**，需补 `transType:"select"` + `transSelectOptions:[{selectValue:id,selectName:名称}]`（BUILD-15）。
-
-### 2.4 业务映射示例（EBU 报表）
-
-| 子表类型 | 父格字段 | 当前字段 | 含义 |
-|----------|----------|----------|------|
-| 直销合同列 | EBU团队·责任人 | 直销合同业绩表·销售经理 | 按责任人关联合同 |
-| 收款明细列 | EBU团队·责任人 | 收款明细表·销售经理 | 按责任人关联收款 |
-
-根格（如 F3 责任人）设置 `leftX=-1, leftY=-1`；子格/公式格 `leftX=2, leftY=5` 指向根格列（0-based：行 2、列 5）。
-
-### 2.5 Python 辅助函数
-
-```python
-def field_key_ref(ds_id, src_id, field):
-    return f"{ds_id}.{src_id}.{field['name']}"
-
-def make_subordination(p_ds_id, p_src_id, p_field, c_ds_id, c_src_id, c_field):
-    return [
-        field_key_ref(p_ds_id, p_src_id, p_field),
-        field_key_ref(c_ds_id, c_src_id, c_field),
-    ]
-
-def make_left_filter(p_ds_id, p_src_id, p_field, c_ds_id, c_src_id, c_field):
-    ck = field_key_ref(c_ds_id, c_src_id, c_field)
-    pk = field_key_ref(p_ds_id, p_src_id, p_field)
-    return [{"parentField": pk, "currentField": ck, "type": "Equals", "id": ck}]
-```
-
----
-
-## 三、单元格自定义筛选（customFilterField）
-
-### 3.1 与数据集级筛选的区别
-
-| 层级 | 配置位置 | 用途 |
-|------|----------|------|
-| **单元格 customFilterField** | `style.cellType.customFilterField` | 该单元格取数时的行级条件 |
-| **数据集 datasetFilter** | `saveReportWithCacheConfig` 的 `datasetFilter` 参数 | 整个数据集的基础过滤 |
-
-单元格自定义筛选同样必须使用 **fieldKey** 作为 `currentField`；每条条件配唯一 `index`（不是 `id`）。
-
-### 3.2 数据结构
-
-```json
-{
-  "customFilterField": [
-    {
-      "index": 101,
-      "currentField": "1304979560546713602.1299789221321891842.field_1299789221321891843",
-      "type": "NotContain",
-      "value": "某核算机构"
-    },
-    {
-      "index": 102,
-      "currentField": "1304979560546713602.1299789221321891842.field_1299789221321891844",
-      "type": "Null",
-      "value": ""
-    }
-  ]
-}
-```
-
-### 3.2.1 🔴 筛选 value 形态：按字段类型分流（★★ 全局规则 A0.20 · 2026-10-29 实证更正）
-
-**触发条件**：`customFilterField` 绑定的字段为 select/文本类型，且 `type` ∈ {`Include`, `Equals`, `Contain`, `NotContain`}。所有报表生成任务统一生效。
-
-**正确写法（唯一合法判据 = 字段元数据 `originFieldType`；多选一律 JSON 数组 · 2026-10-29 源码定案）**：
-
-| 字段类型 | originFieldType | value 形态 | 例 |
-|---|---|---|---|
-| **真 select**（单选/多选/下拉） | `RadioBox` / `CheckBox` / `Select` 等 | **optionId 的 JSON 数组**（多值）/ 单 optionId 字符串（单值） | `value:["1330…621","1330…622"]` |
-| **文本** | `String` / `Text` | **文本值逗号分隔**（即显示名形态） | `value:"优秀,合格"` |
-
-```json
-{
-  "customFilterField": [
-    {
-      "currentField": "{dataSetId}.{sourceId}.{字段名}",
-      "type": "Include",
-      "value": ["{optionId1}", "{optionId2}"],
-      "index": 103
-    }
-  ]
-}
-```
-
-**为什么真 select 字段必须 optionId 数组（2026-10-29 源码级定案，route_ReportDesigner chunk 反编译实证）**：
-1. **数据行存的就是 optionId**（BUILD-15 实证）——筛选 value 写显示名**运行期一条都筛不出来**。
-2. **设计器弹窗写回函数**（`Ut`）：`n({...t,[e]:r})` —— 多选 `Select multiple` 的 onChange 传**选项 id 数组**，**原样**写入 `value` ⇒ 设计器原生形态就是 optionId 数组。
-3. **弹窗回显匹配**：选项映射 `Y=L.map(e=>(ne===e.name&&(x(e.id),ne=e.id),{id:e.id,content:e.name}))` —— Select 按**数组中的 optionId** 勾选；仅「value 精确等于单个选项显示名」这一种历史字符串会被救成单 id。**逗号字符串既不是数组也不等于单个显示名** ⇒ 运行期引擎能切分逗号（预览生效）但弹窗值框永远「请选择」空白（三轮实证：显示名串 / optionId 逗号串均空白，仅数组形态回显）。
-
-**⚠ 结论更正记录（勿回退）**：
-- 2026-10-28 版「select 必须显示名」：金标准（员工培训参训情况汇总表 (2,8)）实为 **Text 字段**（`originFieldType:String`），显示名只是 Text 形态。
-- 2026-10-29 v1「select 必须逗号 optionId」：运行期正确、弹窗不回显——逗号串是**运行期容错形态**，非设计器原生形态。
-- **终版：多选 = optionId JSON 数组；单值 = 单 optionId 字符串；Text = 文本逗号串。**
-
-**金标准方法论（判定 value 形态的通用方法）**：写筛选前先取字段元数据（`fieldsBySource(srcId, appId).find(f=>f.name==='field_xxx')`），看 `originFieldType` / `config.type` / `config.options`：有 `options` 且类型为 RadioBox 族 → optionId 形态（选项 id 取 `config.options[].value`）；String/Text → 文本形态。**人工配置样例必须先核字段类型再对照**。
-
-**构建期检查（2026-10-29 降级）**：构建层 对 optionId 形态 value 默认**只告警不拦截**（构建期无法判定字段类型）；`opts.enforceSelectFilterValues === true` 显式恢复拦截。`verify_self_check` 同步降为 warning。
-
-### 3.3 type 枚举（平台值）
-
-**必须使用下列枚举**，不要用简写：
-
-| 平台 type | 错误写法（无效） | 说明 |
-|-----------|------------------|------|
-| `Equals` | `eq` | 等于 |
-| `NotContain` | `uncontains` | 不包含 |
-| `Null` | `empty` | 为空 |
-| `NotNull` | `nempty` | 不为空 |
-| `Contain` | — | 包含 |
-| `Include` | — | 属于（多值逗号分隔） |
-
-完整枚举见 `report-data-model.md` §2.5。
-
-### 3.4 需求文档到配置的映射
-
-需求 Excel 中常见写法 → API 配置：
-
-```
-核算机构 不包含 机构A,机构B  →  type: NotContain, value: 机构A（多条则多个 filter 项）
-核算机构 为空                →  type: Null, value: ""
-年度={year}                  →  type: Equals, value: "{year}"（系统参数原样保留）
-```
-
-```python
-FILTER_TYPE_MAP = {
-    "eq": "Equals", "uncontains": "NotContain",
-    "empty": "Null", "nempty": "NotNull",
-}
-```
-
----
-
-## 四、保存与验证流程
-
-### 4.1 双保存（API 脚本必做）
-
-1. `POST /api/bs/edc/report/saveReportWithCacheConfig` — workbook + dataset + datasetFilter
-2. `POST /api/bs/edc/report/saveReportDevInfo` — 同 workbook（需带 `designKey`）
-
-仅保存其一可能导致设计器回显异常或筛选丢失。
-
-### 4.2 验证清单
-
-保存后调用 `getReportDevInfo`，检查 L3（或目标数据行）字段：
-
-- [ ] `subordination` 为两段 fieldKey，非 `["",""]`
-- [ ] `leftFilterField` 非空，且 `parentField`/`currentField` 含两个 `.`
-- [ ] `customFilterField`（若有）的 `type` 为平台枚举
-- [ ] **筛选 value 形态与字段类型匹配**：真 select（RadioBox 族）→ optionId 逗号分隔；Text/String → 文本值（A0.20 · 2026-10-29 更正 / §3.2.1）
-- [ ] 设计器打开后左父格筛选、自定义筛选下拉**有选中项**（非空白）
-
-### 4.3 配置校验脚本
-
-```bash
-e10-cli report py validate <配置文件路径>
-```
-
-脚本会检查 fieldKey 格式、type 枚举、customFilterField 结构。
-
----
-
-## 五、常见错误定位
-
-### 5.1 设计器筛选下拉空白
-
-1. 确认 `parentField`/`currentField` 均为 `{dataSetId}.{sourceId}.{fieldName}`；`id` 为该条条件的**唯一雪花号**（不是 fieldKey，BUILD-115）
-2. 确认 `dataSetId` 是报表内数据集 ID，不是 appId / reportId
-3. **select 字段：确认 `value` 是选项显示名而非 optionId**（A0.20 / §3.2.1，注意点 BUILD-98）——这是本症状最高频根因
-3. 确认 `fieldName` 来自 `ds/fields` 接口的 `name` 字段
-4. 双保存后刷新设计器
-
-### 5.2 父格循环引用
-
-子格 `leftY` 指向错误列会导致父格环（如根格在 F 列却设 `leftY=6` 指向 G）。根格用 `leftX=-1, leftY=-1`。
-
-### 5.3 style 与 fields 表不一致
-
-`getAllSheets` 的 `dtTable` 可能为空；**以 `getReportDevInfo.fields` 为准**。workbook 内筛选写在 `style.cellType`，平台解析后同步到 fields 表。
-
----
-
-## 六、生成配置时的 Agent 检查项
-
-生成或修改含跨数据集字段的报表时，Agent 必须：
-
-1. 从 `ds/list` + `ds/fields` 获取真实 `dataSetId`、`sourceId`、`field.name`
-2. 对每个跨数据集列生成 `subordination` + `leftFilterField`（fieldKey + `id`）
-3. 对需求中的过滤条件生成 `customFilterField`（fieldKey + 平台 type）
-4. 含 Formula 单元格时遵守 `formula-cell-api-guide.md`（cellText 无前导 `=`）
-5. 运行 `e10-cli report py validate` 预检
-6. 若通过 API 保存，执行双保存并用 `getReportDevInfo` 验证
-
----
-
-## 八、公式单元格（另见专篇）
-
-含 Formula 单元格且通过 **API / 脚本保存** 时，必须遵守 `formula-cell-api-guide.md`：
-
-- `cellText` / 顶层 `formula` **不带前导 `=`**
-- `countType: count`、`displayType: Group`、`groupType: null`
-- 双保存 + `getReportDevInfo` 回读验证
-
-公式格本身通常 **不需要** subordination / leftFilterField；它引用同表内已配好筛选的 Field 汇总格。
-
----
-
-## 九、相关文档
-
-- `formula-cell-api-guide.md` — 公式单元格 API 写入规范（完整）
-- `report-config-schema.md` §2.4–2.5 — 过滤与 Formula Schema
-- `report-data-model.md` §2.4–2.5 — TypeScript 类型与枚举
-- `ai-report-workflow.md` §4.4、§六 — 交叉表工作流与公式规则
-- `report-knowledge-base.md` §2.1、§2.5 — 父格与自定义筛选概念
+# 跨数据集筛选配置指南（左父格筛选 & 自定义筛选）
+
+> **适用场景**：单元格字段与左/上父格字段来自不同数据集；或单元格需按固定条件过滤（如核算机构排除、年度参数）。
+>
+> **已验证平台**：e-Builder EDC 报表设计器（2026-08，EBU 经营数据统计报表 `1304979556231593985`）。
+>
+> **与「左侧数据集筛选」区分**：整表/行级预过滤走 **`queryInfoSave`**（`conditionData`），见 **`dataset-query-filter-guide.md`**。本文档面向 **subordination / leftFilterField / customFilterField / datasetFilter**（单元格与多实例副本级）。
+
+## 〇、前置门禁：跨源关联必须「先探后写」（强制 · A0.9）
+
+> 血案：供应商绩效看板 `1315297716934582273` 的跨源列定位，因**未先读子表样本数据**，
+> 靠「重建 → 渲染」试错跑了 **~9 轮**，是整次搭建最大的时间浪费。
+
+**在配置任何跨源筛选（`subordination` / `leftFilterField`）之前，必须先完成两步「探」**：
+
+1. **读子表样本数据** —— 要的是**真实取值**，不是字段元数据：
+   确认「子表哪一列真正指向主表记录」及其**取值形态**（记录 id？显示名？逗号串？）。
+2. **跑 `join suggest`** ——
+   `e10-cli report join suggest --app-id <appId> --parent-source <主表sourceId> --child-source <子表sourceId>`
+   取平台建议的关联键，再据此配父格。
+
+**禁止**：未读样本就靠「反复落库 + 渲染」猜关联键 / 猜 `Equals` 还是 `Contain` / 猜 `left` 指向。
+子列取值一旦不对，**先回读样本数据**定位，不要又重建一轮落库。
+（关联键真口径见 **§2.3.1**；子表 1:N 汇总见 **§2.3.2**；禁令总纲见 `targeted-fix-guide.md` §〇 · `pitfalls BUILD-18`。）
+
+## 一、核心结论（必读）
+
+设计器下拉框**按 `fieldKey` 匹配字段**，不是按显示名（`text`）或裸系统名（`field_xxx`）。
+
+**fieldKey 格式**（三段式，用 `.` 连接）：
+
+```
+{dataSetId}.{sourceId}.{fieldName}
+```
+
+| 段 | 含义 | 示例 |
+|----|------|------|
+| dataSetId | 报表内数据集 ID（`ds[].id`） | `1304979556231593994` |
+| sourceId | 数据源/逻辑表 ID（`ds[].sourceId`） | `1299763447342276611` |
+| fieldName | 字段系统名（`fields[].name`） | `field_1299763447342276617` |
+
+**症状对照**：
+
+| 现象 | 常见原因 |
+|------|----------|
+| API 保存成功，设计器筛选区下拉为空白 | `parentField`/`currentField` 用了显示名或裸 `field_xxx` |
+| 筛选条件不生效 | 未配置 `subordination` 或父格坐标错误 |
+| 类型选了但无效 | `type` 用了 `eq`/`uncontains` 而非平台枚举 |
+
+---
+
+## 二、左父格筛选（leftFilterField）
+
+### 2.1 何时需要
+
+当前单元格 `dataSetId` ≠ 左父格单元格 `dataSetId` 时，必须同时配置：
+
+1. **subordination** — VLOOKUP 式字段映射（设计器「从属关系」）
+2. **leftFilterField** — 左父格筛选条件（设计器「左父格筛选」）
+
+两者字段引用**都必须使用 fieldKey**。
+
+### 2.1.1 连续同源区域：筛选只配入口格 · 后续字段以入口格为父格（★★ 最高优先 · 强制）
+
+> 完整规则见 **`datasource-selection-and-parent-filter-guide.md` §二**（含 **§2.5 关联键：需求优先 · 推断须用户确认**、**§2.6 自检判据**）。
+
+若连续一片单元格**全部来自同一数据源**，且整体挂在另一数据源父格下：
+
+- **入口格（区域第一个字段）**：自定义父格指向异源关联键格 + 配置 `subordination` / `leftFilterField`（**只有这一格配筛选**）
+- **同区域其余同源字段**：左父格**必须显式指向「本区域入口格」坐标**；`subordination` / `leftFilterField` **必须为空**
+- **禁止**：后续字段指异源格（**跨源却无筛选** → 数据串源）；也禁止逐格重复配一遍父格筛选
+- **关联字段**：需求已写明则按需求；未写明则字段匹配推断后 **必须提示用户确认**（CLI：`e10-cli report join suggest`）
+
+**铁律**：父格筛选只配在区域「入口格」上；同区域后续字段只要是同一个数据集，一律以这个入口字段为父格。
+
+> **⚠ 边界（A0.21 交叉区布局 · 2026-10-29 实证）**：本条「只配入口格」仅适用于**后续格以入口格为父格**的链式布局。
+> 交叉扩展区（横向日期 × 纵向维度）里每个数据格的左父格都直指**行维度扩展根**（异源）而非入口格
+> ⇒ 每个跨源 Field 数据格**各自**配 `subordination` + `leftFilterField`（细则 `crosstab-raw-workbook-guide.md §4.3.4`）。
+
+### 2.2 数据结构
+
+**workbook 内**（`style.cellType` 上）：
+
+```json
+{
+  "subordination": [
+    "1304979556231593994.1299763447342276611.field_1299763447342276617",
+    "1304979560546713602.1299789221321891842.field_1299789221321891843"
+  ],
+  "leftFilterField": [
+    {
+      "index": 27,
+      "currentField": "1304979560546713602.1299789221321891842.field_1299789221321891843",
+      "type": "Equals",
+      "parentField": "1304979556231593994.1299763447342276611.field_1299763447342276617"
+    }
+  ]
+}
+```
+
+| 字段 | 说明 |
+|------|------|
+| subordination[0] | 父格（左父格）字段 fieldKey |
+| subordination[1] | 当前单元格字段 fieldKey |
+| parentField | 同 subordination[0] |
+| currentField | 同 subordination[1] |
+| type | 匹配关系，跨数据集关联通常用 `Equals` |
+| index | **该条条件自身的唯一序号**（设计器原生形态）—— ⚠ 不是字段 fieldKey，见 §2.3 |
+
+**save 后 fields 表**（`getReportDevInfo`）：`leftFilterField`、`subordination` 出现在字段记录顶层（JSON 字符串或数组），不在 `style` 内。
+
+### 2.3 左父格筛选识别与写入（2026-09 eteams 验证 · 必遵）
+
+设计器 F2「左父格筛选」下拉按 **fieldKey 注册表** 解析标签；下列写法会导致回显 **`undefined`** 或下拉空白：
+
+| 错误写法 | 现象 | 正确写法 |
+|----------|------|----------|
+| `parentField: "...field_5"`（截断/臆造字段名） | 父格关联字段显示 undefined | 完整 `{dataSetId}.{sourceId}.field_4746632256695654785` |
+| `id`/`index` 写成字段 fieldKey | 多格共用同一标识 → 设计器把 N 条当同一条：**改一条全变、删一条全删**（BUILD-115） | **每条条件各自唯一 `index` 序号**，与 currentField 无关 |
+| `subordination: ["",""]` | 从属关系丢失 | `[parentField, currentField]` 与 leftFilter 同步 |
+| 仅改 fields 表、workbook 内 `style.cellType` 未同步 | 保存后字段绑定丢失 | workbook + fields **双保存**（见 §4.1） |
+
+> **🔴 条件标识语义更正（2026-10-30 用户两次点名，E6 金标准实证）**：本表旧版写「`id` 必须等于 `currentField`」是**错的**。
+> ① 平台/设计器认的是 **`index`（序号）**，不是 `id`。条件应写成 `{index, currentField, type, parentField}`；
+> 写 `id` 的条件在设计器里会退化成「按字段归并」，即使 id 全表唯一，UI 里**照样联动**。
+> ② 标识写成 fieldKey ⇒ 同字段的多条条件共享一个标识 ⇒ 设计器当成同一条：
+> **改一个条件另一个跟着变、点一个删除全都被删**（用户原话）。
+> 正解：`index` 全表唯一递增（`normalizeFilterCondIds()` 构建期自动补/改写），门禁第 ⑦ 组 `FILTER_ID_DUP` 兜底。
+>
+> **🔴 指标格左父格口径（E6 金标准）**：Sheet0 指标格 `leftX/leftY` 必须指 **本行 C 列（真实 Field 格）**，
+> 不能指 D 拼接公式列 —— Formula 格没有字段身份，`subordination`/`parentField` 找不到父字段 ⇒ **取数整列 0**。
+> 判据：`(本行 x, 2)`；参考样板 `1331753785429704735` 与用户手调的 E6 完全一致。
+
+**父格坐标（leftX / leftY）**：须指向布局上**真实的左父格单元格**（0-based 列 x、行 y），不能机械套用 `leftY = col - 1`。
+
+**纵向堆叠多数据集示例**（进销存-供应商 + 采购进货单，同列 B）：
+
+- 供应商字段：y=0~4（供应商等级 → 联系方式），根格 y=0 左父格无
+- 采购字段：y=5~9，`leftX=1`, **`leftY=4`**（指向 E2「联系方式」所在行）
+- 关联：`parentField` = 供应商.供应商名称；`currentField` = 进货单.供应商
+
+**生成 helper**（Skill 内置）：
+
+```python
+from scripts.left_filter_builder import build_cross_dataset_filter
+
+lf, sub = build_cross_dataset_filter(
+    ds_supplier, src_supplier, "field_4746632256695654785",
+    ds_purchase, src_purchase, "field_4746633026496455388",
+)
+# lf[0]["id"] 是独立唯一雪花号，**不等于** currentField（BUILD-115）
+```
+
+**保存后验证**（`getReportDevInfo` 抽检首个跨表格，如进货单编号 y=5）：
+
+```bash
+# parentField / currentField 各含两个 '.' 段；subordination 与 leftFilterField 一致
+```
+
+### 2.3.1 🔴 关联键必须是「子表关联字段」，不是本列展示字段（2026-09 验证定论）
+
+> **血案**：报表 `1315297716934582273`（供应商绩效看板）跨源列**整列为空**，反复换 `Equals`/`Contain`、
+> 换 `left` 指向都无效。最后定位到 `currentField` 写错了字段。
+
+| 写作 | 结果 |
+|------|------|
+| `currentField` = 本格要展示的字段（如 评级.现供应商等级 / 风险.风险等级） | ❌ 整列空（拿等级去 Equals 供应商名，永不匹配） |
+| `currentField` = **子表侧参与关联的键字段**（评级.供应商名称 / 风险.关联供应商） | ✅ 正确 |
+
+**判定「哪个是关联键字段」**：子表里「指向主表记录」的那个字段（常常是 **Ebuilder 关联表单**控件），
+**不是**你要显示的那一列。入口格展示字段与关联键字段通常是**两个不同字段**。
+
+**关联键取值口径（同样致命）**：
+
+| 主表侧 parentField | 子表侧 currentField | 结果 |
+|---|---|---|
+| 主表.**数据ID**（Text，值=记录 id） | 子表.Ebuilder 关联字段（原始值=目标记录 id） | ✅ 命中 |
+| 主表.名称（Text 显示名） | 子表.Ebuilder 关联字段 | ❌ 不匹配（id vs 名称） |
+
+Ebuilder 关联字段的原始值是**目标记录 id**，所以父格必须拿「数据ID」去比。
+**并且入口格的左父格要指向承载该 id 的那一格**（无该列时新增一个隐藏列放 `id`），
+不要指向放显示名称的那一列。
+
+> ⚠️ 这个「隐藏列」的落库口径是 **列宽 = 0**（`columns[].size = 0`，Excel 隐藏列语义），
+> **不是** `visible:false`、也不是 cell 顶层 `colVisible=0` —— 后两者会被服务端丢弃/归一化成 `"1"`，
+> 结果是留下一条 1px 宽的**可见**细条。详见 ``ref-report-pitfalls.md``（BUILD-16）。
+
+```
+信息区：A3 供应商名称(根) … M3 数据ID(隐藏列，left→A3)
+评级入口格 I3：leftX/Y → (2,12)=M3   ← 承载关联 id 的格
+             parentField   = 信息.数据ID
+             currentField  = 评级.供应商名称(Ebuilder)
+```
+
+**回读校验**：`subordination` 两段与 `leftFilterField` 的 `parentField`/`currentField` 一致；
+`parentField` 指向主表 id 类字段、`currentField` 指向子表关联字段。
+
+可检索：``ref-report-pitfalls.md``（BUILD-12 / BUILD-13）。
+
+### 2.3.2 子表 1:N → 用「汇总格」收敛成一行（勿让它撑行）
+
+子表一个父记录对应多条时，明细格会**把整行撑开**（出现只有子列有值、主列空白的行）。看板类报表应改为汇总：
+
+| 需求 | 配置 |
+|------|------|
+| 条数 | `displayType:"Count"` + `countType:"count"` |
+| 取最大档（如风险等级） | `displayType:"Count"` + `countType:"max"` |
+| 取明细单值 | 无需汇总，`expandType:"NoExpand"`（多值会逗号拼接） |
+
+**汇总格三件套（缺一不可）**：`displayType:"Count"` + `expandType:"Vertical"` + `groupType:"none"`。
+⚠️ 服务端会把 `displayType=Count` **规范化回 `Group`**；用 `NoExpand` 配 Count 会被规范化掉、汇总失效
+（BUILD-14）。汇总按父格分组计算，不会撑行。
+
+⚠️ 汇总后的 **Select 值是裸 optionId**，需补 `transType:"select"` + `transSelectOptions:[{selectValue:id,selectName:名称}]`（BUILD-15）。
+
+### 2.4 业务映射示例（EBU 报表）
+
+| 子表类型 | 父格字段 | 当前字段 | 含义 |
+|----------|----------|----------|------|
+| 直销合同列 | EBU团队·责任人 | 直销合同业绩表·销售经理 | 按责任人关联合同 |
+| 收款明细列 | EBU团队·责任人 | 收款明细表·销售经理 | 按责任人关联收款 |
+
+根格（如 F3 责任人）设置 `leftX=-1, leftY=-1`；子格/公式格 `leftX=2, leftY=5` 指向根格列（0-based：行 2、列 5）。
+
+### 2.5 Python 辅助函数
+
+```python
+def field_key_ref(ds_id, src_id, field):
+    return f"{ds_id}.{src_id}.{field['name']}"
+
+def make_subordination(p_ds_id, p_src_id, p_field, c_ds_id, c_src_id, c_field):
+    return [
+        field_key_ref(p_ds_id, p_src_id, p_field),
+        field_key_ref(c_ds_id, c_src_id, c_field),
+    ]
+
+def make_left_filter(p_ds_id, p_src_id, p_field, c_ds_id, c_src_id, c_field):
+    ck = field_key_ref(c_ds_id, c_src_id, c_field)
+    pk = field_key_ref(p_ds_id, p_src_id, p_field)
+    return [{"parentField": pk, "currentField": ck, "type": "Equals", "id": ck}]
+```
+
+---
+
+## 三、单元格自定义筛选（customFilterField）
+
+### 3.1 与数据集级筛选的区别
+
+| 层级 | 配置位置 | 用途 |
+|------|----------|------|
+| **单元格 customFilterField** | `style.cellType.customFilterField` | 该单元格取数时的行级条件 |
+| **数据集 datasetFilter** | `saveReportWithCacheConfig` 的 `datasetFilter` 参数 | 整个数据集的基础过滤 |
+
+单元格自定义筛选同样必须使用 **fieldKey** 作为 `currentField`；每条条件配唯一 `index`（不是 `id`）。
+
+### 3.2 数据结构
+
+```json
+{
+  "customFilterField": [
+    {
+      "index": 101,
+      "currentField": "1304979560546713602.1299789221321891842.field_1299789221321891843",
+      "type": "NotContain",
+      "value": "某核算机构"
+    },
+    {
+      "index": 102,
+      "currentField": "1304979560546713602.1299789221321891842.field_1299789221321891844",
+      "type": "Null",
+      "value": ""
+    }
+  ]
+}
+```
+
+### 3.2.1 🔴 筛选 value 形态：按字段类型分流（★★ 全局规则 A0.20 · 2026-10-29 实证更正）
+
+**触发条件**：`customFilterField` 绑定的字段为 select/文本类型，且 `type` ∈ {`Include`, `Equals`, `Contain`, `NotContain`}。所有报表生成任务统一生效。
+
+**正确写法（唯一合法判据 = 字段元数据 `originFieldType`；多选一律 JSON 数组 · 2026-10-29 源码定案）**：
+
+| 字段类型 | originFieldType | value 形态 | 例 |
+|---|---|---|---|
+| **真 select**（单选/多选/下拉） | `RadioBox` / `CheckBox` / `Select` 等 | **optionId 的 JSON 数组**（多值）/ 单 optionId 字符串（单值） | `value:["1330…621","1330…622"]` |
+| **文本** | `String` / `Text` | **文本值逗号分隔**（即显示名形态） | `value:"优秀,合格"` |
+
+```json
+{
+  "customFilterField": [
+    {
+      "currentField": "{dataSetId}.{sourceId}.{字段名}",
+      "type": "Include",
+      "value": ["{optionId1}", "{optionId2}"],
+      "index": 103
+    }
+  ]
+}
+```
+
+**为什么真 select 字段必须 optionId 数组（2026-10-29 源码级定案，route_ReportDesigner chunk 反编译实证）**：
+1. **数据行存的就是 optionId**（BUILD-15 实证）——筛选 value 写显示名**运行期一条都筛不出来**。
+2. **设计器弹窗写回函数**（`Ut`）：`n({...t,[e]:r})` —— 多选 `Select multiple` 的 onChange 传**选项 id 数组**，**原样**写入 `value` ⇒ 设计器原生形态就是 optionId 数组。
+3. **弹窗回显匹配**：选项映射 `Y=L.map(e=>(ne===e.name&&(x(e.id),ne=e.id),{id:e.id,content:e.name}))` —— Select 按**数组中的 optionId** 勾选；仅「value 精确等于单个选项显示名」这一种历史字符串会被救成单 id。**逗号字符串既不是数组也不等于单个显示名** ⇒ 运行期引擎能切分逗号（预览生效）但弹窗值框永远「请选择」空白（三轮实证：显示名串 / optionId 逗号串均空白，仅数组形态回显）。
+
+**⚠ 结论更正记录（勿回退）**：
+- 2026-10-28 版「select 必须显示名」：金标准（员工培训参训情况汇总表 (2,8)）实为 **Text 字段**（`originFieldType:String`），显示名只是 Text 形态。
+- 2026-10-29 v1「select 必须逗号 optionId」：运行期正确、弹窗不回显——逗号串是**运行期容错形态**，非设计器原生形态。
+- **终版：多选 = optionId JSON 数组；单值 = 单 optionId 字符串；Text = 文本逗号串。**
+
+**金标准方法论（判定 value 形态的通用方法）**：写筛选前先取字段元数据（`fieldsBySource(srcId, appId).find(f=>f.name==='field_xxx')`），看 `originFieldType` / `config.type` / `config.options`：有 `options` 且类型为 RadioBox 族 → optionId 形态（选项 id 取 `config.options[].value`）；String/Text → 文本形态。**人工配置样例必须先核字段类型再对照**。
+
+**构建期检查（2026-10-29 降级）**：构建层 对 optionId 形态 value 默认**只告警不拦截**（构建期无法判定字段类型）；`opts.enforceSelectFilterValues === true` 显式恢复拦截。`verify_self_check` 同步降为 warning。
+
+### 3.3 type 枚举（平台值）
+
+**必须使用下列枚举**，不要用简写：
+
+| 平台 type | 错误写法（无效） | 说明 |
+|-----------|------------------|------|
+| `Equals` | `eq` | 等于 |
+| `NotContain` | `uncontains` | 不包含 |
+| `Null` | `empty` | 为空 |
+| `NotNull` | `nempty` | 不为空 |
+| `Contain` | — | 包含 |
+| `Include` | — | 属于（多值逗号分隔） |
+
+完整枚举见 `report-data-model.md` §2.5。
+
+### 3.4 需求文档到配置的映射
+
+需求 Excel 中常见写法 → API 配置：
+
+```
+核算机构 不包含 机构A,机构B  →  type: NotContain, value: 机构A（多条则多个 filter 项）
+核算机构 为空                →  type: Null, value: ""
+年度={year}                  →  type: Equals, value: "{year}"（系统参数原样保留）
+```
+
+```python
+FILTER_TYPE_MAP = {
+    "eq": "Equals", "uncontains": "NotContain",
+    "empty": "Null", "nempty": "NotNull",
+}
+```
+
+---
+
+## 四、保存与验证流程
+
+### 4.1 双保存（API 脚本必做）
+
+1. `POST /api/bs/edc/report/saveReportWithCacheConfig` — workbook + dataset + datasetFilter
+2. `POST /api/bs/edc/report/saveReportDevInfo` — 同 workbook（需带 `designKey`）
+
+仅保存其一可能导致设计器回显异常或筛选丢失。
+
+### 4.2 验证清单
+
+保存后调用 `getReportDevInfo`，检查 L3（或目标数据行）字段：
+
+- [ ] `subordination` 为两段 fieldKey，非 `["",""]`
+- [ ] `leftFilterField` 非空，且 `parentField`/`currentField` 含两个 `.`
+- [ ] `customFilterField`（若有）的 `type` 为平台枚举
+- [ ] **筛选 value 形态与字段类型匹配**：真 select（RadioBox 族）→ optionId 逗号分隔；Text/String → 文本值（A0.20 · 2026-10-29 更正 / §3.2.1）
+- [ ] 设计器打开后左父格筛选、自定义筛选下拉**有选中项**（非空白）
+
+### 4.3 配置校验脚本
+
+```bash
+e10-cli report py validate <配置文件路径>
+```
+
+脚本会检查 fieldKey 格式、type 枚举、customFilterField 结构。
+
+---
+
+## 五、常见错误定位
+
+### 5.1 设计器筛选下拉空白
+
+1. 确认 `parentField`/`currentField` 均为 `{dataSetId}.{sourceId}.{fieldName}`；`id` 为该条条件的**唯一雪花号**（不是 fieldKey，BUILD-115）
+2. 确认 `dataSetId` 是报表内数据集 ID，不是 appId / reportId
+3. **select 字段：确认 `value` 是选项显示名而非 optionId**（A0.20 / §3.2.1，注意点 BUILD-98）——这是本症状最高频根因
+3. 确认 `fieldName` 来自 `ds/fields` 接口的 `name` 字段
+4. 双保存后刷新设计器
+
+### 5.2 父格循环引用
+
+子格 `leftY` 指向错误列会导致父格环（如根格在 F 列却设 `leftY=6` 指向 G）。根格用 `leftX=-1, leftY=-1`。
+
+### 5.3 style 与 fields 表不一致
+
+`getAllSheets` 的 `dtTable` 可能为空；**以 `getReportDevInfo.fields` 为准**。workbook 内筛选写在 `style.cellType`，平台解析后同步到 fields 表。
+
+---
+
+## 六、生成配置时的 Agent 检查项
+
+生成或修改含跨数据集字段的报表时，Agent 必须：
+
+1. 从 `ds/list` + `ds/fields` 获取真实 `dataSetId`、`sourceId`、`field.name`
+2. 对每个跨数据集列生成 `subordination` + `leftFilterField`（fieldKey + `id`）
+3. 对需求中的过滤条件生成 `customFilterField`（fieldKey + 平台 type）
+4. 含 Formula 单元格时遵守 `formula-cell-api-guide.md`（cellText 无前导 `=`）
+5. 运行 `e10-cli report py validate` 预检
+6. 若通过 API 保存，执行双保存并用 `getReportDevInfo` 验证
+
+---
+
+## 八、公式单元格（另见专篇）
+
+含 Formula 单元格且通过 **API / 脚本保存** 时，必须遵守 `formula-cell-api-guide.md`：
+
+- `cellText` / 顶层 `formula` **不带前导 `=`**
+- `countType: count`、`displayType: Group`、`groupType: null`
+- 双保存 + `getReportDevInfo` 回读验证
+
+公式格本身通常 **不需要** subordination / leftFilterField；它引用同表内已配好筛选的 Field 汇总格。
+
+---
+
+## 九、相关文档
+
+- `formula-cell-api-guide.md` — 公式单元格 API 写入规范（完整）
+- `report-config-schema.md` §2.4–2.5 — 过滤与 Formula Schema
+- `report-data-model.md` §2.4–2.5 — TypeScript 类型与枚举
+- `ai-report-workflow.md` §4.4、§六 — 交叉表工作流与公式规则
+- `report-knowledge-base.md` §2.1、§2.5 — 父格与自定义筛选概念