weaver-e10-builder 1.6.16 → 1.7.0

package/skill-docs/references/report/report-verification-discipline-guide.md

@@ -1,203 +1,203 @@
-# 报表验证纪律指南 — 回读清单 / diff 键 / 字节安全 / 双端差异
-
-> 来源：技能竞赛汇总报表 V1/V2 搭建与**四轮公式乱码**定位（2026-10-12）。
-> 适用：所有 E10 e-Builder 报表的 API 搭建、克隆、修改与定位。
-> 关联注意点：`BUILD-46`（refX/refY）· `BUILD-49`（subordination）· `BUILD-51`（保存判定）· `BUILD-52`（字节安全）· `BUILD-53`（本指南）· `BUILD-54`（克隆纪律）。
-
-本指南回答一个问题：**「落库返回 200」之后，凭什么说这张报表是对的？**
-
----
-
-## 一、结构回读清单（每次落库后必做）
-
-`getReportDevInfo` 回读，逐条勾稽：
-
-| # | 检查项 | 通过判据 | 工具 |
-|---|--------|---------|------|
-| 1 | **格数一致** | 回读 fields 数 == 期望格数 | `e10-cli report verify diff` / 手动比对 |
-| 2 | **cellType 分布** | Field / Const / Formula / SequenceNumber 各类计数与蓝图一致 | 同上 |
-| 3 | **fieldKey 全自洽** | 每个 Field 格 `fieldKey` 首段 == 本格 `dataSetId` | 回读脚本逐条断言 |
-| 4 | **0 残留旧 id** | workbook 内所有数据集 id ∈ 本报表白名单 | `e10-cli report check-ids --report-id <rid> --app-id <appId>`（exit 3 = 有外来 id） |
-| 5 | **Field 有绑定** | 每个 Field 格 `fieldKey` 非空、`tableName` 带类型后缀 | `getReportDevInfo` 回读 |
-| 6 | **父格链无循环依赖** | 无「左父格指向自身 / 已删格」 | `e10-cli report scene check` / `formula parent check` |
-| 7 | **data 非空** | `save` 的 `json.data` 非空 | 见 §一.1 |
-
-### 一.1 「200 但 data 带告警」也算失败（★ 铁律）
-
-`saveReportDevInfo` 返回 `code:200` **不等于**落库有效。父格**循环依赖**这类问题会
-**返回 200、但 `data` 里带告警**。判定必须是：
-
-```js
-// ★ BUILD-51：只看解析后的字段
-const ok = saved.json.code === 200 && saved.json.fail !== true;
-// 且进一步检查 data 非空 / 无告警
-```
-
-**禁止**用 `String(raw).includes('fail')` 判失败 —— 响应体**恒带** `"fail":false` 键名，
-该写法会把**成功**误判成失败（历史误判源）。
-
-脚本层已统一：`spec_lib.saveResultOk(saved)`。
-
----
-
-## 二、diff 键清单 —— 必须含 `subordination` 与 `style`（★ 血案）
-
-做「对照报表 / 克隆源 / 蓝图」的逐格 diff 时，**键清单漏项 = 误判等价**。
-
-> 血案：两轮公式乱码定位中，diff 只比了 `leftX/leftY/refX/refY/cellText`，
-> **漏了 `subordination` 和 `style`** → 结论「两端等价」，但真正的差异（`subordination:[]` vs `["",""]`、
-> `style.formatter:"common"` vs `"General"`）恰在被漏掉的两个键里 → 白排两轮。
-
-**必比键清单**：
-
-```
-cellType · cellText · leftX/leftY · topX/topY · refX/refY · expandType
-subordination            ← ★ 必比（BUILD-49）
-style.formatter          ← ★ 必比（BUILD-47 同族）
-style.formatterType / cell.tag.formatterType
-countType · groupType · displayType · isActiveParent
-fieldKey / dataSetId / tableName / allNeedFields
-```
-
-对照工具：`e10-cli report formula parent check`（公式格父格与被引用字段一致性）；
-需要整表 diff 时用 `dump cells` 两侧各导一份再逐键比。
-
----
-
-## 三、字节安全读取（BUILD-52）
-
-**问题**：HTTP 响应按 chunk 返回。若用
-
-```js
-let d = '';
-res.on('data', (c) => (d += c));   // ❌ Buffer → string 的隐式转换是**按块**做的
-```
-
-一个汉字占 3 字节，若恰好被 chunk 边界切开 → 每块各自 `toString('utf8')` → 变成 U+FFFD
-（`�`）→ **假乱码**。这类乱码与格内容无关，纯属读取姿势错误，极易误导成「报表明细乱码」。
-
-**两种正确写法**（任选其一）：
-
-```js
-// ① 指定编码，交给 StringDecoder 跨块缓冲（Node 内部处理不完整多字节序列）
-res.setEncoding('utf8');
-res.on('data', (c) => (d += c));
-
-// ② Buffer 累积，最后一次转字符串（本技能主通道 spec_lib.request 用的就是这种）
-const chunks = [];
-res.on('data', (c) => chunks.push(Buffer.isBuffer(c) ? c : Buffer.from(c)));
-res.on('end', () => { const d = Buffer.concat(chunks).toString('utf8'); /* … */ });
-```
-
-体检： → `✅ 所有读 body 的脚本都字节安全`（`bytesafe` 检查项）。
-（2026-10-15 已批量修复 22 个脚本 / 24 处读取。）
-
----
-
-## 四、服务端正确 ≠ 浏览器端正确（★ 公式乱码的核心认知）
-
-下列三条**都不能**证明浏览器端 SpreadJS 重算正确：
-
-| 服务端证据 | 它能证明什么 | 不能证明什么 |
-|-----------|-------------|-------------|
-| `analysis` / `getJsonStr` 预计算值正确 | 服务端算得出结果 | 浏览器端重算是否命中同一依赖链 |
-| 导出 Excel 缓存值正确 | 导出通道的值 | 预览页重算（走的是**另一条**路径） |
-| `save` 返回 200 | 落库成功 | 渲染是否乱码 |
-
-**公式类乱码必须看浏览器重算路径**：抓预览页渲染输出，用 p-token 正则扫
-
-```
-/p\d+rc\d+/        # 例如 p1900rc1900nt —— 命中即「解析进了隐藏模板区」= 依赖链没建起来
-```
-
-`p1900rc1900nt` 这类 token 是 `BUILD-49`（`subordination:[]`）的**典型指纹**：
-公式引用区间横跨另一个公式格时，`[]` 让展开引擎建不起引用依赖链，
-浏览器端只能把公式落到隐藏模板区，渲染出 `p<row>rc<col>nt` 字面量。
-
----
-
-## 五、对照实验法（定位此类问题的最快路径）
-
-**同报表内**取两个格做对照：
-
-```
-A 格 = 设计器里手工写的（已渲染正常）
-B 格 = API 构建的（渲染异常）
-```
-
-对 A / B **逐键 diff**（键清单见 §二）。差异键即根因候选。
-比「猜 + 改 + 重试」快一个数量级 —— 四轮乱码定位最终就是靠这一步定位到 `subordination`。
-
-### 五.1 离线自测（秒级回归，替代「会话内临时手写脚本」）
-
-改动**防御层 / 重建层**后，先跑一次离线自测（**无 IO，不连服务器**）：
-
-```bash
-e10-cli report     # 期望：RESULT pass=N fail=0（当前 27 项）
-```
-
-覆盖 **BUILD-46/47/49/51/54** 的纯函数口径：Formula 四件套、Field 跨数据集 `subordination` 不被误改、
-防御层 R7/R8/R9 归一、`saveResultOk` 判定、`checkCloneDiscipline` 三条自检。
-**不要**在会话里临时手写定位脚本（历史教训：会话末被清理 → 下次从零重写，见 PERF-6）。
-
----
-
-## 六、克隆 / 移植前置自检（BUILD-54）
-
-新报表优先**克隆已验收状态**，而不是整表重建（BUILD-40）。克隆流程：
-
-```
-dump fields（克隆源）→ 重映射 dataSetId / fieldKey / sourceId → 逐格 diff → save
-```
-
-重映射后**必须**同时满足三条，任一不过即**拒绝落库**：
-
-| # | 检查 | 判据 |
-|---|------|------|
-| ① | **0 残留旧 id** | workbook 内 dataset id 全 ∈ 本报表白名单（`assertNoStaleDatasetIds`） |
-| ② | **0 坐标冲突** | 无同一 `(x,y)` 出现两次（否则后写覆盖前写，静默丢格） |
-| ③ | **META 键已清理** | 无 `id` / `createTime` / `updateTime` / `creator` 残留 |
-
-脚本层：`e10-cli report rebuild from-blueprint` 内的 `checkCloneDiscipline(fields, allowedIds)`
-（不过即 `throw`，拒绝落库）。
-
-**克隆纪律**：
-- 克隆源必须是**用户确认的最新验收状态**；
-- 克隆后逐格 diff（**含 `subordination` / `style`**）留证；
-- 只改用户点名的 `reportId`（见 `user-request-scope-only-guide.md`）。
-
----
-
-## 七、语义与范围纪律
-
-1. **比率 / 派生指标的正解是数据源侧预计算列**（表单加字段，或数据集 SQL 直出），
-   报表**纯绑字段**。这样绕开平台级公式重映射缺陷 —— 比在报表里堆公式稳得多。
-2. 只改用户点名的 `reportId`；**「截图来自哪张表 ≠ 授权改哪张表」**。
-3. 用户手调 / 手复制的副本**未经点名不得碰**。
-
----
-
-## 自检清单（落库前后各过一遍）
-
-- [ ] 落库**前**：`initReportDev` 已 GET 设计器页（建壳顺序，BUILD-50）
-- [ ] 落库**前**：`doctor scripts` 无 `bytesafe` / `port` / `env9` 告警
-- [ ] 落库**后**：`saveResultOk` 通过 **且** `data` 非空、无告警（BUILD-51）
-- [ ] 回读七项（§一表格）逐条勾稽
-- [ ] 公式格：`refX/refY=-1` + `subordination=["",""]` + `expandType=NoExpand` + 左父格挂块入口格
-- [ ] 若要判「乱码」：扫浏览器渲染输出 `p\d+rc\d+`，**不要**只看服务端预计算值
-- [ ] diff 键清单**含** `subordination` / `style`
-- [ ] 克隆场景：三条前置自检全过
-- [ ] 改动防御层 / 重建层后：`e10-cli report` 全过（离线秒级，§五.1）
-
-## 八、设计器前端逻辑反编译定位法（2026-10-29 实证 · 弹窗回显类问题的终极手段）
-
-API 行为与设计器表现矛盾、且注意点库/对照实验都无法解释时（如筛选 value 形态三轮都不回显，BUILD-98），
-直接反编译设计器前端 chunk 读源码——一次性终结猜测：
-
-1. **拿页面资源清单**：GET `https://<平台地址>/sp/edc/report/design/<reportId>`（HTML 里引用 `<静态资源CDN域名>/build/edc/static/js/main.js`）；
-2. **定位 chunk 表**：main.js 里 `static/js/` 后有 webpack chunk 名/版本映射（设计器路由 = chunk 43 `route_ReportDesigner`）；
-3. **下载目标 chunk**：`/build/edc/static/js/<chunk名>.js?v=<hash>`；共享组件可能在 11 `report_builder~route_DatasetList~route_ReportDesigner`、31 `report_builder` 等；
-4. **搜代码**：中文 UI 文案多以 **unicode 转义**存储（`\u7b5b\u9009`=筛选），或直接搜数据键名（`customFilterField` / `transSelectOptions`）；
-5. **读关键函数**：找组件的 state 定义与写回函数（如弹窗行组件 `Ut(e,t,n)=r=>n({...t,[e]:r})` 原样存值），即可确定设计器的**原生数据形态**（例：多选筛选 value = optionId JSON 数组，BUILD-98 终版定案依据）。
-
-适用边界：仅定位读取，**禁止**把前端临时变量当接口契约；结论须回写注意点并附 chunk 证据。
+# 报表验证纪律指南 — 回读清单 / diff 键 / 字节安全 / 双端差异
+
+> 来源：技能竞赛汇总报表 V1/V2 搭建与**四轮公式乱码**定位（2026-10-12）。
+> 适用：所有 E10 e-Builder 报表的 API 搭建、克隆、修改与定位。
+> 关联注意点：`BUILD-46`（refX/refY）· `BUILD-49`（subordination）· `BUILD-51`（保存判定）· `BUILD-52`（字节安全）· `BUILD-53`（本指南）· `BUILD-54`（克隆纪律）。
+
+本指南回答一个问题：**「落库返回 200」之后，凭什么说这张报表是对的？**
+
+---
+
+## 一、结构回读清单（每次落库后必做）
+
+`getReportDevInfo` 回读，逐条勾稽：
+
+| # | 检查项 | 通过判据 | 工具 |
+|---|--------|---------|------|
+| 1 | **格数一致** | 回读 fields 数 == 期望格数 | `e10-cli report verify diff` / 手动比对 |
+| 2 | **cellType 分布** | Field / Const / Formula / SequenceNumber 各类计数与蓝图一致 | 同上 |
+| 3 | **fieldKey 全自洽** | 每个 Field 格 `fieldKey` 首段 == 本格 `dataSetId` | 回读脚本逐条断言 |
+| 4 | **0 残留旧 id** | workbook 内所有数据集 id ∈ 本报表白名单 | `e10-cli report check-ids --report-id <rid> --app-id <appId>`（exit 3 = 有外来 id） |
+| 5 | **Field 有绑定** | 每个 Field 格 `fieldKey` 非空、`tableName` 带类型后缀 | `getReportDevInfo` 回读 |
+| 6 | **父格链无循环依赖** | 无「左父格指向自身 / 已删格」 | `e10-cli report scene check` / `formula parent check` |
+| 7 | **data 非空** | `save` 的 `json.data` 非空 | 见 §一.1 |
+
+### 一.1 「200 但 data 带告警」也算失败（★ 铁律）
+
+`saveReportDevInfo` 返回 `code:200` **不等于**落库有效。父格**循环依赖**这类问题会
+**返回 200、但 `data` 里带告警**。判定必须是：
+
+```js
+// ★ BUILD-51：只看解析后的字段
+const ok = saved.json.code === 200 && saved.json.fail !== true;
+// 且进一步检查 data 非空 / 无告警
+```
+
+**禁止**用 `String(raw).includes('fail')` 判失败 —— 响应体**恒带** `"fail":false` 键名，
+该写法会把**成功**误判成失败（历史误判源）。
+
+脚本层已统一：`spec_lib.saveResultOk(saved)`。
+
+---
+
+## 二、diff 键清单 —— 必须含 `subordination` 与 `style`（★ 血案）
+
+做「对照报表 / 克隆源 / 蓝图」的逐格 diff 时，**键清单漏项 = 误判等价**。
+
+> 血案：两轮公式乱码定位中，diff 只比了 `leftX/leftY/refX/refY/cellText`，
+> **漏了 `subordination` 和 `style`** → 结论「两端等价」，但真正的差异（`subordination:[]` vs `["",""]`、
+> `style.formatter:"common"` vs `"General"`）恰在被漏掉的两个键里 → 白排两轮。
+
+**必比键清单**：
+
+```
+cellType · cellText · leftX/leftY · topX/topY · refX/refY · expandType
+subordination            ← ★ 必比（BUILD-49）
+style.formatter          ← ★ 必比（BUILD-47 同族）
+style.formatterType / cell.tag.formatterType
+countType · groupType · displayType · isActiveParent
+fieldKey / dataSetId / tableName / allNeedFields
+```
+
+对照工具：`e10-cli report formula parent check`（公式格父格与被引用字段一致性）；
+需要整表 diff 时用 `dump cells` 两侧各导一份再逐键比。
+
+---
+
+## 三、字节安全读取（BUILD-52）
+
+**问题**：HTTP 响应按 chunk 返回。若用
+
+```js
+let d = '';
+res.on('data', (c) => (d += c));   // ❌ Buffer → string 的隐式转换是**按块**做的
+```
+
+一个汉字占 3 字节，若恰好被 chunk 边界切开 → 每块各自 `toString('utf8')` → 变成 U+FFFD
+（`�`）→ **假乱码**。这类乱码与格内容无关，纯属读取姿势错误，极易误导成「报表明细乱码」。
+
+**两种正确写法**（任选其一）：
+
+```js
+// ① 指定编码，交给 StringDecoder 跨块缓冲（Node 内部处理不完整多字节序列）
+res.setEncoding('utf8');
+res.on('data', (c) => (d += c));
+
+// ② Buffer 累积，最后一次转字符串（本技能主通道 spec_lib.request 用的就是这种）
+const chunks = [];
+res.on('data', (c) => chunks.push(Buffer.isBuffer(c) ? c : Buffer.from(c)));
+res.on('end', () => { const d = Buffer.concat(chunks).toString('utf8'); /* … */ });
+```
+
+体检： → `✅ 所有读 body 的脚本都字节安全`（`bytesafe` 检查项）。
+（2026-10-15 已批量修复 22 个脚本 / 24 处读取。）
+
+---
+
+## 四、服务端正确 ≠ 浏览器端正确（★ 公式乱码的核心认知）
+
+下列三条**都不能**证明浏览器端 SpreadJS 重算正确：
+
+| 服务端证据 | 它能证明什么 | 不能证明什么 |
+|-----------|-------------|-------------|
+| `analysis` / `getJsonStr` 预计算值正确 | 服务端算得出结果 | 浏览器端重算是否命中同一依赖链 |
+| 导出 Excel 缓存值正确 | 导出通道的值 | 预览页重算（走的是**另一条**路径） |
+| `save` 返回 200 | 落库成功 | 渲染是否乱码 |
+
+**公式类乱码必须看浏览器重算路径**：抓预览页渲染输出，用 p-token 正则扫
+
+```
+/p\d+rc\d+/        # 例如 p1900rc1900nt —— 命中即「解析进了隐藏模板区」= 依赖链没建起来
+```
+
+`p1900rc1900nt` 这类 token 是 `BUILD-49`（`subordination:[]`）的**典型指纹**：
+公式引用区间横跨另一个公式格时，`[]` 让展开引擎建不起引用依赖链，
+浏览器端只能把公式落到隐藏模板区，渲染出 `p<row>rc<col>nt` 字面量。
+
+---
+
+## 五、对照实验法（定位此类问题的最快路径）
+
+**同报表内**取两个格做对照：
+
+```
+A 格 = 设计器里手工写的（已渲染正常）
+B 格 = API 构建的（渲染异常）
+```
+
+对 A / B **逐键 diff**（键清单见 §二）。差异键即根因候选。
+比「猜 + 改 + 重试」快一个数量级 —— 四轮乱码定位最终就是靠这一步定位到 `subordination`。
+
+### 五.1 离线自测（秒级回归，替代「会话内临时手写脚本」）
+
+改动**防御层 / 重建层**后，先跑一次离线自测（**无 IO，不连服务器**）：
+
+```bash
+e10-cli report     # 期望：RESULT pass=N fail=0（当前 27 项）
+```
+
+覆盖 **BUILD-46/47/49/51/54** 的纯函数口径：Formula 四件套、Field 跨数据集 `subordination` 不被误改、
+防御层 R7/R8/R9 归一、`saveResultOk` 判定、`checkCloneDiscipline` 三条自检。
+**不要**在会话里临时手写定位脚本（历史教训：会话末被清理 → 下次从零重写，见 PERF-6）。
+
+---
+
+## 六、克隆 / 移植前置自检（BUILD-54）
+
+新报表优先**克隆已验收状态**，而不是整表重建（BUILD-40）。克隆流程：
+
+```
+dump fields（克隆源）→ 重映射 dataSetId / fieldKey / sourceId → 逐格 diff → save
+```
+
+重映射后**必须**同时满足三条，任一不过即**拒绝落库**：
+
+| # | 检查 | 判据 |
+|---|------|------|
+| ① | **0 残留旧 id** | workbook 内 dataset id 全 ∈ 本报表白名单（`assertNoStaleDatasetIds`） |
+| ② | **0 坐标冲突** | 无同一 `(x,y)` 出现两次（否则后写覆盖前写，静默丢格） |
+| ③ | **META 键已清理** | 无 `id` / `createTime` / `updateTime` / `creator` 残留 |
+
+脚本层：`e10-cli report rebuild from-blueprint` 内的 `checkCloneDiscipline(fields, allowedIds)`
+（不过即 `throw`，拒绝落库）。
+
+**克隆纪律**：
+- 克隆源必须是**用户确认的最新验收状态**；
+- 克隆后逐格 diff（**含 `subordination` / `style`**）留证；
+- 只改用户点名的 `reportId`（见 `user-request-scope-only-guide.md`）。
+
+---
+
+## 七、语义与范围纪律
+
+1. **比率 / 派生指标的正解是数据源侧预计算列**（表单加字段，或数据集 SQL 直出），
+   报表**纯绑字段**。这样绕开平台级公式重映射缺陷 —— 比在报表里堆公式稳得多。
+2. 只改用户点名的 `reportId`；**「截图来自哪张表 ≠ 授权改哪张表」**。
+3. 用户手调 / 手复制的副本**未经点名不得碰**。
+
+---
+
+## 自检清单（落库前后各过一遍）
+
+- [ ] 落库**前**：`initReportDev` 已 GET 设计器页（建壳顺序，BUILD-50）
+- [ ] 落库**前**：`doctor scripts` 无 `bytesafe` / `port` / `env9` 告警
+- [ ] 落库**后**：`saveResultOk` 通过 **且** `data` 非空、无告警（BUILD-51）
+- [ ] 回读七项（§一表格）逐条勾稽
+- [ ] 公式格：`refX/refY=-1` + `subordination=["",""]` + `expandType=NoExpand` + 左父格挂块入口格
+- [ ] 若要判「乱码」：扫浏览器渲染输出 `p\d+rc\d+`，**不要**只看服务端预计算值
+- [ ] diff 键清单**含** `subordination` / `style`
+- [ ] 克隆场景：三条前置自检全过
+- [ ] 改动防御层 / 重建层后：`e10-cli report` 全过（离线秒级，§五.1）
+
+## 八、设计器前端逻辑反编译定位法（2026-10-29 实证 · 弹窗回显类问题的终极手段）
+
+API 行为与设计器表现矛盾、且注意点库/对照实验都无法解释时（如筛选 value 形态三轮都不回显，BUILD-98），
+直接反编译设计器前端 chunk 读源码——一次性终结猜测：
+
+1. **拿页面资源清单**：GET `https://<平台地址>/sp/edc/report/design/<reportId>`（HTML 里引用 `<静态资源CDN域名>/build/edc/static/js/main.js`）；
+2. **定位 chunk 表**：main.js 里 `static/js/` 后有 webpack chunk 名/版本映射（设计器路由 = chunk 43 `route_ReportDesigner`）；
+3. **下载目标 chunk**：`/build/edc/static/js/<chunk名>.js?v=<hash>`；共享组件可能在 11 `report_builder~route_DatasetList~route_ReportDesigner`、31 `report_builder` 等；
+4. **搜代码**：中文 UI 文案多以 **unicode 转义**存储（`\u7b5b\u9009`=筛选），或直接搜数据键名（`customFilterField` / `transSelectOptions`）；
+5. **读关键函数**：找组件的 state 定义与写回函数（如弹窗行组件 `Ut(e,t,n)=r=>n({...t,[e]:r})` 原样存值），即可确定设计器的**原生数据形态**（例：多选筛选 value = optionId JSON 数组，BUILD-98 终版定案依据）。
+
+适用边界：仅定位读取，**禁止**把前端临时变量当接口契约；结论须回写注意点并附 chunk 证据。