weaver-e10-builder 1.6.10 → 1.6.12

package/skill-docs/references/report/column-split-report-guide.md

@@ -0,0 +1,96 @@
+# 分栏报表四案例 · 场景 J（SKILL A0.19）
+
+> 案例一「行分栏」：各分公司员工劳动关系详表——纵向扩展明细横向分 2 栏，标题行复制。
+> 案例二「列分栏」：股票行情——横向扩展记录纵向分块（1-8 / 9-16 / 17-24），表头列复制。
+> 案例三「卡片分栏」：条码卡 3 栏平铺（卡片版式 + 条码格）。
+> 案例四「行分栏汇总统计」：多级行维度（集团→公司→厂）+ 合计行 + 红色百分比预警 + 横向分栏。
+
+---
+
+## 一、核心结论：分栏是渲染级配置，不是多带构造
+
+分栏入口 = 设计器「**页面 → 报表展示 → 分栏**」（help-guide §8.5：按行/列数分栏 / 按栏数分栏；
+模式：垂直 / 水平 / 卡片；复制标题或表头）。**设计 workbook 保持单数据带**，引擎按配置复制标题
+并重排实例 —— 与预聚合 / 分页同属 sheetConfig 级开关（knowledge-base §4.7）。
+
+**落库通道（已固化）**：
+- `build spec`：`layout.sheetConfig: { ... }` → 并入 `sheet.tag.sheetConfig`（A0.19 起，与 dataPreAgg 同通道）
+- `card spec`：`spec.sheetConfig` 原本就透传
+
+⚠️ **分栏 sheetConfig 具体键名待确认**（类比 dataPreAgg 当年也是验证出来的）。
+**验证捕获法**：设计器建一张分栏报表 → `getReportDevInfo` → 看 `sheetProps[0].sheetConfig`
+（JSON 字符串）里的分栏键 → 回填本指南后即可在 spec 里写死。
+示例占位（**未验证**，仅示意形状）：`{"splitConfig":{"mode":"row","count":20}}`。
+
+## 二、四案例解析
+
+### J-1 行分栏（案例一 · 纵向扩展数据横向分栏）
+
+| 特性 | 设计 |
+|---|---|
+| 左维度「分公司名称」纵跨整栏 | 分公司 Field `Vertical+Group`、isActiveParent；明细左父格链到它 |
+| 明细带（序号/姓名/劳动关系/学历） | 序号=`cellType:"seq"`；其余普通 Field 左父格链式 |
+| 每栏复制标题行 | 分栏配置「复制标题行」= 表头 Const 行（引擎自动复制） |
+| 分栏触发 | 按行数（每 N 行一栏）或按栏数 |
+
+spec 骨架：普通分组明细表 `build spec` + `layout.sheetConfig`（分栏键）。
+
+### J-2 列分栏（案例二 · 横向扩展数据纵向分块）
+
+| 特性 | 设计 |
+|---|---|
+| 字段为行标签（日期/成交量/…） | 字段名列 = 各 Field 竖排（不扩展），左父格链 |
+| 记录横向扩展（序号 1-8） | 序号/日期行 = `Horizontal` 扩展格（日期 Group 或记录序），isActiveParent |
+| 分块（1-8 / 9-16 / …） | 分栏配置「按列数」+「复制表头列」（序号+标签列） |
+| 顶层标题合并 | 「某公司2~4月份股票行情」Const 跨全宽 |
+
+直构坐标模板（rebuild 路径）：标签列 A（6 个 Field 竖排），B 列横向扩展锚点；分栏键在 sheetConfig。
+
+### J-3 卡片分栏（案例三 · 卡片版式 3 栏平铺 + 条码）
+
+| 特性 | 设计 |
+|---|---|
+| 一条记录=一张卡片（姓名/编号ID/职务/出生日期/地址/邮编/联系方式） | **`card build` 通道**（cells 网格 label/value，同段落机制） |
+| 3 栏平铺、行间复制 | 分栏模式=**卡片**（栏数 N + 复制单元=整体扩展单元首尾单元格，knowledge-base §4.7-5） |
+| 编号ID 条码 | ✅ A0.19 起 card spec 单元格支持 **`qrcode`/`qrlink`** 透传（`qrcodeType/qrcodelink`）；**条码枚举值待验证**（设计器 条码下拉：无/条码/二维码，具体字符串回填） |
+| 姓名+条码图片位 | 姓名 Field；图片格=字段转换（图片 transType，见 cell-transform-guide）或 Const 占位 |
+
+### J-4 行分栏汇总统计（案例四 · 多级行维度 + 合计 + 预警 + 分栏）
+
+| 特性 | 设计 |
+|---|---|
+| 三级行维度（集团→公司→厂） | 场景 H 多级行维度：子级左父格→上级格（rebuild 直构） |
+| 各级「合计」行 | Formula 左父格=该级维度格（crosstab §4.2 ★禁默认链） |
+| 值列组（全年计划/10月/累计/完成年计划比…） | 普通 Field + 完成率 Formula；红色百分比=conditionRule（超标红字） |
+| 横向分栏 | 同 J-1 分栏配置；多级左维度树整棵随栏复制（引擎行为，已验证） |
+
+## 三、搭建提示语句
+
+**J-1 行分栏**：
+> 按行分栏格式搭一张员工劳动关系详表：列「分公司名称/序号/员工姓名/劳动关系/学历」，
+> 分公司 Field 纵向分组扩展、明细跟随，序号用系统序号；数据源 `<sid>`（appId `<appId>`）；
+> 横向分栏每栏 N 行、复制标题行；用 `build spec` 落库 + `layout.sheetConfig` 写分栏配置
+> （键名以设计器确认回填为准），落库后回读验收父格链。
+
+**J-2 列分栏**：
+> 按列分栏格式搭一张股票行情表：左侧标签列（日期/成交量/开盘/盘高/盘低/收盘）竖排，
+> 记录横向扩展（序号行）；纵向分块每块 N 列、复制表头列；数据源 `<sid>`（appId `<appId>`）；
+> 走 rebuild 直构（横向扩展 + 分栏 sheetConfig），回读验收扩展格与分栏配置。
+
+**J-3 卡片分栏条码**：
+> 按卡片分栏格式搭一张员工条码卡：卡片内 姓名+条码（编号ID 字段，qrcode 透传）+
+> 职务/出生日期/地址/邮编/联系方式 label-value 网格；数据源 `<sid>`（appId `<appId>`）；
+> 用 `card build` 出版式，`spec.sheetConfig` 写卡片分栏（栏数 3，复制单元首尾）；
+> 条码枚举值与分栏键名以设计器确认回填为准，回读验收 qrcodeType 与锚点。
+
+**J-4 行分栏汇总统计**：
+> 按行分栏汇总格式搭一张生产产量完成情况表：行维度三级「集团→公司→厂」逐级缩进、
+> 各级合计行、值列组（计划/实际/完成比），完成率超 100% 红字；
+> 数据源 `<sid>`（appId `<appId>`）；rebuild 直构（多级行维度+合计行）+
+> `layout.sheetConfig` 横向分栏；回读验收合计行左父格与条件色。
+
+## 四、能力边界（如实）
+
+1. 分栏 sheetConfig 键名、条码 qrcodeType 枚举字符串 = **待确认**（通道已通，值待回填）。
+2. 分栏后跨栏的父格/合并表现（尤其多级行维度整棵复制）= 引擎渲染行为，设计器已验证。
+3. J-2/J-4 的多级结构超出 build spec 表达力 → rebuild 直构；J-1/J-3 单源可走 build spec / card build。

package/skill-docs/references/report/condition-format-guide.md

@@ -4,7 +4,7 @@
 > **UI**：设计器「开始 → 条件格式」
 > **落库唯一有效点**：`fields[].conditionRule` / workbook `style.cellType.conditionRule`
 > 结构：`{ highlightDatas, lineDatas, iconDatas }`（**不是** sheet 级 `conditionalFormats`，后者不持久化）
-> **禁黑盒**：禁止下载 SpreadJS / 设计器 chunk 循环试探；见 `session-build-performance-guide.md`
+> **禁黑盒**：禁止下载 SpreadJS / 设计器 chunk 循环试探；见 `api-report-build-fast-path.md`
 
 ---
 
@@ -59,18 +59,18 @@
 
 ```json
 {
- "lineDatas": [
- {
- "index": 0,
- "leftType": "min",
- "leftValue": "",
- "rightType": "max",
- "rightValue": "",
- "gradient": "gradient",
- "color": "#6495ED",
- "negativeFillColor": "#FF0000"
- }
- ]
+  "lineDatas": [
+    {
+      "index": 0,
+      "leftType": "min",
+      "leftValue": "",
+      "rightType": "max",
+      "rightValue": "",
+      "gradient": "gradient",
+      "color": "#6495ED",
+      "negativeFillColor": "#FF0000"
+    }
+  ]
 }
 ```
 
@@ -90,16 +90,16 @@ CLI：`e10-cli report validate condition --map "数据条"` / `--map "实心数
 
 ```json
 {
- "iconDatas": [
- {
- "index": 0,
- "iconSetType": "0",
- "iconCriteria": [
- { "iconValue": "67", "isGreaterThanOrEqualTo": true, "iconValueType": 1 },
- { "iconValue": "33", "isGreaterThanOrEqualTo": true, "iconValueType": 1 }
- ]
- }
- ]
+  "iconDatas": [
+    {
+      "index": 0,
+      "iconSetType": "0",
+      "iconCriteria": [
+        { "iconValue": "67", "isGreaterThanOrEqualTo": true, "iconValueType": 1 },
+        { "iconValue": "33", "isGreaterThanOrEqualTo": true, "iconValueType": 1 }
+      ]
+    }
+  ]
 }
 ```
 
@@ -125,6 +125,31 @@ CLI：`e10-cli report validate condition --map "图标集"`
 2. save 成功 → **先交设计器 URL**
 3. 可选 `verify condition` 后置
 
+### ⚠️ 硬坑一：重建 workbook 会丢/清空 conditionRule（已修复）
+
+`` 的 `fieldToCell()` 若**未把 `fields[].conditionRule` 透传进 workbook `style.cellType.conditionRule`**，则：
+- 引擎读 workbook → **新写的条件格式不生效**；
+- 重建时该 cell 的 style 丢掉 `conditionRule` → **保存后既有规则被清空**。
+
+**当 `workbookProps.sheets` 为空（如 0 cell，本平台常见）时，`mergeWorkbookSafe` 必走 `buildWorkbookFromFields(fields)` 重建**，此坑必现。
+
+→ 已修复：`fieldToCell()` 末尾补
+```js
+const cr = parseJsonMaybe(f.conditionRule, null);
+if (cr && typeof cr === 'object' && Object.keys(cr).length > 0) {
+  if (!style.cellType || typeof style.cellType !== 'object') style.cellType = {};
+  style.cellType.conditionRule = cr;
+}
+```
+> 若条件格式「写了却不生效」或「保存后原有规则消失」，先查此处。
+
+### ⚠️ 硬坑二：单点修改纪律（强制）
+
+- 用户只要求改 A，**禁止顺手改 B**（例如只要求改条件格式，绝不可顺带改公式/字段/布局）；
+- 参考 `user-request-scope-only-guide.md`：仅改用户点名项；
+- 生产报表做单点修改前，**先抓 `getReportDevInfo` 全量快照存档**，改后 diff 校验改动范围；
+- 保存后服务端会**强制规范化**一批等价空值（`subordination ["",""]→[]`、`refX/refY -1→0`、`hiddenContext "0"→删除`、`orderType "no"→删除`、`transSelectOptions "[]"→""`、`allNeedFields` 顺序），属正常，**不是内容丢失**，无法也无需通过接口还原。
+
 ---
 
 ## 七、CLI
@@ -137,4 +162,4 @@ e10-cli report validate condition --map "图标集"
 e10-cli report verify condition <reportId> [appId]
 ```
 
-脚本：`e10-cli report verify condition`。
+脚本：`e10-cli report validate condition`。

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

@@ -6,6 +6,23 @@
 >
 > **与「左侧数据集筛选」区分**：整表/行级预过滤走 **`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`）。
@@ -43,17 +60,22 @@
 
 两者字段引用**都必须使用 fieldKey**。
 
-### 2.1.1 连续同源区域：只配入口格（强制）
+### 2.1.1 连续同源区域：筛选只配入口格 · 后续字段以入口格为父格（★★ 最高优先 · 强制）
 
-> 完整规则见 **`datasource-selection-and-parent-filter-guide.md` §二**（含 **§2.5 关联键：需求优先 · 推断须用户确认**）。
+> 完整规则见 **`datasource-selection-and-parent-filter-guide.md` §二**（含 **§2.5 关联键：需求优先 · 推断须用户确认**、**§2.6 自检判据**）。
 
 若连续一片单元格**全部来自同一数据源**，且整体挂在另一数据源父格下：
 
-- **仅该区域第一个字段**：自定义父格指向异源父格 + 配置 `subordination` / `leftFilterField`
-- **同区域其余字段**：父格用**默认**，**不要**逐格再指异源父格、**不要**重复配父格筛选
-- **关联字段**：需求已写明则按需求；未写明则字段匹配推断后 **必须提示用户确认**（CLI：`e10-cli report join-suggest`）
+- **入口格（区域第一个字段）**：自定义父格指向异源关联键格 + 配置 `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 数据结构
 
@@ -61,18 +83,18 @@
 
 ```json
 {
- "subordination": [
- "1304979556231593994.1299763447342276611.field_1299763447342276617",
- "1304979560546713602.1299789221321891842.field_1299789221321891843"
- ],
- "leftFilterField": [
- {
- "parentField": "1304979556231593994.1299763447342276611.field_1299763447342276617",
- "currentField": "1304979560546713602.1299789221321891842.field_1299789221321891843",
- "type": "Equals",
- "id": "1304979560546713602.1299789221321891842.field_1299789221321891843"
- }
- ]
+  "subordination": [
+    "1304979556231593994.1299763447342276611.field_1299763447342276617",
+    "1304979560546713602.1299789221321891842.field_1299789221321891843"
+  ],
+  "leftFilterField": [
+    {
+      "index": 27,
+      "currentField": "1304979560546713602.1299789221321891842.field_1299789221321891843",
+      "type": "Equals",
+      "parentField": "1304979556231593994.1299763447342276611.field_1299763447342276617"
+    }
+  ]
 }
 ```
 
@@ -83,21 +105,32 @@
 | parentField | 同 subordination[0] |
 | currentField | 同 subordination[1] |
 | type | 匹配关系，跨数据集关联通常用 `Equals` |
-| id | **必须等于 currentField**（设计器回显关键） |
+| index | **该条条件自身的唯一序号**（设计器原生形态）—— ⚠ 不是字段 fieldKey，见 §2.3 |
 
 **save 后 fields 表**（`getReportDevInfo`）：`leftFilterField`、`subordination` 出现在字段记录顶层（JSON 字符串或数组），不在 `style` 内。
 
-### 2.3 左父格筛选识别与写入（2026-09 eteams · 必遵）
+### 2.3 左父格筛选识别与写入（2026-09 eteams 验证 · 必遵）
 
 设计器 F2「左父格筛选」下拉按 **fieldKey 注册表** 解析标签；下列写法会导致回显 **`undefined`** 或下拉空白：
 
 | 错误写法 | 现象 | 正确写法 |
 |----------|------|----------|
 | `parentField: "...field_5"`（截断/臆造字段名） | 父格关联字段显示 undefined | 完整 `{dataSetId}.{sourceId}.field_4746632256695654785` |
-| `id: "c43a895a664140dc"`（随机 UUID） | 筛选行无法匹配字段 | **`id` 必须等于 `currentField`（完整 fieldKey）** |
+| `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）：
@@ -112,10 +145,10 @@
 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",
+    ds_supplier, src_supplier, "field_4746632256695654785",
+    ds_purchase, src_purchase, "field_4746633026496455388",
 )
-# lf[0]["id"] == lf[0]["currentField"] # 必须
+# lf[0]["id"] 是独立唯一雪花号，**不等于** currentField（BUILD-115）
 ```
 
 **保存后验证**（`getReportDevInfo` 抽检首个跨表格，如进货单编号 y=5）：
@@ -124,7 +157,61 @@ lf, sub = build_cross_dataset_filter(
 # parentField / currentField 各含两个 '.' 段；subordination 与 leftFilterField 一致
 ```
 
-参考实现：`本地工作目录`、`restore_and_fix_left_filter.js`。
+### 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 报表）
 
@@ -139,22 +226,20 @@ lf, sub = build_cross_dataset_filter(
 
 ```python
 def field_key_ref(ds_id, src_id, field):
- return f"{ds_id}.{src_id}.{field['name']}"
+    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),
- ]
+    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}]
+    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）
@@ -166,42 +251,66 @@ def make_left_filter(p_ds_id, p_src_id, p_field, c_ds_id, c_src_id, c_field):
 | **单元格 customFilterField** | `style.cellType.customFilterField` | 该单元格取数时的行级条件 |
 | **数据集 datasetFilter** | `saveReportWithCacheConfig` 的 `datasetFilter` 参数 | 整个数据集的基础过滤 |
 
-`currentField` 必须是 **fieldKey**；`id` 平台可接受但设计器回写**不带**（2026-10 抓包），所以
-新写入以设计器形状为准：
+单元格自定义筛选同样必须使用 **fieldKey** 作为 `currentField`；每条条件配唯一 `index`（不是 `id`）。
+
+### 3.2 数据结构
 
 ```json
-[
- { "index": 1,
-   "currentField": "{dataSetId}.{sourceId}.{fieldName}",
-   "type": "Equals",
-   "value": ["1"] }
-]
+{
+  "customFilterField": [
+    {
+      "index": 101,
+      "currentField": "1304979560546713602.1299789221321891842.field_1299789221321891843",
+      "type": "NotContain",
+      "value": "某核算机构"
+    },
+    {
+      "index": 102,
+      "currentField": "1304979560546713602.1299789221321891842.field_1299789221321891844",
+      "type": "Null",
+      "value": ""
+    }
+  ]
+}
 ```
 
-**选项类字段**（Select / RadioBox / CheckBox / …）的 `value` 是**选项 valueKey 数组**；
-文本/数字/日期写字符串。手工拼报文时容易只写选项显示名 —— 平台有时能按名称兜底，
-但设计器回显会变成空，按 valueKey 写最稳。
-
-### 3.2 用 CLI 写入（推荐）
+### 3.2.1 🔴 筛选 value 形态：按字段类型分流（★★ 全局规则 A0.20 · 2026-10-29 实证更正）
 
-```bash
-# 自定义筛选：分类 等于 甲（选项名自动换成 valueKey）
-e10-cli report cell-filter set <reportId> --app-id <appId> \
-  --cell 1,0 --op 等于 --value 甲
+**触发条件**：`customFilterField` 绑定的字段为 select/文本类型，且 `type` ∈ {`Include`, `Equals`, `Contain`, `NotContain`}。所有报表生成任务统一生效。
 
-# 指定同一数据集里的其他字段，追加第二条条件
-e10-cli report cell-filter set ... --field 金额 --op 大于 --value 100 --append
+**正确写法（唯一合法判据 = 字段元数据 `originFieldType`；多选一律 JSON 数组 · 2026-10-29 源码定案）**：
 
-# 结果筛选（前多少个 / 后多少个 / 奇数 / 偶数 / 特定）
-e10-cli report cell-filter set ... --cell 1,1 --kind result --op 前几个 --value 1
+| 字段类型 | originFieldType | value 形态 | 例 |
+|---|---|---|---|
+| **真 select**（单选/多选/下拉） | `RadioBox` / `CheckBox` / `Select` 等 | **optionId 的 JSON 数组**（多值）/ 单 optionId 字符串（单值） | `value:["1330…621","1330…622"]` |
+| **文本** | `String` / `Text` | **文本值逗号分隔**（即显示名形态） | `value:"优秀,合格"` |
 
-# 读回 / 清除
-e10-cli report cell-filter list <reportId> --app-id <appId>
-e10-cli report cell-filter remove <reportId> --app-id <appId> --cell 1,0
+```json
+{
+  "customFilterField": [
+    {
+      "currentField": "{dataSetId}.{sourceId}.{字段名}",
+      "type": "Include",
+      "value": ["{optionId1}", "{optionId2}"],
+      "index": 103
+    }
+  ]
+}
 ```
 
-命令会改 `fields[]` + workbook `style.cellType`、双保存并回读比对；`designKey` 过期
-（code=200 + `data:"您当前的数据不是最新的…"`）会自动重读重写一次。
+**为什么真 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 枚举（平台值）
 
@@ -223,15 +332,15 @@ e10-cli report cell-filter remove <reportId> --app-id <appId> --cell 1,0
 需求 Excel 中常见写法 → API 配置：
 
 ```
-核算机构 不包含 机构A,机构B → type: NotContain, value: 机构A（多条则多个 filter 项）
-核算机构 为空 → type: Null, value: ""
-年度={year} → type: Equals, value: "{year}"（系统参数原样保留）
+核算机构 不包含 机构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",
+    "eq": "Equals", "uncontains": "NotContain",
+    "empty": "Null", "nempty": "NotNull",
 }
 ```
 
@@ -253,12 +362,13 @@ FILTER_TYPE_MAP = {
 - [ ] `subordination` 为两段 fieldKey，非 `["",""]`
 - [ ] `leftFilterField` 非空，且 `parentField`/`currentField` 含两个 `.`
 - [ ] `customFilterField`（若有）的 `type` 为平台枚举
+- [ ] **筛选 value 形态与字段类型匹配**：真 select（RadioBox 族）→ optionId 逗号分隔；Text/String → 文本值（A0.20 · 2026-10-29 更正 / §3.2.1）
 - [ ] 设计器打开后左父格筛选、自定义筛选下拉**有选中项**（非空白）
 
 ### 4.3 配置校验脚本
 
 ```bash
-python e10-cli report validate <配置文件路径>
+e10-cli report py validate <配置文件路径>
 ```
 
 脚本会检查 fieldKey 格式、type 枚举、customFilterField 结构。
@@ -269,8 +379,9 @@ python e10-cli report validate <配置文件路径>
 
 ### 5.1 设计器筛选下拉空白
 
-1. 确认 `parentField`/`currentField`/`id` 均为 `{dataSetId}.{sourceId}.{fieldName}`
+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. 双保存后刷新设计器
 
@@ -292,7 +403,7 @@ python e10-cli report validate <配置文件路径>
 2. 对每个跨数据集列生成 `subordination` + `leftFilterField`（fieldKey + `id`）
 3. 对需求中的过滤条件生成 `customFilterField`（fieldKey + 平台 type）
 4. 含 Formula 单元格时遵守 `formula-cell-api-guide.md`（cellText 无前导 `=`）
-5. 运行 `validate_report_config.py` 预检
+5. 运行 `e10-cli report py validate` 预检
 6. 若通过 API 保存，执行双保存并用 `getReportDevInfo` 验证
 
 ---