weaver-e10-builder 1.6.15 → 1.6.16

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

@@ -1,489 +1,489 @@
-# 数据集表名与字段映射契约（强制 · 历史回归保护）
-
-> **事故（已验证 · 报表 `1313789294296735745`）**
-> 技能包从「手工分步建表」重构为 `build spec`（spec_build 化）后，
-> `e10-cli report build` 的 `fieldCell()` 在生成 `FieldCellType` 时**丢失了 4 个必需字段**：
->
-> | 丢失字段 | 正确值 | 后果 |
-> |----------|--------|------|
-> | `tableName` | `数据集名(业务模块)` / `数据集名(表单)` | **左侧数据源不显示「模块类型」后缀** |
-> | `fieldId` | 数据集字段雪花 id | 属性面板字段回显不全 |
-> | `fieldName` | 字段技术名 `field_<id>` | 同上 |
-> | `fieldText` | 字段显示名 | 同上 |
->
-> 验证证据（同一报表内对照组）：
-> - Agent 建的 10 个 Field：`tableName=None`（异常）
-> - 用户在设计器手动绑的 2 个 Field：`tableName='党员发展(业务模块)'`（正确）
-> - 平台原生报表 `772466395278696448`：`tableName='轻资产处理(表单)'`，9/10 非空
-> - 平台原生报表 `799097275701215232`：16/16 非空
->
-> **根因不是接口、不是服务端** —— 是建表脚本写入的 `cellType` 本身就缺字段。
->
-> 重构时**未迁移**，导致知识随重构丢失。
->
-> **⚠️ 2026-09-11 二次实证校正（重要）**：修复该报表时，从设计器接口返回解出真实 workbook，
-> 对照用户手绑字段发现 —— **`fieldId` / `fieldName` / `fieldText` / `dateTimeProp` 在服务端落库的
-> cellType 里同样是缺失的**（用户手绑字段也没有），它们由设计器**运行时装配**，不属落库契约。
-> **真正需要落库、且能对照验证的只有 `tableName` 一项。** 上表把三件套标为「必需」属过度设计，
-> 但**写上去无害**（幂等），建表脚本保留即可；**修复存量报表时只需补 `tableName`**。
->
-> **⚠️⚠️ 2026-09-11 第三次实证校正（关键 · 推翻上一条因果）**：
-> 上文「`tableName` 缺失 → 左侧数据源不显示模块类型后缀」的**因果链是错的**。
->
-> 决定性对照（同一环境，平台原生/健康报表）：
->
-> | 报表 | Field 单元格 `tableName` | 左侧面板显示 | 结论 |
-> |---|---|---|---|
-> | `1313798296523022337`（销售单，健康） | **全部 10 个为 `None`** | **完全正常** | `tableName` 与显示名**无关** |
-> | `1313789294296735745`（党员发展，问题） | 10 个 `None` + 1 个有值 | 出现重复分组/缺后缀 | 真实原因见下 |
->
-> **左侧数据源「分组显示名」的唯一权威来源** = `GET /api/bs/edc/dataset/listWithPageReport?hasField=true&reportId=`
-> 返回的**源级记录**（`id` 即 **sourceId**，非 datasetId）的 `name` / `tableText`：
->
-> | 状态 | `name` / `tableText` 形态 |
-> |---|---|
-> | 正常 | `事项清单(uf_ydsxqd_1)`、`进销存-销售单(uf_jxcxsd)`（业务模块名 + 物理表名/表单标识） |
-> | 异常 | `党员发展`（纯中文名，无后缀） |
->
-> **故 `tableName` 的正确落库意义**：它是**单元格级**的字段归属标记（供属性面板/导出识别「这个字段来自哪个源表」），
-> **不是**左侧树的显示名来源。补它有益（属性面板回显更全），但**修不了面板显示名问题**。
->
-> **面板显示名异常的真实定位路径** → 见 `dataset-sidebar-ops-guide.md` §5.3：
-> ① `dataset/list` 是否挂载了重复数据集；② 遍历**全部 sheet** 找引用重复数据集的游离单元格；③ 源级 `name` 是否带后缀。
->
-> **校验口径修正**：`tableName` 非空率**不能**作为「面板显示名正确」的判据；
-> 应改用 `dataset/list` 去重 + `listWithPageReport.name` 含后缀 + 全 sheet 无游离 `dataSetId` 三项联合校验。
-
----
-
-## 一、`FieldCellType` 必需字段全表
-
-服务端从 `workbook.sheets.Sheet1.data.dataTable[行][列].style.cellType`
-反解出 `getReportDevInfo.fields[]`。**cellType 里没有的字段，回读就是 `None`。**
-
-| 字段 | 是否必需 | 值 | 说明 |
-|------|----------|-----|------|
-| `typeName` | ✅ | `FieldCellType` | 固定 |
-| `cellType` | ✅ | `Field` | 固定 |
-| `name` | ✅ | `field_<雪花>` | 必须逐字等于 `fieldsKey[].name` |
-| `nameIndex` | ✅ | 底层 FORM sourceId | **不是字段 id** |
-| `text` | ✅ | 字段显示名 | |
-| `dataSetId` | ✅ | 报表内部注册 id | `dataset/list` 的 `id` |
-| **`tableName`** | ○ 建议写 | **`数据集名(业务模块)`** | 单元格级字段归属标记；**非**面板显示名来源（见开头三次校正）。⚠️ **只有单元格**要带后缀；数据集 `name` 必须裸名（§二 更正框） |
-| `fieldId` | ○ 建议写 | 字段雪花 id | 落库本不含；设计器运行时装配，写入幂等无害 |
-| `fieldName` | ○ 建议写 | `field_<雪花>` | 同上 |
-| `fieldText` | ○ 建议写 | 字段显示名 | 同上 |
-| `fieldKey` | ✅ | `dataSetId.nameIndex.name` | 三段式 |
-
----
-
-## 二、`tableName` 后缀由注册契约决定
-
-`tableName` = **数据集显示名 + 后缀**，后缀取决于 `addDataset` 的注册类型：
-
-| 注册形态 | `sourceType` / `sourceGroup` | 后缀 | 适用 |
-|----------|------------------------------|------|------|
-| **A（默认）** | `LOGIC` + `weaver-ebuilder-form-service` | **`(业务模块)`** | 普通应用表单 |
-| **B（共享表）** | `form` + `<appId>` | **`(表单)`** | `xxx-共享表` 类应用 |
-| **C（数据加工 SQL 视图）** | `eteams`（**小写 type**） + `sql` | **`(数据加工)`** | 数据集来自「数据加工」SQL 视图 |
-
-> **⚠️⚠️ 形态 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`；
-> ② 否则 `数据集名 + (数据加工)`；③ 都没有才按 `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`（服务端有则用）
-2. `fieldsKey[].datasetName`
-3. `datasetLabel + datasetSuffix(sourceType)` ← **兜底，保证恒非空**
-
-`datasetLabel` 来自 `dataset/list` 的 `name`（即 `addDataset` 的 `sourceName`），
-由 构建层 回传、`fieldsKeyOf()` 注入到每个字段。
-
----
-
-## 三、字段三件套取值来源
-
-| 字段 | 来源 |
-|------|------|
-| `fieldId` | `fieldsKey[].config.fieldId`（**首选**）→ `fieldsKey[].fieldId` |
-| `fieldName` | `fieldsKey[].name` |
-| `fieldText` | `fieldsKey[].text`（→ `showName` → 列标题） |
-
-`fieldsKey[]` 验证可用键（`fieldsAndOriginFields?isFront=true`）：
-
-```
-name / text / originName / fieldType / formatType
-dataSetId / nameIndex / tableId / tableText / datasetName
-config{ fieldId, formId, sformId, formName, componentKey, ... }
-```
-
-### 三点五、两接口返回格式对照（**以 `fieldsAndOriginFields` 为准** · 2026-09-11 验证）
-
-同一表单 `sourceId=753880319550169088` 双接口 30/30 逐条比对：
-
-| 接口 | 信封（顶层） | 字段元素 | `dataSetId` |
-|------|--------------|----------|-------------|
-| `GET /dataset/fieldsBySource?sourceId=&sourceType=logic&groupId=` | `data` = **裸数组** `[{…}]` | 18 键 | **恒 `"0"`**（未落库） |
-| `GET /dataset/fieldsAndOriginFields?datasetId=&hasField=true&isFront=true&reportId=` | `data` = **对象** `{ fieldsKey:[…], originFieldsKey:[…] }` | 18 键 | **真实 datasetId** |
-
-逐键差异统计：**仅 `dataSetId` 30/30 不同**；其余 17 键
-（`name` / `text` / `originName` / `fieldType` / `originFieldType` / `usage` / `config` /
-`formatType` / `showOrder` / `tableId` / `tableText` / `nameIndex` / `datasetName` /
-`originField` / `dsSelectField` / `dsBrowserField` / `deleteType`）**完全一致**。
-
-**统一归一化入口**：`spec_lib.normalizeFieldList(payload, { datasetId })`
-
-```javascript
-const { fields } = normalizeFieldList(res, { datasetId });   // 冒号：任一接口 → 字段元素数组
-```
-
-- 抹平「裸数组 / `{fieldsKey}` 对象 / `{fields}` 对象」三种信封 → 一律返回**字段元素数组**；
-- `datasetId` 传入时**覆盖** `dataSetId`（`fieldsBySource` 恒为 `0`，**直接落库会绑错数据集**）；
-- 返回 `{ fields, originFields, shape, dataSetIdInjected }`，`shape ∈ bare-array | fieldsKey-object | fields-array | empty`。
-
-> **禁止**把 `fieldsBySource` 的原始 `data`（裸数组）当成 `{fieldsKey}` 取 —— `data.fieldsKey` 会是 `undefined`。
-> **禁止**把 `fieldsBySource` 元素原样写入 `cellType.dataSetId` —— 必须换成**本报表真实 datasetId**。
-> 另：语义上的「返回 data」= 接口的 `json.data`；`json.code === 200` 表示成功。
-
----
-
-## 四、落库后强制门禁
-
-`build spec` 已在 `getReportDevInfo` 回读阶段自动校验：
-
-```javascript
-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;   // 非零退出，提示需修正
-}
-```
-
-输出 JSON 附带：`tableName`（首格值）、`tableNameMissing`（缺失数）。
-
-| 检查 | 通过标准 |
-|------|----------|
-| `tableName` 非空率 | **100%**（`tableNameMissing == 0`） |
-| 后缀与注册形态一致 | LOGIC→`(业务模块)`；form→`(表单)` |
-| `fieldId` / `fieldName` / `fieldText` 齐全 | 非空 |
-| `name` ∈ fieldsKey | 见 `field-bind-exact-match-guide.md` |
-
----
-
-## 四点五、修复存量报表（tableName 缺失）— 最小侵入路径 ✅ 已验证
-
-> **场景**：报表已落库，但 `tableName` 缺失（旧脚本产物）。
-> **报表 `1313789294296735745` 验证修复成功（HTTP 200 + 双向验证通过）。**
-
-**关键接口认知（务必先读）**
-
-| 接口 | 提交物 | 易错点 |
-|------|--------|--------|
-| `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）**
-
-```
-groupId / appId / reportId / name / nameLabelId / designKey / workbook
-```
-- `designKey` 是**乐观锁**，必须取线上当前值（`getReportDevInfo.data.designKey`），否则拒写
-- `workbook`（默认口径）= `base64(gzip(json.dumps(workbook), mtime=0))`；**部分环境需明文 JSON**（见上）
-
-**获取「当前真实 workbook」（唯一可靠来源）**
-
-线上 `getReportDevInfo` **拿不到** `dataTable`（其 `workbookProps.sheets` 为空 `{}`）。正确做法：
-
-1. CDP 打开设计器：`https://{host}/sp/edc/report/designer/{reportId}`
-2. 派发 **Ctrl+S**（`Input.dispatchKeyEvent`，`modifiers:2`, `key:"s"`）触发一次保存
-3. 从 `Network.requestWillBeSent` 抓 `saveReportDevInfo` 的 `postData`
-4. 按 `name="workbook"\n\n(.*?)\n-{2,}`（**换行是 `\n`，不是 `\r\n`**）提取 → `gzip.decompress(base64.b64decode(...))`
-
-**修复步骤**
-
-```python
-wb = json.loads(解码后的workbook)
-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
-# 重新编码并提交 saveReportDevInfo
-```
-
-**验证（双向）**
-
-| 检查 | 通过标准 |
-|------|----------|
-| `getReportDevInfo` 回读 | `fields[]` 中带 `tableName` 的数量 = Field 总数 |
-| 设计器实时 workbook | dataTable 内 `Field` 单元格 `tableName` 缺失数 = 0 |
-
-> 验证结果：12/12 带 tableName ✅；设计器实时 workbook 11/11 Field 全齐、0 缺失 ✅
-
----
-
-## 四点六、修复存量报表（tableName 缺失）— **免浏览器反向重建** ✅ 已验证（首选）
-
-> **场景**：整张报表的 Field 单元格 `tableName` 全为空 → 设计器里单元格/属性面板不回显数据集名；
-> 但**孤例**（某个手绑单元格）是对的。用户会说「参考 XX 单元格的规则才对，调整其他字段」。
->
-> **报表 `1314970921403138199` 验证成功（2026-09-14）**：
-> 48 个 Field 中 47 个 `tableName=""`，唯 `AM5`（row4,col38）为 `考勤汇总报表(优化)` → 一键补齐。
-
-### 为什么优先走这条路（而不是 §四点五 的 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 路径仅作兜底。
-
-### 重建规则（照抄即可）
-
-```
-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 }
-cellType 键序 = 设计器真实键序（见 §一，逐字照排）
-```
-
-### ⚠️ 四个坑（踩过，必须照做，否则 `{"code":500,"msg":"报表内部错误"}`）
-
-| # | 坑 | 正确做法 |
-|---|----|----------|
-| 1 | **`fields[]` 不回传 `typeName`/`allowOverflow`/`editorType`/`groupType`/`isActiveParent`/`arrowType`**，但服务端保存**必须要 `typeName`** | 这 6 个键由脚本**强制兜底**：`typeName='FieldCellType'/'ConstCellType'`、`allowOverflow=true`、`editorType=1`、`groupType=null`；`arrowType` 由 `expandType` 派生（Vertical/Horizontal/None）；`isActiveParent` = Field 且 `leftX=-1 && topX=-1 && expandType∈{Vertical,Horizontal}` |
-| 2 | `dateTimeProps` / `highlightDatas` / `allNeedFields` / `fillDtIndex` / `fillShow` / `fillAddLine` / `fillDelLine` / `fillMergeShow` / `fillSelectId` / `fillTextLength` 是**服务端保存时自行派生**的，设计器保存的 workbook 里**没有** | **排除，不得回写**（回写即 500） |
-| 3 | `cellType.formatterType` 设计器保存值是 **`[]`**（不是 `['common']`；`['common']` 在 `tag.formatterType`） | 强制 `formatterType: []` |
-| 4 | `designKey` **每次 GET 都返回新值**（即时令牌，不是静态乐观锁）→ 读后隔久了再存会失败 | 读取 `designKey` 与 `saveReportDevInfo` 必须**紧邻** |
-
-两个次要坑：
-- `fields[].width/height` **可能合法为 0**（Excel 隐藏列，如「人员ID」）→ 不能用 `Number(w) || 40` 兜底，会把 0 吞成 40。
-- 合并区覆盖但**无单元格**的列（日期块被合并掉的第 2/3 列）在 `fields[]` 里不存在 → 沿用左侧最近已知列宽，避免列宽塌成默认值。
-
-> ⚠️ **与 `` 的一处分歧**：该脚本的 `stripWorkbookGridlineKeys()` 会删掉
-> `gridline` / `__gridline`，注释称「存在即 500」。**在某自建站点环境（`<自建站点域名>:5001`）验证不成立**：
-> 带 `__gridline: 0` 的 workbook 保存返回 200（报表 `1314970921403138199` 连续两次）。
-> 该断言可能只对某站点成立 —— 保留删除动作更安全，但**不要据此判定其他 500 的成因**。
-
-### 合并单元格的副作用（重要）
-
-提交含合并区全部单元格的 workbook 时，**服务端/设计器会丢掉被合并覆盖的单元格，只留左上角**。
-例：日期带 `(0,45)(0,46)(0,47)` 三格 + span → 回读只剩 `(0,45)`。
-**→ 重建时不要凭空补这些格子**；`fields[]` 里没有就是不该有。
-
-### 现成脚本
-
-```bash
-# 默认 dry-run（打印计划 + 保真自检，不落库）
-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> --apply
-```
-- 自动定值：`--table-name` > `fieldsKey[].datasetName` > `dataset/list[].name`
-- `--restore-from`：把备份 workbook 中「线上已不存在」的单元格补回（例如被误删的手绑单元格）
-- 内置门禁：重建保真度不一致即拒绝保存；保存后快照 diff 非 `tableName` 有差异则退出码 2
-- 保存**必须** `--apply`（整份替换，防误覆盖）
-
-### 验收口径（保存前后 fields[] 快照 diff）
-
-```
-保存前 fields = A（含孤例），保存后 fields = B
-diff(A,B) 期望：仅 `tableName` 变化（条数 = 缺失数）+ 可选 `(新增)`（补回的手绑单元格）
-            其余键（cellType/name/dataSetId/父子格/expandType/displayType/style…）必须 0 差异
-```
-
-再跑 `e10-cli report verify all <rid> <appId>`（`ok:true, errors:[]`）+ 渲染回读
-（`view/analysis` → `getJsonStr` → gunzip：`rowCount`/表头纵向合并条数/数据行非空数）确认版面未坏。
-
-> ⚠️ **重建会覆盖服务端现状**：`saveReportDevInfo` 是**整份替换**。
-> 若线上存在「`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 无后缀」——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/(新增)            （防洗数据）
-```
-
----
-
-## 六、相关文档
-
-| 文档 | 关系 |
-|------|------|
-| `add-dataset-registration-guide.md` | 两种注册形态（决定后缀） |
-| `field-bind-exact-match-guide.md` | `name` 逐字匹配 fieldsKey |
-| `spec-build-schema.md` | `build spec` 声明式用法 |
-| `query-condition-api-guide.md` §2.1.2 | `browserType` 富对象（关联浏览分类元数据接口） |
+# 数据集表名与字段映射契约（强制 · 历史回归保护）
+
+> **事故（已验证 · 报表 `1313789294296735745`）**
+> 技能包从「手工分步建表」重构为 `build spec`（spec_build 化）后，
+> `e10-cli report build` 的 `fieldCell()` 在生成 `FieldCellType` 时**丢失了 4 个必需字段**：
+>
+> | 丢失字段 | 正确值 | 后果 |
+> |----------|--------|------|
+> | `tableName` | `数据集名(业务模块)` / `数据集名(表单)` | **左侧数据源不显示「模块类型」后缀** |
+> | `fieldId` | 数据集字段雪花 id | 属性面板字段回显不全 |
+> | `fieldName` | 字段技术名 `field_<id>` | 同上 |
+> | `fieldText` | 字段显示名 | 同上 |
+>
+> 验证证据（同一报表内对照组）：
+> - Agent 建的 10 个 Field：`tableName=None`（异常）
+> - 用户在设计器手动绑的 2 个 Field：`tableName='党员发展(业务模块)'`（正确）
+> - 平台原生报表 `772466395278696448`：`tableName='轻资产处理(表单)'`，9/10 非空
+> - 平台原生报表 `799097275701215232`：16/16 非空
+>
+> **根因不是接口、不是服务端** —— 是建表脚本写入的 `cellType` 本身就缺字段。
+>
+> 重构时**未迁移**，导致知识随重构丢失。
+>
+> **⚠️ 2026-09-11 二次实证校正（重要）**：修复该报表时，从设计器接口返回解出真实 workbook，
+> 对照用户手绑字段发现 —— **`fieldId` / `fieldName` / `fieldText` / `dateTimeProp` 在服务端落库的
+> cellType 里同样是缺失的**（用户手绑字段也没有），它们由设计器**运行时装配**，不属落库契约。
+> **真正需要落库、且能对照验证的只有 `tableName` 一项。** 上表把三件套标为「必需」属过度设计，
+> 但**写上去无害**（幂等），建表脚本保留即可；**修复存量报表时只需补 `tableName`**。
+>
+> **⚠️⚠️ 2026-09-11 第三次实证校正（关键 · 推翻上一条因果）**：
+> 上文「`tableName` 缺失 → 左侧数据源不显示模块类型后缀」的**因果链是错的**。
+>
+> 决定性对照（同一环境，平台原生/健康报表）：
+>
+> | 报表 | Field 单元格 `tableName` | 左侧面板显示 | 结论 |
+> |---|---|---|---|
+> | `1313798296523022337`（销售单，健康） | **全部 10 个为 `None`** | **完全正常** | `tableName` 与显示名**无关** |
+> | `1313789294296735745`（党员发展，问题） | 10 个 `None` + 1 个有值 | 出现重复分组/缺后缀 | 真实原因见下 |
+>
+> **左侧数据源「分组显示名」的唯一权威来源** = `GET /api/bs/edc/dataset/listWithPageReport?hasField=true&reportId=`
+> 返回的**源级记录**（`id` 即 **sourceId**，非 datasetId）的 `name` / `tableText`：
+>
+> | 状态 | `name` / `tableText` 形态 |
+> |---|---|
+> | 正常 | `事项清单(uf_ydsxqd_1)`、`进销存-销售单(uf_jxcxsd)`（业务模块名 + 物理表名/表单标识） |
+> | 异常 | `党员发展`（纯中文名，无后缀） |
+>
+> **故 `tableName` 的正确落库意义**：它是**单元格级**的字段归属标记（供属性面板/导出识别「这个字段来自哪个源表」），
+> **不是**左侧树的显示名来源。补它有益（属性面板回显更全），但**修不了面板显示名问题**。
+>
+> **面板显示名异常的真实定位路径** → 见 `dataset-sidebar-ops-guide.md` §5.3：
+> ① `dataset/list` 是否挂载了重复数据集；② 遍历**全部 sheet** 找引用重复数据集的游离单元格；③ 源级 `name` 是否带后缀。
+>
+> **校验口径修正**：`tableName` 非空率**不能**作为「面板显示名正确」的判据；
+> 应改用 `dataset/list` 去重 + `listWithPageReport.name` 含后缀 + 全 sheet 无游离 `dataSetId` 三项联合校验。
+
+---
+
+## 一、`FieldCellType` 必需字段全表
+
+服务端从 `workbook.sheets.Sheet1.data.dataTable[行][列].style.cellType`
+反解出 `getReportDevInfo.fields[]`。**cellType 里没有的字段，回读就是 `None`。**
+
+| 字段 | 是否必需 | 值 | 说明 |
+|------|----------|-----|------|
+| `typeName` | ✅ | `FieldCellType` | 固定 |
+| `cellType` | ✅ | `Field` | 固定 |
+| `name` | ✅ | `field_<雪花>` | 必须逐字等于 `fieldsKey[].name` |
+| `nameIndex` | ✅ | 底层 FORM sourceId | **不是字段 id** |
+| `text` | ✅ | 字段显示名 | |
+| `dataSetId` | ✅ | 报表内部注册 id | `dataset/list` 的 `id` |
+| **`tableName`** | ○ 建议写 | **`数据集名(业务模块)`** | 单元格级字段归属标记；**非**面板显示名来源（见开头三次校正）。⚠️ **只有单元格**要带后缀；数据集 `name` 必须裸名（§二 更正框） |
+| `fieldId` | ○ 建议写 | 字段雪花 id | 落库本不含；设计器运行时装配，写入幂等无害 |
+| `fieldName` | ○ 建议写 | `field_<雪花>` | 同上 |
+| `fieldText` | ○ 建议写 | 字段显示名 | 同上 |
+| `fieldKey` | ✅ | `dataSetId.nameIndex.name` | 三段式 |
+
+---
+
+## 二、`tableName` 后缀由注册契约决定
+
+`tableName` = **数据集显示名 + 后缀**，后缀取决于 `addDataset` 的注册类型：
+
+| 注册形态 | `sourceType` / `sourceGroup` | 后缀 | 适用 |
+|----------|------------------------------|------|------|
+| **A（默认）** | `LOGIC` + `weaver-ebuilder-form-service` | **`(业务模块)`** | 普通应用表单 |
+| **B（共享表）** | `form` + `<appId>` | **`(表单)`** | `xxx-共享表` 类应用 |
+| **C（数据加工 SQL 视图）** | `eteams`（**小写 type**） + `sql` | **`(数据加工)`** | 数据集来自「数据加工」SQL 视图 |
+
+> **⚠️⚠️ 形态 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`；
+> ② 否则 `数据集名 + (数据加工)`；③ 都没有才按 `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`（服务端有则用）
+2. `fieldsKey[].datasetName`
+3. `datasetLabel + datasetSuffix(sourceType)` ← **兜底，保证恒非空**
+
+`datasetLabel` 来自 `dataset/list` 的 `name`（即 `addDataset` 的 `sourceName`），
+由 构建层 回传、`fieldsKeyOf()` 注入到每个字段。
+
+---
+
+## 三、字段三件套取值来源
+
+| 字段 | 来源 |
+|------|------|
+| `fieldId` | `fieldsKey[].config.fieldId`（**首选**）→ `fieldsKey[].fieldId` |
+| `fieldName` | `fieldsKey[].name` |
+| `fieldText` | `fieldsKey[].text`（→ `showName` → 列标题） |
+
+`fieldsKey[]` 验证可用键（`fieldsAndOriginFields?isFront=true`）：
+
+```
+name / text / originName / fieldType / formatType
+dataSetId / nameIndex / tableId / tableText / datasetName
+config{ fieldId, formId, sformId, formName, componentKey, ... }
+```
+
+### 三点五、两接口返回格式对照（**以 `fieldsAndOriginFields` 为准** · 2026-09-11 验证）
+
+同一表单 `sourceId=753880319550169088` 双接口 30/30 逐条比对：
+
+| 接口 | 信封（顶层） | 字段元素 | `dataSetId` |
+|------|--------------|----------|-------------|
+| `GET /dataset/fieldsBySource?sourceId=&sourceType=logic&groupId=` | `data` = **裸数组** `[{…}]` | 18 键 | **恒 `"0"`**（未落库） |
+| `GET /dataset/fieldsAndOriginFields?datasetId=&hasField=true&isFront=true&reportId=` | `data` = **对象** `{ fieldsKey:[…], originFieldsKey:[…] }` | 18 键 | **真实 datasetId** |
+
+逐键差异统计：**仅 `dataSetId` 30/30 不同**；其余 17 键
+（`name` / `text` / `originName` / `fieldType` / `originFieldType` / `usage` / `config` /
+`formatType` / `showOrder` / `tableId` / `tableText` / `nameIndex` / `datasetName` /
+`originField` / `dsSelectField` / `dsBrowserField` / `deleteType`）**完全一致**。
+
+**统一归一化入口**：`spec_lib.normalizeFieldList(payload, { datasetId })`
+
+```javascript
+const { fields } = normalizeFieldList(res, { datasetId });   // 冒号：任一接口 → 字段元素数组
+```
+
+- 抹平「裸数组 / `{fieldsKey}` 对象 / `{fields}` 对象」三种信封 → 一律返回**字段元素数组**；
+- `datasetId` 传入时**覆盖** `dataSetId`（`fieldsBySource` 恒为 `0`，**直接落库会绑错数据集**）；
+- 返回 `{ fields, originFields, shape, dataSetIdInjected }`，`shape ∈ bare-array | fieldsKey-object | fields-array | empty`。
+
+> **禁止**把 `fieldsBySource` 的原始 `data`（裸数组）当成 `{fieldsKey}` 取 —— `data.fieldsKey` 会是 `undefined`。
+> **禁止**把 `fieldsBySource` 元素原样写入 `cellType.dataSetId` —— 必须换成**本报表真实 datasetId**。
+> 另：语义上的「返回 data」= 接口的 `json.data`；`json.code === 200` 表示成功。
+
+---
+
+## 四、落库后强制门禁
+
+`build spec` 已在 `getReportDevInfo` 回读阶段自动校验：
+
+```javascript
+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;   // 非零退出，提示需修正
+}
+```
+
+输出 JSON 附带：`tableName`（首格值）、`tableNameMissing`（缺失数）。
+
+| 检查 | 通过标准 |
+|------|----------|
+| `tableName` 非空率 | **100%**（`tableNameMissing == 0`） |
+| 后缀与注册形态一致 | LOGIC→`(业务模块)`；form→`(表单)` |
+| `fieldId` / `fieldName` / `fieldText` 齐全 | 非空 |
+| `name` ∈ fieldsKey | 见 `field-bind-exact-match-guide.md` |
+
+---
+
+## 四点五、修复存量报表（tableName 缺失）— 最小侵入路径 ✅ 已验证
+
+> **场景**：报表已落库，但 `tableName` 缺失（旧脚本产物）。
+> **报表 `1313789294296735745` 验证修复成功（HTTP 200 + 双向验证通过）。**
+
+**关键接口认知（务必先读）**
+
+| 接口 | 提交物 | 易错点 |
+|------|--------|--------|
+| `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）**
+
+```
+groupId / appId / reportId / name / nameLabelId / designKey / workbook
+```
+- `designKey` 是**乐观锁**，必须取线上当前值（`getReportDevInfo.data.designKey`），否则拒写
+- `workbook`（默认口径）= `base64(gzip(json.dumps(workbook), mtime=0))`；**部分环境需明文 JSON**（见上）
+
+**获取「当前真实 workbook」（唯一可靠来源）**
+
+线上 `getReportDevInfo` **拿不到** `dataTable`（其 `workbookProps.sheets` 为空 `{}`）。正确做法：
+
+1. CDP 打开设计器：`https://{host}/sp/edc/report/designer/{reportId}`
+2. 派发 **Ctrl+S**（`Input.dispatchKeyEvent`，`modifiers:2`, `key:"s"`）触发一次保存
+3. 从 `Network.requestWillBeSent` 抓 `saveReportDevInfo` 的 `postData`
+4. 按 `name="workbook"\n\n(.*?)\n-{2,}`（**换行是 `\n`，不是 `\r\n`**）提取 → `gzip.decompress(base64.b64decode(...))`
+
+**修复步骤**
+
+```python
+wb = json.loads(解码后的workbook)
+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
+# 重新编码并提交 saveReportDevInfo
+```
+
+**验证（双向）**
+
+| 检查 | 通过标准 |
+|------|----------|
+| `getReportDevInfo` 回读 | `fields[]` 中带 `tableName` 的数量 = Field 总数 |
+| 设计器实时 workbook | dataTable 内 `Field` 单元格 `tableName` 缺失数 = 0 |
+
+> 验证结果：12/12 带 tableName ✅；设计器实时 workbook 11/11 Field 全齐、0 缺失 ✅
+
+---
+
+## 四点六、修复存量报表（tableName 缺失）— **免浏览器反向重建** ✅ 已验证（首选）
+
+> **场景**：整张报表的 Field 单元格 `tableName` 全为空 → 设计器里单元格/属性面板不回显数据集名；
+> 但**孤例**（某个手绑单元格）是对的。用户会说「参考 XX 单元格的规则才对，调整其他字段」。
+>
+> **报表 `1314970921403138199` 验证成功（2026-09-14）**：
+> 48 个 Field 中 47 个 `tableName=""`，唯 `AM5`（row4,col38）为 `考勤汇总报表(优化)` → 一键补齐。
+
+### 为什么优先走这条路（而不是 §四点五 的 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 路径仅作兜底。
+
+### 重建规则（照抄即可）
+
+```
+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 }
+cellType 键序 = 设计器真实键序（见 §一，逐字照排）
+```
+
+### ⚠️ 四个坑（踩过，必须照做，否则 `{"code":500,"msg":"报表内部错误"}`）
+
+| # | 坑 | 正确做法 |
+|---|----|----------|
+| 1 | **`fields[]` 不回传 `typeName`/`allowOverflow`/`editorType`/`groupType`/`isActiveParent`/`arrowType`**，但服务端保存**必须要 `typeName`** | 这 6 个键由脚本**强制兜底**：`typeName='FieldCellType'/'ConstCellType'`、`allowOverflow=true`、`editorType=1`、`groupType=null`；`arrowType` 由 `expandType` 派生（Vertical/Horizontal/None）；`isActiveParent` = Field 且 `leftX=-1 && topX=-1 && expandType∈{Vertical,Horizontal}` |
+| 2 | `dateTimeProps` / `highlightDatas` / `allNeedFields` / `fillDtIndex` / `fillShow` / `fillAddLine` / `fillDelLine` / `fillMergeShow` / `fillSelectId` / `fillTextLength` 是**服务端保存时自行派生**的，设计器保存的 workbook 里**没有** | **排除，不得回写**（回写即 500） |
+| 3 | `cellType.formatterType` 设计器保存值是 **`[]`**（不是 `['common']`；`['common']` 在 `tag.formatterType`） | 强制 `formatterType: []` |
+| 4 | `designKey` **每次 GET 都返回新值**（即时令牌，不是静态乐观锁）→ 读后隔久了再存会失败 | 读取 `designKey` 与 `saveReportDevInfo` 必须**紧邻** |
+
+两个次要坑：
+- `fields[].width/height` **可能合法为 0**（Excel 隐藏列，如「人员ID」）→ 不能用 `Number(w) || 40` 兜底，会把 0 吞成 40。
+- 合并区覆盖但**无单元格**的列（日期块被合并掉的第 2/3 列）在 `fields[]` 里不存在 → 沿用左侧最近已知列宽，避免列宽塌成默认值。
+
+> ⚠️ **与 `` 的一处分歧**：该脚本的 `stripWorkbookGridlineKeys()` 会删掉
+> `gridline` / `__gridline`，注释称「存在即 500」。**在某自建站点环境（`<自建站点域名>:5001`）验证不成立**：
+> 带 `__gridline: 0` 的 workbook 保存返回 200（报表 `1314970921403138199` 连续两次）。
+> 该断言可能只对某站点成立 —— 保留删除动作更安全，但**不要据此判定其他 500 的成因**。
+
+### 合并单元格的副作用（重要）
+
+提交含合并区全部单元格的 workbook 时，**服务端/设计器会丢掉被合并覆盖的单元格，只留左上角**。
+例：日期带 `(0,45)(0,46)(0,47)` 三格 + span → 回读只剩 `(0,45)`。
+**→ 重建时不要凭空补这些格子**；`fields[]` 里没有就是不该有。
+
+### 现成脚本
+
+```bash
+# 默认 dry-run（打印计划 + 保真自检，不落库）
+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> --apply
+```
+- 自动定值：`--table-name` > `fieldsKey[].datasetName` > `dataset/list[].name`
+- `--restore-from`：把备份 workbook 中「线上已不存在」的单元格补回（例如被误删的手绑单元格）
+- 内置门禁：重建保真度不一致即拒绝保存；保存后快照 diff 非 `tableName` 有差异则退出码 2
+- 保存**必须** `--apply`（整份替换，防误覆盖）
+
+### 验收口径（保存前后 fields[] 快照 diff）
+
+```
+保存前 fields = A（含孤例），保存后 fields = B
+diff(A,B) 期望：仅 `tableName` 变化（条数 = 缺失数）+ 可选 `(新增)`（补回的手绑单元格）
+            其余键（cellType/name/dataSetId/父子格/expandType/displayType/style…）必须 0 差异
+```
+
+再跑 `e10-cli report verify all <rid> <appId>`（`ok:true, errors:[]`）+ 渲染回读
+（`view/analysis` → `getJsonStr` → gunzip：`rowCount`/表头纵向合并条数/数据行非空数）确认版面未坏。
+
+> ⚠️ **重建会覆盖服务端现状**：`saveReportDevInfo` 是**整份替换**。
+> 若线上存在「`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 无后缀」——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/(新增)            （防洗数据）
+```
+
+---
+
+## 六、相关文档
+
+| 文档 | 关系 |
+|------|------|
+| `add-dataset-registration-guide.md` | 两种注册形态（决定后缀） |
+| `field-bind-exact-match-guide.md` | `name` 逐字匹配 fieldsKey |
+| `spec-build-schema.md` | `build spec` 声明式用法 |
+| `query-condition-api-guide.md` §2.1.2 | `browserType` 富对象（关联浏览分类元数据接口） |