weaver-e10-builder 1.1.8 → 1.2.2

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

@@ -0,0 +1,339 @@
+# 数据集表名与字段映射契约（强制 · 历史回归保护）
+
+> **事故（已验证 · 报表 `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` 本身就缺字段。
+> 旧包 `references/data_source_rule.md` §2.2/§2.5 与 `e10-cli report verify bind` 有完整契约，
+> 重构时**未迁移**，导致知识随重构丢失。
+>
+> **⚠️ 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`** | ○ 建议写 | **`数据集名(业务模块)`** | 单元格级字段归属标记；**非**面板显示名来源（见开头三次校正） |
+| `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` + `sql` | **无后缀**（= `datasetName` 原样） | 数据集来自「数据加工」SQL 视图 |
+
+> **形态 C （2026-09-14 · 报表 `1314970921403138199`）**：数据集「考勤汇总报表(优化)」
+> （`sourceType=ETEAMS` / `sourceGroup=sql`）→ 设计器手绑单元格 `tableName` = **`考勤汇总报表(优化)`**，
+> 且 `dataset/fieldsAndOriginFields.fieldsKey[].datasetName` / `tableText` 也都是这个裸名。
+> **判断口径（三条一致即可定值）**：① 设计器里已有手绑单元格 → 用它的 `tableName`；
+> ② 否则用 `fieldsKey[].datasetName`；③ 都没有才按 `dataset/list[].name`。
+
+> 与 `add-dataset-registration-guide.md` §一 的两种注册形态一一对应。
+> **禁止**给共享表硬套 `(业务模块)` —— 后缀必须与注册形态一致。
+
+**取值优先级**（服务端常不回传，必须脚本兜底）：
+
+1. `fieldsKey[].tableName`（服务端有则用）
+2. `fieldsKey[].datasetName`
+3. `datasetLabel + datasetSuffix(sourceType)` ← **兜底，保证恒非空**
+
+`datasetLabel` 来自 `dataset/list` 的 `name`（即 `addDataset` 的 `sourceName`），
+由 `spec_lib.resolveDataset()` 回传、`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`**（gzip + base64） | ❌ 用 `fields=<json>` 提交 → **400 Bad Request** |
+| `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))`
+
+**获取「当前真实 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[]` 里不存在 → 沿用左侧最近已知列宽，避免列宽塌成默认值。
+
+> ⚠️ **与 `safe_report_save.js` 的一处分歧**：该脚本的 `stripWorkbookGridlineKeys()` 会删掉
+> `gridline` / `__gridline`，注释称「存在即 500」。**在本环境（itsm.hongjing-wh.com:5001） 不成立**：
+> 带 `__gridline: 0` 的 workbook 保存返回 200（报表 `1314970921403138199` 连续两次）。
+> 该断言可能只对某站点成立 —— 保留删除动作更安全，但**不要据此判定其他 500 的成因**。
+
+### 合并单元格的副作用（重要）
+
+提交含合并区全部单元格的 workbook 时，**服务端/设计器会丢掉被合并覆盖的单元格，只留左上角**。
+例：日期带 `(0,45)(0,46)(0,47)` 三格 + span → 回读只剩 `(0,45)`。
+**→ 重建时不要凭空补这些格子**；`fields[]` 里没有就是不该有。
+
+### 现成脚本
+
+```bash
+# 默认 dry-run（打印计划 + 保真自检，不落库）
+node 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
+```
+- 自动定值：`--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 无后缀）
+- ❌ 用 `saveReportDevInfo` 的 `fields[]` 数组下发字段 —— 服务端**只认 workbook**
+- ❌ 重构时把本契约从 references 删除（本事故成因）
+
+---
+
+## 六、相关文档
+
+| 文档 | 关系 |
+|------|------|
+| `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` 富对象（关联浏览分类元数据接口） |
+| 旧包 `data_source_rule.md` §2.2/§2.5 | 本契约原始出处（已迁回本文件） |