weaver-e10-builder 1.6.10 → 1.6.12

package/skill-docs/references/report/add-dataset-registration-guide.md

@@ -14,12 +14,18 @@
 
 | 形态 | 典型 `addDataset` | `dataset/list` 特征 | 业务字段 `fieldsKey.name` | `tableName` 后缀 | 何时用 |
 |------|-------------------|---------------------|---------------------------|------------------|--------|
-| **A. 设计器默认（LOGIC）** | `sourceType=LOGIC`（或 `logic`）+ `sourceGroup=weaver-ebuilder-form-service` + `appid=<appId>` | `type:"logic"`，`sourceGroup:"weaver-ebuilder-form-service"` | **`field_{雪花}`** | **`(业务模块)`** | **普通应用表单（默认强制）** |
+| **A. 设计器默认（logic，小写）** | `sourceType=logic`（**必须小写**；大写 `LOGIC` 会让报表复制 500）+ `sourceGroup=weaver-ebuilder-form-service` + `appid=<appId>` | `type:"logic"`，`sourceGroup:"weaver-ebuilder-form-service"` | **`field_{雪花}`** | **`(业务模块)`** | **普通应用表单（默认强制）** |
 | **B. 共享表 / form 契约** | `sourceType=form` + `sourceGroup=<appId>` | `type:"form"`，`sourceGroup` 等于 appId | 常为**裸雪花** | **`(表单)`** | 仅「xxx-共享表」类应用且已验证必须用此契约时（见 MEMORY/共享表笔记） |
+| **C. 数据加工 SQL 视图** | `sourceType=eteams`（**必须小写**）+ `sourceGroup=sql` + `appid=<appId>` | `type:"eteams"`，`sourceGroup:"sql"` | 视图原字段名（如 `title`/`zymc`/`major_no`，**无 `field_` 前缀**） | **`(数据加工)`** | 数据集来自「数据加工」SQL 视图 |
 
 **禁止**：在普通应用里误用形态 B，再抱怨「没有 field_」——那是注册错了，不是 fieldsKey 坏了。
 
-> ⚠️ **`tableName` 后缀必须与注册形态一致**：形态 A → `(业务模块)`，形态 B → `(表单)`。
+> ⚠️ **形态 C 大小写门禁（2026-10-09 实证 · 应用 `1323883777452843010`）**：
+> `sourceType` **必须小写 `eteams`** + `sourceGroup=sql`，落库 `type="eteams"` → 面板/单元格显示 **`X(数据加工)`** ✅。
+> 若传大写 `ETEAMS`（或 sourceGroup 用 `-98`）→ 落库 `type="ETEAMS"`/`sourceGroup:"-98"` → 被当成 **`X(业务模块)`** ❌。
+> 同应用验证：`eteams`/`sql` 的 5 张表单元格全为 `X(数据加工)`；`ETEAMS`/`-98` 的 2 张表全为 `X(业务模块)`。
+
+> ⚠️ **`tableName` 后缀必须与注册形态一致**：形态 A → `(业务模块)`，形态 B → `(表单)`，形态 C → `(数据加工)`。
 > 后缀缺失或写错会导致左侧数据源不显示模块类型。
 > 详见 **`dataset-table-field-contract-guide.md`**（含 `FieldCellType` 必需字段全表 + 落库门禁）。
 
@@ -31,17 +37,33 @@
 POST /api/bs/edc/report/addDataset
 Content-Type: multipart/form-data
 
-reportId = {reportId}
-sourceType = LOGIC
-sourceIds = {sourceId} // 表单/数据源 ID
-sourceName = {显示名} // **回显名强制**：`{表单名}(业务模块)`，如 `轻资产信息(业务模块)`；禁止只传裸表单名
-appid = {appId} // 注意小写 appid（与设计器一致）
-sourceGroup = weaver-ebuilder-form-service
+reportId     = {reportId}
+sourceType   = logic              // ★★ 必须小写！大写 LOGIC 会让报表「复制」500（见下方红框）
+sourceIds    = {sourceId}          // 表单/数据源 ID
+sourceName   = {裸名}              // ★ 传**裸名** `轻资产信息`（不带后缀）
+                                  //   面板显示名 = sourceName + (添加类型标签)，标签由平台按添加类型自动拼
+                                  //   旧口径「必须传 {表单名}(业务模块)」已于 2026-09-16 推翻（注意点 BUILD-36）
+appid        = {appId}             // 注意小写 appid（与设计器一致）
+sourceGroup  = weaver-ebuilder-form-service
 ```
-> **回显名（已验证）**：`sourceName` 写入 `edc_dataset_dev.name`，左侧回显应为 **`xxx(业务模块)`**。
-> 只传 `轻资产信息` 会缺后缀；源合并后的 `tableText` 可能仍是 `轻资产信息(uf_xxx)`，与回显名不是同一字段——**以 `name`=sourceName 为准**。
+> ★★ **`sourceType` 必须小写 `logic`（2026-09-15 实证 · 注意点 BUILD-29）**
+> 服务端会把入参**原样**写进 `edc_dataset_dev.type`：
+> - `sourceType=logic` → `type="logic"`（= 设计器口径）→ 报表「复制」**200**
+> - `sourceType=LOGIC` → `type="LOGIC"`（大写）→ 报表「复制」**500「报表内部错误」**（HTTP 仍 200）
+>
+> 决定性实验：同应用同表单两张空壳，唯一差别就是这里的大小写 → 200 / 500。
+> CLI 侧已把默认值统一为小写（`dataset add --source-type` 默认 `logic`），**不要显式传大写**。
+> 存量注意报表：`e10-cli report copy-health`（诊断）→ `e10-cli report dataset heal --purge --apply`（原地换型修复）。
+
+> **回显名（2026-09-16 更正 · 注意点 BUILD-36）**：`sourceName` 写入 `edc_dataset_dev.name`，面板显示时为
+> **`{sourceName} + (添加类型标签)`** —— 所以 `sourceName` 要传**裸名** `轻资产信息`，面板才会显示 `轻资产信息(业务模块)`。
+> **旧说法「只传裸表单名会缺后缀、必须传 `轻资产信息(业务模块)`」已推翻**：那样写会让面板显示 **`轻资产信息(业务模块)(业务模块)`**。
+> 决定性对照（报表 `1315265856934289408`，同 sourceId 两条）：脚本建那条 `name="采购入库(业务模块)"` → 双后缀 ❌；
+> 设计器「+」那条 `name="采购入库"` → `采购入库(业务模块)` ✅。
+> 源合并后的 `tableText` 可能仍是 `轻资产信息(uf_xxx)`，与回显名不是同一字段——**以 `name` 为准**。
+> 存量脏值清理：`e10-cli report fix dataset-name --report-id <rid> --app-id <appId> [--apply]`。
 
-可选字段以设计器实际请求为准；**不得**把 `sourceGroup` 写成 appId，除非走 §一 形态 B。
+可选字段以设计器接口返回为准；**不得**把 `sourceGroup` 写成 appId，除非走 §一 形态 B。
 
 `addDataset` **不返回** datasetId → 短轮询：
 
@@ -53,7 +75,7 @@ GET /api/bs/edc/dataset/list?hasField=true&reportId={reportId}
 
 ### 2.1 同源只挂一次（**强制 · 2026-09-11 事故**）
 
-`spec_lib.resolveDataset()` 在 `addDataset` **之前**先查 `dataset/list`：
+构建层 在 `addDataset` **之前**先查 `dataset/list`：
 
 | 场景 | 行为 |
 |------|------|
@@ -74,18 +96,18 @@ GET /api/bs/edc/dataset/list?hasField=true&reportId={reportId}
 
 ```javascript
 const biz = fieldsKey.filter(
- (f) => /^\d{15,}$/.test(f.name) || /^field_\d{15,}$/.test(f.name)
+  (f) => /^\d{15,}$/.test(f.name) || /^field_\d{15,}$/.test(f.name)
 );
 const withPrefix = biz.filter((f) => String(f.name).startsWith('field_')).length;
 const bare = biz.filter((f) => /^\d{15,}$/.test(f.name)).length;
 
 // 普通应用（非共享表 form 契约）：业务字段应多数带 field_
 if (!isSharedFormContract && biz.length > 0 && bare > withPrefix) {
- throw new Error(
- 'addDataset 注册错误：fieldsKey 业务字段为裸雪花（无 field_）。' +
- '应使用 sourceType=LOGIC + sourceGroup=weaver-ebuilder-form-service；' +
- 'delDataset 后重建，禁止在 Field 上凭记忆加 field_ 前缀凑数。'
- );
+  throw new Error(
+    'addDataset 注册错误：fieldsKey 业务字段为裸雪花（无 field_）。' +
+      '应使用 sourceType=LOGIC + sourceGroup=weaver-ebuilder-form-service；' +
+      'delDataset 后重建，禁止在 Field 上凭记忆加 field_ 前缀凑数。'
+  );
 }
 ```
 
@@ -98,9 +120,9 @@ if (!isSharedFormContract && biz.length > 0 && bare > withPrefix) {
 失败处理：
 
 1. `POST /api/bs/edc/report/delDataset` 删掉错误注册
- - form：`reportId=<报表ID>` · **`sourceIds=<datasetId>`**（参数名历史遗留，**不是**表单 sourceId）
- - 建议先 `GET /api/bs/edc/dataset/checkDataSetUsed?reportId=&datasetId=`；CLI：`e10-cli report dataset delete`
- - 完整侧栏操作见 `dataset-sidebar-ops-guide.md`
+   - form：`reportId=<报表ID>` · **`sourceIds=<datasetId>`**（参数名历史遗留，**不是**表单 sourceId）
+   - 建议先 `GET /api/bs/edc/dataset/checkDataSetUsed?reportId=&datasetId=`；CLI：`e10-cli report dataset delete`
+   - 完整侧栏操作见 `dataset-sidebar-ops-guide.md`
 2. 按 §二 重新 `addDataset`
 3. 再拉 `fieldsKey`，确认出现 `field_*`
 4. 再写 Field / `saveReportDevInfo`
@@ -124,7 +146,7 @@ if (!isSharedFormContract && biz.length > 0 && bare > withPrefix) {
 - [ ] `addDataset` 使用 `sourceType=LOGIC` + `sourceGroup=weaver-ebuilder-form-service`（除非共享表契约）
 - [ ] `dataset/list` 回读该条 `type/sourceGroup` 与设计器一致
 - [ ] `fieldsKey` 业务字段已出现 `field_*`（普通应用）
-- [ ] Field.`name` / fieldKey 末段 ∈ **该** dataset 的 fieldsKey（`verify_field_bind.js`）
+- [ ] Field.`name` / fieldKey 末段 ∈ **该** dataset 的 fieldsKey（`e10-cli report verify bind`）
 - [ ] 同 sourceId 多实例时，未误绑到旧的 form+appId 裸雪花数据集
 
 ---

package/skill-docs/references/report/advanced-crosstab-tree-guide.md

@@ -0,0 +1,82 @@
+# 高阶交叉表与折叠树报表 · 场景 H / I（SKILL A0.18）
+
+> 案例一「销售额等级分析」：多级行维度（一级品类→二级品类→品牌）× 多指标列组（销量对比/销售额/
+> 销售额年别/无人区/违杀率…，组内 2014/2015/占比/合计多列）+ 每级小计行 + 环比涨跌红绿条件色。
+> 案例二「江苏地区截止应收账款汇总表」：左侧折叠树（地区→区县→等级→分类，▶/▼ 可收起）+
+> 多层列组（合同销售/产品费用/实施费用，组内小计/已上线/未上线 + 个数/金额子列）+ 底部合计行。
+
+---
+
+## 一、案例 H：高阶交叉表（多级行维度 × 多指标列组）
+
+| # | 特性 | 机制 | 落点 |
+|---|---|---|---|
+| ① | 多级行维度（品类→子类→品牌，逐级缩进） | 每级一个 Field（`Vertical+Group`），**子级左父格自定义→上级格**（链式缩进）；最末级左父格挂上一级 | rebuild 直构路径（crosstab guide §2），**build spec 单列平铺表达不了多级行维度** |
+| ② | 每级小计行（计/合计） | 小计 Formula 行左父格自定义→**该级维度格**，上父格→列维度；整行公式禁默认左父格（crosstab guide §4.2 ★） | 同上 |
+| ③ | 多指标列组（组内 年份/占比/合计） | 第一层列维度 `Horizontal+Group` 横向扩展；组内子表头 Const 上父格→列维度；占比/环比 = Formula（上父格→列维度，`SUM()` 引扩展格=对全部实例求和） | 知识库 §4.8 多横向维度交叉（两层横向维度的父格定案） |
+| ④ | 环比涨跌红绿（▲绿 ▼红 百分比） | `conditionRule.highlightDatas[]`：greater→红 / less→绿（或反之），relation highlight | build spec `columns[].rule` / 直构 `cellType.conditionRule` |
+
+**列组直构坐标模板**（列维度两组：年份组 + 无人区组）：
+
+```
+x=0  A1 行维度1(Vertical/Group)   B1 列维度1(Horizontal/Group)      F1 列维度2(Horizontal/Group)
+x=1  B2..E2 子表头Const(上父→B1)  F2..H2 子表头(上父→F1)
+x=2  A3 二级行维度(左父→A1)        B3.. 数值/占比(左父→A1/上级, 上父→B1/F1)
+x=3  A4 「计」小计行(左父→A1)      B4.. SUM公式(上父→B1/F1)
+```
+
+## 二、案例 I：折叠树报表（树形扩展）
+
+| # | 特性 | 机制 | 落点 |
+|---|---|---|---|
+| ① | 左侧树形层级（▶/▼ 收起展开） | 树形字段：**左父格无、上父格无、纵向扩展、`displayType:'Tree'`**（枚举定案 `AnalysisDisplayType: Group/List/Count/Tree`，knowledge-base §2/§4.6） | **`build spec` 已内置**：`columns[].display:'tree'` → 自动 Tree + 左父格 [-1,-1] + isActiveParent |
+| ② | 上下级从属关系 | 树形字段按**字段值上下级**（id 匹配上级）分叉；多数据集时配 `subordination`（VLOOKUP 映射） | 数据集单源自包含层级（如 组织表 pid）直接可树；跨表层级配 subordination |
+| ③ | 默认收起 / 默认展开 | 默认收起；展开 = 设计器「页面 → 页面布局 → 数据展开 → 树形」（sheetConfig） | spec 落库默认收起；默认展开=设计器确认项（sheetConfig 键名待确认回填） |
+| ④ | 多层列组（费用类型→状态→个数/金额） | 同案例 H ③：两层横向维度父格定案（知识库 §4.8） | rebuild 直构路径 |
+| ⑤ | 底部合计行 | `COMB_GRAND_TOTAL` → `SUM(...)`；左父格挂合计标签格 | crosstab guide §4.2 |
+
+**build spec 树形最小示例**：
+
+```json
+{
+  "appId": "<appId>", "sourceId": "<sid>", "sourceName": "<组织/地区表>",
+  "reportName": "江苏地区应收汇总",
+  "columns": [
+    { "title": "公司/项目/形态", "field": "组织层级", "display": "tree" },
+    { "title": "合同销售-个数", "field": "合同个数", "format": "value" },
+    { "title": "合同销售-金额", "field": "合同金额", "format": "huobi" }
+  ],
+  "layout": { "title": "江苏地区截止应收账款汇总表", "showLocation": "left", "freezeRows": 1, "freezeCols": 1 }
+}
+```
+
+## 三、能力边界（如实）
+
+1. **折叠按钮（▶/▼）由 `displayType=Tree` 引擎渲染**，API 侧只需树形字段+父格规则；`sheetConfig` 默认展开键名待确认回填。
+2. **多级行维度 / 多层列组**超出 build spec 表达力 → 走 rebuild 直构（`e10-cli report build` / `rebuild from-blueprint`），坐标模板见 §一。
+3. 树形列**必须**在数据源里有明确的上下级关系字段（自引用 pid 或 subordination 映射）；纯平铺字段强上 Tree 无层级效果。
+4. 渲染展开形态设计器确认为准（渲染接口取不到展开数据，crosstab guide §5.4）。
+
+## 四、搭建提示语句
+
+**案例 H（高阶交叉）**：
+
+> 按高阶交叉格式搭一张销售额等级分析：行维度三级「一级品类→二级品类→品牌」逐级缩进，
+> 每级带小计行，底部总计；列侧多指标组「销量对比/销售额/…」（组内 2014/2015/占比/合计）；
+> 环比列红绿条件色（`columns[].rule`）；数据源 `<sid>`（appId `<appId>`）；
+> 多级行维度+多列组走 rebuild 直构路径（crosstab + 本指南 §一坐标模板），落库后回读验收父格拓扑与 Formula 存活。
+
+**案例 I（折叠树）**：
+
+> 按折叠树格式搭一张地区应收汇总：左侧「组织层级」树形列（可收起展开，`display:"tree"`），
+> 列侧多层费用组（组内小计/已上线/未上线 → 个数/金额子列），底部合计行；
+> 数据源 `<sid>`（自包含层级；跨表层级给 subordination 映射），appId `<appId>`；
+> 冻结左 1 列+上方表头、居左；单源用 `build spec`、多源列组用 rebuild 直构，
+> 落库后回读验收：树形格 displayType=Tree 且左父格 -1,-1、冻结锚点唯一、check-ids 干净。
+
+## 五、验证清单
+
+1. 树形列回读：`displayType === 'Tree'`、`leftX/leftY === -1`、`isActiveParent === true`、`expandType === 'Vertical'`
+2. 案例 H：小计行 Formula 左父格=该级维度格；多列组子表头 Const 上父格→列维度格
+3. 条件色：`conditionRule.highlightDatas[]` 关系/颜色逐条回读
+4. 树形折叠表现、默认展开 = 设计器确认；验证后回填 sheetConfig 键名

package/skill-docs/references/report/ai-report-workflow.md

@@ -1,38 +1,38 @@
 # AI 报表生成工作流程
 
-> **冷启动禁止通读**：见 `cold-start-scan-guide.md`。纯搭表走 `api-report-build-fast-path.md`，勿开场读本文。
+> **冷启动禁止通读**：见 `api-report-build-fast-path.md`。纯搭表走 `api-report-build-fast-path.md`，勿开场读本文。
 
 ## 一、整体流程概览
 
 ```
 用户输入（文本描述 / 图片效果 / 需求文件）
- |
- v
- 1. 需求解析：理解报表类型、数据维度、指标、样式需求
- |
- v
- 2. 字段分类：将需求中的字段映射为三类
- - groupFields（分组/维度字段）
- - listFields（列表/展示字段）
- - targetFields（指标/度量字段）
- |
- v
- 3. 报表类型判定：根据字段组合判断报表类型
- - 简单列表（LIST）
- - 分组表（GROUP）
- - 交叉表/统计表（COUNT）
- |
- v
- 4. 布局规划：确定单元格位置、扩展方向、父格关系
- |
- v
- 5. 样式配置：主题选择、条件格式、字体样式
- |
- v
- 6. 高级配置：查询条件、分页、打印、解析优化
- |
- v
- 7. 输出配置：生成完整的 ReportProps JSON 配置
+        |
+        v
+  1. 需求解析：理解报表类型、数据维度、指标、样式需求
+        |
+        v
+  2. 字段分类：将需求中的字段映射为三类
+     - groupFields（分组/维度字段）
+     - listFields（列表/展示字段）
+     - targetFields（指标/度量字段）
+        |
+        v
+  3. 报表类型判定：根据字段组合判断报表类型
+     - 简单列表（LIST）
+     - 分组表（GROUP）
+     - 交叉表/统计表（COUNT）
+        |
+        v
+  4. 布局规划：确定单元格位置、扩展方向、父格关系
+        |
+        v
+  5. 样式配置：主题选择、条件格式、字体样式
+        |
+        v
+  6. 高级配置：查询条件、分页、打印、解析优化
+        |
+        v
+  7. 输出配置：生成完整的 ReportProps JSON 配置
 ```
 
 ## 二、需求解析规则
@@ -78,8 +78,8 @@
 配置示例：
 ```json
 {
- "fieldName": "创建日期",
- "groupType": "yearmonth" // 按年月分组
+    "fieldName": "创建日期",
+    "groupType": "yearmonth"    // 按年月分组
 }
 ```
 
@@ -100,8 +100,8 @@ groupType 中文到系统值映射：
 配置示例：
 ```json
 {
- "fieldName": "客户名称",
- "groupType": "none"
+    "fieldName": "客户名称",
+    "groupType": "none"
 }
 ```
 
@@ -115,8 +115,8 @@ groupType 中文到系统值映射：
 配置示例：
 ```json
 {
- "fieldName": "合同金额",
- "countType": "sum" // 求和
+    "fieldName": "合同金额",
+    "countType": "sum"     // 求和
 }
 ```
 
@@ -144,7 +144,7 @@ countType 中文到系统值映射：
 **单元格布局示例**：
 ```
 A1: 标题行（常量）
-A2: 字段1(纵向扩展,排列) B2: 字段2(纵向扩展,排列) C2: 字段3(纵向扩展,排列)
+A2: 字段1(纵向扩展,排列)  B2: 字段2(纵向扩展,排列)  C2: 字段3(纵向扩展,排列)
 ```
 
 ### 4.2 分组表（GROUP）
@@ -160,7 +160,7 @@ A2: 字段1(纵向扩展,排列) B2: 字段2(纵向扩展,排列) C2: 字段3(
 **单元格布局示例**：
 ```
 A1: 标题行（常量）
-A2: 分组字段(纵向扩展,分组) B2: 指标字段(纵向扩展,汇总,求和)
+A2: 分组字段(纵向扩展,分组)  B2: 指标字段(纵向扩展,汇总,求和)
 ```
 
 ### 4.3 交叉表/统计表（COUNT）
@@ -178,9 +178,9 @@ A2: 分组字段(纵向扩展,分组) B2: 指标字段(纵向扩展,汇总,求
 **单元格布局示例**（2个分组字段+1个指标）：
 ```
 A1: 标题行（常量）
-A2: 行维度字段(纵向扩展,分组) B2: 列维度字段(横向扩展,分组)
- B3: 指标字段(纵向扩展,汇总,求和)
- 左父格=自定义(A2), 上父格=自定义(B2)
+A2: 行维度字段(纵向扩展,分组)  B2: 列维度字段(横向扩展,分组)
+                              B3: 指标字段(纵向扩展,汇总,求和)
+                                  左父格=自定义(A2), 上父格=自定义(B2)
 ```
 
 ### 4.4 交叉表父格筛选配置
@@ -192,22 +192,22 @@ A2: 行维度字段(纵向扩展,分组) B2: 列维度字段(横向扩展,分组
 
 ```json
 {
- "subordination": [
- "1304979556231593994.1299763447342276611.field_1299763447342276617",
- "1304979560546713602.1299789221321891842.field_1299789221321891843"
- ],
- "leftFilterField": [{
- "parentField": "1304979556231593994.1299763447342276611.field_1299763447342276617",
- "currentField": "1304979560546713602.1299789221321891842.field_1299789221321891843",
- "type": "Equals",
- "id": "1304979560546713602.1299789221321891842.field_1299789221321891843"
- }],
- "customFilterField": [{
- "currentField": "1304979560546713602.1299789221321891842.field_1299789221321891844",
- "type": "NotContain",
- "value": "排除机构",
- "id": "1304979560546713602.1299789221321891842.field_1299789221321891844"
- }]
+    "subordination": [
+        "1304979556231593994.1299763447342276611.field_1299763447342276617",
+        "1304979560546713602.1299789221321891842.field_1299789221321891843"
+    ],
+    "leftFilterField": [{
+        "parentField": "1304979556231593994.1299763447342276611.field_1299763447342276617",
+        "currentField": "1304979560546713602.1299789221321891842.field_1299789221321891843",
+        "type": "Equals",
+        "id": "1304979560546713602.1299789221321891842.field_1299789221321891843"
+    }],
+    "customFilterField": [{
+        "currentField": "1304979560546713602.1299789221321891842.field_1299789221321891844",
+        "type": "NotContain",
+        "value": "排除机构",
+        "id": "1304979560546713602.1299789221321891842.field_1299789221321891844"
+    }]
 }
 ```
 
@@ -226,9 +226,9 @@ A2: 行维度字段(纵向扩展,分组) B2: 列维度字段(横向扩展,分组
 - x = 行号（从0开始，向下递增）
 - y = 列号（从0开始，向右递增）
 - 父格坐标：[type, x, y]
- - `["default", 0, 0]` = 默认（依赖相邻单元格）
- - `["custom", x, y]` = 自定义（指向坐标 x,y 的单元格）
- - `["empty", 0, 0]` = 无父格
+  - `["default", 0, 0]` = 默认（依赖相邻单元格）
+  - `["custom", x, y]` = 自定义（指向坐标 x,y 的单元格）
+  - `["empty", 0, 0]` = 无父格
 
 ### 5.3 多数据集布局
 
@@ -257,12 +257,12 @@ A2: 行维度字段(纵向扩展,分组) B2: 列维度字段(横向扩展,分组
 
 ```json
 {
- "cellType": "Formula",
- "cellText": "IF(J3=0,0,L3/J3)",
- "displayType": "Group",
- "countType": "count",
- "groupType": null,
- "expandType": "NoExpand"
+    "cellType": "Formula",
+    "cellText": "IF(J3=0,0,L3/J3)",
+    "displayType": "Group",
+    "countType": "count",
+    "groupType": null,
+    "expandType": "NoExpand"
 }
 ```
 
@@ -270,10 +270,10 @@ A2: 行维度字段(纵向扩展,分组) B2: 列维度字段(横向扩展,分组
 
 ```json
 {
- "cellType": "Formula",
- "cellText": "=IF(J3=0,0,L3/J3)",
- "displayType": "List",
- "countType": "none"
+    "cellType": "Formula",
+    "cellText": "=IF(J3=0,0,L3/J3)",
+    "displayType": "List",
+    "countType": "none"
 }
 ```
 
@@ -305,28 +305,28 @@ workbook `dataTable` 中 Formula 格需同时设置：
 
 1. 双保存：`saveReportWithCacheConfig` + `saveReportDevInfo`
 2. `getReportDevInfo` 回读：确认 `cellText` 不以 `=` 开头
-3. 运行 `validate_report_config.py` 预检 Formula 格式
+3. 运行 `e10-cli report py validate` 预检 Formula 格式
 
 ## 七、高级功能配置
 
 ### 7.1 查询条件配置
 
-> **API/脚本写入完整规范**见 `query-condition-api-guide.md`（条件字段形态、asNameIndex、21 项日期选项、系统参数默认值）。以下为 ReportProps 摘要，**不可直接等同于 saveQueryItem payload**。
+> **API/脚本写入完整规范**见 `query-condition-api-guide.md`（条件字段形态、asNameIndex、21 项日期选项、系统参数默认值）。以下为 ReportProps 摘要，**不可直接等同于 saveQueryItem  payload**。
 
 ```json
 {
- "queryFields": [{
- "uuid": "query-1",
- "id": "field-001",
- "text": "日期范围",
- "displayType": "date",
- "conditions": [{
- "dataSetId": "ds-001",
- "fieldId": "createdate",
- "relation": "between"
- }],
- "showOrder": 1
- }]
+    "queryFields": [{
+        "uuid": "query-1",
+        "id": "field-001",
+        "text": "日期范围",
+        "displayType": "date",
+        "conditions": [{
+            "dataSetId": "ds-001",
+            "fieldId": "createdate",
+            "relation": "between"
+        }],
+        "showOrder": 1
+    }]
 }
 ```
 
@@ -334,10 +334,10 @@ workbook `dataTable` 中 Formula 格需同时设置：
 
 ```json
 {
- "pageNum": 1,
- "pageRowCount": 200, // 每页行数
- "dynamicField": "", // 动态Sheet页字段
- "scrollPage": false // 滚动分页
+    "pageNum": 1,
+    "pageRowCount": 200,        // 每页行数
+    "dynamicField": "",        // 动态Sheet页字段
+    "scrollPage": false        // 滚动分页
 }
 ```
 
@@ -345,8 +345,8 @@ workbook `dataTable` 中 Formula 格需同时设置：
 
 ```json
 {
- "rowMode": false, // 行式加载（仅单数据集简单列表）
- "preAggregate": true // 数据预聚合（默认开启）
+    "rowMode": false,          // 行式加载（仅单数据集简单列表）
+    "preAggregate": true       // 数据预聚合（默认开启）
 }
 ```
 
@@ -354,18 +354,18 @@ workbook `dataTable` 中 Formula 格需同时设置：
 
 ```json
 {
- "printInfo": {
- "area": { "startRow": -1, "endRow": -1, "startCol": -1, "endCol": -1 },
- "repeatArea": { "startRow": -1, "endRow": -1, "startCol": -1, "endCol": -1 },
- "printGridLine": false,
- "printOuterBorder": false,
- "allRowsInOnePage": false,
- "allColsInOnePage": false,
- "printOrder": "auto"
- },
- "pageMargin": { "top": -1, "bottom": -1, "left": -1, "right": -1, "header": -1, "footer": -1 },
- "paperSize": "A4",
- "paperOrientation": "portrait"
+    "printInfo": {
+        "area": { "startRow": -1, "endRow": -1, "startCol": -1, "endCol": -1 },
+        "repeatArea": { "startRow": -1, "endRow": -1, "startCol": -1, "endCol": -1 },
+        "printGridLine": false,
+        "printOuterBorder": false,
+        "allRowsInOnePage": false,
+        "allColsInOnePage": false,
+        "printOrder": "auto"
+    },
+    "pageMargin": { "top": -1, "bottom": -1, "left": -1, "right": -1, "header": -1, "footer": -1 },
+    "paperSize": "A4",
+    "paperOrientation": "portrait"
 }
 ```
 

package/skill-docs/references/report/api-auth-headers.md

@@ -0,0 +1,129 @@
+# E10 API 鉴权请求头规范（硬约束）
+
+> **适用范围**：本 Skill 内所有 EDC 报表 API、DataSetAction、Python 脚本 HTTP 请求。
+> **与登录 Skill 关系**：鉴权参数**必须**来自 `e10-cli auth` 登录 Skill 的会话结果，禁止绕过登录 Skill 自行拼 token。
+
+---
+
+## 一、登录必须走 e10-cli auth Skill
+
+| 允许 | 禁止 |
+|------|------|
+| `export EB_ETEAMSID=... EB_HOST=...`（凭证只走环境变量） | 在脚本/对话中硬编码 ETEAMSID；把凭证明文粘贴进对话；`e10-cli auth oidc` 兜底（部分环境 SSO 不返回授权码会一直卡住） |
+| 引导用户在本机终端 `e10-cli auth login` / `export EB_ETEAMSID=...` | 把凭证作为命令行参数（如 `e10-cli auth set --eteamsid "PCACCOUNT_xxx"`）——会进 shell 历史与 `ps` 进程列表 |
+| `e10-cli auth status` / `whoami --json` 确认会话 | 跳过 e10-cli auth，直接 curl 拼 Cookie |
+|  从 profile 读取 | 裁剪/去重/改写 cookies.raw |
+
+**Agent 执行顺序**：
+
+1. 加载 `weaver-e10-cli auth`
+2. 执行 `e10-cli auth status`（一次即结论）；缺凭证 → **引导用户在本机终端自助登录**（`e10-cli auth login` 或 `export EB_ETEAMSID=...`），**禁止**引导用户把凭证明文粘贴进对话、**禁止**用 `--eteamsid "<值>"` 传参
+3. 通过 `e10-cli auth status` 或 `e10-cli report creds` 取得完整鉴权三元组
+4. 再调用报表 API / 运行搭建脚本
+
+---
+
+## 二、API 请求必须携带三项（缺一不可）
+
+每次 HTTP 请求**必须同时**包含以下三项，且均来自 e10-cli auth 返回的用户会话信息：
+
+| # | 请求头 | 取值来源 | 硬约束 |
+|---|--------|----------|--------|
+| ① | `Cookie` | `auth.cookies.raw`（e10-cli auth profile） | **完整原始串**；禁止裁剪、去重、改写、重拼（如禁止自行拼 `ETEAMSID=xxx`） |
+| ② | `eteamsid` | 与 Cookie 中 `ETEAMSID` 值一致 | 独立请求头，不可省略 |
+| ③ | `User-Agent` | `auth.agentType` | 末尾必须为 `AgentType=<agentType>,IsAgent=true`（如 `AgentType=WorkBuddy,IsAgent=true`） |
+
+### 正确示例
+
+```http
+Cookie: <完整 Cookie 原始串来自 e10-cli auth cookies.raw> ; ETEAMSID=<ETEAMSID 值>
+eteamsid: <ETEAMSID 值>
+User-Agent: Mozilla/5.0 ... Chrome/<browser-version> Safari/537.36 Edg/<browser-version> AgentType=WorkBuddy,IsAgent=true
+```
+
+### 错误示例（禁止）
+
+```http
+# ❌ 仅裸 ETEAMSID，丢失 cookies.raw 其它键
+Cookie: ETEAMSID=<不应手动拼写>
+
+# ❌ 自行重拼 Cookie，非 e10-cli auth 原始串
+Cookie: <不应手动拼写>; ETEAMSID=<不应手动拼写>
+
+# ❌ User-Agent 占位符或未带 IsAgent
+User-Agent: ... AgentType=<agentType>,IsAgent=true
+
+# ❌ 缺少 eteamsid 请求头
+```
+
+---
+
+## 三、Python 脚本实现
+
+本 Skill 统一通过  构造请求头：
+
+```python
+from weaver_auth_headers import build_auth_headers
+
+headers = build_auth_headers(
+    host=creds["host"],
+    eteamsid=creds["eteamsid"],
+    cookie=creds["cookie"],          # cookies.raw 完整串
+    agent_type=creds["agent_type"],  # 来自 e10-cli auth
+    ebbusinessid=creds["ebbusinessid"],
+)
+```
+
+```json
+{
+  "host": "weapp.xxx.cn",
+  "eteamsid": "PCACCOUNT_...",
+  "cookie": "<cookies.raw 完整原始串>",
+  "agent_type": "WorkBuddy",
+  "ebbusinessid": "...",
+  "app_id": "..."
+}
+```
+
+---
+
+## 四、与脚本环境变量
+
+- 推荐：`eval "$(e10-cli report env)"` 或 `e10-cli auth status` 后由脚本读 profile。
+- 报表 API **仍须满足上述三项**；可从 `e10-cli auth status` 或 profile `auth` 取 `cookies.raw` / `agentType`。
+- 本报表包 **不依赖、不扫描** e10-cli。
+
+---
+
+## 五、常见错误
+
+| 现象 | 原因 | 处理 |
+|------|------|------|
+| `token为空或失效` | Cookie 被改写或只有裸 token | 请用户重新提供 ETEAMSID，再用 `cookies.raw` |
+| `token empty or invalid`（**保存**接口） | 部分自建环境 `saveReportDevInfo` multipart **缺 `et` 表单字段** | 走 `saveReportDevInfoAuto`（载荷矩阵自动补 `et` = 当前 ETEAMSID）—— 注意点 **ENV-11** |
+| 401 / 403 | 缺少 `eteamsid` 头或 User-Agent 无 IsAgent | 检查 `weaver_auth_headers.build_auth_headers` |
+| Agent 环境被拒 | `agentType` 与登录时不一致 | 用 `e10-cli auth set` 重新写入（`agentType` 由 eb_auth 统一生成） |
+
+---
+
+## 六、ETEAMSID 的环境隔离与过期（硬规则 · 注意点 ENV-11）
+
+| 规则 | 说明 |
+|------|------|
+| **按环境隔离** | ETEAMSID **绑定平台地址** —— **A 环境的凭证在 B 环境同样报 `token invalid`**；多个环境各自保存各自凭证，别混用 |
+| **会过期** | 过期后报「**登录超时**」/`token 为空或失效` —— **失效时直接向用户索要新凭证，勿反复重试** |
+| **沙箱 `spawn EBUSY`** | 无法 spawn 登录 CLI 时，统一走 **env 三件套**：`EB_HOST` + `EB_ETEAMSID` + `EB_AUTH_NO_CLI=1`（`eb_auth.js` 零 spawn 模式） |
+
+```bash
+# 缺凭证 / 过期：先一次就绪探测，再向用户索要（勿刷重试）
+e10-cli auth status
+# 沙箱环境（spawn 被禁）：
+export EB_HOST='<平台地址>' EB_ETEAMSID='<浏览器 Cookie 里 ETEAMSID 的值>' EB_AUTH_NO_CLI=1
+```
+
+---
+
+## 相关文档
+
+- `weaver-e10-cli auth` — 登录命令与 profile 结构
+- `references/`e10-cli auth` 文档 — 报表任务步骤 0 登录流程