weaver-e10-builder 1.6.10 → 1.6.11

package/skill-docs/references/report/report-self-check-guide.md

@@ -1,164 +1,164 @@
-# 报表落库自检（强制）
-
-> **适用**：API/脚本保存布局后、交付设计器链接前（可后台跑，但**不得跳过**）。 
-> **目标**：尽早发现字段丢失、伪父格、绑定失败、超链接被冲掉，避免「设计器看着有格、取数/父格全错」。
-
----
-
-## 一、父格坐标语义（勿混）
-
-| API `leftX/leftY` 或 `topX/topY` | 设计器含义 | 说明 |
-|----------------------------------|------------|------|
-| **`-1, -1`** | **默认** 或 **无** | 普通 Const / 单数据集 Field 的常见正确态 |
-| **`0, 0`** | **自定义 → 原点 (0,0)** | **不是默认**；写成 0,0 会显示父格「不对」 |
-| **其它 `x,y`** | **自定义** 指向该坐标 | 多数据集入口、交叉、**超链接占位依赖**等 |
-
----
-
-## 二、按单元格类型的父格规则
-
-### 2.1 普通 Const（表头 / 标题 / 无链接）
-
-| 项 | 规则 |
-|----|------|
-| 左父格 | **`-1,-1`** |
-| 上父格 | **`-1,-1`** |
-| 禁止 | `(0,0)`；勿把「默认」误写成原点 |
-
-### 2.2 超链接 Const（`pcHreflink` / `h5Hreflink`，URL 含 `{L4}` `{C4}` 等）
-
-> **事故**：把「左父格默认」套到「点击查看」上 → 设计器左/上显示不对，且 `{L4}` 无法解析；或重建 workbook 时丢掉 `ConstCellType.cellText` → 保存后 `cellText` 变空、`pcHreflink` 丢失。
-
-| 项 | 规则 | 例（供应商表 M4） |
-|----|------|-------------------|
-| **上父格** | 无横向扩展时必须 **`topX=topY=-1`**（不需要上父格） | `(-1,-1)` |
-| **左父格** | **禁止**一律改成默认；须指向占位符依赖的数据格 | `{L4}` → 左父格 **`(3,11)`**（同行「数据ID」） |
-| **链接元数据** | 须进 **workbook `ConstCellType`**（`pcHreflink`/`openType`/`cellText`/`left*`/`top*`）；仅写 `fields[]` **不够** | `/sp/ebdfpage/card/0/{sourceId}/{L4}` |
-| **workbook** | `ConstCellType` 必须含：`cellText`、`leftX/leftY/topX/topY`、有链接时还要 `pcHreflink` | 服务端 `saveReportDevInfo` **从 cellType 回写 fields**；缺 `leftX` → Java int **0** → 伪 `(0,0)`；缺 `pcHreflink` → 链接丢失 |
-| **禁止** | 只塞 `{typeName,cellText}` 的残 ConstCellType；禁止左=`(0,0)`；禁止有 `{Ln}` 却左=`-1,-1` |
-
-**占位符 → 左父格**（自检算法）：
-
-1. 从 `pcHreflink`/`h5Hreflink` 提取 `{L4}` / `{C4}` / `{Ln}` 等。
-2. `{L4}`：同行纵向扩展语境下，左父格应指向同列（或约定列）上提供 ID 的 Field（本需求为 `(3,11)`）。
-3. 若 URL 含占位而 `leftX/leftY === -1` → **FAIL**（不是「默认正确」）。
-4. 若 `topX/topY !== -1` 且无横向交叉需求 → **FAIL**。
-
-### 2.3 Field（单数据集、无指定计算）
-
-| 场景 | 左父格 |
-|------|--------|
-| **新建**报表 | 优先 **`-1,-1`（默认）** |
-| **已有**报表 | **禁止**用户未点名时批量改父格 |
-
----
-
-## 三、保存门禁（每次 `saveReportDevInfo`）
-
-### 保存前
-
-1. `fields` 中 `cellType=Field` 数量 ≥ 保存前（或与预期列数一致）。
-2. workbook `dataTable` 内 `FieldCellType` 数量 ≥ Field 数。
-3. 每个 **Const**：workbook `ConstCellType` 须含 `cellText`（有文案时）以及显式 **`leftX/leftY/topX/topY`（常用 -1，禁止省略）**。
-4. 每个 **超链接 Const**：`ConstCellType` 须含非空 `pcHreflink`、`openType`，且父格与 `fields` 一致（服务端以 workbook 为准回写）。
-5. 每个 Field：`name` ∈ `fieldsAndOriginFields.fieldsKey[].name`（须带 `field_`；禁止裸雪花 ID）。 
- - 拉 fieldsKey 参数名用 **`datasetId`**（不是 `dataSetId`）。
-
-### 保存后立刻回读
-
-| 检查项 | 失败标准 |
-|--------|----------|
-| Field 数量 | 比保存前减少 → **立即失败**，禁止再改，优先恢复 |
-| Field.`name` | 裸 ID 或不在 fieldsKey → FAIL（`e10-cli report verify bind`） |
-| 普通 Const 父格 | `left=top=(0,0)` → FAIL（伪自定义 A1） |
-| 超链接 Const | 缺 `pcHreflink` / `cellText` 空 / `top≠-1` / 含 `{L*}` 但 `left=-1` 或 `left=(0,0)` → FAIL |
-| 同数据集 leftFilterField | Field 上仍有跨源 leftFilter → WARN/FAIL |
-
-```bash
-e10-cli report verify bind <reportId> [appId] # 字段绑定
-e10-cli report verify self <reportId> [appId] # 父格/超链接自检
-e10-cli report verify all <reportId> [appId] # 自检 + 绑定（推荐）
-```
-
----
-
-## 四、Agent 自检脚本逻辑（摘要）
-
-```javascript
-function assertParents(fields) {
- for (const f of fields) {
- if (f.cellType !== 'Const') continue;
- const origin =
- f.leftX === 0 && f.leftY === 0 && f.topX === 0 && f.topY === 0;
- const href = f.pcHreflink || f.h5Hreflink || '';
- if (origin && !href) {
- throw new Error(`Const(${f.x},${f.y}) 父格(0,0)=伪自定义A1，应为-1,-1`);
- }
- if (!href) continue;
- // 超链接：上父格默认无
- if (f.topX !== -1 || f.topY !== -1) {
- throw new Error(`链接格(${f.x},${f.y}) 不需要上父格，top 应为 -1,-1`);
- }
- if (!f.cellText) {
- throw new Error(`链接格(${f.x},${f.y}) cellText 为空（workbook 可能未写 ConstCellType）`);
- }
- // URL 占位依赖左父格，禁止「默认」
- if (/\{L\d+\}|\{C\d+\}/.test(href)) {
- if (f.leftX === -1 && f.leftY === -1) {
- throw new Error(`链接格(${f.x},${f.y}) 含占位符但左父格为默认，应指向依赖数据格`);
- }
- if (f.leftX === 0 && f.leftY === 0) {
- throw new Error(`链接格(${f.x},${f.y}) 左父格不能为(0,0)`);
- }
- }
- }
-}
-
-function assertWorkbookConstCellType(dataTable, fields) {
- for (const f of fields) {
- if (f.cellType !== 'Const') continue;
- const cell = dataTable?.[String(f.x)]?.[String(f.y)];
- const ct = cell?.style?.cellType;
- if (!ct || ct.typeName !== 'ConstCellType') {
- throw new Error(`workbook 缺 ConstCellType @(${f.x},${f.y})`);
- }
- if ((f.cellText || f.text) && !ct.cellText) {
- throw new Error(`workbook 缺 cellText @(${f.x},${f.y})，保存会冲掉文案`);
- }
- // 缺 leftX 时服务端写成 0 → 伪自定义 A1
- for (const k of ['leftX', 'leftY', 'topX', 'topY']) {
- if (ct[k] === undefined || ct[k] === null) {
- throw new Error(`workbook ConstCellType 缺 ${k} @(${f.x},${f.y})，会落成 0`);
- }
- }
- if (f.pcHreflink && ct.pcHreflink !== f.pcHreflink) {
- throw new Error(`workbook 缺/错 pcHreflink @(${f.x},${f.y})（服务端只认 cellType）`);
- }
- }
-}
-
-function assertFieldPreserved(before, after) {
- const n = (fs) => fs.filter((f) => f.cellType === 'Field').length;
- if (n(after) < n(before)) throw new Error('Field 被冲掉，禁止继续改');
-}
-```
-
----
-
-## 五、与交付节奏
-
-- 布局落库成功 → **先交设计器地址**（`report-delivery-contract.md` §〇）。
-- 本节自检可后台跑；**FAIL 必须补丁修复并告知**，不得假装完成。
-- **禁止**：为修一格 Const 父格而提交残缺 workbook（会导致 Field 全变 Const，或 Const 文案/超链接被冲掉）。修父格必须 **整表 Field + ConstCellType 完整写入 workbook**。
-
----
-
-## 六、相关文档
-
-| 文档 | 关系 |
-|------|------|
-| `field-bind-exact-match-guide.md` | name ∈ fieldsKey |
-| `datasource-selection-and-parent-filter-guide.md` §〇 | 单数据集左父格默认；**勿**套用到超链接 Const；勿擅自改已有表 |
-| `safe-partial-save-guide.md` | 禁止空 workbook；须从 fields 重建 dataTable |
-| `e10-cli report verify bind` | 绑定门禁 |
-| `targeted-fix-guide.md` | 用户点名某处不对时禁止整表重扫 |
+# 报表落库自检（强制）
+
+> **适用**：API/脚本保存布局后、交付设计器链接前（可后台跑，但**不得跳过**）。
+> **目标**：尽早发现字段丢失、伪父格、绑定失败、超链接被冲掉，避免「设计器看着有格、取数/父格全错」。
+
+---
+
+## 一、父格坐标语义（勿混）
+
+| API `leftX/leftY` 或 `topX/topY` | 设计器含义 | 说明 |
+|----------------------------------|------------|------|
+| **`-1, -1`** | **默认** 或 **无** | 普通 Const / 单数据集 Field 的常见正确态 |
+| **`0, 0`** | **自定义 → 原点 (0,0)** | **不是默认**；写成 0,0 会显示父格「不对」 |
+| **其它 `x,y`** | **自定义** 指向该坐标 | 多数据集入口、交叉、**超链接占位依赖**等 |
+
+---
+
+## 二、按单元格类型的父格规则
+
+### 2.1 普通 Const（表头 / 标题 / 无链接）
+
+| 项 | 规则 |
+|----|------|
+| 左父格 | **`-1,-1`** |
+| 上父格 | **`-1,-1`** |
+| 禁止 | `(0,0)`；勿把「默认」误写成原点 |
+
+### 2.2 超链接 Const（`pcHreflink` / `h5Hreflink`，URL 含 `{L4}` `{C4}` 等）
+
+> **事故**：把「左父格默认」套到「点击查看」上 → 设计器左/上显示不对，且 `{L4}` 无法解析；或重建 workbook 时丢掉 `ConstCellType.cellText` → 保存后 `cellText` 变空、`pcHreflink` 丢失。
+
+| 项 | 规则 | 例（供应商表 M4） |
+|----|------|-------------------|
+| **上父格** | 无横向扩展时必须 **`topX=topY=-1`**（不需要上父格） | `(-1,-1)` |
+| **左父格** | **禁止**一律改成默认；须指向占位符依赖的数据格 | `{L4}` → 左父格 **`(3,11)`**（同行「数据ID」） |
+| **链接元数据** | 须进 **workbook `ConstCellType`**（`pcHreflink`/`openType`/`cellText`/`left*`/`top*`）；仅写 `fields[]` **不够** | `/sp/ebdfpage/card/0/{sourceId}/{L4}` |
+| **workbook** | `ConstCellType` 必须含：`cellText`、`leftX/leftY/topX/topY`、有链接时还要 `pcHreflink` | 服务端 `saveReportDevInfo` **从 cellType 回写 fields**；缺 `leftX` → Java int **0** → 伪 `(0,0)`；缺 `pcHreflink` → 链接丢失 |
+| **禁止** | 只塞 `{typeName,cellText}` 的残 ConstCellType；禁止左=`(0,0)`；禁止有 `{Ln}` 却左=`-1,-1` |
+
+**占位符 → 左父格**（自检算法）：
+
+1. 从 `pcHreflink`/`h5Hreflink` 提取 `{L4}` / `{C4}` / `{Ln}` 等。
+2. `{L4}`：同行纵向扩展语境下，左父格应指向同列（或约定列）上提供 ID 的 Field（本需求为 `(3,11)`）。
+3. 若 URL 含占位而 `leftX/leftY === -1` → **FAIL**（不是「默认正确」）。
+4. 若 `topX/topY !== -1` 且无横向交叉需求 → **FAIL**。
+
+### 2.3 Field（单数据集、无指定计算）
+
+| 场景 | 左父格 |
+|------|--------|
+| **新建**报表 | 优先 **`-1,-1`（默认）** |
+| **已有**报表 | **禁止**用户未点名时批量改父格 |
+
+---
+
+## 三、保存门禁（每次 `saveReportDevInfo`）
+
+### 保存前
+
+1. `fields` 中 `cellType=Field` 数量 ≥ 保存前（或与预期列数一致）。
+2. workbook `dataTable` 内 `FieldCellType` 数量 ≥ Field 数。
+3. 每个 **Const**：workbook `ConstCellType` 须含 `cellText`（有文案时）以及显式 **`leftX/leftY/topX/topY`（常用 -1，禁止省略）**。
+4. 每个 **超链接 Const**：`ConstCellType` 须含非空 `pcHreflink`、`openType`，且父格与 `fields` 一致（服务端以 workbook 为准回写）。
+5. 每个 Field：`name` ∈ `fieldsAndOriginFields.fieldsKey[].name`（须带 `field_`；禁止裸雪花 ID）。
+   - 拉 fieldsKey 参数名用 **`datasetId`**（不是 `dataSetId`）。
+
+### 保存后立刻回读
+
+| 检查项 | 失败标准 |
+|--------|----------|
+| Field 数量 | 比保存前减少 → **立即失败**，禁止再改，优先恢复 |
+| Field.`name` | 裸 ID 或不在 fieldsKey → FAIL（`e10-cli report verify bind`） |
+| 普通 Const 父格 | `left=top=(0,0)` → FAIL（伪自定义 A1） |
+| 超链接 Const | 缺 `pcHreflink` / `cellText` 空 / `top≠-1` / 含 `{L*}` 但 `left=-1` 或 `left=(0,0)` → FAIL |
+| 同数据集 leftFilterField | Field 上仍有跨源 leftFilter → WARN/FAIL |
+
+```bash
+e10-cli report verify bind <reportId> [appId]     # 字段绑定
+e10-cli report verify self <reportId> [appId]     # 父格/超链接自检
+e10-cli report verify all <reportId> [appId]      # 自检 + 绑定（推荐）
+```
+
+---
+
+## 四、Agent 自检脚本逻辑（摘要）
+
+```javascript
+function assertParents(fields) {
+  for (const f of fields) {
+    if (f.cellType !== 'Const') continue;
+    const origin =
+      f.leftX === 0 && f.leftY === 0 && f.topX === 0 && f.topY === 0;
+    const href = f.pcHreflink || f.h5Hreflink || '';
+    if (origin && !href) {
+      throw new Error(`Const(${f.x},${f.y}) 父格(0,0)=伪自定义A1，应为-1,-1`);
+    }
+    if (!href) continue;
+    // 超链接：上父格默认无
+    if (f.topX !== -1 || f.topY !== -1) {
+      throw new Error(`链接格(${f.x},${f.y}) 不需要上父格，top 应为 -1,-1`);
+    }
+    if (!f.cellText) {
+      throw new Error(`链接格(${f.x},${f.y}) cellText 为空（workbook 可能未写 ConstCellType）`);
+    }
+    // URL 占位依赖左父格，禁止「默认」
+    if (/\{L\d+\}|\{C\d+\}/.test(href)) {
+      if (f.leftX === -1 && f.leftY === -1) {
+        throw new Error(`链接格(${f.x},${f.y}) 含占位符但左父格为默认，应指向依赖数据格`);
+      }
+      if (f.leftX === 0 && f.leftY === 0) {
+        throw new Error(`链接格(${f.x},${f.y}) 左父格不能为(0,0)`);
+      }
+    }
+  }
+}
+
+function assertWorkbookConstCellType(dataTable, fields) {
+  for (const f of fields) {
+    if (f.cellType !== 'Const') continue;
+    const cell = dataTable?.[String(f.x)]?.[String(f.y)];
+    const ct = cell?.style?.cellType;
+    if (!ct || ct.typeName !== 'ConstCellType') {
+      throw new Error(`workbook 缺 ConstCellType @(${f.x},${f.y})`);
+    }
+    if ((f.cellText || f.text) && !ct.cellText) {
+      throw new Error(`workbook 缺 cellText @(${f.x},${f.y})，保存会冲掉文案`);
+    }
+    // 缺 leftX 时服务端写成 0 → 伪自定义 A1
+    for (const k of ['leftX', 'leftY', 'topX', 'topY']) {
+      if (ct[k] === undefined || ct[k] === null) {
+        throw new Error(`workbook ConstCellType 缺 ${k} @(${f.x},${f.y})，会落成 0`);
+      }
+    }
+    if (f.pcHreflink && ct.pcHreflink !== f.pcHreflink) {
+      throw new Error(`workbook 缺/错 pcHreflink @(${f.x},${f.y})（服务端只认 cellType）`);
+    }
+  }
+}
+
+function assertFieldPreserved(before, after) {
+  const n = (fs) => fs.filter((f) => f.cellType === 'Field').length;
+  if (n(after) < n(before)) throw new Error('Field 被冲掉，禁止继续改');
+}
+```
+
+---
+
+## 五、与交付节奏
+
+- 布局落库成功 → **先交设计器地址**（`report-delivery-contract.md` §〇）。
+- 本节自检可后台跑；**FAIL 必须补丁修复并告知**，不得假装完成。
+- **禁止**：为修一格 Const 父格而提交残缺 workbook（会导致 Field 全变 Const，或 Const 文案/超链接被冲掉）。修父格必须 **整表 Field + ConstCellType 完整写入 workbook**。
+
+---
+
+## 六、相关文档
+
+| 文档 | 关系 |
+|------|------|
+| `field-bind-exact-match-guide.md` | name ∈ fieldsKey |
+| `datasource-selection-and-parent-filter-guide.md` §〇 | 单数据集左父格默认；**勿**套用到超链接 Const；勿擅自改已有表 |
+| `safe-partial-save-guide.md` | 禁止空 workbook；须从 fields 重建 dataTable |
+| `e10-cli report verify bind` | 绑定门禁 |
+| `targeted-fix-guide.md` | 用户点名某处不对时禁止整表重扫 |

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

@@ -0,0 +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 证据。