weaver-e10-builder 1.6.9 → 1.6.11

package/skill-docs/references/report/failure-cleanup-and-nonblocking-guide.md

@@ -0,0 +1,183 @@
+# 失败清理与非阻塞执行（强制）
+
+> **适用**：API/脚本建表、改查询、改布局等全过程。
+> **目标**：① 失败/中止不留下空壳报表；② 单点失败不卡死整条流水线。
+
+---
+
+## 一、空壳报表必须删除（强制）
+
+### 1.1 何谓空壳 / 废壳
+
+| 情形 | 判定 |
+|------|------|
+| 已 `baseInfo` 建壳，但 **`saveReportDevInfo` 未成功** 或 fields 为空 | **空壳** |
+| 临时名 `__build_*` / `__probe_*` / `__bench_*` 且任务失败或中止 | **废壳** |
+| 同任务多次失败留下的多个半成品 reportId | **废壳（全部清）** |
+| 布局已成功落库、仅查询条件等附属能力失败 | **不是空壳** → **保留**报表，只提示附属失败 |
+
+### 1.2 何时必须删
+
+出现以下**任一**情况，在收尾或换路径前 **立刻**删除（进回收站即可）：
+
+1. 命令/脚本 **失败**（exit ≠ 0、save 500、抛错未交付可用表）
+2. 用户 **中止** / Agent 放弃本轮建表
+3. 决定 **删壳重建**（新 reportId）之前，旧失败壳必须先删
+4. 探测用临时壳（`__probe_*`）用完必须删
+
+**优先 CLI**：
+
+```bash
+e10-cli report cleanup shells --app-id <appId> --report-id <reportId>
+# 或临时名前缀：
+e10-cli report cleanup shells --app-id <appId> --prefix __build_
+```
+
+等价 API：
+
+```
+POST 或 GET /api/bs/edc/report/deleteReport
+  id={reportId}   # 可逗号分隔批量
+  + Header ebBusinessId={appId}
+```
+
+见 `report-lifecycle-api-guide.md` §删除。
+
+### 1.3 执行纪律
+
+| 规则 | 说明 |
+|------|------|
+| **跟踪 reportId** | 建壳成功后立刻记下 `reportId`；`finally`/catch 中若未交付成功布局 → 删除 |
+| **禁止留页面垃圾** | 失败后列表页不应残留「点进去空白/无字段」的报表 |
+| **告知用户** | 若已删：一句话说明「已删除失败空壳 {name/id}」；若附属失败保留主表：说明「主表已交，XX 未配上请确认」 |
+| **禁止** | 失败后不管、叠多个 `__build_*`；或把空壳改成目标名交付 |
+
+```javascript
+let reportId = null;
+let layoutOk = false;
+try {
+  reportId = await createShell(tempName);
+  // ... addDataset / saveReportDevInfo ...
+  layoutOk = true;
+  await rename(reportId, targetName);
+} catch (e) {
+  // 提示用户，勿死循环
+} finally {
+  if (reportId && !layoutOk) {
+    await deleteReport(reportId); // 空壳必删
+  }
+}
+```
+
+---
+
+## 二、单壳搭建（强制 · 一次任务只允许 1 个报表壳）
+
+> **用户强制要求（2026-09-14）**：搭建报表**不要搭多个模板空壳报表**。
+> 现象：一次搭建里为每个变体/每次试验各建一个壳（`__probe_*`、`__regtest_*`、`__build_a/__build_b/...`），
+> 结果应用列表页堆一堆半成品，既难维护又违反交付契约。
+
+### 2.1 铁律
+
+| # | 规则 |
+|---|------|
+| 1 | **一次搭建任务从头到尾只建 1 个报表壳**，命名 `__build_<业务>_<时间戳>`，全程复用（失败重试、变体试验、布局迭代都改同一个壳） |
+| 2 | **禁止**为「试 A 方案 / 试 B 方案」各建一个壳。变体 = 同一个壳内改单元格后重新 `saveReportDevInfo` |
+| 3 | **禁止**为探针建报表壳。只读回读即可满足 90% 探针需求：<br>`getReportDevInfo.fields`（结构/字段/父格）、`GET /api/bs/edc/dataset/list?reportId=`（数据集）、`fieldsAndOriginFields`（字段映射）、`getQueryItemNew`（查询条件） |
+| 4 | 仅在「必须验证某个**写**接口行为」时才允许临时壳，命名 `__probe_*`，且**同一时刻最多 1 个、用完立即删** |
+| 5 | 主路径成功 → **立刻把唯一那个壳改名为目标名**并交付；主路径失败 → 删掉它（见 §一），**不留待下次** |
+| 6 | 交付时向用户交代的 reportId 清单必须**恰好 1 个**（最终表） |
+
+### 2.2 收尾自查（只读，不改任何东西）
+
+```bash
+# 全应用空壳体检：列出每张报表的 fields 数，标出 fields=0 的空壳
+e10-cli report cleanup shells --app-id <appId> --list
+
+# 确认没有遗留的建表壳
+e10-cli report cleanup shells --app-id <appId> --prefix __build_ --dry-run
+
+# 确认没有遗留的探针壳
+e10-cli report cleanup shells --app-id <appId> --prefix __probe_ --dry-run
+```
+
+`--list` / `--dry-run` 为**只读**模式，只输出 JSON 结论（`verdict: ✅ 无空壳报表`），不会删除任何报表。
+
+### 2.3 报告壳 ≠ 数据集
+
+「空壳报表」是**报表级**残留；报表内**挂错/多余的 dataset 条目**同样算残留，须按 §四清理。
+
+---
+
+## 三、报表内多余数据集清理（强制）
+
+一次 `addDataset` 失败重试、或注册形态返工，很容易在同一张报表上**挂多套数据集**（设计器左侧出现重复数据源）。判定与清理：
+
+| 步骤 | 做法 |
+|------|------|
+| ① 数引用 | `getReportDevInfo` → 按 `fields[].dataSetId` 分组计数，**计数 = 0 的即为残留** |
+| ② 占用检查 | `GET /api/bs/edc/dataset/checkDataSetUsed?datasetId=<dsId>&reportId=<rid>`，`data=false` = 安全 |
+| ③ 删除 | `POST /api/bs/edc/report/delDataset`，**multipart 参数是 `reportId` + `sourceIds`**，其中 **`sourceIds` 传的值是 `datasetId`（不是 sourceId！）** |
+| ④ 豁免 | 系统默认数据集 `dataUpdateTime` / `数据更新时间` **禁止删除** |
+| ⑤ 回归 | 删完再跑 `e10-cli report verify all <reportId> <appId>`，确认 `fields` 数不变、绑定 PASS |
+
+> ⚠️ 常见坑：`delDataset` 用 `datasetId` / `id` / `sheetId` 作参数名一律 **400 Bad Request**；正确键名只有 `sourceIds`。
+
+---
+
+## 四、单点失败不卡死（强制 · 非阻塞）
+
+### 4.1 原则
+
+| 能力分层 | 失败时 |
+|----------|--------|
+| **主路径**（找表、建壳、绑数据集、布局 save） | 失败 → 清理空壳 → **提示用户** → 可问清后重试；**禁止**同点无限重试 |
+| **附属路径**（查询条件、权限、快照、预聚合、HTML 手册、视觉核对） | 失败 → **提示用户自行确认/可后补** → **继续其它步骤** → 交付主成果 → **末尾再尝试自动修复 1 次** |
+
+**禁止**：在 `saveQueryItem` / 某次 options / 某次 verify 上连试 5～10 轮导致整任务卡死。
+
+### 4.2 重试上限
+
+| 类型 | 上限 | 之后 |
+|------|------|------|
+| 同一 API/同一步 | **1 次重试**（共 2 次尝试） | 记入「待用户确认 / 待收尾补丁」清单，**跳过** |
+| 找表探测 | 见 `app-datasource-lookup-guide.md` §六预算 | **打断询问** |
+| 布局 save | 1 次修正后仍失败 | 删壳，提示用户，停止建表 |
+
+### 4.3 提示话术（简短）
+
+附属失败示例：
+
+> 查询条件写入失败（`saveQueryItem` 返回 500/超时）。报表主体已保存，请你在设计器「查询设置」中确认或告知正确条件字段；我先继续其它配置，最后再自动补试一次。
+
+主路径失败示例：
+
+> 布局保存失败，已删除空壳报表 `{临时名}`（`{reportId}`）。请确认应用/数据源是否正确，或提供可用的 sourceId 后我再重建。
+
+### 4.4 推荐流水线顺序
+
+```
+1. 主路径：找表 → 建壳 → 布局落库 → 【成功则立刻交设计器地址】
+2. 附属：查询条件 / 权限 / …（任一步失败 → 提示 + 跳过）
+3. 收尾：对「跳过清单」各自动补试 ≤1 次；仍失败 → 汇总给用户，不阻塞结束
+4. finally：若主路径未成功 → deleteReport 空壳
+```
+
+### 4.5 与查询条件 500
+
+见 `query-condition-api-guide.md` §二点五：先按调用形态自检 **1 次**；仍失败 → **提示用户 + 继续其它工作**，禁止卡在 saveQueryItem。
+
+---
+
+## 五、与现有文档
+
+| 文档 | 关系 |
+|------|------|
+| `api-report-build-fast-path.md` | 建表纪律引用本节 |
+| `report-delivery-contract.md` | 主路径成功才交链接；附属失败不挡交付 |
+| `report-lifecycle-api-guide.md` | deleteReport |
+| `app-datasource-lookup-guide.md` §六 | 找表预算与打断 |
+| `query-condition-api-guide.md` §二点五 | 查询 500 不卡死 |
+| `targeted-fix-guide.md` | 定点改；失败同样清理废壳 |
+| `add-dataset-registration-guide.md` | §三「报表内多余数据集清理」的注册形态背景 |
+| `report-data-model.md` | 数据集 / 单元格 `dataSetId` 引用模型 |

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` 提示用户指定字段，禁止任何自动兜底（尤其禁止回退系统字段）。**
-> 落地实现：`spec_lib.resolveFieldBindings()` + `e10-cli report build` 的**建表前预检**。
-
-对需求中的每一列（显示名 → 数据字段）：
-
-### 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`→「标题」是历史事故）；
-- 先带病落库、事后再让用户改。
-
-> 一页速览：`e10-cli report --help`。
-
-```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 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` 全部通过
-- [ ] 保存后 `verify_field_bind.js` / 等价断言全部通过
-- [ ] 未通过则**不交付**
+# 字段精确绑定（强制 · 禁止匹配失败）
+
+> **事故案例（已验证）**：报表 `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` / 等价断言全部通过
+- [ ] 未通过则**不交付**