weaver-e10-builder 1.6.9 → 1.6.11

package/skill-docs/references/report/dataset-sidebar-ops-guide.md

@@ -3,7 +3,7 @@
 > **入口**：报表设计器左侧数据集标题 `…` 菜单
 > **页面例**：`/sp/edc/report/designer/{reportId}`
 > **CLI**：`e10-cli report dataset rename|agg|sort|replace|delete|check-used|preview`
-> **鉴权**：e10-login 三项头（`api-auth-headers.md`）
+> **鉴权**：e10-cli auth 三项头（`api-auth-headers.md`）
 
 ---
 
@@ -59,13 +59,13 @@ e10-cli report dataset rename --dataset-id <id> --name "轻资产主表" [--name
 
 ```json
 [
- {
- "fieldId": "{datasetId}.{tableId}.{fieldName}",
- "countType": "sum",
- "showName": "库存合计",
- "fieldName": "s_sum_field_xxx"
- },
- { "groupBy": "{datasetId}.{tableId}.{fieldName}" }
+  {
+    "fieldId": "{datasetId}.{tableId}.{fieldName}",
+    "countType": "sum",
+    "showName": "库存合计",
+    "fieldName": "s_sum_field_xxx"
+  },
+  { "groupBy": "{datasetId}.{tableId}.{fieldName}" }
 ]
 ```
 
@@ -108,8 +108,8 @@ e10-cli report dataset agg clear --dataset-id <id>
 
 ```json
 [
- { "fieldId": "{datasetId}.{tableId}.{name}", "orderType": "asc" },
- { "fieldId": "{datasetId}.{tableId}.{name2}", "orderType": "desc" }
+  { "fieldId": "{datasetId}.{tableId}.{name}", "orderType": "asc" },
+  { "fieldId": "{datasetId}.{tableId}.{name2}", "orderType": "desc" }
 ]
 ```
 
@@ -132,20 +132,20 @@ Content-Type: application/json
 
 ```json
 {
- "reportId": 1313049481975267329,
- "builtinId": 旧datasetId,
- "name": "新数据源显示名",
- "sourceType": "LOGIC",
- "sourceId": "新表单sourceId",
- "sourceGroup": "weaver-ebuilder-form-service",
- "appid": "<appId>",
- "fieldMap": [
- {
- "builtinField": "旧字段leaf或度量别名",
- "replaceField": "新字段name",
- "replaceFieldName": "新显示名"
- }
- ]
+  "reportId": 1313049481975267329,
+  "builtinId": 旧datasetId,
+  "name": "新数据源显示名",
+  "sourceType": "LOGIC",
+  "sourceId": "新表单sourceId",
+  "sourceGroup": "weaver-ebuilder-form-service",
+  "appid": "<appId>",
+  "fieldMap": [
+    {
+      "builtinField": "旧字段leaf或度量别名",
+      "replaceField": "新字段name",
+      "replaceFieldName": "新显示名"
+    }
+  ]
 }
 ```
 
@@ -159,6 +159,40 @@ e10-cli report dataset replace --file replace-body.json
 
 替换后须用新 id 再 `fieldsAndOriginFields` / 必要时 remap 单元格 `dataSetId`/`fieldKey`。
 
+### 4.1 ★ replaceDataset 的「原地换型」用法（复制 500 的正解 · 2026-09-15 实证）
+
+**场景**：报表「复制」报 500「报表内部错误」→ 根因是数据集 `type` 为大写 `LOGIC`
+（设计器/手动建表写小写 `logic`）。此时**用 `replaceDataset` 指向同一 `sourceId`** 即可原地换型：
+
+```json
+{
+  "reportId": "<rid>", "builtinId": "<旧 datasetId>",
+  "name": "<原显示名>", "sourceType": "logic",
+  "sourceId": "<原 sourceId>", "sourceGroup": "weaver-ebuilder-form-service",
+  "appid": "<appId>",
+  "fieldMap": [ { "builtinField": "field_x", "replaceField": "field_x", "replaceFieldName": "" } ]
+}
+```
+
+- `fieldMap` = 旧字段名 → 同名字段（同源换型时即自映射），逐条来自旧数据集的 `fieldsKey`。
+- **验证服务端会自动把单元格的 `dataSetId` / `fieldKey` 重映射到新数据集**（案例：33 格报表换型后
+  格数/类型/公式/父格/合并 完全一致）→ 这两项**不需要**手工 remap。
+- 🔴 **但「零损失」是错的（2026-09-16 更正，注意点 BUILD-31）**：服务端重建绑定时还会**抹掉/降级**一批
+  **不在结构骨架里**的属性，`verify contract` / `dump cells` 全绿也查不出来：
+  | 键 | 后果 |
+  |---|---|
+  | `text`（**字段显示名**） | **被清空** → 设计器里字段格没有内容可显示 ⇒ **整行字段格看起来是空的**（用户报「字段值都不展示」） |
+  | `allNeedFields` | 被清空（该格的取数字段清单） |
+  | `tableName` | 从 `采招-招标项目(业务模块)` 降级成**裸雪花号** `865889931247566866` |
+  | `openType`（Const 格） | 被清空 |
+  ⇒ 换数据集后**必须补跑** `e10-cli report fix field-binding --report-id <rid> --app-id <appId> --apply` 才算收工。
+  ⚠ 验证心法：**换绑定的保真校验要逐属性 diff**（拿换之前的 `getReportDevInfo.fields` 全量快照对比），
+  只比「格数/cellType/公式/父格」会漏掉整类损伤 —— 本包在 BUILD-27（把复制 500 错归给 groupId）上已经犯过同一个错。
+- 幂等封装：**`e10-cli report dataset heal --report-id <rid> --app-id <appId> [--purge] [--apply]`**
+  （默认 dry-run；`--purge` 顺带删除 `sourceId` 为空的脏数据集；落库后回读 + 提示跑 `copy-health`）。
+  **跑完后接 `fix field-binding`（上表四项）。**
+- ⚠ 共享表应用里数据集 `appId` ≠ 报表 `appId` **属正常**（指向表单归属应用），不要当脏数据删。
+
 ---
 
 ## 五、移除（删除数据集）
@@ -197,10 +231,17 @@ e10-cli report dataset delete --report-id <rid> --dataset-id <did> [--force]
 
 | 层 | 现象 | 定位接口 |
 |---|---|---|
-| **① 报表挂载了重复数据集** | `dataset/list` 返回 **2 条同 `sourceId`、同 `name`** 的数据集记录 | `GET /api/bs/edc/dataset/list?hasField=true&reportId=` |
+| **① 报表挂载了重复数据集** | `dataset/list` 返回 **2 条同 `sourceId`** 的数据集记录（`name` 可能相同、也可能一条带后缀一条不带） | `GET /api/bs/edc/dataset/list?hasField=true&reportId=` |
 | **② 画布存在游离单元格** | 某单元格 `dataSetId` 指向第二个数据集，常在**另一张 sheet 或表格远端的孤立格** | 遍历 workbook 全部 sheet 的 `dataTable`，按 `cellType.dataSetId` 统计 |
+| **③ 数据集 `name` 被脚本写进了类型后缀** | 左侧显示 **`采购入库(业务模块)(业务模块)`** 双后缀（看起来像「两条同名分组」） | 读 `dataset/list[].name`：带后缀的那条就是脏值 → `fix dataset-name`（注意点 **BUILD-36**）。**先看后修**：`e10-cli report dataset list --report-id <rid> --app-id <appId>` 现在会逐行**预演**「面板显示名」并给脏名标 ⚠ |
+| **④ 数据集 `name` 被写成裸雪花号**（建表把 `sourceId` 当名字传） | 左侧显示 **`865889931247566866(业务模块)`**（一串数字 + 类型标签），而同行 `originalName` 是可读名 `采招-招标项目` | `dataset list` 标 ⚠「name 是裸雪花号」并打出「应为 `采招-招标项目(业务模块)`」→ `fix dataset-name` 按 `originalName` 还原（注意点 **BUILD-37**）。⛔ 不阻断「复制」 |
 
 > **关键陷阱**：游离单元格**不一定在 Sheet1**。本例游标藏在 **Sheet2 的 B3**（`sheetIndex:1, x:2, y:1`），只扫 Sheet1 会漏诊。**必须遍历全部 sheet**。
+>
+> ⚠️ **先分诊再动手（2026-09-16 补充，注意点 BUILD-35）**：`dataset/list?hasField=true&reportId=` 返回**两条**并不等于重复挂载。
+> **每张报表天然就有两条**：主业务数据集（`type=logic`/`form`）+ 系统字段数据集 `dataUpdateTime`（`type=systemField`、0 格引用、平台自动附带）。
+> 判据只看一条：**两条记录的 `sourceId` 是否相同** —— 相同 = 真重复（按本节清）；不同 = 正常共存（**勿动**）。
+> `dataUpdateTime` / `数据更新时间` 是**禁止删除**豁免项，删了「数据更新时间」单元格类型就没了。
 
 **左侧树显示名的权威来源**：`GET /api/bs/edc/dataset/listWithPageReport?hasField=true&reportId=` → 返回**源级**记录（`id` 是 **sourceId 而非 datasetId**），其 `name`/`tableText` 决定分组显示名。
 - 正常：`name = '事项清单(uf_ydsxqd_1)'`（业务模块名 + 物理表名）
@@ -219,22 +260,22 @@ e10-cli report dataset delete --report-id <rid> --dataset-id <did> [--force]
 ```python
 # 1) 先摘除游标：遍历 workbook 全 sheet，删除/改绑指向重复数据集的单元格
 for sheet_name, sh in wb["sheets"].items():
- dt = (sh.get("data") or {}).get("dataTable") or {}
- for ri in list(dt):
- for ci in list(dt[ri]):
- ct = ((dt[ri][ci].get("style") or {}).get("cellType")) or {}
- if ct.get("dataSetId") == DUP_DS:
- del dt[ri][ci] # 或改绑 KEEP_DS
+    dt = (sh.get("data") or {}).get("dataTable") or {}
+    for ri in list(dt):
+        for ci in list(dt[ri]):
+            ct = ((dt[ri][ci].get("style") or {}).get("cellType")) or {}
+            if ct.get("dataSetId") == DUP_DS:
+                del dt[ri][ci]            # 或改绑 KEEP_DS
 
 # 2) saveReportDevInfo 落库（提交 workbook，gzip+base64，带 designKey）
 
 # 3) 再调用 delDataset 删除重复数据集
-POST /api/bs/edc/report/delDataset form: reportId=<rid>&sourceIds=<dupDatasetId>
+POST /api/bs/edc/report/delDataset   form: reportId=<rid>&sourceIds=<dupDatasetId>
 
 # 4) 校验
-dataset/list → 只剩 1 条同源数据集
+dataset/list            → 只剩 1 条同源数据集
 getReportDevInfo.fields → 无任何字段引用 DUP_DS（注意看 sheetIndex 分布）
-列表/面板 → 顶层分组只剩 1 个
+列表/面板               → 顶层分组只剩 1 个
 ```
 
 > **顺序原因**：被引用时 `delDataset` 会被服务端拒绝（引用检查）。必须先清画布再删数据集。

package/skill-docs/references/report/dataset-table-field-contract-guide.md

@@ -11,17 +11,17 @@
 > | `fieldName` | 字段技术名 `field_<id>` | 同上 |
 > | `fieldText` | 字段显示名 | 同上 |
 >
-> 证据（同一报表内对照组）：
+> 验证证据（同一报表内对照组）：
 > - Agent 建的 10 个 Field：`tableName=None`（异常）
 > - 用户在设计器手动绑的 2 个 Field：`tableName='党员发展(业务模块)'`（正确）
 > - 平台原生报表 `772466395278696448`：`tableName='轻资产处理(表单)'`，9/10 非空
 > - 平台原生报表 `799097275701215232`：16/16 非空
 >
 > **根因不是接口、不是服务端** —— 是建表脚本写入的 `cellType` 本身就缺字段。
-> 旧包 `references/data_source_rule.md` §2.2/§2.5 与 `e10-cli report verify bind` 有完整契约，
+>
 > 重构时**未迁移**，导致知识随重构丢失。
 >
-> **⚠️ 2026-09-11 二次实证校正（重要）**：修复该报表时，从设计器实际请求解出真实 workbook，
+> **⚠️ 2026-09-11 二次实证校正（重要）**：修复该报表时，从设计器接口返回解出真实 workbook，
 > 对照用户手绑字段发现 —— **`fieldId` / `fieldName` / `fieldText` / `dateTimeProp` 在服务端落库的
 > cellType 里同样是缺失的**（用户手绑字段也没有），它们由设计器**运行时装配**，不属落库契约。
 > **真正需要落库、且能对照验证的只有 `tableName` 一项。** 上表把三件套标为「必需」属过度设计，
@@ -69,7 +69,7 @@
 | `nameIndex` | ✅ | 底层 FORM sourceId | **不是字段 id** |
 | `text` | ✅ | 字段显示名 | |
 | `dataSetId` | ✅ | 报表内部注册 id | `dataset/list` 的 `id` |
-| **`tableName`** | ○ 建议写 | **`数据集名(业务模块)`** | 单元格级字段归属标记；**非**面板显示名来源（见开头三次校正） |
+| **`tableName`** | ○ 建议写 | **`数据集名(业务模块)`** | 单元格级字段归属标记；**非**面板显示名来源（见开头三次校正）。⚠️ **只有单元格**要带后缀；数据集 `name` 必须裸名（§二 更正框） |
 | `fieldId` | ○ 建议写 | 字段雪花 id | 落库本不含；设计器运行时装配，写入幂等无害 |
 | `fieldName` | ○ 建议写 | `field_<雪花>` | 同上 |
 | `fieldText` | ○ 建议写 | 字段显示名 | 同上 |
@@ -85,17 +85,42 @@
 |----------|------------------------------|------|------|
 | **A（默认）** | `LOGIC` + `weaver-ebuilder-form-service` | **`(业务模块)`** | 普通应用表单 |
 | **B（共享表）** | `form` + `<appId>` | **`(表单)`** | `xxx-共享表` 类应用 |
-| **C（数据加工 SQL 视图）** | `ETEAMS` + `sql` | **无后缀**（= `datasetName` 原样） | 数据集来自「数据加工」SQL 视图 |
+| **C（数据加工 SQL 视图）** | `eteams`（**小写 type**） + `sql` | **`(数据加工)`** | 数据集来自「数据加工」SQL 视图 |
 
-> **形态 C （2026-09-14 · 报表 `1314970921403138199`）**：数据集「考勤汇总报表(优化)」
-> （`sourceType=ETEAMS` / `sourceGroup=sql`）→ 设计器手绑单元格 `tableName` = **`考勤汇总报表(优化)`**，
-> 且 `dataset/fieldsAndOriginFields.fieldsKey[].datasetName` / `tableText` 也都是这个裸名。
+> **⚠️⚠️ 形态 C 更正（2026-10-09 实证 · 应用 `1323883777452843010` 全量 8 表比对）**：
+> 此前本表把形态 C 写成「无后缀」是**错的** —— 验证「数据加工」数据源的单元格 `tableName`
+> **带 `(数据加工)` 后缀**（= `数据集名(数据加工)`）。
+>
+> | 落库形态（`dataset/list`） | 单元格 `tableName` | 判定 |
+> |---|---|---|
+> | `type=eteams`（小写）+ `sourceGroup=sql` | **`学院表(数据加工)`** | ✅ 数据加工 |
+> | `type=ETEAMS`（大写）+ `sourceGroup=-98` | `学院表(业务模块)` | ❌ 被当成业务模块 |
+>
+> 验证对照（同应用）：`eteams`/`sql` 的 5 张表（`培训报表`/`汇总表`/`test`/`12`/新建表）
+> 单元格全是 `X(数据加工)`；`ETEAMS`/`-98` 的 2 张表（`各学院专业人数统计` / `…-chl`）单元格全是 `X(业务模块)`。
+> **口径分水岭就是 `type` 大小写 + `sourceGroup`**，与 `LOGIC`(BUILD-29) 同理 —— 脚本注册
+> 「数据加工」SQL 视图时 `addDataset.sourceType` **必须传小写 `eteams`**、`sourceGroup='sql'`。
+>
 > **判断口径（三条一致即可定值）**：① 设计器里已有手绑单元格 → 用它的 `tableName`；
-> ② 否则用 `fieldsKey[].datasetName`；③ 都没有才按 `dataset/list[].name`。
+> ② 否则 `数据集名 + (数据加工)`；③ 都没有才按 `dataset/list[].name`。
 
 > 与 `add-dataset-registration-guide.md` §一 的两种注册形态一一对应。
 > **禁止**给共享表硬套 `(业务模块)` —— 后缀必须与注册形态一致。
 
+> ⚠️⚠️ **本节只适用于「单元格 `tableName`」（2026-09-16 更正 · 注意点 BUILD-36）**：
+> **数据集自己的 `name`（= `addDataset.sourceName`）绝不能带这个后缀。**
+> 左侧「数据集」面板显示名 = `数据源名 + (添加类型标签)`，那个标签由**平台按数据源的「添加类型」自动拼接**：
+> `业务模块 / 表单 / 数据加工 / 外部数据源 / 内置数据集 / 数据集合 / 系统字段 …`，**不是固定写死的**。
+> 脚本若自行拼一遍 → 面板显示 **`采购入库(业务模块)(业务模块)`**（双后缀）。
+>
+> | 对象 | 后缀 | 谁负责 |
+> |---|---|---|
+> | 单元格 `tableName` | ✅ 要（`X(业务模块)`） | `build_from_spec.resolveTableName()` / `fix field-binding`（写文件时） |
+> | 数据集 `name` / `sourceName` | ❌ 不要（裸名 `X`） | 构建层 / `fix dataset-name`（写 `edc_dataset_dev.name` 时） |
+>
+> 验证对照（报表 `1315265856934289408`，同 sourceId 两条）：脚本建 `name="采购入库(业务模块)"` → 双后缀 ❌；
+> 设计器「+」建 `name="采购入库"` → `采购入库(业务模块)` ✅。（`originalName` 两者都是 `采购入库`）
+
 **取值优先级**（服务端常不回传，必须脚本兜底）：
 
 1. `fieldsKey[].tableName`（服务端有则用）
@@ -103,7 +128,7 @@
 3. `datasetLabel + datasetSuffix(sourceType)` ← **兜底，保证恒非空**
 
 `datasetLabel` 来自 `dataset/list` 的 `name`（即 `addDataset` 的 `sourceName`），
-由 `spec_lib.resolveDataset()` 回传、`fieldsKeyOf()` 注入到每个字段。
+由 构建层 回传、`fieldsKeyOf()` 注入到每个字段。
 
 ---
 
@@ -115,7 +140,7 @@
 | `fieldName` | `fieldsKey[].name` |
 | `fieldText` | `fieldsKey[].text`（→ `showName` → 列标题） |
 
-`fieldsKey[]` 可用键（`fieldsAndOriginFields?isFront=true`）：
+`fieldsKey[]` 验证可用键（`fieldsAndOriginFields?isFront=true`）：
 
 ```
 name / text / originName / fieldType / formatType
@@ -123,7 +148,7 @@ dataSetId / nameIndex / tableId / tableText / datasetName
 config{ fieldId, formId, sformId, formName, componentKey, ... }
 ```
 
-### 三点五、两接口返回格式对照（**以 `fieldsAndOriginFields` 为准** · 2026-09-11 ）
+### 三点五、两接口返回格式对照（**以 `fieldsAndOriginFields` 为准** · 2026-09-11 验证）
 
 同一表单 `sourceId=753880319550169088` 双接口 30/30 逐条比对：
 
@@ -140,7 +165,7 @@ config{ fieldId, formId, sformId, formName, componentKey, ... }
 **统一归一化入口**：`spec_lib.normalizeFieldList(payload, { datasetId })`
 
 ```javascript
-const { fields } = normalizeFieldList(res, { datasetId }); // 冒号：任一接口 → 字段元素数组
+const { fields } = normalizeFieldList(res, { datasetId });   // 冒号：任一接口 → 字段元素数组
 ```
 
 - 抹平「裸数组 / `{fieldsKey}` 对象 / `{fields}` 对象」三种信封 → 一律返回**字段元素数组**；
@@ -161,8 +186,8 @@ const { fields } = normalizeFieldList(res, { datasetId }); // 冒号：任一接
 const fieldCells = fields.filter((f) => f.cellType === 'Field');
 const missingTableName = fieldCells.filter((f) => !f.tableName);
 if (missingTableName.length) {
- console.error(`WARN ${missingTableName.length}/${fieldCells.length} 个 Field 单元格缺 tableName`);
- process.exitCode = 2; // 非零退出，提示需修正
+  console.error(`WARN ${missingTableName.length}/${fieldCells.length} 个 Field 单元格缺 tableName`);
+  process.exitCode = 2;   // 非零退出，提示需修正
 }
 ```
 
@@ -180,13 +205,13 @@ if (missingTableName.length) {
 ## 四点五、修复存量报表（tableName 缺失）— 最小侵入路径 ✅ 已验证
 
 > **场景**：报表已落库，但 `tableName` 缺失（旧脚本产物）。
-> **报表 `1313789294296735745` 修复成功（HTTP 200 + 双向验证通过）。**
+> **报表 `1313789294296735745` 验证修复成功（HTTP 200 + 双向验证通过）。**
 
 **关键接口认知（务必先读）**
 
 | 接口 | 提交物 | 易错点 |
 |------|--------|--------|
-| `saveReportDevInfo` | **`workbook`**（gzip + base64） | ❌ 用 `fields=<json>` 提交 → **400 Bad Request** |
+| `saveReportDevInfo` | **`workbook`** | ❌ 用 `fields=<json>` 提交 → **400 Bad Request**。⚠️ 载荷形态**因环境而异**：多数环境 `gzip+base64`，**部分自建环境只认明文 JSON**（传 gzip+b64 → 整表 500「报表内部错误」）。脚本走 构建层 自适应（先 gzip+b64，非 200 回退明文）—— 见 `report-internal-error-guide.md` §三.0 / 注意点 **BUILD-39** |
 | `getReportDevInfo` | 返回 `fields[]` | ⚠️ 只有 `cellType: "Field"/"Const"` **类型标记**，**不含字段绑定明细**；明细只在 workbook 里 |
 
 **`saveReportDevInfo` 完整表单（7 字段，multipart）**
@@ -195,7 +220,7 @@ if (missingTableName.length) {
 groupId / appId / reportId / name / nameLabelId / designKey / workbook
 ```
 - `designKey` 是**乐观锁**，必须取线上当前值（`getReportDevInfo.data.designKey`），否则拒写
-- `workbook` = `base64(gzip(json.dumps(workbook), mtime=0))`
+- `workbook`（默认口径）= `base64(gzip(json.dumps(workbook), mtime=0))`；**部分环境需明文 JSON**（见上）
 
 **获取「当前真实 workbook」（唯一可靠来源）**
 
@@ -210,17 +235,17 @@ groupId / appId / reportId / name / nameLabelId / designKey / workbook
 
 ```python
 wb = json.loads(解码后的workbook)
-dt = wb["sheets"]["Sheet1"]["data"]["dataTable"] # {row: {col: {"style": {...}, "tag": {...}}}}
+dt = wb["sheets"]["Sheet1"]["data"]["dataTable"]      # {row: {col: {"style": {...}, "tag": {...}}}}
 for r in dt:
- for c in dt[r]:
- ct = (dt[r][c].get("style") or {}).get("cellType") or {}
- if ct.get("cellType") != "Field": continue
- if str(ct.get("dataSetId")) == DS_OLD and not ct.get("tableName"):
- newct = {}
- for k, v in ct.items(): # 保持键顺序：插在 dataSetId 之后
- newct[k] = v
- if k == "dataSetId": newct["tableName"] = "党员发展(业务模块)"
- dt[r][c]["style"]["cellType"] = newct
+    for c in dt[r]:
+        ct = (dt[r][c].get("style") or {}).get("cellType") or {}
+        if ct.get("cellType") != "Field": continue
+        if str(ct.get("dataSetId")) == DS_OLD and not ct.get("tableName"):
+            newct = {}
+            for k, v in ct.items():                   # 保持键顺序：插在 dataSetId 之后
+                newct[k] = v
+                if k == "dataSetId": newct["tableName"] = "党员发展(业务模块)"
+            dt[r][c]["style"]["cellType"] = newct
 # 重新编码并提交 saveReportDevInfo
 ```
 
@@ -231,7 +256,7 @@ for r in dt:
 | `getReportDevInfo` 回读 | `fields[]` 中带 `tableName` 的数量 = Field 总数 |
 | 设计器实时 workbook | dataTable 内 `Field` 单元格 `tableName` 缺失数 = 0 |
 
-> 结果：12/12 带 tableName ✅；设计器实时 workbook 11/11 Field 全齐、0 缺失 ✅
+> 验证结果：12/12 带 tableName ✅；设计器实时 workbook 11/11 Field 全齐、0 缺失 ✅
 
 ---
 
@@ -240,26 +265,26 @@ for r in dt:
 > **场景**：整张报表的 Field 单元格 `tableName` 全为空 → 设计器里单元格/属性面板不回显数据集名；
 > 但**孤例**（某个手绑单元格）是对的。用户会说「参考 XX 单元格的规则才对，调整其他字段」。
 >
-> **报表 `1314970921403138199` 成功（2026-09-14）**：
+> **报表 `1314970921403138199` 验证成功（2026-09-14）**：
 > 48 个 Field 中 47 个 `tableName=""`，唯 `AM5`（row4,col38）为 `考勤汇总报表(优化)` → 一键补齐。
 
-### 为什么优先走这条路（而不是 §四点五 的 CDP 实际请求）
+### 为什么优先走这条路（而不是 §四点五 的 CDP 接口返回）
 
 `getReportDevInfo` 的 `workbookProps.sheets` **恒为 `{}`**，拿不到 `dataTable`；
 但它的 **`fields[]` 是服务端对 workbook 的逐单元格回读**，字段足够重建：
 `x/y`、`xCount/yCount`（合并跨度）、`leftX/leftY/topX/topY`（父子格）、`expandType/displayType`、
 `countType`、`style`（整份 style JSON 串）、`name/text/nameIndex/dataSetId/fieldKey/tableName`、`width/height`。
-**→ 不需要浏览器、不需要按键实际请求**。§四点五 的 CDP 路径仅作兜底。
+**→ 不需要浏览器、不需要按键接口返回**。§四点五 的 CDP 路径仅作兜底。
 
 ### 重建规则（照抄即可）
 
 ```
 dataTable[x][y] = { style: { ...JSON.parse(fields[].style), cellType }, tag: { fixed:false, formatterType:['common'] } }
-spans = 每个 xCount>1 || yCount>1 的单元格 → { row:x, col:y, rowCount:xCount, colCount:yCount }
-columns[c] = fields[].width（该列任一单元格）; rows[r] = fields[].height
-sheet.tag = sheetProps[0] 的 childMerge / showLocation / filterSheet / tableNameSuffix
- + JSON.parse(columnConfig) + JSON.parse(sheetConfig)
-workbook = { version, __scrollbarShowMax, __excelSheet, workbookConfig:{}, sheets }
+spans      = 每个 xCount>1 || yCount>1 的单元格 → { row:x, col:y, rowCount:xCount, colCount:yCount }
+columns[c] = fields[].width（该列任一单元格）;  rows[r] = fields[].height
+sheet.tag  = sheetProps[0] 的 childMerge / showLocation / filterSheet / tableNameSuffix
+             + JSON.parse(columnConfig) + JSON.parse(sheetConfig)
+workbook   = { version, __scrollbarShowMax, __excelSheet, workbookConfig:{}, sheets }
 cellType 键序 = 设计器真实键序（见 §一，逐字照排）
 ```
 
@@ -276,8 +301,8 @@ cellType 键序 = 设计器真实键序（见 §一，逐字照排）
 - `fields[].width/height` **可能合法为 0**（Excel 隐藏列，如「人员ID」）→ 不能用 `Number(w) || 40` 兜底，会把 0 吞成 40。
 - 合并区覆盖但**无单元格**的列（日期块被合并掉的第 2/3 列）在 `fields[]` 里不存在 → 沿用左侧最近已知列宽，避免列宽塌成默认值。
 
-> ⚠️ **与 `safe_report_save.js` 的一处分歧**：该脚本的 `stripWorkbookGridlineKeys()` 会删掉
-> `gridline` / `__gridline`，注释称「存在即 500」。**在本环境（itsm.hongjing-wh.com:5001） 不成立**：
+> ⚠️ **与 `` 的一处分歧**：该脚本的 `stripWorkbookGridlineKeys()` 会删掉
+> `gridline` / `__gridline`，注释称「存在即 500」。**在某自建站点环境（`<自建站点域名>:5001`）验证不成立**：
 > 带 `__gridline: 0` 的 workbook 保存返回 200（报表 `1314970921403138199` 连续两次）。
 > 该断言可能只对某站点成立 —— 保留删除动作更安全，但**不要据此判定其他 500 的成因**。
 
@@ -291,10 +316,10 @@ cellType 键序 = 设计器真实键序（见 §一，逐字照排）
 
 ```bash
 # 默认 dry-run（打印计划 + 保真自检，不落库）
-node e10-cli report fix table-name --report-id <rid> [--app-id <aid>] \
- [--table-name "<数据集名>"] [--restore-from <备份workbook.json>]
+e10-cli report fix table-name --report-id <rid> [--app-id <aid>] \
+     [--table-name "<数据集名>"] [--restore-from <备份workbook.json>]
 # 确认后落库
-node e10-cli report fix table-name --report-id <rid> --apply
+e10-cli report fix table-name --report-id <rid> --apply
 ```
 - 自动定值：`--table-name` > `fieldsKey[].datasetName` > `dataset/list[].name`
 - `--restore-from`：把备份 workbook 中「线上已不存在」的单元格补回（例如被误删的手绑单元格）
@@ -306,7 +331,7 @@ node e10-cli report fix table-name --report-id <rid> --apply
 ```
 保存前 fields = A（含孤例），保存后 fields = B
 diff(A,B) 期望：仅 `tableName` 变化（条数 = 缺失数）+ 可选 `(新增)`（补回的手绑单元格）
- 其余键（cellType/name/dataSetId/父子格/expandType/displayType/style…）必须 0 差异
+            其余键（cellType/name/dataSetId/父子格/expandType/displayType/style…）必须 0 差异
 ```
 
 再跑 `e10-cli report verify all <rid> <appId>`（`ok:true, errors:[]`）+ 渲染回读
@@ -316,18 +341,144 @@ diff(A,B) 期望：仅 `tableName` 变化（条数 = 缺失数）+ 可选 `(新
 > 若线上存在「`fields[]` 也看不到」的内容（未知键），重建会丢。故保存前**先把重建出的
 > 『原样 workbook』落一份备份**（本脚本 `--restore-from` 亦依赖它补回被误删的手绑单元格）。
 
-
 ---
 
 - ❌ 只在 `fields[]` 回读层「补」tableName —— 必须写入 workbook 的 `cellType`，服务端才会落库
 - ❌ **照抄 `fields[]` 的键集重建 cellType** —— `typeName` 等 6 个键服务端不回传，漏了必 500（见 §四点六 坑 1）
 - ❌ **把服务端派生键回写 cellType**（`dateTimeProps`/`highlightDatas`/`allNeedFields`/`fill*`）—— 必 500（坑 2）
-- ❌ 给共享表（form 契约）写 `(业务模块)` 后缀；给 SQL 视图（ETEAMS/sql）硬加后缀（形态 C 无后缀）
+- ❌ 给共享表（form 契约）写 `(业务模块)` 后缀；给「数据加工」SQL 视图（`eteams`/`sql`）漏写 `(数据加工)` 后缀
+  （此前误写「形态 C 无后缀」——2026-10-09 更正，验证带 `(数据加工)`）
 - ❌ 用 `saveReportDevInfo` 的 `fields[]` 数组下发字段 —— 服务端**只认 workbook**
 - ❌ 重构时把本契约从 references 删除（本事故成因）
 
 ---
 
+## 五、两个「回显不对」症状的字段归属（2026-09-14 实证补录）
+
+用户报「回显不对」时，**先分清是哪一种**，两者落库字段不同、修法相同（同一脚本一次修完）：
+
+| 症状 | 落库字段 | 判据 | 期望形态 |
+|------|----------|------|----------|
+| ①「数据集名称显示不对 / 不回显」 | `tableName` | Field 单元格 `tableName` 为空 | `数据集显示名(业务模块)` / `(表单)` / 裸名(形态C) |
+| ②「字段回显不对，应是『数据集名.字段名』」 | **`fieldKey`** | 非 `dataSetId.nameIndex.name` 三段一致 | `1313903497535856649.865906673130749953.field_xxx` |
+
+> **`fieldKey` 契约（本次补录）**：三段 = ①本报表内部 `dataSetId`（`dataset/list[].id`，**不是** sourceId）
+> ②`nameIndex`（底层表单 sourceId）③`name`（`field_<雪花>`，须逐字等于 `fieldsKey[].name`）。
+> **⚠️ 修复时绝不臆造段值**：若某段（如 `name`）在 `cellType` 里本身缺失，宁可留空也不拼接，
+> 否则会造出「看起来有值但绑错字段」的假回显。脚本 `assemble()` 已按此实现（缺段则不重建）。
+
+**一次双向修复**：`e10-cli report fix table-name` 的 `assemble()` 同时处理 ①`tableName` ②`fieldKey`；
+dry-run 会分别打印「tableName 缺失 n/N」+「fieldKey 不合规 n/N」+ 将修复的单元格坐标，
+落库后快照 diff 期望仅 `tableName` / `fieldKey` / `(新增)` 三类键变化。
+
+### ⚠️⚠️ 重建 workbook 的三个致命坑（2026-09-14 血案 · 报表 1313903497535856640）
+
+| # | 坑 | 症状 | 正确做法 |
+|---|----|------|----------|
+| 1 | **`typeName` 必须与 `cellType` 一一对应** | Formula 格被写成 `ConstCellType` → 服务端保存后**静默丢弃**该格 | `Field→FieldCellType`、`Formula→FormulaCellType`、`Const→ConstCellType` |
+| 2 | **`rows[]` 必须覆盖真实工作表行数** | 只按 live `fields[]` 的 maxX 生成 → `rows.length=3`，第 9 行的格子落在声明行数外 → 被丢 | `rowsLen = max(maxX+1, sheetProps.rowCount, 200)`，`rowCount` 同步 |
+| 3 | **同一报表可挂多个数据集** | 全局套一个 `tableName` → 第二数据集的格被写错名 | `tableName` **按每格自身 `dataSetId` 分别解析**（`assemble(f, tnMap)`） |
+
+> **`fields[]` 是「不完整视图」**：验证同一报表在两次 GET 之间，
+> `fields[]` 会漏报某些格（如属第二数据集的 `(14,2)`），也会**受上一次保存影响**而增删。
+> **禁止**把 `fields[]` 当作 workbook 的等价物；重建前必须做「期望格集合 == 实际格集合」比对。
+
+> **Formula 格无法经重建写入（2026-09-14 双血案后定论）**：
+> 报表 `1313903497535856640`（J3）与 `1313903463073415168`（J3）两起事故，
+> 均为「修 tableName 时重建 workbook → 保存后 Formula 格消失（`fields 23→22`）」。
+> **共穷举 6 种组合全部失败**（服务端一律 code 200 但不落库）：
+>
+> | # | 尝试 | 结果 |
+> |---|------|------|
+> | ① | `--restore-from <pre-loss workbook>` 补回 | ❌ 200 但不落库 |
+> | ② | `(2,9).leftX/leftY` 改为紧邻 `(2,8)` | ❌ 同上 |
+> | ③ | `left=(2,8) + expandType=Vertical`（随父链） | ❌ 同上 |
+> | ④ | `left=(2,0) + expandType=Vertical` | ❌ 同上 |
+> | ⑤ | 原样提交（仅补 tableName，其余字段零改动） | ❌ 同上 |
+> | ⑥ | 从 pre-loss workbook 全量重放 | ❌ 同上 |
+>
+> **定论：服务端不接受由 `saveReportDevInfo` 写入的 Formula 格。** 重建式写入**必然丢 Formula 格**。
+> **恢复此类格首选**：CDP 抓设计器真实 workbook（§四点五），或**让用户在设计器手工补一格（最稳）**。
+> **⚠️ 不要反复盲试** —— 每次尝试都是一次真实落库，且失败不报错（静默 200），风险不可控。
+
+> **⚠️ 执行纪律（血案后强制）**：对**含 Formula 格的报表**执行 `fix table-name --apply` 前，
+> 必须先向用户明示「本操作会丢失公式格」，取得明确授权；
+> 或改为只读 `verify contract` 出报告 + 由用户在设计器手工修 `tableName`。
+> 判定方法：`verify contract` 输出里 `fields` 总数 > `Const` + `Field` 之和（差额即 Formula 格数）。
+
+> **回落路径必须补形态后缀（2026-09-14 补）**：`tableName` 回落取 `dataset/list[].originalName` 时，
+> 拿到的是**裸显示名**（如 `采招-招标项目`），**必须**经 `withFormSuffix()` 拼成 `采招-招标项目(业务模块)`。
+> 否则与「参照单元格路径」「人工手绑」的值不一致 → 设计器仍不回显数据集名。
+> 规则：`sourceType=LOGIC 且 sourceGroup 含 ebuilder/form-service → (业务模块)`；`FORM → (表单)`；
+> `eteams`（小写 type）且 `sourceGroup=sql → (数据加工)`；其它无后缀。
+> ⚠️ 仍是**单元格** `tableName` 的口径。且 `originalName` 本身就是**裸名**（这是对的）——
+> 不要把后缀回写进数据集 `name`（BUILD-36）。回落取值优先级见本节上方。
+
+### ⚠️⚠️ 重建 workbook 的第四个致命坑 —— `tag.formatterType`（2026-09-15 血案 · 报表 1315015331503456271）
+
+**症状**：`tableName` / `fieldKey` / 字段绑定 / `showLocation` 全对，脚本自报「快照 diff = 0 处」，
+但用户发现**列格式变了** —— 身份证列本该是「文本」格式（防科学计数）变回常规，金额列「数值」格式也没了。
+
+**根因**：重建时 `put()` 把每格的 tag 写死：
+
+```js
+tag: { fixed: !!f.fixed, formatterType: ['common'] }   // ← 每格格式被强制成 common
+```
+
+**关键认知 —— 格式存在 `tag` 上，不是 `cellType` 上**：
+
+| 位置 | 语义 | 设计器保存值 |
+|------|------|--------------|
+| `cellType.formatterType` | 单元格类型层的占位 | **恒为 `[]`** |
+| **`tag.formatterType`** | **真正的「单元格格式」** | `["common"]` / `["text"]` / `["value"]`… |
+| `fields[].formatterType`（回读顶层） | 由 `tag.formatterType` 映射而来 | 同上 |
+
+验证验证：把 `["text"]` 写进 `cellType.formatterType` → 服务端回读**仍是 `["common"]`**（无效写法）；
+只有写进 `tag.formatterType` 才生效。**故格式必须落在 `tag` 上。**
+
+**修复写法**：
+
+```js
+tag: {
+  fixed: !!f.fixed,
+  formatterType: (Array.isArray(f.formatterType) && f.formatterType.length) ? f.formatterType : ['common'],
+}
+```
+
+**为什么自检没抓到**：`CMP_KEYS` 是**白名单**，里面没有 `formatterType`；`diffSnap` 又只遍历它 →
+改坏了照样报绿。**已在保真自检里新增 `tag.formatterType` 逐格比对。**
+
+**★ 通用教训**：`CMP_KEYS` 白名单以外的一切键，重建都可能被静默改写而自检仍报绿。
+**动生产报表前必须另做一次「全键独立比对」**：落库前存快照 → 落库后回读 →
+逐格遍历 `Object.keys` 求差集（`updateTime` / `allNeedFields` / `fill*` / `dateTimeProps` 等派生键可白名单排除）。
+本次正是靠这一步才抓到 `formatterType` 被抹。
+
+**定点修正命令**（恢复即用它）：
+
+```bash
+e10-cli report fix parent --report-id <id> --app-id <appId> \
+  --set-json '2,1:formatterType:["text"]' \
+  --set-json '2,6:formatterType:["value"]' --apply
+```
+
+> **配套：`fix parent` 的左父格定点修正**
+> 多数据集「连续同源区域」的**后续字段**被错误指向异源格时：
+> `e10-cli report fix parent --report-id <id> --set-parent "x,y=leftX,leftY" [--apply]`
+> （`x,y` = 目标格，0 基；`x`=行 / `y`=列）。规则见
+> `datasource-selection-and-parent-filter-guide.md` §2.1（强制）/ §2.3（反例）。
+
+### 硬门禁（apply 前必须通过）
+
+```
+① 重建格数 == fields.length + extraCells.length          （防丢格）
+② 每个格的 typeName 与 cellType 匹配                      （防服务端静默丢格）
+③ rows.length >= 该 sheet 真实行数                        （防越界丢格）
+④ tnMap 覆盖全部用到的 dataSetId                          （防多源写错名）
+⑤ 保存后快照 diff 仅 tableName/fieldKey/(新增)            （防洗数据）
+```
+
+---
+
 ## 六、相关文档
 
 | 文档 | 关系 |
@@ -336,4 +487,3 @@ diff(A,B) 期望：仅 `tableName` 变化（条数 = 缺失数）+ 可选 `(新
 | `field-bind-exact-match-guide.md` | `name` 逐字匹配 fieldsKey |
 | `spec-build-schema.md` | `build spec` 声明式用法 |
 | `query-condition-api-guide.md` §2.1.2 | `browserType` 富对象（关联浏览分类元数据接口） |
-| 旧包 `data_source_rule.md` §2.2/§2.5 | 本契约原始出处（已迁回本文件） |