weaver-e10-builder 1.6.15 → 1.6.16

package/skill-docs/references/report/report-internal-error-guide.md

@@ -1,149 +1,149 @@
-# 报表内部错误 · 规则校验 / 修复 / 优化
-
-> **现象**：接口或页面返回 `code=500` / `msg=报表内部错误`，或列表页整页失败。
-> **原则**：先用 CLI 校验定位，再定点修复；禁止反复对损坏壳盲 save。
-> **相关**：`report-baseinfo-defaults-guide.md` · `condition-format-guide.md` · `api-report-build-fast-path.md` · `safe-partial-save-guide.md`
-
----
-
-## 一、常见根因速查
-
-| 根因 | 典型表现 | 校验 | 修复 |
-|------|----------|------|------|
-| `nameLabelId` 含 `\r\n` 等控制符 | 应用报表列表 `list?groupid=-1` 整页 500 | `e10-cli report verify meta` | `baseInfo` 强制改写干净 `name` + `nameLabelId=-1` |
-| `name` 含控制符 / 保存时 `name` 为空/`undefined` | `saveReportDevInfo` → 报表内部错误 | `validate base`；保存前从 `baseInfo` 取名 | multipart `name` 必填且干净 |
-| `groupId=-1` 入库 | 与 list「全部」哨兵易混淆；部分租户 baseInfo 默认即 `-1` | `verify meta`（warning） | **勿擅自改**；保存时 `baseInfo.groupId` 原样回传；新建未指定用 `0` |
-| workbook / designKey 错乱 | 偶发 500 或「数据不是最新」 | 回读 `designKey` | 用当次 `getReportDevInfo.designKey`；必要时新会话 |
-| **空 workbook 落库**（提交 `sheets:{}`） | 保存控制台报错 / 布局被清空 | 保存前 rebuild 后 cells=0 且 fields>0 | 从 fields 重建完整 Sheet1 + spans 再 save；**禁止**把读到的空 sheets 原样回写 |
-| **`(0,0)` 空 Const 幽灵格** | 异常格、父格误判、保存预检失败 | fields 含 x=0,y=0 且 text 空 | **删除该幽灵格**后再重建 workbook |
-| **cell `transSelectOptions` 为空串 `""` 或 `{}`** | `saveReportDevInfo` → **500「报表内部错误」**（与格内容无关，最小 1 格也 500） | `e10-cli report verify all`；或看 cellType 里的空值键 | **省略该键**（只在非空数组时写入）；注意 `[]`（数组，含空数组）**合法**，勿误删 —— 注意点 **BUILD-33** |
-| **workbook sheet 含 `gridline` 键** | `saveReportDevInfo` → **500「报表内部错误」**（二分：存在即 500） | `e10-cli report validate gridline` | **删除** sheets.* 上的 `gridline`/`gridLine`/`__gridline`；网格线只写 page 层 `gridLine:0\|1` |
-| **`workbook` 载荷形态**（应传明文 JSON 却传了 gzip+base64） | `saveReportDevInfo` → **500「报表内部错误」**，且**与格内容无关**（1 格表 / 最小平铺表也 500） | 0 位移判别：同一 workbook 分别发「不带 / 空串 / 明文 / gzip+b64 / 明文再 b64」→ 只有**明文=200**（见 §三.0） | 改用**明文 JSON**。脚本一律走 构建层（**自适应**：先发 gzip+b64，非 200 自动回退明文）—— 注意点 **BUILD-39** |
-| **multipart 缺 `et` 表单字段**（部分自建环境） | `saveReportDevInfo` → **`token empty or invalid`**（HTTP 200 body 或 401），或 500「报表内部错误」 | 对比「带/不带 `et` 字段」各发一次 | 走 `saveReportDevInfoAuto`（载荷矩阵自动追加 `et` = 当前 ETEAMSID）—— 注意点 **ENV-11** |
-| **Formula 格 `refX`/`refY` 非 -1** | 不 500，但**预览第一行正常、后续行渲染乱码**（扩展带公式格） | `e10-cli report verify all`（R7） | 落库前把 `style.cellType` 的 `refX/refY` 归 -1（防御层 R7 已自动）—— 注意点 **BUILD-46** |
-| **Formula 格 `subordination:[]` / `expandType:Vertical`** | 不 500，但**浏览器端渲染出 `p1900rc1900nt` 乱码**（公式区间横跨另一公式格时依赖链建不起来） | `e10-cli report verify all`（R8） | 落库前 force `subordination=["",""]` + `expandType="NoExpand"`（防御层 R8 已自动）—— 注意点 **BUILD-49** |
-| **`style.formatter` 落成短码**（`common`…） | 不 500，但**预览显示字面量 `co12on`** | `e10-cli report verify all`（R9） | 按 数字格式目录 换合法格式串（防御层 R9 已自动）—— 注意点 **BUILD-47** |
-
-> **注意**：`getReportDevInfo` 回读时 `workbookProps.sheets` 常为 `{}`、`sheetCount=0`（与正常报表一致，布局在 `fields`）。判断「空 workbook」以**保存载荷**是否含 cell 为准，不要因回读 sheets 空就乱改 `groupId` 或清布局。
-
-> ### 复制 500 的正解（2026-09-15 二次更正）
-> 复制失败**只有**「数据集形态」这一列会触发，且判据是**大小写**，不是「类型叫 LOGIC」：
-> - ✅ `type="logic"`（小写）= 设计器「+」/ 页面手动建表口径 → copySheet **200**
-> - ❌ `type="LOGIC"`（大写）= 脚本 `addDataset` 传 `sourceType=LOGIC` 的产物 → copySheet **500**
->
-> 决定性实验：同应用 + **同表单** 两张空壳，唯一差别是挂数据集时 `--source-type logic` / `--source-type LOGIC`
-> → **200 / 500**。带数据集与字段的**手动建表复制本来就正常**，所以「LOGIC 一类都不可复制」的说法是错的。
-> 一键处置：`e10-cli report copy-health`（诊断）→ `e10-cli report dataset heal --purge --apply`（修复）→ 复查 `copy-health`。
-| **数据集 `type` 是大写 `LOGIC`**（复制 500 的**真因**） | **`GET copySheet` 复制报表 → body `code=500`「报表内部错误」**（HTTP 仍是 200）；`type="logic"`（小写，即设计器/手动建表口径）→ **200**。与分组 / AI 建表 / 字段数量全都无关 | `e10-cli report copy-health --report-id <rid> --app-id <appId>`；或 `e10-cli report dataset list --report-id <rid> --app-id <appId> --raw` 看 `type` 大小写 | `e10-cli report dataset heal --report-id <rid> --app-id <appId> [--purge] --apply`（replaceDataset 原地换型，单元格 `dataSetId`/`fieldKey` 服务端自动重映射，格数/公式/布局零损失）。**源头**：新建数据集一律 `sourceType=logic`（小写），见 `add-dataset-registration-guide.md` §二；注意点 **BUILD-29** |
-| **数据集 `sourceId` 为空**（半成品 / 跨应用残留） | 同样让 copySheet 报 500 | 同上（`--raw` 看 `sourceId`） | `e10-cli report dataset heal --purge --apply`（删除该脏数据集；删前自动 checkDataSetUsed） |
-| **`groupId=0` 孤儿分组** | 该报表在「菜单选取 / 按分组枚举」里**列不出来**（全应用只有手动建的能被选到）；**与复制 500 无关**（改成 -1 后复制仍 500，已证伪两轮） | `e10-cli report group audit --app-id <appId>`（命中 exit 3） | `e10-cli report group sync --app-id <appId> --apply`（批量对齐到页面手动建表口径 `-1`）或 `group set --report-id <rid> --group-id -1 --apply` |
-| 条件格式 `highlight:between` 等非法算子 | **不一定 500**，但规则**静默不生成** | `e10-cli report verify condition` | 改为 `highlight:interval` 等白名单 |
-
-### §三.0 · `workbook` 载荷形态判别（0 位移实验 · 注意点 BUILD-39）
-
-**触发**：`saveReportDevInfo` 恒 500「报表内部错误」，且**连最小平铺表 / 手写 1 格 workbook 也 500**（排除布局、跨源筛选、gridline 后仍 500）。
-
-**判别**（同一空壳 + 同一 workbook，**只换 `workbook` 字段形态**；2026-10-09 在 `<客户自建站点>` 实证）：
-
-| 载荷形态 | 结果 |
-|---|---|
-| 不带 `workbook` 字段 | `400` |
-| 空串 `''` | `500 报表内部错误` |
-| **明文 JSON** | **`200 接口返回成功`** ✅ |
-| gzip + base64（技能历史默认） | `500 报表内部错误` |
-| 明文 JSON 再 base64 | `500 报表内部错误` |
-
-**结论**：部分自建环境的服务端**只接受明文 JSON**；技能历史统一发的 gzip+base64 会被解析失败 → 整表 500，**与格内容无关**。
-
-**兼容写法（已固化到脚本）**：`spec_lib.saveReportDevInfoAuto({ reportId, appId, name, groupId, workbook, ... })` —— 先发 gzip+b64，非 200 自动回退明文。`build_from_spec` / `safe_report_save`（含 `safeSaveReportDevInfo`）/ `card_ops` / `rebuild_from_blueprint` / `restore_cell` / `restore_report_from_version` / `preagg_ops` / `formula_parent_ops` / `fix_field_binding` / `set_freeze_cells` / `fix_table_name_echo` 均已改走自适应通道。
-
-> ⚠️ 判别实验**必须在一次性空壳上做**（save 是整份替换、无 dry-run、200 即落库）——见 `failure-cleanup-and-nonblocking-guide.md`。
-
-### §三.1 · 部分自建环境 `saveReportDevInfo` 硬规则（注意点 ENV-11）
-
-> 与 §三.0 的「只认明文」环境**互斥**：另有部分自建环境要求 **gzipB64 + `et` 字段**（明文反而 500）。
-
-| 硬规则 | 缺了会怎样 | 对策 |
-|--------|-----------|------|
-| multipart **必须含 `et` 表单字段** | `token empty or invalid`（HTTP 200 body / 401） | `saveReportDevInfoAuto` 载荷矩阵自动追加 `et` = 当前 ETEAMSID |
-| workbook 走 **gzipB64** | 传明文 → 500「报表内部错误」 | 同上（矩阵：无 et `gzipB64` → 明文 → 有 et `gzipB64` → 有 et 明文） |
-| `stripWorkbookGridlineKeys` **始终必调** | sheet 带 gridline 族键 → 500 | JS 侧 = 防御层 **R1**（`saveReportDevInfoAuto` 每次落库前自动执行）；Python 侧函数名即为 `stripWorkbookGridlineKeys` |
-| `ETEAMSID` **按环境隔离** | A 环境凭证在 B 环境同样报 token invalid | 按 host 分别保存凭证；**失效直接向用户索要新的，勿反复重试** |
-| `ETEAMSID` **会过期** | 报「登录超时」 | 重新 `e10-cli auth status` / 请用户给新值 |
-| 沙箱 **`spawn EBUSY`** | 拿不到凭证 | 统一走 **env 三件套**：`EB_HOST` + `EB_ETEAMSID` + `EB_AUTH_NO_CLI=1`（零 spawn） |
-
-```bash
-e10-cli auth status
-`e10-cli report verify all`
-export EB_HOST='<平台地址>' EB_ETEAMSID='<值>' EB_AUTH_NO_CLI=1
-```
-
----
-
-## 二、强制校验门禁（落库前 / 交付前）
-
-> **★ 一键体检（首选）**：所有已知 500 成因已收口到 ``，用**一条命令**查完/修完：
->
-> ```bash
-> `e10-cli report verify all`
-> `e10-cli report verify all`
-> `e10-cli report verify all`
-> ```
->
-> **`saveReportDevInfoAuto` 每次落库前已自动过防御层**（剔除 gridline 族键 / transSelectOptions 空串 /
-> (0,0) 幽灵格 + 规范化 name/nameLabelId），任何调用方传脏 workbook 也不会再因这些成因 500；
-> `EB_SAVE_NO_SANITIZE=1` 可关闭（仅对照诊断）。载荷形态（gzip vs 明文）仍由该通道自适应回退。注意点 **BUILD-41**。
->
-> 下列细分门禁仍可用于**定点校验**：
-
-```bash
-# 1) base 元数据（防列表 500）
-e10-cli report validate base --name "报表名" --name-label-id -1 --group-id 0
-e10-cli report verify meta <reportId> [appId]
-
-# 2) 网格线（防 workbook.gridline → 500「报表内部错误」）
-e10-cli report validate gridline --file workbook-or-patch.json
-e10-cli report verify gridline <reportId> [appId]
-
-# 3) 条件格式（防静默丢规则 / 冲突）
-e10-cli report validate condition --file rule.json
-e10-cli report verify condition <reportId> [appId]
-
-# 4) 综合
-e10-cli report verify all <reportId> [appId]
-```
-
-| 时机 | 必须 |
-|------|------|
-| `baseInfo` / `saveReportDevInfo` **前** | `validate base`；**`validate gridline`（workbook 禁含 gridline 键）** |
-| 写入条件格式 **前** | `validate condition`（白名单 + 冲突 warnings） |
-| 交付 / 定点改完 | `verify meta` + `verify gridline` + `verify condition` 或 `verify all` |
-| `validate`/`verify` exit≠0 | **禁止**跳过继续 save；有 warnings（冲突）须**提示用户确认** |
-
----
-
-## 三、修复优化步骤
-
-1. **定位**：`verify meta` → 看 name/nameLabelId/groupId；`verify condition` → 看非法 relation / 冲突。
-2. **元数据**：干净 `name` + `nameLabelId` 用 baseInfo 原值；**`groupId` 用 baseInfo 原值，禁止脚本硬编码**（改分组仅用户明确要求后 `removeReport`）。
-3. **布局保存**：`name`/`groupId`/`nameLabelId` 从 `baseInfo` 读取；带当前 `designKey`；`mergeWorkbookSafe` 防空表；**若 `sheets` 空但 fields 有内容 → 从 fields 重建 workbook（含 spans）**；**剔除 `(0,0)` 空 Const**；**剔除 sheets.* 上的 `gridline` 族键**。
-4. **条件格式**：`between`→`interval`；区间一条介于；重叠档位请用户确认后改 `interval`+`greater`。
-5. **壳已损坏**（空 fields + 持续 500）：`cleanup shells` / `lifecycle delete` 后按临时名重建（见 `failure-cleanup-and-nonblocking-guide.md`）。
-6. **列表页**：修完后用 `groupid=-1` 与真实分组各拉一次 list，确认不再 500。
-
----
-
-## 四、与条件格式的关系
-
-「报表内部错误」≠「条件格式不显示」。
-非法 `relation`（如 `between`）通常**不抛 500**，而是引擎跳过 → 设计器无规则。
-两者都纳入 **同一交付校验包**：`verify all` = 自检 + 绑定 + **条件格式** +（建议另跑）`verify meta`。
-
-详见 `condition-format-guide.md` §CLI。
-
----
-
-## 五、Agent 话术（冲突 / 不支持）
-
-- 元数据失败：直接报 CLI errors，禁止编造默认值绕过。
-- 条件格式映射失败 / 冲突：按 `condition-format-guide.md` §四、§五 **请用户确认** 后再写入。
+# 报表内部错误 · 规则校验 / 修复 / 优化
+
+> **现象**：接口或页面返回 `code=500` / `msg=报表内部错误`，或列表页整页失败。
+> **原则**：先用 CLI 校验定位，再定点修复；禁止反复对损坏壳盲 save。
+> **相关**：`report-baseinfo-defaults-guide.md` · `condition-format-guide.md` · `api-report-build-fast-path.md` · `safe-partial-save-guide.md`
+
+---
+
+## 一、常见根因速查
+
+| 根因 | 典型表现 | 校验 | 修复 |
+|------|----------|------|------|
+| `nameLabelId` 含 `\r\n` 等控制符 | 应用报表列表 `list?groupid=-1` 整页 500 | `e10-cli report verify meta` | `baseInfo` 强制改写干净 `name` + `nameLabelId=-1` |
+| `name` 含控制符 / 保存时 `name` 为空/`undefined` | `saveReportDevInfo` → 报表内部错误 | `validate base`；保存前从 `baseInfo` 取名 | multipart `name` 必填且干净 |
+| `groupId=-1` 入库 | 与 list「全部」哨兵易混淆；部分租户 baseInfo 默认即 `-1` | `verify meta`（warning） | **勿擅自改**；保存时 `baseInfo.groupId` 原样回传；新建未指定用 `0` |
+| workbook / designKey 错乱 | 偶发 500 或「数据不是最新」 | 回读 `designKey` | 用当次 `getReportDevInfo.designKey`；必要时新会话 |
+| **空 workbook 落库**（提交 `sheets:{}`） | 保存控制台报错 / 布局被清空 | 保存前 rebuild 后 cells=0 且 fields>0 | 从 fields 重建完整 Sheet1 + spans 再 save；**禁止**把读到的空 sheets 原样回写 |
+| **`(0,0)` 空 Const 幽灵格** | 异常格、父格误判、保存预检失败 | fields 含 x=0,y=0 且 text 空 | **删除该幽灵格**后再重建 workbook |
+| **cell `transSelectOptions` 为空串 `""` 或 `{}`** | `saveReportDevInfo` → **500「报表内部错误」**（与格内容无关，最小 1 格也 500） | `e10-cli report verify all`；或看 cellType 里的空值键 | **省略该键**（只在非空数组时写入）；注意 `[]`（数组，含空数组）**合法**，勿误删 —— 注意点 **BUILD-33** |
+| **workbook sheet 含 `gridline` 键** | `saveReportDevInfo` → **500「报表内部错误」**（二分：存在即 500） | `e10-cli report validate gridline` | **删除** sheets.* 上的 `gridline`/`gridLine`/`__gridline`；网格线只写 page 层 `gridLine:0\|1` |
+| **`workbook` 载荷形态**（应传明文 JSON 却传了 gzip+base64） | `saveReportDevInfo` → **500「报表内部错误」**，且**与格内容无关**（1 格表 / 最小平铺表也 500） | 0 位移判别：同一 workbook 分别发「不带 / 空串 / 明文 / gzip+b64 / 明文再 b64」→ 只有**明文=200**（见 §三.0） | 改用**明文 JSON**。脚本一律走 构建层（**自适应**：先发 gzip+b64，非 200 自动回退明文）—— 注意点 **BUILD-39** |
+| **multipart 缺 `et` 表单字段**（部分自建环境） | `saveReportDevInfo` → **`token empty or invalid`**（HTTP 200 body 或 401），或 500「报表内部错误」 | 对比「带/不带 `et` 字段」各发一次 | 走 `saveReportDevInfoAuto`（载荷矩阵自动追加 `et` = 当前 ETEAMSID）—— 注意点 **ENV-11** |
+| **Formula 格 `refX`/`refY` 非 -1** | 不 500，但**预览第一行正常、后续行渲染乱码**（扩展带公式格） | `e10-cli report verify all`（R7） | 落库前把 `style.cellType` 的 `refX/refY` 归 -1（防御层 R7 已自动）—— 注意点 **BUILD-46** |
+| **Formula 格 `subordination:[]` / `expandType:Vertical`** | 不 500，但**浏览器端渲染出 `p1900rc1900nt` 乱码**（公式区间横跨另一公式格时依赖链建不起来） | `e10-cli report verify all`（R8） | 落库前 force `subordination=["",""]` + `expandType="NoExpand"`（防御层 R8 已自动）—— 注意点 **BUILD-49** |
+| **`style.formatter` 落成短码**（`common`…） | 不 500，但**预览显示字面量 `co12on`** | `e10-cli report verify all`（R9） | 按 数字格式目录 换合法格式串（防御层 R9 已自动）—— 注意点 **BUILD-47** |
+
+> **注意**：`getReportDevInfo` 回读时 `workbookProps.sheets` 常为 `{}`、`sheetCount=0`（与正常报表一致，布局在 `fields`）。判断「空 workbook」以**保存载荷**是否含 cell 为准，不要因回读 sheets 空就乱改 `groupId` 或清布局。
+
+> ### 复制 500 的正解（2026-09-15 二次更正）
+> 复制失败**只有**「数据集形态」这一列会触发，且判据是**大小写**，不是「类型叫 LOGIC」：
+> - ✅ `type="logic"`（小写）= 设计器「+」/ 页面手动建表口径 → copySheet **200**
+> - ❌ `type="LOGIC"`（大写）= 脚本 `addDataset` 传 `sourceType=LOGIC` 的产物 → copySheet **500**
+>
+> 决定性实验：同应用 + **同表单** 两张空壳，唯一差别是挂数据集时 `--source-type logic` / `--source-type LOGIC`
+> → **200 / 500**。带数据集与字段的**手动建表复制本来就正常**，所以「LOGIC 一类都不可复制」的说法是错的。
+> 一键处置：`e10-cli report copy-health`（诊断）→ `e10-cli report dataset heal --purge --apply`（修复）→ 复查 `copy-health`。
+| **数据集 `type` 是大写 `LOGIC`**（复制 500 的**真因**） | **`GET copySheet` 复制报表 → body `code=500`「报表内部错误」**（HTTP 仍是 200）；`type="logic"`（小写，即设计器/手动建表口径）→ **200**。与分组 / AI 建表 / 字段数量全都无关 | `e10-cli report copy-health --report-id <rid> --app-id <appId>`；或 `e10-cli report dataset list --report-id <rid> --app-id <appId> --raw` 看 `type` 大小写 | `e10-cli report dataset heal --report-id <rid> --app-id <appId> [--purge] --apply`（replaceDataset 原地换型，单元格 `dataSetId`/`fieldKey` 服务端自动重映射，格数/公式/布局零损失）。**源头**：新建数据集一律 `sourceType=logic`（小写），见 `add-dataset-registration-guide.md` §二；注意点 **BUILD-29** |
+| **数据集 `sourceId` 为空**（半成品 / 跨应用残留） | 同样让 copySheet 报 500 | 同上（`--raw` 看 `sourceId`） | `e10-cli report dataset heal --purge --apply`（删除该脏数据集；删前自动 checkDataSetUsed） |
+| **`groupId=0` 孤儿分组** | 该报表在「菜单选取 / 按分组枚举」里**列不出来**（全应用只有手动建的能被选到）；**与复制 500 无关**（改成 -1 后复制仍 500，已证伪两轮） | `e10-cli report group audit --app-id <appId>`（命中 exit 3） | `e10-cli report group sync --app-id <appId> --apply`（批量对齐到页面手动建表口径 `-1`）或 `group set --report-id <rid> --group-id -1 --apply` |
+| 条件格式 `highlight:between` 等非法算子 | **不一定 500**，但规则**静默不生成** | `e10-cli report verify condition` | 改为 `highlight:interval` 等白名单 |
+
+### §三.0 · `workbook` 载荷形态判别（0 位移实验 · 注意点 BUILD-39）
+
+**触发**：`saveReportDevInfo` 恒 500「报表内部错误」，且**连最小平铺表 / 手写 1 格 workbook 也 500**（排除布局、跨源筛选、gridline 后仍 500）。
+
+**判别**（同一空壳 + 同一 workbook，**只换 `workbook` 字段形态**；2026-10-09 在 `<客户自建站点>` 实证）：
+
+| 载荷形态 | 结果 |
+|---|---|
+| 不带 `workbook` 字段 | `400` |
+| 空串 `''` | `500 报表内部错误` |
+| **明文 JSON** | **`200 接口返回成功`** ✅ |
+| gzip + base64（技能历史默认） | `500 报表内部错误` |
+| 明文 JSON 再 base64 | `500 报表内部错误` |
+
+**结论**：部分自建环境的服务端**只接受明文 JSON**；技能历史统一发的 gzip+base64 会被解析失败 → 整表 500，**与格内容无关**。
+
+**兼容写法（已固化到脚本）**：`spec_lib.saveReportDevInfoAuto({ reportId, appId, name, groupId, workbook, ... })` —— 先发 gzip+b64，非 200 自动回退明文。`build_from_spec` / `safe_report_save`（含 `safeSaveReportDevInfo`）/ `card_ops` / `rebuild_from_blueprint` / `restore_cell` / `restore_report_from_version` / `preagg_ops` / `formula_parent_ops` / `fix_field_binding` / `set_freeze_cells` / `fix_table_name_echo` 均已改走自适应通道。
+
+> ⚠️ 判别实验**必须在一次性空壳上做**（save 是整份替换、无 dry-run、200 即落库）——见 `failure-cleanup-and-nonblocking-guide.md`。
+
+### §三.1 · 部分自建环境 `saveReportDevInfo` 硬规则（注意点 ENV-11）
+
+> 与 §三.0 的「只认明文」环境**互斥**：另有部分自建环境要求 **gzipB64 + `et` 字段**（明文反而 500）。
+
+| 硬规则 | 缺了会怎样 | 对策 |
+|--------|-----------|------|
+| multipart **必须含 `et` 表单字段** | `token empty or invalid`（HTTP 200 body / 401） | `saveReportDevInfoAuto` 载荷矩阵自动追加 `et` = 当前 ETEAMSID |
+| workbook 走 **gzipB64** | 传明文 → 500「报表内部错误」 | 同上（矩阵：无 et `gzipB64` → 明文 → 有 et `gzipB64` → 有 et 明文） |
+| `stripWorkbookGridlineKeys` **始终必调** | sheet 带 gridline 族键 → 500 | JS 侧 = 防御层 **R1**（`saveReportDevInfoAuto` 每次落库前自动执行）；Python 侧函数名即为 `stripWorkbookGridlineKeys` |
+| `ETEAMSID` **按环境隔离** | A 环境凭证在 B 环境同样报 token invalid | 按 host 分别保存凭证；**失效直接向用户索要新的，勿反复重试** |
+| `ETEAMSID` **会过期** | 报「登录超时」 | 重新 `e10-cli auth status` / 请用户给新值 |
+| 沙箱 **`spawn EBUSY`** | 拿不到凭证 | 统一走 **env 三件套**：`EB_HOST` + `EB_ETEAMSID` + `EB_AUTH_NO_CLI=1`（零 spawn） |
+
+```bash
+e10-cli auth status
+`e10-cli report verify all`
+export EB_HOST='<平台地址>' EB_ETEAMSID='<值>' EB_AUTH_NO_CLI=1
+```
+
+---
+
+## 二、强制校验门禁（落库前 / 交付前）
+
+> **★ 一键体检（首选）**：所有已知 500 成因已收口到 ``，用**一条命令**查完/修完：
+>
+> ```bash
+> `e10-cli report verify all`
+> `e10-cli report verify all`
+> `e10-cli report verify all`
+> ```
+>
+> **`saveReportDevInfoAuto` 每次落库前已自动过防御层**（剔除 gridline 族键 / transSelectOptions 空串 /
+> (0,0) 幽灵格 + 规范化 name/nameLabelId），任何调用方传脏 workbook 也不会再因这些成因 500；
+> `EB_SAVE_NO_SANITIZE=1` 可关闭（仅对照诊断）。载荷形态（gzip vs 明文）仍由该通道自适应回退。注意点 **BUILD-41**。
+>
+> 下列细分门禁仍可用于**定点校验**：
+
+```bash
+# 1) base 元数据（防列表 500）
+e10-cli report validate base --name "报表名" --name-label-id -1 --group-id 0
+e10-cli report verify meta <reportId> [appId]
+
+# 2) 网格线（防 workbook.gridline → 500「报表内部错误」）
+e10-cli report validate gridline --file workbook-or-patch.json
+e10-cli report verify gridline <reportId> [appId]
+
+# 3) 条件格式（防静默丢规则 / 冲突）
+e10-cli report validate condition --file rule.json
+e10-cli report verify condition <reportId> [appId]
+
+# 4) 综合
+e10-cli report verify all <reportId> [appId]
+```
+
+| 时机 | 必须 |
+|------|------|
+| `baseInfo` / `saveReportDevInfo` **前** | `validate base`；**`validate gridline`（workbook 禁含 gridline 键）** |
+| 写入条件格式 **前** | `validate condition`（白名单 + 冲突 warnings） |
+| 交付 / 定点改完 | `verify meta` + `verify gridline` + `verify condition` 或 `verify all` |
+| `validate`/`verify` exit≠0 | **禁止**跳过继续 save；有 warnings（冲突）须**提示用户确认** |
+
+---
+
+## 三、修复优化步骤
+
+1. **定位**：`verify meta` → 看 name/nameLabelId/groupId；`verify condition` → 看非法 relation / 冲突。
+2. **元数据**：干净 `name` + `nameLabelId` 用 baseInfo 原值；**`groupId` 用 baseInfo 原值，禁止脚本硬编码**（改分组仅用户明确要求后 `removeReport`）。
+3. **布局保存**：`name`/`groupId`/`nameLabelId` 从 `baseInfo` 读取；带当前 `designKey`；`mergeWorkbookSafe` 防空表；**若 `sheets` 空但 fields 有内容 → 从 fields 重建 workbook（含 spans）**；**剔除 `(0,0)` 空 Const**；**剔除 sheets.* 上的 `gridline` 族键**。
+4. **条件格式**：`between`→`interval`；区间一条介于；重叠档位请用户确认后改 `interval`+`greater`。
+5. **壳已损坏**（空 fields + 持续 500）：`cleanup shells` / `lifecycle delete` 后按临时名重建（见 `failure-cleanup-and-nonblocking-guide.md`）。
+6. **列表页**：修完后用 `groupid=-1` 与真实分组各拉一次 list，确认不再 500。
+
+---
+
+## 四、与条件格式的关系
+
+「报表内部错误」≠「条件格式不显示」。
+非法 `relation`（如 `between`）通常**不抛 500**，而是引擎跳过 → 设计器无规则。
+两者都纳入 **同一交付校验包**：`verify all` = 自检 + 绑定 + **条件格式** +（建议另跑）`verify meta`。
+
+详见 `condition-format-guide.md` §CLI。
+
+---
+
+## 五、Agent 话术（冲突 / 不支持）
+
+- 元数据失败：直接报 CLI errors，禁止编造默认值绕过。
+- 条件格式映射失败 / 冲突：按 `condition-format-guide.md` §四、§五 **请用户确认** 后再写入。