weaver-e10-builder 1.6.10 → 1.6.11

package/skill-docs/references/report/report-designer-feature-map.md

@@ -1,7 +1,7 @@
 # 报表设计器 · 功能全景与 API 对照
 
 > **页面**：`https://{host}/sp/edc/report/designer/{reportId}`
-> **示例**：`https://weapp.yunteams.cn/sp/edc/report/designer/1310535032076214273`
+> **示例**：`https://<平台地址>/sp/edc/report/designer/<reportId>`
 > **源码**：`EdcReportDevDesignController.java`、`EdcReportDevBaseController.java`（weaver-edcreportd）
 > **UI 说明**：`report-help-guide.md`、`report-building-guide.md`
 > **鉴权**：`api-auth-headers.md`（Cookie.raw + eteamsid + User-Agent）
@@ -10,7 +10,7 @@
 
 ## 一、设计器进入时加载链
 
-> **Live **（2026-09-04 · 报表 `1310535032076214273` · 浏览器自动化实际请求 + e10-login）见 §十一。
+> **Live 验证**（2026-09-04 · 报表 `1310535032076214273` · 浏览器自动化接口返回 + e10-cli auth）见 §十一。
 
 | 顺序 | 接口 | 说明 |
 |------|------|------|
@@ -33,18 +33,18 @@
 
 ```mermaid
 flowchart TB
- subgraph top["顶部 Ribbon + 右上角"]
- T1[开始]
- T2[页面]
- T3[公式]
- TR[保存 / 预览 / 历史版本]
- end
- subgraph body["主体"]
- L[左侧 · 数据集面板]
- C[中间 · SpreadJS 画布]
- R[右侧 · 单元格/事件/样式]
- end
- top --> body
+  subgraph top["顶部 Ribbon + 右上角"]
+    T1[开始]
+    T2[页面]
+    T3[公式]
+    TR[保存 / 预览 / 历史版本]
+  end
+  subgraph body["主体"]
+    L[左侧 · 数据集面板]
+    C[中间 · SpreadJS 画布]
+    R[右侧 · 单元格/事件/样式]
+  end
+  top --> body
 ```
 
 | 区域 | 作用 | 核心配置落点 |
@@ -117,7 +117,7 @@ flowchart TB
 
 | 功能 | UI 路径 | API | 说明 |
 |------|---------|-----|------|
-| **查询设置** | 页面 → 查询设置 | `GET getQueryConfig?sheetId={reportId}` | Live 打开面板即 GET |
+| **查询设置** | 页面 → 查询设置 | `GET getQueryConfig?sheetId={reportId}` | Live 验证：打开面板即 GET |
 | **更新查询类型** | 查询设置内 | `POST updateQueryType` | `queryType`: **`["advance"]` / `["filter"]`（JSON 数组）** ⚠️ 会批量覆盖所有条件的 `queryType` |
 | **+ 添加查询条件** | 页面 → + 添加 | `POST saveQueryItem` | 条件字段 JSON 数组 |
 | **删除条件** | 条件列表 | `POST delQueryItem` | 按 id |
@@ -190,7 +190,7 @@ flowchart TB
 #### 4.6.1 网格线 / 行号 / 列头 — 默认关闭（强制 · 防 500）
 
 > **平台常规默认关闭**。Agent **不得**在用户未明确要求时自行开启。
-> ** 固化**：`saveReportDevInfo` 曾 500「报表内部错误」，二分定位为 workbook sheet **多写了 `gridline` 字段（存在即 500）**，去掉即恢复。
+> **验证固化**：`saveReportDevInfo` 曾 500「报表内部错误」，二分定位为 workbook sheet **多写了 `gridline` 字段（存在即 500）**，去掉即恢复。
 > 落库前须 `e10-cli report validate gridline`（`validate blank` / `safe_report_save` 已联动剔除）。
 
 | 能力 | 关闭（默认 · 必须保持） | 开启（仅当会话明确要求） |
@@ -234,8 +234,8 @@ flowchart TB
 | 功能 | UI 路径 | API / 脚本 | 说明 |
 |------|---------|--------------|------|
 | 快照生成策略 | 页面 → 快照设置 | `saveReportDevInfo` + `workbook.snapshot` | cron 透传 escheduler；`functionName=createSnapshot` |
-| 定时快照脚本 | — | `e10-cli report snapshot set` / `e10-cli report snapshot set` | **必须**经 `safe_report_save.js`；默认名 **`{报表名}-{date}-{time}`**；`sheetId=String(reportId)` 禁 Number |
-| 空白门禁 | — | `validate_designer_blank_guard.js` / `verify blank` | 见 `designer-blank-prevention-guide.md` |
+| 定时快照脚本 | — | `e10-cli report snapshot` / `e10-cli report snapshot set` | **必须**经 ``；默认名 **`{报表名}-{date}-{time}`**；`sheetId=String(reportId)` 禁 Number |
+| 空白门禁 | — | `e10-cli report validate blank` / `verify blank` | 见 `designer-blank-prevention-guide.md` |
 | 查看快照列表 | 运行态 | `POST getSnapshotDatas` | |
 | 还原版本（layout 事故） | 版本管理 | `GET rollbackReport` | 优先于空 workbook 重保存 |
 
@@ -322,7 +322,7 @@ flowchart TB
 | 显示方式 | 分组 / 排列 / 汇总 / 树形 | 汇总含求和/计数/平均等 |
 | 日期分组 | 年 / 年月 / 不设置 | — |
 | 分组排序 | 升序 / 降序 / 不排序 | — |
-| **筛选** | 父格筛选 / 自定义筛选 / 结果筛选 | `cross-dataset-filter-guide.md` · CLI `report cell-filter set\|remove` |
+| **筛选** | 父格筛选 / 自定义筛选 / 结果筛选 | `cross-dataset-filter-guide.md` |
 | **字段转换** | 人员/部门/部门全路径/checkbox/选择框/颜色/分值图标/斜线/关联/图片 | **`cell-transform-guide.md`** · `transType`+`browserType` |
 | **HTML转换** | 是/否 | `isHtml` `"1"|"0"` |
 | **前缀/后缀** | 文本 | `prefixAndSuffix:["前","后"]` |
@@ -332,7 +332,7 @@ flowchart TB
 
 ### 7.2 「事件」Tab
 
-> **完整**：`event-hreflink-guide.md` · 写入 CLI `report cell-event set|clear` · 写法校验 `validate href`
+> **完整**：`event-hreflink-guide.md` · CLI `validate href`
 
 | 属性 | 落库 | 说明 |
 |------|------|------|
@@ -385,8 +385,6 @@ flowchart TB
 
 示例：`供应商采购进货明细表-2026-09-04-14-09-30`
 
-脚本：`本地工作目录`（禁止自造 `V20260904…` 这类 UTC 压缩名）。
-
 **版本列表**（POST form）：
 
 ```
@@ -430,15 +428,13 @@ pageNo=1&pageSize=10&dateRange=["",""]&sheetId=<reportId>&versionName=&creators=
 
 ---
 
-## 十一、yunteams Live 实际请求（2026-09-04）
+## 十一、官方 SaaS 环境 Live 接口返回（2026-09-04）
 
 | 项 | 值 |
 |----|-----|
-| 设计器 URL | `https://weapp.yunteams.cn/sp/edc/report/designer/1310535032076214273` |
+| 设计器 URL | `https://<平台地址>/sp/edc/report/designer/<reportId>` |
 | 报表 | 销售经营分析报表 |
 | appId | `1310076187728674816` |
-| 实际请求脚本 | `本地工作目录` |
-| 原始 JSON | `本地工作目录` |
 
 ### 11.1 进入设计器（页面 load，12 条 report/dataset API）
 
@@ -455,12 +451,12 @@ pageNo=1&pageSize=10&dateRange=["",""]&sheetId=<reportId>&versionName=&creators=
 
 ```json
 {
- "permissionId": "report_view",
- "permissionType": 16,
- "id": "1310535032076214273",
- "sourceId": "1310535032076214273",
- "pageSize": 10000,
- "current": 1
+  "permissionId": "report_view",
+  "permissionType": 16,
+  "id": "1310535032076214273",
+  "sourceId": "1310535032076214273",
+  "pageSize": 10000,
+  "current": 1
 }
 ```
 
@@ -488,13 +484,12 @@ pageNo=1&pageSize=10&dateRange=["",""]&sheetId=<reportId>&versionName=&creators=
 | `designKey` | 设计器会话 UUID |
 | `pageSetting` | JSON 数组，含 `split`（分页/分栏）、`scrollPage` 等 |
 
-### 11.4 对照实际请求
+### 11.4 复现接口返回
 
 ```bash
-cd 本地工作目录
 npm install
 node capture_designer_ribbon_live.js
 # 可选环境变量：REPORT_ID / APP_ID
 ```
 
-鉴权：自动读 `e10-login status` 的 ETEAMSID；失效时脚本尝试 passport 表单登录。
+鉴权：自动读 `e10-cli auth status` 的 ETEAMSID；失效时脚本尝试 passport 表单登录。

package/skill-docs/references/report/report-help-guide.md

@@ -0,0 +1,304 @@
+# E-Builder 报表功能帮助指南（精简版）
+
+> **冷启动禁止通读**：见 `api-report-build-fast-path.md`。仅帮助手册问答时按需打开。
+> 本文档基于 e-builder 报表功能帮助文档整理，保留核心功能说明和配置要点。
+
+## 一、功能概述
+
+e-Builder 可视化报表功能帮助用户完成各种常见汇总报表的设计、展现和导出。基于浏览器所见即所得地快速完成报表制作，无需安装插件。
+
+核心能力：
+- 拖拽绑定字段方式制作分组汇总表或交叉表
+- 支持 Excel 运算公式
+- 支持多数据集关联
+- 支持条件格式、查询条件、填报字段
+- 支持主题样式、打印设置、分页设置
+
+## 二、报表设计器布局
+
+三栏布局：
+- **左侧**：数据集添加展示区，支持添加多个数据集
+- **中间**：设计展示区（SpreadJS 电子表格引擎）
+- **右侧**：单元格基本信息设置区
+
+## 三、数据集管理
+
+### 3.1 数据集类型
+
+| 类型 | 说明 |
+|------|------|
+| e-builder | e-builder 表单数据 |
+| 数据加工 | SQL 视图等加工数据 |
+| 外部数据源 | 外部数据库数据 |
+| 业务模块 | 系统业务模块数据 |
+| 数据集 | 已有数据集 |
+
+### 3.2 数据集核心功能
+
+- 数据获取与整合：连接多种数据源
+- 数据处理与转换：去重、汇总计算
+- 数据聚合和分组：分组聚合统计
+- 数据安全控制：基于人员的数据访问权限
+- 性能优化：数据缓存、查询优化
+
+### 3.3 数据集操作
+
+- **添加**：左上角"+"按钮，支持多选
+- **预览**：查看数据（展示10条）
+- **筛选**：支持 or/and 组合筛选
+- **聚合**：提前分组汇总
+- **排序**：多字段排序，前面的优先级高
+- **替换**：快速替换数据集和字段
+- **删除**：需先移除报表中引用的字段
+
+## 四、单元格设置
+
+### 4.0 事件 Tab（PC/H5 链接与传参）
+
+> **完整规则**：`event-hreflink-guide.md`（帮助手册 §传参 + 源码占位符）。
+
+| 配置项 | 说明 |
+|--------|------|
+| PC链接地址 | 落库 `pcHreflink` |
+| H5链接地址 | 落库 `h5Hreflink`（移动端优先） |
+| 打开方式 | **弹出页**=`blank`（默认）· **当前页**=`self` · **执行js代码**=`jsscript` |
+
+**传单元格值**（手册）：支持当前格值、父格值、父格的父格；链接中写 `{L4}` / `{A1}`，或如 `/sp/ebdfpage/list/xxx?ry=B5&kssj=E3`。
+**传查询条件值**：写 `{searchfield001}`（与条件 `asNameIndex` 对应）；区间可用 `_start`/`_end`。
+**超链接文本格**：左父格须指向提供 `{坐标}` 的数据格（见自检指南）。
+
+CLI：`e10-cli report validate href --map "弹出页"` / `--file cell.json`
+
+### 4.1 单元格类型
+
+| 类型 | 说明 |
+|------|------|
+| 文本字段 | 自定义文本内容 |
+| 数据字段 | 数据集选取的字段 |
+| 公式字段 | 公式计算 |
+| 序号字段 | 自动生成序号 |
+| 全选字段 | 全选框字段 |
+| 数据更新时间字段 | ETL 数据更新时间 |
+| 控件字段 | 多级填报字段 |
+
+### 4.2 扩展方向
+
+- **纵向扩展**：从上至下，不同单元格展示
+- **横向扩展**：从左至右，不同单元格展示
+- **不扩展**：所有数据在一个单元格
+
+### 4.3 显示方式
+
+- **分组**：相同数据合并为一组
+- **排列**：逐条排列展示
+- **汇总**：求和/最大值/最小值/平均数/个数/去重个数
+- **树形**：上下级层级展示
+
+### 4.4 父格设置
+
+- **左父格**：纵向扩展时，其他单元格以此单元格为基准纵向扩展
+- **上父格**：横向扩展时，其他单元格以此单元格为基准横向扩展
+- 左父格和上父格一起设置则交叉扩展
+
+注意事项：
+1. 父格设置不当会导致数据错乱或重复
+2. 复杂的父子关系可能影响报表性能
+3. 注意父子格扩展方向的协调一致
+
+### 4.5 分组方式
+
+日期字段分组方式：年份、年月、月份、年月日
+
+### 4.6 字段格式
+
+支持格式：常规、数值、货币、会计专用、短日期、长日期、时间、百分比、分数、科学计数法、文本
+
+> 注意：数值类型字段未设置格式时默认为"常规"，导出 excel 会被识别为文本导致公式计算为 0。参与计算的单元格需设置为数值格式。
+
+## 五、字段转换
+
+| 转换类型 | 说明 |
+|----------|------|
+| 人员 | 显示人员卡片，可点击查看 |
+| 部门 | 超链接形式，可点击查看部门详情 |
+| Checkbox | 转换为选择框，默认全选 |
+| 选择框 | id 值映射显示名称 |
+| 颜色选择框 | 选项值映射颜色 |
+| 分值图标 | 五星数据展示 |
+| 斜线文字 | 多维交叉表头（最多3个文本） |
+| 关联类型 | 人力/项目/任务/文档/流程/日程/表单/CRM/报告/绩效 |
+| 图片 | 附件/图片字段转换（仅 eb 表单） |
+| HTML | 富文本/标签值 HTML 转换 |
+| 前后缀 | 字段值前后拼接 |
+| 条码/二维码 | 数值字段转换为条码/二维码 |
+
+## 六、筛选设置
+
+### 6.1 父格筛选
+
+当单元格字段与其父格字段不属于同一数据集时，通过父格筛选关联数据集。
+
+- **左父格筛选**：当前单元格数据集与左父格数据集的筛选关系
+- **上父格筛选**：当前单元格数据集与上父格数据集的筛选关系
+- **从属关系（subordination）**：与左父格筛选配套，VLOOKUP 式字段映射
+- **字段引用格式**：fieldKey = `{dataSetId}.{sourceId}.{fieldName}`；`id` 必须等于 `currentField`
+
+详见 `cross-dataset-filter-guide.md`。
+
+### 6.2 自定义筛选
+
+当前单元格数据集的自定义筛选条件，支持多个 and/or 组合。配置时 `currentField`/`id` 用 fieldKey，type 用平台枚举。
+
+### 6.3 结果筛选
+
+- 前多少个 / 后多少个
+- 奇数 / 偶数
+- 特定：指定条数索引，如 "1,3" 或 "3-16,"
+
+## 七、条件格式
+
+### 7.1 突出显示
+
+支持条件：大于、小于、等于、介于、文本包含、发生日期、重复值
+
+可设置：字体、字号、字形、背景色、字体颜色
+
+### 7.2 数据条
+
+渐变填充 / 实心填充，最大值填满单元格
+
+### 7.3 图标集
+
+4类图标：方向、形状、标记、等级
+
+### 7.4 清除规则
+
+可清除所选单元格规则或整个工作表规则
+
+## 八、高级功能
+
+### 8.1 冻结单元格
+
+点击单元格设置冻结，冻结该单元格左侧和上方区域。
+
+### 8.2 解析优化
+
+- **行式加载**：列表展示时优化解析速度（仅单数据集简单列表）
+- **数据预聚合**：默认开启，按分组聚合逻辑解析
+
+### 8.3 分页设置
+
+- 默认每页200条，最大1000条（私有化260201基线后最大2000条）
+- 动态 Sheet 页：按字段值分不同 Sheet 页展示
+
+### 8.4 打印设置
+
+- 打印区域：起始行/列/结束行/列
+- 打印重复区域：表头重复
+- 打印网格线/外框线
+- 所有行/列打印在一页
+- 打印顺序：自动/先行后列/先列后行
+- 页边距/页眉页脚/纸张大小方向
+
+### 8.5 报表分栏
+
+- 按行/列数分栏：每N行/列自动为一栏
+- 按栏数分栏：整体分为N栏
+- 分栏模式：垂直/水平/卡片
+- 复制标题或表头
+
+### 8.6 按钮控制
+
+支持隐藏预览页面按钮，支持权限控制
+
+### 8.7 启用编辑/工具栏
+
+- 启用编辑：预览页面可双击编辑数据
+- 工具栏：调整字体样式、插入公式、设置打印
+
+## 九、公式功能
+
+### 9.1 公式分类
+
+| 分类 | 常用公式 |
+|------|----------|
+| 文本 | LEFT, RIGHT, MID, LEN, CONCAT, UPPER, LOWER |
+| 日期和时间 | YEAR, MONTH, DAY, DATE, DAYS, DATEDIF |
+| 数学 | SUM, AVERAGE, COUNT, MAX, MIN, ABS, ROUND |
+| 逻辑计算 | IF, IFERROR, AND, OR, NOT |
+| 信息 | ISERROR, ISBLANK, ISNUMBER |
+| 组合公式 | 多公式组合 |
+
+### 9.2 使用方式
+
+- 在单元格直接输入 `=sum` 联想公式
+- 公式 tab 选取公式插入
+
+### 9.3 注意事项
+
+- 求和字段需按特定父格分组时，公式资源也需指定自定义父格
+- iferror 包裹避免错误值导致计算失败
+- DAYS 函数结束日期在前，开始日期在后
+
+## 十、填报字段
+
+### 10.1 字段类型
+
+单行文本、多行文本、整数、浮点数、日期、人力资源、部门、分部、关联浏览、下拉框、check 框
+
+### 10.2 显示方式
+
+| 显示方式 | 适用字段类型 |
+|----------|-------------|
+| 输入框 | 单行文本、多行文本、整数、浮点数 |
+| 关联浏览 | 日期、人力资源、部门、分部、关联浏览 |
+| 选择框 | 下拉框 |
+| check框 | check 框 |
+
+### 10.3 关键属性
+
+- 控件名称：必填，可自定义
+- 表字段名：自动生成字母缩写，只读
+- 数据集名称：报表名+Sheet页名，只读
+- 数据库名：edc_uf_tb 开头，保存后生成
+- 字段属性：只读/编辑/必填
+- 显示字段：默认开启，关闭后不展示
+
+## 十一、数据分析
+
+- 默认分析页：开启数据分析后自动开启
+- 引用已有页面：选取有权限的 e-builder 页面
+- 新建分析：可新建多个分析，每个支持添加多个图表
+- 参数配置：自定义传参或系统参数
+- 展示宽度：像素或百分比，默认 280px
+- 打开方式：仅支持右侧滑出
+
+## 十二、版本管理
+
+- 存为新版本：保存当前配置为新版本
+- 历史版本：查看、预览、还原
+- 版本命名：报表名称-{date}-{time}，支持自定义
+
+## 十三、报表快速构建
+
+> **API / CLI（列表页新建）**：见 **`report-create-modes-guide.md`** — `e10-cli report create quick` · `quicklyParam`。
+
+### 13.1 列表式快速构建
+
+入口：后台管理中心 -> 报表 -> **新建报表** -> **快速构建-列表式**
+
+- 选取数据源（支持多选）
+- 设置显示字段（支持搜索）
+- 主题设置
+- 基础属性：列名称、列宽、对齐方式、分组、隐藏列、冻结单元格、自动换行
+- 落库：`POST baseInfo` + `quicklyParam`（非设计器手工拖格）
+
+### 13.2 报表设计页快速构建
+
+入口：报表设计器 -> 添加数据集后 -> 更多按钮
+
+生成简单列表式报表，默认开启行式加载。载荷为设计保存时的 `quicklyParamList`（与列表页新建 `quicklyParam` 不同入口）。
+
+### 13.3 模版创建（同对话框另一卡片）
+
+入口：新建报表 -> **模版创建** → `GET getReportModels` → `POST baseInfo` 且 `reportModel={模板ID}`。详见 `report-create-modes-guide.md`。

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

@@ -16,15 +16,86 @@
 | 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

package/skill-docs/references/report/report-knowledge-base.md

@@ -1,6 +1,6 @@
 # e-Builder 报表功能知识库
 
-> **冷启动禁止通读**：见 `cold-start-scan-guide.md`。仅文档与引擎冲突、或用户要源码级对齐时再读相关节（优先第九节）。
+> **冷启动禁止通读**：见 `api-report-build-fast-path.md`。仅文档与引擎冲突、或用户要源码级对齐时再读相关节（优先第九节）。
 
 ## 一、报表设计器布局
 
@@ -55,7 +55,7 @@
 - **分组**：相同值合并显示为一条
 - **排列**：所有数据一一展示，不合并
 - **汇总**：按父格分组进行聚合计算
- - 汇总方式：求和、计数、计数(去重)、最大值、最小值、平均值
+  - 汇总方式：求和、计数、计数(去重)、最大值、最小值、平均值
 - **树形**：按字段上下级关系分层级展示
 - **隐藏内容**：分组后可隐藏明细，仅显示分组汇总
 
@@ -305,9 +305,9 @@ I5~J5（交叉后字段）: 左父格自定义E5, 上父格默认, 纵向扩展
 
 ### 9.1 引擎选择与报表类型映射（代码事实）
 - 渲染引擎工厂 `Engine.getInstance(sheet.getQuickType())`（`SplitUtilThread.java:70` / `Engine.java:18-26`）：
- - `QuickType.Custom` → `CustomEngine`（自由布局，手动指定左/上父格坐标）
- - `QuickType.SimpleList` → `SimpleListEngine`（行式列表，无分组聚合）
- - 其它（默认）→ `GroupCrossEngine`（分组 + 交叉，x 列维 / y 行维 / z 度量）
+  - `QuickType.Custom` → `CustomEngine`（自由布局，手动指定左/上父格坐标）
+  - `QuickType.SimpleList` → `SimpleListEngine`（行式列表，无分组聚合）
+  - 其它（默认）→ `GroupCrossEngine`（分组 + 交叉，x 列维 / y 行维 / z 度量）
 - **结论**：报表类型不是用户随意选的"展示形态"，而是由底层 `QuickType` 决定走哪套引擎；分组/交叉/树形/合计均运行在 `GroupCrossEngine` 之上。
 
 ### 9.2 父格解析与循环依赖（代码事实）
@@ -321,9 +321,9 @@ I5~J5（交叉后字段）: 左父格自定义E5, 上父格默认, 纵向扩展
 - 枚举 `AnalysisExpandType` = `NoExpand / Horizontal / Vertical`；标题格默认 `Horizontal`。
 - 真实扩展由 `AnalysisUtil.expandCell` + `OffSet` 偏移实现：子格被推到父格扩展末端；交叉区在 `BaseEngine.analysisCrossField` 按 `leftParent×topParent` 坐标分组，取首个可扩展子格类型决定整体方向。
 - **聚合算法**（`DataSetEngine.getListLikeMap`）：
- - `sum`：`BigDecimal` 累加，初值 `ZERO`；`min/max`：流比较；`avg`：`sum/size`，`divide(scale=10, ROUND_HALF_UP)`，`size==0` 返回 `ZERO`；`count`：分组数据集取 `s_*_*` 整数字段求和，否则计非空 map 数；`distinctcount`：按 `dataSetKey` 去重。
- - **Null 处理**：`sum/min/max` 用 `getBigDecimalValue(v, ZERO)`（null→0）；`avg` 先过滤 null 再除；聚合 key 用 `NumberFormat` 最多 10 位小数。
- - **预聚合（SQL 下推）**：当"全部分组字段可分组、无自定义/结果筛选、排序仅含分组字段"时，`BaseEngine.initDataSetByGroup` 构造 `EdcDatasetAggregateDto(groupBy+countType)` 走 `queryForListGroupByFields`，打 `QuickTypeTag=GroupQuery`。
+  - `sum`：`BigDecimal` 累加，初值 `ZERO`；`min/max`：流比较；`avg`：`sum/size`，`divide(scale=10, ROUND_HALF_UP)`，`size==0` 返回 `ZERO`；`count`：分组数据集取 `s_*_*` 整数字段求和，否则计非空 map 数；`distinctcount`：按 `dataSetKey` 去重。
+  - **Null 处理**：`sum/min/max` 用 `getBigDecimalValue(v, ZERO)`（null→0）；`avg` 先过滤 null 再除；聚合 key 用 `NumberFormat` 最多 10 位小数。
+  - **预聚合（SQL 下推）**：当"全部分组字段可分组、无自定义/结果筛选、排序仅含分组字段"时，`BaseEngine.initDataSetByGroup` 构造 `EdcDatasetAggregateDto(groupBy+countType)` 走 `queryForListGroupByFields`，打 `QuickTypeTag=GroupQuery`。
 - **合计/小计不自动插入**：引擎不会自动加合计行。合计由设计器在分组旁放置一个 `AnalysisDisplayType.Count` 单元格实现（其聚合值即渲染值）；树形字段组内合计通过 `groupCountConfig`（location first/last）插入；总计 `COMB_GRAND_TOTAL` → 转 `SUM(...)`。
 - **占比/同环比是公式，不在 Java 端计算**：`AnalysisField.initFormula` 中 `COMB_GROWTH_RATE/COMB_DYNAMIC_RATE/COMB_DIFF` 仅生成 `IFERROR+原串`，`COMB_GRAND_TOTAL` 生成 `SUM+原串`；同比增长率/环比/差值的具体算术在 **SpreadJS 前端计算引擎**执行，Java 端无对应算式。
 
@@ -332,30 +332,30 @@ I5~J5（交叉后字段）: 左父格自定义E5, 上父格默认, 纵向扩展
 - **应用位置**：仅在结果集映射阶段、且只对 `field.isDate()` 字段触发（`YunConnect/LocalViewConnect/DataSetConnect` 的 `switchDate`）。
 - **唯一转换**：`DateUtil.timeZoneTransfer` 写死 `source="0"、target="+8"`，即"假定源是 GMT+0，转成 GMT+8"；server→DB 方向无任何转换。
 - `switchDate` 分支条件（`YunConnect` 为例）：
- - `length==13`（epoch 毫秒）→ 用 JVM 默认时区 `format "yyyy-MM-dd HH:mm:ss"`
- - `length==21` → `substring(0,19)`，无转换
- - `length==29 && contains("T")` → 触发 `timeZoneTransfer`（**唯一时区转换分支**）
- - 其它 → 原样返回
-- **隐式规则（极易踩坑）**：
- 1. 源时区被忽略：即使 ISO 串自带偏移（如 `+09:00`），代码先 `substring(0,19)` 丢弃偏移再硬按 `GMT+0` 解析，非 UTC 源会算错。
- 2. 设计预览 ≠ 运行预览：`EdcReportDevDesignServiceImpl.switchDate`（设计态）只有 13/21 两个分支，**没有 `T` 的时区转换分支**——设计预览不做 +8，运行态做。
- 3. 13 位毫秒分支依赖 JVM 默认时区（无显式 setTimeZone），仅因服务器通常在国内才"恰巧"+8；非 +8 服务器此处结果偏移。
- 4. 只对 `isDate()` 字段生效；基础类型、Map/List、select/browser 字段一律跳过。
- 5. 多数据库（mysql/oracle/sqlserver/pg/dm）**无差异**：无 `convert_tz/FROM_TZ/AT TIME ZONE`，时区逻辑纯 Java 层。
+  - `length==13`（epoch 毫秒）→ 用 JVM 默认时区 `format "yyyy-MM-dd HH:mm:ss"`
+  - `length==21` → `substring(0,19)`，无转换
+  - `length==29 && contains("T")` → 触发 `timeZoneTransfer`（**唯一时区转换分支**）
+  - 其它 → 原样返回
+- **隐式规则（极易注意）**：
+  1. 源时区被忽略：即使 ISO 串自带偏移（如 `+09:00`），代码先 `substring(0,19)` 丢弃偏移再硬按 `GMT+0` 解析，非 UTC 源会算错。
+  2. 设计预览 ≠ 运行预览：`EdcReportDevDesignServiceImpl.switchDate`（设计态）只有 13/21 两个分支，**没有 `T` 的时区转换分支**——设计预览不做 +8，运行态做。
+  3. 13 位毫秒分支依赖 JVM 默认时区（无显式 setTimeZone），仅因服务器通常在国内才"恰巧"+8；非 +8 服务器此处结果偏移。
+  4. 只对 `isDate()` 字段生效；基础类型、Map/List、select/browser 字段一律跳过。
+  5. 多数据库（mysql/oracle/sqlserver/pg/dm）**无差异**：无 `convert_tz/FROM_TZ/AT TIME ZONE`，时区逻辑纯 Java 层。
 
 ### 9.5 参数校验与静默改值（代码事实）
 - **报表名校验不在保存事务内**：`checkReportName`（`EdcReportDevBaseServiceImpl:2758-2784`）在新增时校验许可数量（`count>aliveCount && aliveCount!=-1 → OUT_OF_NUMBER`）与重名（`SAME_NAME`）；但 `saveReportDevInfo/doAddReportBaseInfo` 自身不调用该检查，仅前端先调 `checkReportName` 防御——**保存事务内无二次校验**。
 - **乐观锁**：`designKey` 与缓存不符 → "您当前的数据不是最新的，请重新打开获取最新的数据！"（label 284414）。
 - **查询参数解析**（`QueryParamsBuilder`）：
- - 字段名按固定格式 `name.split('.')[2]` 解析；名称不含 2 个 `.` 会 `ArrayIndexOutOfBoundsException`，无格式校验。
- - 别名 `length>25` 时生成 `f_<uuid>` 别名。
- - **缺失必填参数不报错**，仅跳过该 filter（`filterList.isEmpty → new ArrayList`），查询照常执行。
- - `SELECT` 非数字值兜底：有 `selectId` 用 `selectId`，否则非数字 value 置 `"-1"`。
- - **SQL 注入防护**：`sql_where` 类型经 `LZString.decompress → buildOnlySearchField`（占位符 `searchfield00x`）→ `QueryFilterBiz.buildSqlWhereParams` 参数化，未见原始拼接。
- - 范围值拆分：日期/数字 EQ/RANGE 拆 GTE+LTE；数字 NEQ 拆 LT+GT 并生成新 groupId；其它 func 不合法时"不做处理"。
+  - 字段名按固定格式 `name.split('.')[2]` 解析；名称不含 2 个 `.` 会 `ArrayIndexOutOfBoundsException`，无格式校验。
+  - 别名 `length>25` 时生成 `f_<uuid>` 别名。
+  - **缺失必填参数不报错**，仅跳过该 filter（`filterList.isEmpty → new ArrayList`），查询照常执行。
+  - `SELECT` 非数字值兜底：有 `selectId` 用 `selectId`，否则非数字 value 置 `"-1"`。
+  - **SQL 注入防护**：`sql_where` 类型经 `LZString.decompress → buildOnlySearchField`（占位符 `searchfield00x`）→ `QueryFilterBiz.buildSqlWhereParams` 参数化，未见原始拼接。
+  - 范围值拆分：日期/数字 EQ/RANGE 拆 GTE+LTE；数字 NEQ 拆 LT+GT 并生成新 groupId；其它 func 不合法时"不做处理"。
 - **静默改值（不抛异常）**（`ReportConfigConverter.applyDefaultFieldValues`）：
- - `xCount<=0→1`、`yCount<=0→1`；空 JSON 数组默认 `[]`；`orderType` 空→`"no"`、`openType` 空→`"blank"`、`thumbnail` 空→`"NoDisplay"`、`subordination` 空→`"[\"\",\"\"]"`、`valueCompletion`→`"{}"`；`colVisible/rowVisible` 空→`"1"`；`cellType=="Field" && transType` 空→`"default"`；`refX==0&&refY==0 → refX=refY=-1`。
- - 设计服务中字段 `cellType` 为 null/空串时**静默跳过该单元格**（不入库）。
+  - `xCount<=0→1`、`yCount<=0→1`；空 JSON 数组默认 `[]`；`orderType` 空→`"no"`、`openType` 空→`"blank"`、`thumbnail` 空→`"NoDisplay"`、`subordination` 空→`"[\"\",\"\"]"`、`valueCompletion`→`"{}"`；`colVisible/rowVisible` 空→`"1"`；`cellType=="Field" && transType` 空→`"default"`；`refX==0&&refY==0 → refX=refY=-1`。
+  - 设计服务中字段 `cellType` 为 null/空串时**静默跳过该单元格**（不入库）。
 - **AI 配置保存**（`ReportConfigSaveServiceImpl`）：`@Transactional(rollbackFor=Exception.class)`；`validateParams` 仅做循环依赖检查；`user==null → ReportException("user is required")`；更新路径只补齐缺失 sheet 不删已有；按 `uniqKey` 增量增/改/删，重复 `uniqKey` 跳过。
 
 ### 9.6 多端差异化（代码事实）
@@ -382,7 +382,7 @@ I5~J5（交叉后字段）: 左父格自定义E5, 上父格默认, 纵向扩展
 | 合计行由报表自动生成 | 引擎不自动插入合计，需手动放 `Count` 单元格 | 合计/小计均为手动放置 |
 | 同环比在后端计算 | `COMB_*` 仅生成 `IFERROR/SUM` 公式串，算术在 SpreadJS 前端 | 占比/同环比是前端公式 |
 | API 写入公式与手动相同（带 `=`） | `EdcReportDevDesignServiceImpl` 原样持久化 `cell.getFormula()`；设计器保存去 `=` | API 存储 `cellText` **无前导 `=`**，见 `formula-cell-api-guide.md` |
-| IF 公式 API 不可用 | 为 `=` 前缀 + 错误 countType/displayType 导致空白 | IF/IFERROR 可用，须 `countType=count`、`displayType=Group` |
+| IF 公式 API 不可用 | 验证为 `=` 前缀 + 错误 countType/displayType 导致空白 | IF/IFERROR 可用，须 `countType=count`、`displayType=Group` |
 | 报表支持配置时区 | 全仓库无时区配置字段，写死 GMT+8 且仅 isDate 字段、运行态才转换 | 时区不可配置、仅运行态+8 |
 | 保存时会校验报表名/重名 | `checkReportName` 不在保存事务内，仅前端防御 | 后端保存事务不二次校验重名 |
 | 移动端自动适配 | 无 UA 嗅探，靠 `isMobile` 参数 + `belong`/`mbhreflink` 元数据 | 必须显式配置 belong=MOBILE |