weaver-work-cli 0.1.23 → 0.1.25

package/skills/weaver-e10-builder/references/report/formula-cell-api-guide.md

@@ -0,0 +1,258 @@
+# 公式单元格 API 写入规范
+
+> **适用场景**：通过 API / 脚本写入报表 workbook（`saveReportWithCacheConfig` + `saveReportDevInfo`），或生成含 Formula 单元格的 ReportProps JSON。 
+> **权威原则**：设计器手动保存的格式为准；文档与脚本冲突时以 `getReportDevInfo` 回读结果为准。
+
+---
+
+## 一、问题现象
+
+设计器里输入 `=IF(J3=0,0,L3/J3)` 能正常保存并展示，但 **API 脚本写入「相同公式」可能导致设计器整页空白**。
+
+**根因不是 IF 函数被禁用**，而是持久化字段格式与手动保存不一致：
+
+| 字段 | 设计器手动保存 ✅ | 脚本 API 常见错误 ❌ |
+|------|-------------------|----------------------|
+| `cellText` / 顶层 `formula` | `IF(J3=0,0,L3/J3)` **无前导 `=`** | `=IF(J3=0,0,L3/J3)` **带 `=`** |
+| `countType` | `count` | `none` |
+| `displayType` | `Group` | `List` |
+| `groupType` | `null` | `none` |
+| `style.formatter` | 空字符串 | `0.00%`、`General` 等 |
+
+平台源码（`EdcReportDevDesignServiceImpl`）从 workbook 提取 Formula 时：
+
+```java
+if (field.getCellType() == Formula) {
+ field.setCellText(cell.getFormula()); // 原样写入 DB
+}
+```
+
+设计器保存时会去掉 leading `=`；脚本若 workbook 顶层 `formula` 带 `=`，DB 里 `cellText` 也会带 `=`。 
+设计器再次加载时 SpreadJS 可能再补 `=` → 变成 `==IF(...)` 或解析失败 → **整页空白**。
+
+DB 种子数据同样 **不带 `=`**：`'IFERROR(G5/F5,"--")'`、`'SUM(F5)'`。
+
+---
+
+## 二、Agent 必遵守则（硬约束）
+
+生成或修改含公式单元格的报表时，**必须**同时满足：
+
+1. **`cellText` 与 workbook 顶层 `formula` 均不带前导 `=`** 
+ - 设计器输入：`=IF(J3=0,0,L3/J3)` 
+ - API 存储：`IF(J3=0,0,L3/J3)` 
+ - 写入前统一：`bare = formula_expr.lstrip("=")`
+
+2. **`countType` 必须为 `count`**（勿用 `none`）
+
+3. **`displayType` 必须为 `Group`**（分组报表中的公式格；勿用 `List`）
+
+4. **`groupType` 必须为 `null`**（JSON 中写 `null`，勿写 `"none"`）
+
+5. **`expandType` 为 `NoExpand`**
+
+6. **`style.formatter` 为空字符串**（与手动保存对齐；百分比展示依赖公式结果或后续在设计器设格式，脚本勿擅自写 `0.00%`）
+
+7. **父格坐标**：公式格与同级 Field 子格一致，指向根格（如 `leftX=2, leftY=5` 对应 F 列责任人，0-based）
+
+8. **双保存**：`saveReportWithCacheConfig` + `saveReportDevInfo`，保存后用 `getReportDevInfo` 回读验证
+
+9. **除零保护**：占比/达成率类公式推荐 `IF(分母=0,0,分子/分母)`，与设计器手动写法一致
+
+---
+
+## 三、workbook 单元格结构（dataTable）
+
+Formula 单元格在 workbook `dataTable[row][col]` 中的标准结构：
+
+```json
+{
+ "formula": "IF(J3=0,0,L3/J3)",
+ "style": {
+ "hAlign": 1,
+ "vAlign": 1,
+ "formatter": "",
+ "cellType": {
+ "typeName": "FormulaCellType",
+ "editorType": 1,
+ "cellType": "Formula",
+ "cellText": "IF(J3=0,0,L3/J3)",
+ "displayType": "Group",
+ "countType": "count",
+ "groupType": null,
+ "expandType": "NoExpand",
+ "leftX": 2,
+ "leftY": 5,
+ "topX": -1,
+ "topY": -1,
+ "refX": -1,
+ "refY": -1,
+ "subordination": ["", ""],
+ "formatterType": [],
+ "orderType": "no",
+ "isActiveParent": false,
+ "arrowType": "None",
+ "textDirection": "FromLeftToRight",
+ "allowOverflow": true,
+ "hiddenContext": "0",
+ "transSelectOptions": [],
+ "browserType": [],
+ "thumbnail": "NoDisplay"
+ }
+ },
+ "tag": { "formatterType": ["common"] }
+}
+```
+
+**注意**：顶层 `formula` 与 `style.cellType.cellText` **内容相同且均无前导 `=`**。
+
+---
+
+## 四、参考实现 `make_formula()`
+
+```python
+def make_formula(formula_expr, formatter=""):
+ """构建 Formula 单元格，格式对齐设计器手动保存。"""
+ bare = formula_expr.lstrip("=")
+ ct = {
+ "allowOverflow": True,
+ "typeName": "FormulaCellType",
+ "editorType": 1,
+ "leftX": ROOT_ROW,
+ "leftY": ROOT_COL,
+ "topX": -1,
+ "topY": -1,
+ "refX": -1,
+ "refY": -1,
+ "expandType": "NoExpand",
+ "displayType": "Group",
+ "cellType": "Formula",
+ "cellText": bare,
+ "transSelectOptions": [],
+ "browserType": [],
+ "thumbnail": "NoDisplay",
+ "hiddenContext": "0",
+ "orderType": "no",
+ "formatterType": [],
+ "subordination": ["", ""],
+ "countType": "count",
+ "groupType": None,
+ "isActiveParent": False,
+ "arrowType": "None",
+ "textDirection": "FromLeftToRight",
+ }
+ fmt = formatter if formatter is not None else ""
+ return {
+ "style": {"hAlign": 1, "vAlign": 1, "formatter": fmt, "cellType": ct},
+ "formula": bare,
+ "tag": {"formatterType": ["common"]},
+ }
+```
+
+项目参考：`本地工作目录` 的 `make_formula()`。
+
+---
+
+## 五、公式表达式规范
+
+### 5.1 单元格引用
+
+- 使用 Excel A1 风格：`J3`、`L3`、`AA3`
+- 行号与数据行一致（通常第 3 行即 `x=2` 的数据行写 `...3`）
+- 引用同报表内 Field 汇总格，不引用数据集字段名
+
+### 5.2 常用模式
+
+| 场景 | 设计器输入 | API 存储（无前导 `=`） |
+|------|-----------|------------------------|
+| 达成率 | `=IF(J3=0,0,L3/J3)` | `IF(J3=0,0,L3/J3)` |
+| 业绩占比 | `=IF(L3=0,0,M3/L3)` | `IF(L3=0,0,M3/L3)` |
+| 合计 | `=SUM(F4:F10)` | `SUM(F4:F10)` |
+| 安全除法 | `=IFERROR(G5/F5,"--")` | `IFERROR(G5/F5,"--")` |
+
+### 5.3 IF / IFERROR
+
+- **IF、IFERROR 均允许**通过 API 写入；此前「IF 导致空白」是格式错误，不是函数限制
+- 占比类公式 **推荐** `IF(分母=0,0,...)` 而非裸除法
+
+### 5.4 禁止写法
+
+| 禁止 | 原因 |
+|------|------|
+| `cellText: "=SUM(A1)"` | 双 `=` 导致 SpreadJS 解析失败 |
+| `countType: "none"` | 与手动保存不一致，可能引发展示异常 |
+| `displayType: "List"` | 公式格应为 `Group` |
+| `groupType: "none"` | 应为 `null` |
+| 仅写 `style.cellType.cellText` 不写顶层 `formula` | workbook 与设计器可能不同步 |
+
+---
+
+## 六、验证清单
+
+写入公式后，Agent **必须**执行：
+
+### 6.1 `getReportDevInfo` 回读
+
+对每个 Formula 格（如 K3 → `x=2, y=10`）检查：
+
+- [ ] `cellType` 为 `Formula`
+- [ ] `cellText` **不以 `=` 开头**
+- [ ] `countType` 为 `count`
+- [ ] `displayType` 为 `Group`
+- [ ] `groupType` 为 `null`
+- [ ] 公式内容与预期一致（如 `IF(J3=0,0,L3/J3)`）
+
+### 6.2 保存接口
+
+- [ ] `saveReportWithCacheConfig` 返回 200
+- [ ] `saveReportDevInfo` 返回 200
+- [ ] `checkSave` 返回 200（可选）
+
+### 6.3 设计器 smoke test
+
+- [ ] 刷新设计器 URL 后页面非空白
+- [ ] 公式格可点击编辑，显示为 `=IF(...)`（设计器 UI 会自动加 `=`）
+- [ ] 预览/解析后公式列有数值
+
+### 6.4 本地预检
+
+```bash
+python e10-cli report validate <配置文件路径>
+```
+
+脚本会对 Formula 单元格检查前导 `=`、`countType`、`displayType` 等（见脚本内 `validate_formula_fields`）。
+
+---
+
+## 七、与父格 / 跨数据集筛选的关系
+
+- 公式格 **不参与** subordination / leftFilterField（通常 `subordination: ["", ""]`）
+- 公式引用的是 **同报表内已配置好的 Field 汇总格**（如 L3 总业绩、J3 指标）
+- 被引用的 Field 格若跨数据集，须先按 `cross-dataset-filter-guide.md` 配好筛选；公式本身不再重复配 fieldKey
+
+---
+
+## 八、EBU 经营报表示例（37 列）
+
+| 列 | 字段 | 公式（API 存储，无前导 `=`） |
+|----|------|------------------------------|
+| K | 达成率 | `IF(J3=0,0,L3/J3)` |
+| R | 新客户业绩占比 | `IF(L3=0,0,M3/L3)` |
+| S | 纯专项业绩占比 | `IF(L3=0,0,N3/L3)` |
+| T | 信创客户业绩占比 | `IF(L3=0,0,O3/L3)` |
+| X | 新签合同个数占比 | `IF(V3=0,0,W3/V3)` |
+| Z | 纯专项合同个数占比 | `IF(V3=0,0,Y3/V3)` |
+| AB | 信创合同个数占比 | `IF(V3=0,0,AA3/V3)` |
+
+报表 ID 示例：`1304979556231593985` 
+验证脚本：`本地工作目录`
+
+---
+
+## 九、相关文档
+
+- `SKILL.md` — 能力一步骤 6.2 公式配置
+- `ai-report-workflow.md` §六 — 工作流中的公式规则
+- `report-config-schema.md` §2.5 — Formula Schema
+- `cross-dataset-filter-guide.md` — 跨数据集筛选（与公式格配合）
+- `report-building-guide.md` §8.2 — 占比/同环比为前端 SpreadJS 计算

package/skills/weaver-e10-builder/references/report/guide-report-build.md

@@ -0,0 +1,131 @@
+# 新建报表（声明式一步落库）
+
+> 命令：`e10-cli report build --spec <spec.json>` · 结构详解见 `spec-build-schema.md`
+> 交付形态：给出设计器地址即完成，详见 `report-delivery-contract.md`
+
+---
+
+## 一、一句话说清
+
+报表 = **一张表单当数据源** + **若干列绑定到该表单的字段** + 可选布局/查询条件/权限。
+
+`report build` 一次调用跑完：定源 → 字段预检 → 建表 → 挂数据集 → 落库 → 回读，中途不留空壳。
+
+```bash
+e10-cli report build --spec spec.json           # 正式建表
+e10-cli report build --spec spec.json --dry-run # 只看定源与字段绑定，不写任何数据
+```
+
+---
+
+## 二、最小 spec
+
+```json
+{
+  "appId": "1315401436173942786",
+  "name": "销售明细报表",
+  "form": "销售订单",
+  "columns": [
+    { "title": "客户名称", "width": 160 },
+    { "title": "合同金额", "width": 120, "format": "货币" },
+    { "title": "签订日期", "width": 140, "format": "短日期" }
+  ]
+}
+```
+
+| 键 | 说明 |
+|---|---|
+| `appId` | 应用 ID（必填） |
+| `name` | 报表名。**写入即最终名**，不留 `__build_*`、不落库后改名 |
+| `form` / `sourceId` | 表单名或表单 id。**两个都不给就是没指明表**，会停下让你选 |
+| `columns[]` | 列定义。`title` 同时是**字段匹配键** |
+| `layout` | `{ title, freezeRows, showLocation }` |
+| `style` / `titleStyle` / `headerStyle` / `bodyStyle` | 分层样式；不给就是默认表头样式 |
+
+列的可选项：`width`、`format`（`货币`/`短日期`/`百分比`…，见 `cell-config-echo-guide.md`）、`formula`（公式列不参与字段绑定）、`groupType`（日期分组）、`rule`（条件格式，见 `condition-format-guide.md`）、`field` / `fieldName`（显式指定字段）。
+
+---
+
+## 三、两处「必须问用户」的门禁
+
+这是本能力最重要的两条规则。两处都**不建表、不回退、不猜**。
+
+### 规则 B · 表没指明或不是完全精准匹配
+
+触发：需求没写表名；或应用内检索是模糊命中 / 同名多条 / 未命中。
+
+行为：退出码 **3**，列出 `candidates[]`，**不建任何报表**。
+
+```bash
+e10-cli report find <appId> --list             # 列应用内全部表单
+e10-cli report find <appId> "销售订单"          # 精确/模糊查找
+e10-cli report build --spec spec.json --form-confirmed --source-id <id>   # 用户确认后复跑
+```
+
+### 规则 A · 列字段没有精确匹配
+
+触发：列标题与该表单字段的**显示名**对不上（归一化后仍不等），且没有显式指定。
+
+行为：退出码 **4**，列出 `unmatched[]` + `allFields[]`（全量可选字段），**不建报表**（若已建到一半会删掉）。
+
+**绝对禁止**用系统字段（`name`/`id`/`create_time`…）兜底。历史事故：需求写「姓名」，被静默绑到系统字段 `name`（真实显示名是「标题」），报表能用但数据全错，用户毫不知情。
+
+三种收场方式：
+
+```bash
+# 1) 从候选里挑，写进 spec.fieldMap
+"fieldMap": { "党组织": "所属党委" }
+
+# 2) 文案与字段真实显示名不同但确实有意如此
+e10-cli report build --spec spec.json --field-confirmed "列名A,列名B"
+e10-cli report build --spec spec.json --field-confirmed        # 不带值 = 全部确认
+
+# 3) 先看清楚再决定
+e10-cli report build --spec spec.json --dry-run
+```
+
+---
+
+## 四、退出码
+
+| 码 | 含义 |
+|---|---|
+| 0 | 成功，已输出设计器地址 |
+| 2 | 成功但有警告（显示名不一致 / tableName 缺失 / 重复数据集挂载） |
+| 3 | 规则 B：需要用户指定表，**未建表** |
+| 4 | 规则 A：需要用户指定字段，**未建表或已删掉未完成的报表** |
+| 1 | 失败 |
+
+---
+
+## 五、建完之后
+
+```bash
+e10-cli report read <reportId> --fields        # 回读字段记录
+e10-cli report verify bind <reportId> --app-id <appId>   # 字段绑定体检
+e10-cli report verify all  <reportId> --app-id <appId>   # 综合自检
+```
+
+**搭表不要求渲染。** 落库成功、字段绑定正确就是交付完成。全量渲染超过 5 万格必然失败且空耗几十秒，
+真要评估用 `e10-cli report verify limit <reportId>` 做算术预检（见 `report-designer-feature-map.md`）。
+
+---
+
+## 六、不要做的事
+
+- ❌ 建 `__build_*` / `__probe_*` 空壳试探 —— 字段预检不需要报表就能做
+- ❌ 落库后再改报表名 —— 直接用目标名建
+- ❌ 跨报表复用 `datasetId` —— 数据集不能跨报表引用
+- ❌ 同一张表挂两次 —— 左侧会出现重复数据源分组；`report dataset list` 可核对
+- ❌ 一上来拉全系统表单分组树 —— 用户给了应用就在应用内找（`report find`）
+
+---
+
+## 相关文档
+
+- `spec-build-schema.md` —— spec 全字段
+- `add-dataset-registration-guide.md` —— 数据集注册契约
+- `field-bind-exact-match-guide.md` —— 字段精确绑定细则
+- `dataset-table-field-contract-guide.md` —— `tableName` 与字段三件套
+- `api-report-build-fast-path.md` —— 接口层逐步流程
+- `report-create-modes-guide.md` —— 空白 / 模板 / 快速构建三种建法

package/skills/weaver-e10-builder/references/report/guide-report-modify.md

@@ -0,0 +1,100 @@
+# 修改已有报表（只改用户点名项）
+
+> **最高优先级规则**：用户没点名的东西，一个都不动。
+> 完整版见 `user-request-scope-only-guide.md`。
+
+---
+
+## 一、铁律
+
+改已有报表时，**默认什么都不改**。用户说了什么就改什么，其余部分原样写回。
+
+**禁止**：
+
+- ❌ 「顺便」改单元格内容、合并、样式、行高、父格、公式、查询条件、数据集、权限、快照、报表名
+- ❌ 为了「好维护」把整张表重新识别、重扫字段、重建布局
+- ❌ 用「全表重写更干净」当借口覆盖用户的手工调整
+- ❌ 改列宽/冻结/居左时顺手改样式或拆掉合并 —— 这些是**独立**的改动
+
+**允许**：只 patch 点名项；其余从回读结果原样写回。
+
+拿不准就**问用户**，不要替用户决定。
+
+---
+
+## 二、典型改法
+
+### 改字段（列）
+
+```bash
+e10-cli report read <reportId> --fields          # 先看清楚现状
+```
+
+改列 = 重建布局再整体保存。走 `report build` 的重跑不适用（会新建一张），
+定点改要用 `report fix` 系列或重新组表后 `saveReportDevInfo`。
+
+**关键**：保存前必须回读最新的 `designKey`（乐观锁），并且**从回读的 `fields[]` 重建工作簿**，
+不能把读到的空 `sheets` 原样写回 —— 那会把整张表的布局清掉。详见 `safe-partial-save-guide.md`。
+
+### 改显示名 / 改名
+
+报表名走 `baseInfo`，字段显示名走字段接口，两者不是一回事。
+
+### 改共享范围
+
+```bash
+e10-cli report scope list <reportId> --app-id <appId>     # 先读
+e10-cli report scope set  <reportId> --app-id <appId> --scope "部门:销售部"
+```
+
+⚠️ `savePermissions` 是**全量替换**：只改 `viewRight` 时，`disableRight` 与 `viewMatrixRight`
+必须原样带回，否则会把「不可见」矩阵一起清掉。
+
+### 冻结 / 居左
+
+```bash
+e10-cli report fix freeze <reportId> --anchor <x,y>        # 预演
+e10-cli report fix freeze <reportId> --anchor <x,y> --apply
+```
+
+唯一持久化标记是 `cell.tag.fixed`；`frozenRowCount` / `tag.fixedCell` 只影响设计器显示。
+
+### 改查询条件
+
+见 `guide-report-query.md`。**改条件不改显示方式**，除非用户点名。
+
+---
+
+## 三、改完必做
+
+```bash
+e10-cli report verify all <reportId> --app-id <appId>   # 绑定 + 结构 + tableName
+```
+
+改坏了**立刻回滚**：
+
+```bash
+e10-cli report version list <reportId>                  # 找版本
+e10-cli report restore <reportId> --version <versionId> # 回滚
+```
+
+布局被冲掉（字段数骤降）时的首选是回滚，不是「再存一次试试」。
+
+---
+
+## 四、保存前的三道防线
+
+CLI 已内置，改动时不要绕过：
+
+1. **布局守卫** —— 字段与工作簿内容不能同时为空；保存后字段数不能掉。
+2. **空白守卫** —— `showLocation=0` 会被纠正为 2；`scrollPage=1` 却没内容字段会拦下。
+3. **雪花守卫** —— `snapshot.sheetId/id/jobId` 是 number 直接拒绝保存（`Number()` 截断会让设计区空白）。
+
+---
+
+## 相关文档
+
+- `targeted-fix-guide.md` —— 定点改的细则
+- `safe-partial-save-guide.md` —— 安全局部保存
+- `designer-blank-prevention-guide.md` —— 设计区空白的成因与预防
+- `report-delivery-contract.md` —— 改完交付什么

package/skills/weaver-e10-builder/references/report/guide-report-multisource.md

@@ -0,0 +1,143 @@
+# 多数据源报表（跨数据集）· spec 写法与落地
+
+> **命令**：`e10-cli report build --spec <spec.json>`
+> **校验**：`e10-cli report verify parents <reportId> --app-id <id>`
+> **证明跑得通**：`e10-cli report render <reportId> --app-id <id>`
+> 配套规则见 `cross-dataset-filter-guide.md`（fieldKey 写法）、
+> `datasource-selection-and-parent-filter-guide.md`（区域与入口格）。
+
+---
+
+## 一、什么时候需要多数据源
+
+**先问能不能不加。** 主表上已有可展示字段时，不要为了"好看/完整"再挂一张表回显名称
+（`datasource-selection-and-parent-filter-guide.md` §一）。只有主表确实取不到该字段、
+且业务必须跨表关联时才加第二源。
+
+典型：主从明细（客户 × 该客户的订单）、维度下钻（合同 × 供应商主数据）。
+
+---
+
+## 二、spec 写法
+
+```json
+{
+  "appId": "1316387504760741888",
+  "name": "客户订单综合分析",
+  "formConfirmed": true,
+  "sources": [
+    { "key": "customer", "form": "客户信息表" },
+    { "key": "order", "form": "销售订单表",
+      "link": { "parent": "customer", "parentField": "客户名称", "childField": "客户名称",
+                "type": "Equals" } }
+  ],
+  "layout": { "title": "客户订单综合分析", "freezeRows": 1, "showLocation": "left" },
+  "columns": [
+    { "source": "customer", "title": "客户名称", "field": "客户名称", "width": 170 },
+    { "source": "customer", "title": "客户等级", "field": "客户等级", "width": 120 },
+    { "source": "order", "title": "订单编号", "field": "订单编号", "width": 150 },
+    { "source": "order", "title": "销售金额", "field": "销售金额", "width": 150, "format": "huobi" }
+  ]
+}
+```
+
+| 键 | 说明 |
+|---|---|
+| `sources[0]` | **父源**。它的列区域是报表的根，不写 `link` |
+| `sources[].key` | spec 内引用名，`columns[].source` 用它；必须唯一 |
+| `sources[].form` / `sourceId` | 与单源 spec 同义；`sourceId` 是已确认的表单 ID |
+| `sources[].sourceType/Group/Name` | 数据集注册契约，普通应用留空即可（默认 `LOGIC` + `weaver-ebuilder-form-service`） |
+| `sources[].link.parent` | 挂在哪个源上；**必须是左边紧邻的那个源** |
+| `link.parentField` / `childField` | 关联字段，写**显示名或 `field_xxx`**，各自在**本方**表里解析 |
+| `link.type` | 比较方式，TitleCase 枚举，默认 `Equals` |
+| `columns[].source` | 该列属于哪个源；**缺省 = 父源** |
+
+**不写 `sources` 时行为与单源报表完全一致** —— 老 spec 不需要改。
+
+---
+
+## 三、布局是怎么排的
+
+平台侧"多数据集"的机制是：字段按来源排成**连续区域**，区域入口格挂到左边区域的父格上。
+
+```
+┌─ 父源区域 ────────┐┌─ 子源区域（连续） ──────────┐
+│ 客户名称 客户等级 ││ 订单编号  销售金额  订单状态 │
+│   ↑               ││   ↑ 入口格（挂父格筛选）     │
+│   └── 默认父格     ││     其余格：普通链式父格     │
+└───────────────────┘└─────────────────────────────┘
+```
+
+CLI 按 `columns[]` 的顺序自动切区域：
+
+- **父源区域**：整行首列默认父格，其余逐列链式；
+- **子源区域**：**只有入口格**（该区域第一列）写 `subordination` + `leftFilterField` 并指向父区域，
+  其余格一律普通链式父格 —— **不逐格重复配**（逐格重复会让预览异常）。
+
+### 关键：关联键不必是入口格自己的字段
+
+文档示例里入口格指向「联系方式」，而关联字段是「供应商名称」。**锚点看位置，关联键看字段引用**，
+两者互不相干。所以 `link.parentField`/`childField` 只要能在那张表里唯一定位到字段即可，
+**不需要**把关联字段单独排成一列。
+
+### 当前限制
+
+每个**子源只能占一段**连续区域（父源可以多段）。平台允许一段以上（每段各配一次入口筛选），
+CLI 暂不支持——需要时请在设计器里手工补，或把该源的列排到一起。
+
+---
+
+## 四、落库时 CLI 自动做的事
+
+1. 逐个源走**规则 B**（定源）与**规则 A**（字段精确绑定），任一不通过都不建表；
+2. 逐个源挂数据集，并断言 N 个 datasetId 互不相同（两个源指向同一张表会退化成自引用，直接报错）；
+3. 按 `link` 解析关联字段（显示名歧义时报错，不取首条）；
+4. 组表时把 `subordination` / `leftFilterField` 写到入口格；
+5. **双保存**：先 `saveReportDevInfo`，再 `saveReportWithCacheConfig`；
+6. 跨源报表**自动关预聚合**（`dataPreAgg=false`）—— 父格筛选参与取数，预聚合结果不成立，
+   这是必然代价不是配置错误。设计器「预聚合」开关会显示为关闭。
+
+> `saveReportWithCacheConfig` 并非所有站点都有。缺该路由时 CLI 降级为警告，
+> 报表本身仍然建成；此时跨源缓存的生效情况需在设计器里手工保存一次确认。
+
+---
+
+## 五、验证
+
+```bash
+e10-cli report verify parents <reportId> --app-id <appId>   # 结构合规
+e10-cli report render <reportId> --app-id <appId>           # 真跑一遍看行数
+```
+
+`verify parents` 检查：入口格唯一、同区域其余格留空、`subordination[1] === leftFilterField[0].currentField`、
+`id === currentField`、`type` 在白名单内、fieldKey 三段式且指向正确的数据集、锚点落在真实的父区域单元格上。
+
+**`render` 是唯一能证明关联真的生效的手段** —— 结构对不代表数据对。判读方式：
+
+- 父源 N 行、子表 M 条明细 → 展开后数据行数应 = 子表匹配到的明细数；
+- 用 `--dump <file>` 把 workbook 写出来，逐行看父源字段是否只在该组第一行出现、后续行留空。
+
+---
+
+## 六、常见报错与处置
+
+| 报错 | 含义 | 处置 |
+|---|---|---|
+| `源「b」的列排在源「a」后面，但没写 link` | 子源没声明怎么关联 | 补 `link` |
+| `link.parent=「a」，但它左边紧邻的区域来自「b」` | 关联只能指向左边紧邻区域 | 调整列顺序或改 `link.parent` |
+| `源「b」被拆成了 N 段连续区域` | 子源列没排在一起 | 把该源的列排到一起 |
+| `源「x」与「y」解析到同一张表单` | 两个源指同一张表 | 改为单源布局 |
+| `源「x」的父格关联字段「…」匹配到 N 个字段` | 显示名歧义 | 改用 `field_xxx` 精确指定 |
+| `带缓存保存未成功` | 站点缺 `saveReportWithCacheConfig` 路由 | 见 §四 说明；在设计器里手工保存一次 |
+
+---
+
+## 七、相关文档
+
+| 文档 | 关系 |
+|---|---|
+| `cross-dataset-filter-guide.md` | fieldKey 三段式、`id=currentField`、filter 结构权威说明 |
+| `datasource-selection-and-parent-filter-guide.md` | 区域/入口格规则、少挂源的判定顺序 |
+| `spec-build-schema.md` | spec 全量字段 |
+| `preaggregate-auto-disable-guide.md` | 为什么跨源必须关预聚合 |
+| `api-report-build-fast-path.md` | 双保存顺序与禁忌 |