weaver-e10-builder 1.6.14 → 1.6.16

package/skill-docs/references/report/field-bind-exact-match-guide.md

@@ -1,208 +1,208 @@
-# 字段精确绑定（强制 · 禁止匹配失败）
-
-> **事故案例（已验证）**：报表 `AAA`（`1312677851392417792`）保存了 9 个 Field 格，但 `name` / `fieldKey` 末段写成裸雪花 ID `3506271516100878845`，而数据源真实字段名是 `field_3506271516100878845` → **设计器有字段格、取数全部匹配失败（字段获取不上）**。
-> **前置事故（已验证 · `1312765120721813505`）**：Agent 用错 `addDataset`（`type=form` + `sourceGroup=appId`）时，`fieldsKey` **本身只有裸雪花**；用户在设计器手动「+」同表则得到 `field_*`。
-> **遗漏点**：不是写 Field 时忘加前缀，而是 **注册契约与设计器不一致** —— 必先读 **`add-dataset-registration-guide.md`**，把数据集加成 LOGIC + `weaver-ebuilder-form-service`，再绑定。
-> **唯一标准**：`name` / `fieldKey` 末段必须 **精确等于** 当前数据集 `fieldsAndOriginFields.fieldsKey[].name`（以接口回读为准）。
-> **禁止**：注册错了却在 cell 上「手工补 `field_`」；或对正确的 `field_*` fieldsKey 去前缀。
-> **硬目标**：任意 Field 的 `name` **必须**等于该 dataset 的 `fieldsKey[].name`；**零容忍**猜测、截断、错数据集。
-
----
-
-## 〇、先保证 fieldsKey 带 `field_`（普通应用）
-
-| 检查 | 说明 |
-|------|------|
-| addDataset | 默认 `sourceType=LOGIC` + `sourceGroup=weaver-ebuilder-form-service` |
-| 门禁 | 业务字段若多为裸雪花 → **注册错误**，`delDataset` 重建；见 `add-dataset-registration-guide.md` |
-| 同 sourceId 多实例 | **优先绑**设计器/LOGIC 那条（`field_*`），勿绑旧 form+appId 实例 |
-
----
-
-## 一、唯一合法字段名来源
-
-```
-GET /api/bs/edc/dataset/fieldsAndOriginFields
-  ?datasetId={datasetId}&hasField=true&isFront=true&reportId={reportId}
-→ data.fieldsKey[]     // 权威列表；isFront=false 常为空，禁止依赖
-```
-
-每个 `fieldsKey` 项的关键属性：
-
-| 属性 | 用途 | 示例 |
-|------|------|------|
-| **`name`** | **写入 Field 的 `name` / fieldKey 末段（唯一正确）** | `field_3506271516100878845`、`create_time` |
-| `text` / `showName` | 仅用于按中文显示名**查找**对应 `name` | `资产类别` |
-| `originName` | 参考，不可直接当 fieldKey 末段（除非与 `name` 相同） | — |
-
-**禁止**从下列来源臆造 `name`：
-
-| 错误来源 | 错误示例 | 后果 |
-|----------|----------|------|
-| 表单字段 ID / 雪花 ID（无 `field_`） | `3506271516100878845` | **取数匹配失败**（本案） |
-| 显示名 | `资产类别` | 设计器/取数均失败 |
-| 截断 / 半截 | `field_5`、`field_3506` | 匹配失败 |
-| 去掉 `field_` 前缀 | 把 `field_xxx` 写成 `xxx` | **取数匹配失败** |
-| 外部字段表 fieldId 未与 fieldsKey 交叉核对 | 形态可能不同 | 须与 fieldsKey.name 对齐后再用 |
-
----
-
-## 二、绑定算法（强制）
-
-> **⚠️ 2026-09-11 追加门禁（事故：报表 `1313789294296735745`）**：B3 列文案「姓名」，但该表单**没有「姓名」字段**，
-> 旧逻辑静默兜底到系统字段 `name`（真实显示名「标题」）→ 单元格文案与绑定字段语义不符、属性面板回显对不上。
-> **新规则：精确匹配失败必须 `exit 4` 提示用户指定字段，禁止任何自动兜底（尤其禁止回退系统字段）。**
-> 落地实现：构建层 + `e10-cli report build spec` 的**建表前预检**。
-
-对需求中的每一列（显示名 → 数据字段）：
-
-### 2.0 允许的匹配（命中即止，**全为精确匹配**）
-
-| 顺序 | 依据 | 说明 |
-|------|------|------|
-| 1 | `column.fieldName` / `spec.fieldMap[列标题]` | 用户/Agent 显式指定（可为 `field_xxx`、显示名、系统字段名） |
-| 2 | 列标题 === `fieldsKey[].text/showName`（归一化：去空白、全角括号→半角） | 主路径 |
-| 3 | `column.field` === `text/showName` 或 `name` | 兼容旧 spec |
-| 4 | 都不中 | **`unmatched` → exit 4**（附模糊候选供用户挑选） |
-
-**禁止**：包含/被包含（`includes`）等模糊规则自动绑定；**禁止**把 `name`/`id`/`create_time` 等系统字段当作兜底。
-
-### 2.0.1 规则 A · 找不到字段 → **停下让用户指定**（强制 · 2026-09-11）
-
-> **核心**：需求里的字段在当前数据集表单里**找不到**时，**不许猜、不许兜底**，必须停下把候选交给用户。
-
-`resolveFieldBindings()` 的 `unmatched[]` 三种 `reason` 及处置：
-
-| `reason` | 含义 | 退出码 | 处置 |
-|----------|------|--------|------|
-| `no_exact_match` | 列标题在 `fieldsKey.text` 中**无精确命中** | **4** | 把 `candidates` + `allFields` 抛给用户，请其指定字段 |
-| `explicit_not_found` | 显式 `fieldName`/`fieldMap` 指向的字段**不存在** | **4** | 同上（禁止臆造字段名） |
-| `display_mismatch` | 能绑到，但字段**真实显示名 ≠ 列文案**且未确认 | **4** | 用户确认列名有意如此 → `fieldConfirmed` / `--field-confirmed "列标题"` |
-
-**两阶段拦截**（都不建表 / 删未完成表）：
-
-| 阶段 | 时机 | 未通过 |
-|------|------|--------|
-| 预检 | `fieldsBySource`（**建表前**） | **exit 4 · 未创建任何报表** |
-| 复校 | 本表 `addDataset` → `fieldsKey`（落库前） | **exit 4 · 删除本轮未完成报表** |
-
-输出结构（`rule:"A"`）：
-
-```json
-{
-  "action": "confirm_field", "rule": "A", "needConfirm": true, "reportCreated": false,
-  "unmatched": [ { "column": "姓名", "reason": "no_exact_match", "prompt": "…请用户从 allFields/candidates 中指定字段",
-                   "candidates": [ { "name": "field_...", "text": "发展人", "system": false } ] } ],
-  "allFields": [ { "name": "field_...", "text": "发展人", "system": false } ],
-  "next": { "specFields": { "fieldMap": { "<列标题>": "<字段显示名 | field_雪花 | 系统字段名>" } } }
-}
-```
-
-用户指定后复跑：`spec.fieldMap = { "姓名": "发展人" }`（或 `field_xxx`）。
-若列名坚持与字段显示名不同 → 另加 `fieldConfirmed: ["姓名"]` / CLI `--field-confirmed "姓名"`。
-
-**禁止**：
-- 用「最相近的」字段顶上（哪怕语义看似接近）；
-- 回退系统字段（`name`→「标题」是历史事故）；
-- 先带病落库、事后再让用户改。
-
-> 一页速览：。
-
-```javascript
-// 1. 拉权威列表
-const fieldsKey = (await fieldsAndOriginFields(...)).data.fieldsKey;
-
-// 2. 解析（库函数，已含门禁）
-const plan = resolveFieldBindings(fieldsKey, spec.columns, { fieldMap, fieldConfirmed });
-if (!plan.ok) {
-  // exit 4：把每列 candidates 抛给用户，等其指定字段；不要自己猜
-}
-const nf = plan.bindings.find(b => b.index === colIndex).field;
-```
-
-**规则摘要**：
-
-1. **先** `fieldsAndOriginFields`，**再**写任何 Field 单元格
-2. `name` **逐字等于** `fieldsKey[].name`（含 `field_` 前缀；系统字段如 `create_time` 原样）
-3. `fieldKey` = `{datasetId}.{sourceId}.{fieldsKey.name}`，三段齐全
-4. 保存前对**每一个** Field 做 `byName.has(name)`；任一失败 → **中止保存**，禁止带病落库
-
----
-
-## 三、保存后强制回读校验（交付门禁）
-
-`getReportDevInfo` 后，对每个 `cellType === 'Field'`：
-
-```javascript
-function assertFieldBindExact(devFields, fieldsKey) {
-  const legal = new Set(fieldsKey.map(f => f.name));
-  const fieldCells = devFields.filter(f => f.cellType === 'Field');
-  if (!fieldCells.length) throw new Error('无 Field 单元格');
-  for (const f of fieldCells) {
-    const last = String(f.fieldKey || '').split('.')[2] || '';
-    if (!f.name || !legal.has(f.name)) {
-      throw new Error(`字段匹配失败 name=${f.name} text=${f.text}`);
-    }
-    if (last !== f.name || !legal.has(last)) {
-      throw new Error(`fieldKey 末段不在 fieldsKey: ${f.fieldKey}`);
-    }
-    // 裸雪花：若 fieldsKey 里已有 field_xxx，则禁止用裸名；否则先查 addDataset 是否注册错
-  }
-}
-```
-
-| 检查 | 失败即 FAIL |
-|------|-------------|
-| 每个 Field 的 `name ∈ fieldsKey.name` | ✅ |
-| `fieldKey` 末段 === `name` | ✅ |
-| 普通应用：fieldsKey 业务字段含 `field_*`（注册门禁） | ✅ 见 `add-dataset-registration-guide.md` |
-| Field 数量 ≥ 需求列数 | ✅ |
-| **单元格文案 === 绑定字段真实显示名**（否则须用户确认） | ⚠ `verify bind` 列出 `display_mismatch` |
-| **同 sourceId 只挂 1 个数据集**（否则左侧重复分组） | ⚠ `verify bind` 列出 `duplicate_dataset_mount` |
-
-`e10-cli report verify bind <reportId> [appId] [--strict]`：门禁失败 exit 1；`--strict` 时「待用户确认项」exit 2。
-
-**未通过校验 → 须修正并告知用户**；可与「已交付的设计器链接」并行：先给链接（见 `report-delivery-contract.md` §〇），校验失败再补丁修复，**禁止**为等校验而拖延首轮地址。
-
----
-
-## 四、故障对照
-
-| 现象 | 根因 | 处理 |
-|------|------|------|
-| 设计器有 Field 格，预览/取数无数据或字段空白 | `name` 为裸 ID，缺 `field_` | 按 fieldsKey.name 重绑并 saveReportDevInfo |
-| **手动加的数据集有 `field_`，API 加的没有** | **addDataset 用了 form+appId，不是设计器 LOGIC** | 按 `add-dataset-registration-guide.md` del 后重建 |
-| **单元格表头文案 ≠ 属性面板字段名**（如「姓名」实为「标题」） | 旧逻辑把无匹配列**兜底到系统字段** | 改为 `exit 4` 让用户指定；存量报表用 `fieldMap`/重绑修复 |
-| **左侧出现重复数据源分组** | 同 sourceId 被重复 `addDataset` 挂载 + 画布游离单元格引用 | 先改绑/清单元格再 `delDataset`；见 `dataset-sidebar-ops-guide.md §5.3` |
-| `matchByName=false`（自检） | 同上 / 用了显示名 | 强制走 §二 resolve |
-| 部分列有数据部分没有 | 个别列 name 写错 | 逐列对照 fieldsKey |
-| fieldsKey 为空 | 未传 `isFront=true` 或 datasetId 错 | 修正后再绑定，禁止用空列表继续 |
-
----
-
-## 五、与现有文档关系
-
-| 文档 | 关系 |
-|------|------|
-| **`add-dataset-registration-guide.md`** | **addDataset 与设计器对齐；fieldsKey 无 `field_` 的根因** |
-| `api-report-build-fast-path.md` | 建表流程 §三/§五 引用本节；保存门禁 |
-| `cross-dataset-filter-guide.md` | leftFilter 的 fieldKey 末段同样必须是 fieldsKey.name |
-| `e10-cli report verify bind` | 保存后一键校验（必跑） |
-| `e10-cli report py validate` | 离线 JSON 形态检查；**线上以本节 + verify_field_bind 为准** |
-
----
-
-## 六、Agent 执行清单（复制即用）
-
-- [ ] `sourceName` 为 `{表单名}(业务模块)`（回显名），不是裸表单名（`build spec` 已自动补后缀）
-- [ ] 本报表**已有同 sourceId 数据集 → 复用**，不重复 `addDataset`
-- [ ] `addDataset` 为 `LOGIC` + `weaver-ebuilder-form-service`（非共享表特例）
-- [ ] `fieldsKey` 业务字段已含 `field_*`（否则先修注册）
-- [ ] `fieldsAndOriginFields?isFront=true` 已拿到非空 `fieldsKey`
-- [ ] 每个需求列：`显示名 → fieldsKey.name` 映射表已打印确认（`build spec` 输出 `fieldBindings`）
-- [ ] **任一无精确命中 → exit 4 时，把 `candidates`/`allFields` 交给用户指定字段，禁止自行猜**
-- [ ] 同 sourceId 多实例时绑的是 LOGIC/`field_*` 那条
-- [ ] `name` ∈ 当前 dataset 的 fieldsKey（勿臆造 / 勿手工补 `field_`）
-- [ ] 保存前 `assert` 全部通过
-- [ ] 保存后 `e10-cli report verify bind` / 等价断言全部通过
-- [ ] 未通过则**不交付**
+# 字段精确绑定（强制 · 禁止匹配失败）
+
+> **事故案例（已验证）**：报表 `AAA`（`1312677851392417792`）保存了 9 个 Field 格，但 `name` / `fieldKey` 末段写成裸雪花 ID `3506271516100878845`，而数据源真实字段名是 `field_3506271516100878845` → **设计器有字段格、取数全部匹配失败（字段获取不上）**。
+> **前置事故（已验证 · `1312765120721813505`）**：Agent 用错 `addDataset`（`type=form` + `sourceGroup=appId`）时，`fieldsKey` **本身只有裸雪花**；用户在设计器手动「+」同表则得到 `field_*`。
+> **遗漏点**：不是写 Field 时忘加前缀，而是 **注册契约与设计器不一致** —— 必先读 **`add-dataset-registration-guide.md`**，把数据集加成 LOGIC + `weaver-ebuilder-form-service`，再绑定。
+> **唯一标准**：`name` / `fieldKey` 末段必须 **精确等于** 当前数据集 `fieldsAndOriginFields.fieldsKey[].name`（以接口回读为准）。
+> **禁止**：注册错了却在 cell 上「手工补 `field_`」；或对正确的 `field_*` fieldsKey 去前缀。
+> **硬目标**：任意 Field 的 `name` **必须**等于该 dataset 的 `fieldsKey[].name`；**零容忍**猜测、截断、错数据集。
+
+---
+
+## 〇、先保证 fieldsKey 带 `field_`（普通应用）
+
+| 检查 | 说明 |
+|------|------|
+| addDataset | 默认 `sourceType=LOGIC` + `sourceGroup=weaver-ebuilder-form-service` |
+| 门禁 | 业务字段若多为裸雪花 → **注册错误**，`delDataset` 重建；见 `add-dataset-registration-guide.md` |
+| 同 sourceId 多实例 | **优先绑**设计器/LOGIC 那条（`field_*`），勿绑旧 form+appId 实例 |
+
+---
+
+## 一、唯一合法字段名来源
+
+```
+GET /api/bs/edc/dataset/fieldsAndOriginFields
+  ?datasetId={datasetId}&hasField=true&isFront=true&reportId={reportId}
+→ data.fieldsKey[]     // 权威列表；isFront=false 常为空，禁止依赖
+```
+
+每个 `fieldsKey` 项的关键属性：
+
+| 属性 | 用途 | 示例 |
+|------|------|------|
+| **`name`** | **写入 Field 的 `name` / fieldKey 末段（唯一正确）** | `field_3506271516100878845`、`create_time` |
+| `text` / `showName` | 仅用于按中文显示名**查找**对应 `name` | `资产类别` |
+| `originName` | 参考，不可直接当 fieldKey 末段（除非与 `name` 相同） | — |
+
+**禁止**从下列来源臆造 `name`：
+
+| 错误来源 | 错误示例 | 后果 |
+|----------|----------|------|
+| 表单字段 ID / 雪花 ID（无 `field_`） | `3506271516100878845` | **取数匹配失败**（本案） |
+| 显示名 | `资产类别` | 设计器/取数均失败 |
+| 截断 / 半截 | `field_5`、`field_3506` | 匹配失败 |
+| 去掉 `field_` 前缀 | 把 `field_xxx` 写成 `xxx` | **取数匹配失败** |
+| 外部字段表 fieldId 未与 fieldsKey 交叉核对 | 形态可能不同 | 须与 fieldsKey.name 对齐后再用 |
+
+---
+
+## 二、绑定算法（强制）
+
+> **⚠️ 2026-09-11 追加门禁（事故：报表 `1313789294296735745`）**：B3 列文案「姓名」，但该表单**没有「姓名」字段**，
+> 旧逻辑静默兜底到系统字段 `name`（真实显示名「标题」）→ 单元格文案与绑定字段语义不符、属性面板回显对不上。
+> **新规则：精确匹配失败必须 `exit 4` 提示用户指定字段，禁止任何自动兜底（尤其禁止回退系统字段）。**
+> 落地实现：构建层 + `e10-cli report build spec` 的**建表前预检**。
+
+对需求中的每一列（显示名 → 数据字段）：
+
+### 2.0 允许的匹配（命中即止，**全为精确匹配**）
+
+| 顺序 | 依据 | 说明 |
+|------|------|------|
+| 1 | `column.fieldName` / `spec.fieldMap[列标题]` | 用户/Agent 显式指定（可为 `field_xxx`、显示名、系统字段名） |
+| 2 | 列标题 === `fieldsKey[].text/showName`（归一化：去空白、全角括号→半角） | 主路径 |
+| 3 | `column.field` === `text/showName` 或 `name` | 兼容旧 spec |
+| 4 | 都不中 | **`unmatched` → exit 4**（附模糊候选供用户挑选） |
+
+**禁止**：包含/被包含（`includes`）等模糊规则自动绑定；**禁止**把 `name`/`id`/`create_time` 等系统字段当作兜底。
+
+### 2.0.1 规则 A · 找不到字段 → **停下让用户指定**（强制 · 2026-09-11）
+
+> **核心**：需求里的字段在当前数据集表单里**找不到**时，**不许猜、不许兜底**，必须停下把候选交给用户。
+
+`resolveFieldBindings()` 的 `unmatched[]` 三种 `reason` 及处置：
+
+| `reason` | 含义 | 退出码 | 处置 |
+|----------|------|--------|------|
+| `no_exact_match` | 列标题在 `fieldsKey.text` 中**无精确命中** | **4** | 把 `candidates` + `allFields` 抛给用户，请其指定字段 |
+| `explicit_not_found` | 显式 `fieldName`/`fieldMap` 指向的字段**不存在** | **4** | 同上（禁止臆造字段名） |
+| `display_mismatch` | 能绑到，但字段**真实显示名 ≠ 列文案**且未确认 | **4** | 用户确认列名有意如此 → `fieldConfirmed` / `--field-confirmed "列标题"` |
+
+**两阶段拦截**（都不建表 / 删未完成表）：
+
+| 阶段 | 时机 | 未通过 |
+|------|------|--------|
+| 预检 | `fieldsBySource`（**建表前**） | **exit 4 · 未创建任何报表** |
+| 复校 | 本表 `addDataset` → `fieldsKey`（落库前） | **exit 4 · 删除本轮未完成报表** |
+
+输出结构（`rule:"A"`）：
+
+```json
+{
+  "action": "confirm_field", "rule": "A", "needConfirm": true, "reportCreated": false,
+  "unmatched": [ { "column": "姓名", "reason": "no_exact_match", "prompt": "…请用户从 allFields/candidates 中指定字段",
+                   "candidates": [ { "name": "field_...", "text": "发展人", "system": false } ] } ],
+  "allFields": [ { "name": "field_...", "text": "发展人", "system": false } ],
+  "next": { "specFields": { "fieldMap": { "<列标题>": "<字段显示名 | field_雪花 | 系统字段名>" } } }
+}
+```
+
+用户指定后复跑：`spec.fieldMap = { "姓名": "发展人" }`（或 `field_xxx`）。
+若列名坚持与字段显示名不同 → 另加 `fieldConfirmed: ["姓名"]` / CLI `--field-confirmed "姓名"`。
+
+**禁止**：
+- 用「最相近的」字段顶上（哪怕语义看似接近）；
+- 回退系统字段（`name`→「标题」是历史事故）；
+- 先带病落库、事后再让用户改。
+
+> 一页速览：。
+
+```javascript
+// 1. 拉权威列表
+const fieldsKey = (await fieldsAndOriginFields(...)).data.fieldsKey;
+
+// 2. 解析（库函数，已含门禁）
+const plan = resolveFieldBindings(fieldsKey, spec.columns, { fieldMap, fieldConfirmed });
+if (!plan.ok) {
+  // exit 4：把每列 candidates 抛给用户，等其指定字段；不要自己猜
+}
+const nf = plan.bindings.find(b => b.index === colIndex).field;
+```
+
+**规则摘要**：
+
+1. **先** `fieldsAndOriginFields`，**再**写任何 Field 单元格
+2. `name` **逐字等于** `fieldsKey[].name`（含 `field_` 前缀；系统字段如 `create_time` 原样）
+3. `fieldKey` = `{datasetId}.{sourceId}.{fieldsKey.name}`，三段齐全
+4. 保存前对**每一个** Field 做 `byName.has(name)`；任一失败 → **中止保存**，禁止带病落库
+
+---
+
+## 三、保存后强制回读校验（交付门禁）
+
+`getReportDevInfo` 后，对每个 `cellType === 'Field'`：
+
+```javascript
+function assertFieldBindExact(devFields, fieldsKey) {
+  const legal = new Set(fieldsKey.map(f => f.name));
+  const fieldCells = devFields.filter(f => f.cellType === 'Field');
+  if (!fieldCells.length) throw new Error('无 Field 单元格');
+  for (const f of fieldCells) {
+    const last = String(f.fieldKey || '').split('.')[2] || '';
+    if (!f.name || !legal.has(f.name)) {
+      throw new Error(`字段匹配失败 name=${f.name} text=${f.text}`);
+    }
+    if (last !== f.name || !legal.has(last)) {
+      throw new Error(`fieldKey 末段不在 fieldsKey: ${f.fieldKey}`);
+    }
+    // 裸雪花：若 fieldsKey 里已有 field_xxx，则禁止用裸名；否则先查 addDataset 是否注册错
+  }
+}
+```
+
+| 检查 | 失败即 FAIL |
+|------|-------------|
+| 每个 Field 的 `name ∈ fieldsKey.name` | ✅ |
+| `fieldKey` 末段 === `name` | ✅ |
+| 普通应用：fieldsKey 业务字段含 `field_*`（注册门禁） | ✅ 见 `add-dataset-registration-guide.md` |
+| Field 数量 ≥ 需求列数 | ✅ |
+| **单元格文案 === 绑定字段真实显示名**（否则须用户确认） | ⚠ `verify bind` 列出 `display_mismatch` |
+| **同 sourceId 只挂 1 个数据集**（否则左侧重复分组） | ⚠ `verify bind` 列出 `duplicate_dataset_mount` |
+
+`e10-cli report verify bind <reportId> [appId] [--strict]`：门禁失败 exit 1；`--strict` 时「待用户确认项」exit 2。
+
+**未通过校验 → 须修正并告知用户**；可与「已交付的设计器链接」并行：先给链接（见 `report-delivery-contract.md` §〇），校验失败再补丁修复，**禁止**为等校验而拖延首轮地址。
+
+---
+
+## 四、故障对照
+
+| 现象 | 根因 | 处理 |
+|------|------|------|
+| 设计器有 Field 格，预览/取数无数据或字段空白 | `name` 为裸 ID，缺 `field_` | 按 fieldsKey.name 重绑并 saveReportDevInfo |
+| **手动加的数据集有 `field_`，API 加的没有** | **addDataset 用了 form+appId，不是设计器 LOGIC** | 按 `add-dataset-registration-guide.md` del 后重建 |
+| **单元格表头文案 ≠ 属性面板字段名**（如「姓名」实为「标题」） | 旧逻辑把无匹配列**兜底到系统字段** | 改为 `exit 4` 让用户指定；存量报表用 `fieldMap`/重绑修复 |
+| **左侧出现重复数据源分组** | 同 sourceId 被重复 `addDataset` 挂载 + 画布游离单元格引用 | 先改绑/清单元格再 `delDataset`；见 `dataset-sidebar-ops-guide.md §5.3` |
+| `matchByName=false`（自检） | 同上 / 用了显示名 | 强制走 §二 resolve |
+| 部分列有数据部分没有 | 个别列 name 写错 | 逐列对照 fieldsKey |
+| fieldsKey 为空 | 未传 `isFront=true` 或 datasetId 错 | 修正后再绑定，禁止用空列表继续 |
+
+---
+
+## 五、与现有文档关系
+
+| 文档 | 关系 |
+|------|------|
+| **`add-dataset-registration-guide.md`** | **addDataset 与设计器对齐；fieldsKey 无 `field_` 的根因** |
+| `api-report-build-fast-path.md` | 建表流程 §三/§五 引用本节；保存门禁 |
+| `cross-dataset-filter-guide.md` | leftFilter 的 fieldKey 末段同样必须是 fieldsKey.name |
+| `e10-cli report verify bind` | 保存后一键校验（必跑） |
+| `e10-cli report py validate` | 离线 JSON 形态检查；**线上以本节 + verify_field_bind 为准** |
+
+---
+
+## 六、Agent 执行清单（复制即用）
+
+- [ ] `sourceName` 为 `{表单名}(业务模块)`（回显名），不是裸表单名（`build spec` 已自动补后缀）
+- [ ] 本报表**已有同 sourceId 数据集 → 复用**，不重复 `addDataset`
+- [ ] `addDataset` 为 `LOGIC` + `weaver-ebuilder-form-service`（非共享表特例）
+- [ ] `fieldsKey` 业务字段已含 `field_*`（否则先修注册）
+- [ ] `fieldsAndOriginFields?isFront=true` 已拿到非空 `fieldsKey`
+- [ ] 每个需求列：`显示名 → fieldsKey.name` 映射表已打印确认（`build spec` 输出 `fieldBindings`）
+- [ ] **任一无精确命中 → exit 4 时，把 `candidates`/`allFields` 交给用户指定字段，禁止自行猜**
+- [ ] 同 sourceId 多实例时绑的是 LOGIC/`field_*` 那条
+- [ ] `name` ∈ 当前 dataset 的 fieldsKey（勿臆造 / 勿手工补 `field_`）
+- [ ] 保存前 `assert` 全部通过
+- [ ] 保存后 `e10-cli report verify bind` / 等价断言全部通过
+- [ ] 未通过则**不交付**

package/skill-docs/references/report/financial-stats-report-guide.md

@@ -1,89 +1,89 @@
-# 同比环比等财务统计表 · 场景 K（SKILL A0.20）
-
-> 案例「同比环比等财务统计表」：年份/月份两级分组 + 销售额，配五类派生指标——
-> ①月环比 ②年同比 ③年内占比 ④年内排名+总排名 ⑤年内累计+总累计。
-
----
-
-## 一、机制定案（源码级事实）
-
-| 事实 | 出处 |
-|---|---|
-| EDC 内置组合公式 `COMB_GROWTH_RATE / COMB_DYNAMIC_RATE / COMB_DIFF / COMB_GRAND_TOTAL`，后端仅生成 `IFERROR+原串` 公式串，**具体算术在 SpreadJS 前端逐实例执行** | knowledge-base §9.3 / report-building-guide §8.2 |
-| 合计/小计**不自动插入**；`SUM(扩展格)` = 对该扩展全部实例求和；公式父格上下文决定分组范围 | knowledge-base §9.3 / crosstab guide |
-| 公式格落库形态：`cellText` 与顶层 `formula` 均**不带前导 `=`**；公式格四件套（BUILD-49） | formula-cell-api-guide |
-
-**结论**：环比/同比/占比/排名/累计的「相对实例引用」靠 SpreadJS 前端逐实例求值 —— 报表侧可做，但
-**跨组引用（同比=上年同月）与排名/累计的层次语义是 FineReport 层次坐标的领地**，EDC 侧等价写法需验证。
-
-## 二、两条实现路径
-
-### 路径一：数据集侧预计算（★ 语义正解 · 推荐 · 与 MEMORY 铁律一致）
-
-比率/派生指标走**数据源侧预计算列**（数据加工 SQL 视图），报表**纯绑字段**——五行指标一次算全，
-格式/空值/排序全可控，不依赖前端公式语义：
-
-```sql
-SELECT
-  年份, 月份, 销售额,
-  销售额 / LAG(销售额) OVER (PARTITION BY 年份 ORDER BY 月份) - 1        AS 月环比,
-  销售额 / LAG(销售额, 12) OVER (ORDER BY 年份, 月份) - 1                AS 年同比,   -- 或按年月对齐
-  销售额 / SUM(销售额) OVER (PARTITION BY 年份)                          AS 年内占比,
-  RANK() OVER (PARTITION BY 年份 ORDER BY 销售额 DESC)                   AS 年内排名,
-  RANK() OVER (ORDER BY 销售额 DESC)                                     AS 总排名,
-  SUM(销售额) OVER (PARTITION BY 年份 ORDER BY 月份)                     AS 年内累计,
-  SUM(销售额) OVER (ORDER BY 年份, 月份)                                 AS 总累计
-FROM 销售明细
-```
-
-报表结构（build spec 直出，无需公式列）：
-
-```json
-{
-  "columns": [
-    { "title": "年份", "field": "年份" },
-    { "title": "月份", "field": "月份" },
-    { "title": "销售额", "field": "销售额", "format": "value" },
-    { "title": "月环比", "field": "月环比", "format": "percent" },
-    { "title": "年同比", "field": "年同比", "format": "percent" },
-    { "title": "占比", "field": "年内占比", "format": "percent" },
-    { "title": "年内排名", "field": "年内排名" },
-    { "title": "总排名", "field": "总排名" },
-    { "title": "年内累计", "field": "年内累计", "format": "value" },
-    { "title": "总累计", "field": "总累计", "format": "value" }
-  ],
-  "layout": { "title": "同比环比等财务统计表", "freezeRows": 1 }
-}
-```
-
-年份分组缩进（年份格纵跨）= 年份 Field Group 扩展 + 月份左父格→年份；纯列表版直接平铺。
-
-### 路径二：报表侧 SpreadJS 公式（能力边界 + 验证捕获法）
-
-| 指标 | 报表侧写法 | 状态 |
-|---|---|---|
-| 占比 | Formula `IFERROR(C3/SUM(C3),0)`（C3=销售额设计格；SUM 引扩展格=组内求和，父格上下文=年份） | 机制已验证方向，**分组作用域已验证** |
-| 环比 | Formula 相对上一实例 `IFERROR((C3-C2)/C2,"--")` 形态（SpreadJS 逐实例偏移） | ⚠️ 验证项（COMB_GROWTH_RATE 证明前端有此能力，**自写串的实例偏移规则待验证**） |
-| 同比 | 跨组相对引用（上年同月 = 偏移 N 实例） | ⚠️ 验证项（层次语义最弱的一环，优先路径一） |
-| 排名 | SpreadJS RANK 或数据集预计算 | ⚠️ 验证项 / 路径一 |
-| 累计 | 逐实例递推累计公式 | ⚠️ 验证项 / 路径一 |
-
-**捕获法（把内置组合公式固化进 CLI 的通道）**：设计器对某格配「环比/占比」内置组合公式 →
-`getReportDevInfo` 回读该格 `cellText`/`formula` 串 → 拿到 COMB_* 展开后的真实公式形态，
-回填本指南后即可在 rebuild 直构里复刻。
-
-## 三、搭建提示语句（路径一 · 推荐）
-
-> 按同比环比财务统计表搭一张报表：年份/月份两级分组，销售额按月汇总；
-> 指标列：月环比 / 年同比 / 年内占比 / 年内排名+总排名 / 年内累计+总累计；
-> **在数据加工 SQL 里用窗口函数预计算这五类指标**（LAG 环比、SUM OVER 占比累计、RANK OVER 排名），
-> 报表纯绑字段（`build spec` 直出，百分比列 format:percent）；
-> 数据源 `<sid 或 SQL 视图>`（appId `<appId>`）；年份格分组缩进、冻结表头；
-> 落库后回读验收：字段绑定与格式、无公式列依赖。
-
-## 四、验证清单
-
-1. 路径一：预计算列在数据集预览有值（空值=首月环比等，SQL 侧 NULL→"--" 或留空）
-2. build spec 回读：列绑定逐一命中、percent 格式 `0.00%`（禁 "common" 短码，BUILD-47）
-3. 路径二（如走）：公式格四件套（BUILD-49）+ `subordination=["",""]` + 渲染形态设计器确认
-4. 排名并列/方向（DESC）、累计首行初值——以 SQL 侧验收为准
+# 同比环比等财务统计表 · 场景 K（SKILL A0.20）
+
+> 案例「同比环比等财务统计表」：年份/月份两级分组 + 销售额，配五类派生指标——
+> ①月环比 ②年同比 ③年内占比 ④年内排名+总排名 ⑤年内累计+总累计。
+
+---
+
+## 一、机制定案（源码级事实）
+
+| 事实 | 出处 |
+|---|---|
+| EDC 内置组合公式 `COMB_GROWTH_RATE / COMB_DYNAMIC_RATE / COMB_DIFF / COMB_GRAND_TOTAL`，后端仅生成 `IFERROR+原串` 公式串，**具体算术在 SpreadJS 前端逐实例执行** | knowledge-base §9.3 / report-building-guide §8.2 |
+| 合计/小计**不自动插入**；`SUM(扩展格)` = 对该扩展全部实例求和；公式父格上下文决定分组范围 | knowledge-base §9.3 / crosstab guide |
+| 公式格落库形态：`cellText` 与顶层 `formula` 均**不带前导 `=`**；公式格四件套（BUILD-49） | formula-cell-api-guide |
+
+**结论**：环比/同比/占比/排名/累计的「相对实例引用」靠 SpreadJS 前端逐实例求值 —— 报表侧可做，但
+**跨组引用（同比=上年同月）与排名/累计的层次语义是 FineReport 层次坐标的领地**，EDC 侧等价写法需验证。
+
+## 二、两条实现路径
+
+### 路径一：数据集侧预计算（★ 语义正解 · 推荐 · 与 MEMORY 铁律一致）
+
+比率/派生指标走**数据源侧预计算列**（数据加工 SQL 视图），报表**纯绑字段**——五行指标一次算全，
+格式/空值/排序全可控，不依赖前端公式语义：
+
+```sql
+SELECT
+  年份, 月份, 销售额,
+  销售额 / LAG(销售额) OVER (PARTITION BY 年份 ORDER BY 月份) - 1        AS 月环比,
+  销售额 / LAG(销售额, 12) OVER (ORDER BY 年份, 月份) - 1                AS 年同比,   -- 或按年月对齐
+  销售额 / SUM(销售额) OVER (PARTITION BY 年份)                          AS 年内占比,
+  RANK() OVER (PARTITION BY 年份 ORDER BY 销售额 DESC)                   AS 年内排名,
+  RANK() OVER (ORDER BY 销售额 DESC)                                     AS 总排名,
+  SUM(销售额) OVER (PARTITION BY 年份 ORDER BY 月份)                     AS 年内累计,
+  SUM(销售额) OVER (ORDER BY 年份, 月份)                                 AS 总累计
+FROM 销售明细
+```
+
+报表结构（build spec 直出，无需公式列）：
+
+```json
+{
+  "columns": [
+    { "title": "年份", "field": "年份" },
+    { "title": "月份", "field": "月份" },
+    { "title": "销售额", "field": "销售额", "format": "value" },
+    { "title": "月环比", "field": "月环比", "format": "percent" },
+    { "title": "年同比", "field": "年同比", "format": "percent" },
+    { "title": "占比", "field": "年内占比", "format": "percent" },
+    { "title": "年内排名", "field": "年内排名" },
+    { "title": "总排名", "field": "总排名" },
+    { "title": "年内累计", "field": "年内累计", "format": "value" },
+    { "title": "总累计", "field": "总累计", "format": "value" }
+  ],
+  "layout": { "title": "同比环比等财务统计表", "freezeRows": 1 }
+}
+```
+
+年份分组缩进（年份格纵跨）= 年份 Field Group 扩展 + 月份左父格→年份；纯列表版直接平铺。
+
+### 路径二：报表侧 SpreadJS 公式（能力边界 + 验证捕获法）
+
+| 指标 | 报表侧写法 | 状态 |
+|---|---|---|
+| 占比 | Formula `IFERROR(C3/SUM(C3),0)`（C3=销售额设计格；SUM 引扩展格=组内求和，父格上下文=年份） | 机制已验证方向，**分组作用域已验证** |
+| 环比 | Formula 相对上一实例 `IFERROR((C3-C2)/C2,"--")` 形态（SpreadJS 逐实例偏移） | ⚠️ 验证项（COMB_GROWTH_RATE 证明前端有此能力，**自写串的实例偏移规则待验证**） |
+| 同比 | 跨组相对引用（上年同月 = 偏移 N 实例） | ⚠️ 验证项（层次语义最弱的一环，优先路径一） |
+| 排名 | SpreadJS RANK 或数据集预计算 | ⚠️ 验证项 / 路径一 |
+| 累计 | 逐实例递推累计公式 | ⚠️ 验证项 / 路径一 |
+
+**捕获法（把内置组合公式固化进 CLI 的通道）**：设计器对某格配「环比/占比」内置组合公式 →
+`getReportDevInfo` 回读该格 `cellText`/`formula` 串 → 拿到 COMB_* 展开后的真实公式形态，
+回填本指南后即可在 rebuild 直构里复刻。
+
+## 三、搭建提示语句（路径一 · 推荐）
+
+> 按同比环比财务统计表搭一张报表：年份/月份两级分组，销售额按月汇总；
+> 指标列：月环比 / 年同比 / 年内占比 / 年内排名+总排名 / 年内累计+总累计；
+> **在数据加工 SQL 里用窗口函数预计算这五类指标**（LAG 环比、SUM OVER 占比累计、RANK OVER 排名），
+> 报表纯绑字段（`build spec` 直出，百分比列 format:percent）；
+> 数据源 `<sid 或 SQL 视图>`（appId `<appId>`）；年份格分组缩进、冻结表头；
+> 落库后回读验收：字段绑定与格式、无公式列依赖。
+
+## 四、验证清单
+
+1. 路径一：预计算列在数据集预览有值（空值=首月环比等，SQL 侧 NULL→"--" 或留空）
+2. build spec 回读：列绑定逐一命中、percent 格式 `0.00%`（禁 "common" 短码，BUILD-47）
+3. 路径二（如走）：公式格四件套（BUILD-49）+ `subordination=["",""]` + 渲染形态设计器确认
+4. 排名并列/方向（DESC）、累计首行初值——以 SQL 侧验收为准