weaver-e10-builder 1.6.10 → 1.6.11

package/skill-docs/references/report/ref-report-commands.md

@@ -2,6 +2,11 @@
 
 > 全部挂在 `e10-cli report` 下。全局加 `--profile <名>` 切环境、`--json` 出结构化结果。
 > 破坏性命令（`delete` / `lifecycle recycle purge` / `cleanup --apply`）必须用户本轮明确要求才执行。
+> 两级写法等价：`report build spec` = `report build`、`report find form` = `report find`、
+> `report find form-global` = `report find-global`、`report join suggest` = `report join-suggest`、
+> `report app search` = `report app-search`、`report verify self` = `report verify all`、
+> `report verify query` = `report query verify`、`report restore cell` = `report restore-cell`、
+> `report sheets restore` = `report restore-sheets`。
 
 ---
 
@@ -11,20 +16,32 @@
 |---|---|
 | `report build --spec <file>` | 声明式一步建表（**首选**）。spec 最小形状 `{"appId":"…","name":"报表名","columns":[{"title":"列标题"}]}` —— 列定义的键名是 **`columns[]`（不是 `fields`）**，**`form` 是表单名字符串（不是对象）**，写错会回「spec 需要包含 appId / name(报表名) / columns[]」；完整 schema 见 `spec-build-schema.md`。spec 写 `sources[]` 即**多数据源**，见 `guide-report-multisource.md` |
 | `report render <reportId> --app-id <id> [--page-row-count <n>] [--condition <json>] [--dump <file>]` | **渲染回读**：真跑一遍拿展开后的行列数，是「关联/公式/条件格式真的生效」的唯一证据 |
+| `report render values <reportId> --app-id <id> [--max-rows] [--max-cols]` | 渲染后打印**取值网格**（确认数据真的出来了；公式格恒无值） |
 | `report build --spec <file> --dry-run` | 只做定源与字段预检 |
 | `report build ... --form-confirmed --source-id <id>` | 用户已确认表 |
 | `report build ... --field-confirmed "列A,列B"` | 确认文案与显示名不同 |
 | `report find <appId> [表名]` / `--list` / `--suggest <kw>` | 应用内定源 |
+| `report find form-global --name <表名> (--app-name <应用名>\|--app-id <id>) [--max-apps 6]` | 跨应用限次找表：精确名优先，默认扫 6 个 / 硬顶 12；缺应用线索 exit 5 |
+| `report rebuild from-blueprint --blueprint <f> [--allow-ids <id,id>] [--apply]` | 按蓝图整表重建（灾后救援）。数据集声明用 `dataset` / `datasets[]`，格上用 `datasetKey` 选择；落库前跑克隆纪律与数据集白名单门禁。格坐标可写 `x/y` 或 `r/c`，`field`/`text` 可简写 Field/Const |
+| `report restore cell --report-id --app-id --cell-file <json> [--preagg-off] [--apply]` | 补写/恢复单个单元格；丢失的 Formula 格走这条通道才会存活 |
+| `report sheets restore --report-id --app-id --layout <快照.json> [--apply]` | 多 sheet 被并成单页后，按参考快照的 `sheetIndex` 还原分页 |
 | `report create blank --app-id --name` | 空白报表 |
 | `report create template --app-id --name --model-id` | 按模板建 |
 | `report create quick --app-id --name --quickly-file <f>` | 快速构建（列表式） |
 | `report create models` | 列出可用模板 |
+| `report card example [paragraph] [--out <f>]` | 导出卡片式报表 spec 模板（发票卡片 / 段落明细表） |
+| `report card build --spec <f> [--dry-run]` | 直构卡片式报表：锚点格纵向扩展、卡片内其余格左父格指向锚点；落库后回读校验 |
+| `report scene rules` | 打印三个分支场景的判定条件与强制配置 |
+| `report scene detect --req <f>` | 从需求文本识别场景 A/B/C（只读） |
+| `report scene check <id> --app-id [--scene A\|B\|C] [--seq-cells "x,y"] [--jump-cells "x,y=N"]` | 场景体检：公共父格 / 序号格 / 跳转链接 |
+| `report scene apply <id> --app-id --scene A\|B\|C [...] [--apply]` | 按场景写入配置（默认预演）：A 公共父格 `--at x,y --anchor "x,y;x,y"`；B 序号格 `--seq-cells`；C 跳转 `--jump-cells "x,y=N" --base --open-type` |
 
 ## 读取
 
 | 命令 | 用途 |
 |---|---|
 | `report read <reportId> [--fields]` | 基础信息 + 数据集 + 字段记录 |
+| `report dump cells <reportId> --app-id` | **只读**：按行打印每个格子的类型与内容，并标出空缺（定位「整格丢失」） |
 | `report list --app-id <id>` | 应用内报表列表 |
 | `report app-search --name <kw>` | 搜应用 |
 
@@ -38,9 +55,10 @@
 | `report dataset preview --dataset-id` | 预览数据 |
 | `report dataset check-used --report-id --dataset-id` | 是否仍被引用 |
 | `report dataset delete --report-id --dataset-id [--force]` | 移除数据集 |
-| `report dataset agg get\|save\|clear --dataset-id [--file]` | 预聚合 |
+| `report dataset agg get\|save\|clear --dataset-id [--file]` | 左侧数据集菜单里的「数据聚合」（不是解析优化的预聚合） |
 | `report dataset sort get\|save\|clear --dataset-id [--file]` | 排序 |
 | `report dataset replace --file <f>` | 整表换源（含 fieldMap） |
+| `report dataset heal [<reportId>] --app-id [--purge] [--apply]` | 修复数据集形态：`type=LOGIC` 大写原地换型（单元格引用自动重映射），`--purge` 顺带删 `sourceId` 为空的脏数据集。默认预演；落库后提示跑 `fix field-binding` |
 
 ## 查询条件
 
@@ -83,6 +101,9 @@
 | 命令 | 用途 |
 |---|---|
 | `report group list\|add\|delete --app-id [--name] [--group-id]` | 报表分组 |
+| `report group audit --app-id` | 分组归属体检：找出 `groupId=0` 的孤儿报表（菜单选取列不出它们，exit 3） |
+| `report group set --app-id --report-id --group-id [--apply]` | 把单张报表归到指定分组（默认预演） |
+| `report group sync --app-id [--report-id ...] [--apply]` | 批量把 `groupId=0` 孤儿归到 -1 |
 | `report lifecycle copy-and-menu --app-id --source-name` | 复制 + 授权 + 挂菜单 |
 | `report lifecycle add-menu --app-id --report-id --menu-name` | 挂菜单 |
 | `report lifecycle move --app-id --report-id --group-id` | 移到分组 |
@@ -104,11 +125,22 @@
 | `report validate href (--map\|--file\|--list) [--fix]` | 事件超链接 |
 | `report validate gridline\|blank (--file\|--inline)` | 网格线 / 空白风险 |
 | `report validate style [--list\|--inline]` | 默认分层样式 |
-| `report verify bind\|all\|meta\|condition\|format\|blank\|gridline\|contract\|limit <reportId>` | 线上体检 |
+| `report verify bind\|all\|meta\|condition\|format\|blank\|gridline\|contract\|limit\|anchors <reportId>` | 线上体检。`anchors` 专查汇总格三件套与父格锚点 |
 | `report verify parents <reportId> --app-id <id>` | 跨数据源父格体检（入口格唯一 / fieldKey 三段式 / id=currentField / 算子白名单 / 锚点） |
+| `report copy-health --app-id <id> [--report-id <rid>] [--probe] [--clean]` | 能否复制体检：数据集形态（大写 type / 空 sourceId / 重复挂载）+ 复制探针；有阻断项 exit 3 |
+| `report locate --report-id <rid> [--app-id <id>|--app-name <名>] [--max-apps <n>]` | 只有报表 ID 时反查所属应用、是否正常态、是否在回收站；未找到 exit 3 |
+| `report fix field-binding [<reportId>] --app-id [--table-name <名>] [--apply]` | 回补 Field 格的 `text`（字段显示名）与 `tableName`（数据集回显名）；换数据集 / heal 后必跑。默认预演 |
+| `report fix dataset-id [<reportId>] --app-id [--apply]` | 把外来数据集 ID 按引用自身的 sourceId 换回本报表；无法解析或映射冲突时整单中止（exit 3） |
+| `report fix empty-dataset <reportId> --app-id [--dataset-id <did>] [--source-type eteams] [--source-group sql] [--keep-old] [--apply]` | 重挂「字段为 0」的空壳数据集并整表重映射，删旧空壳 |
 | `report fix table-name <reportId> [--apply]` | 补 tableName |
 | `report fix freeze <reportId> [--anchor x,y] [--apply]` | 冻结单元格 |
+| `report fix parent <reportId> --set-parent "x,y=leftX,leftY" [--apply]` | 左父格定点修正（默认预演） |
+| `report fix dataset-name <reportId> --app-id [--apply]` | 去掉数据集名里重复拼的类型后缀（`X(业务模块)(业务模块)` → `X(业务模块)`） |
 | `report fix echo <reportId> --app-id` | 同 `query fix-echo` |
+| `report check-ids <reportId> --app-id` | **只读**：单元格里的数据集 id 是否都来自本报表（外来 id 会让设计器字段下拉空白） |
+| `report formula parent check <reportId> --app-id` | **只读**体检：公式格左父格是否等于被引用字段的区域根格；refX/refY 是否 -1；父格链是否经过公式格（不一致 exit 3） |
+| `report formula parent align <reportId> --app-id [--apply]` | 把公式格左父格对齐到区域根格，并把 refX/refY 归 -1 |
+| `report formula top <reportId> --set-top-parent "x,y=topX,topY" [--apply]` | 上父格定点修正（交叉表合计列 → 列头格） |
 
 ## 分析
 
@@ -116,6 +148,8 @@
 |---|---|
 | `report join-suggest --app-id (--parent-source\|--parent-form) (--child-source\|--child-form)` | 推断两表关联字段（须用户确认） |
 | `report py preagg (--fields <f> \| --report-id <id>) [--layout <f>]` | 预聚合可用性判定 |
+| `report preagg check <reportId> --app-id` | 线上判定：该报表是否应关闭预聚合（命中阻断条件 exit 2） |
+| `report preagg disable <reportId> --app-id [--apply]` | 关闭预聚合（写 `sheetConfig.dataPreAgg=false`） |
 | `report py left-filter --parent-ds/--parent-src/--parent-field --child-ds/--child-src/--child-field [--type]` | 算跨数据集父格筛选（输出 `subordination` + `leftFilterField`），定点修复时手工拼配置用 |
 
 ---
@@ -129,8 +163,12 @@
 | 2 | 成功但有警告；或 `--strict` 下有「待用户确认」项；预聚合建议关闭 |
 | 3 | `report build` / `join-suggest`：需要用户指定表，未建表 |
 | 4 | `report build`：需要用户指定字段，未建表或已删未完成报表 |
+| 5 | `report find form-global`：缺少应用线索（不做全系统扫描） |
 
 ## 默认只读、要 `--apply` 才写的命令
 
-`fix table-name`、`fix freeze`、`fix query-default`、`fix query-style`、`cleanup`。
+`fix table-name`、`fix freeze`、`fix query-default`、`fix query-style`、`fix parent`、
+`fix dataset-name`、`fix field-binding`、`fix dataset-id`、`fix empty-dataset`、
+`dataset heal`、`restore cell`、`sheets restore`、`rebuild from-blueprint`、`cleanup`、
+`group set`、`group sync`。
 不带 `--apply` 时只预演并打印将要做的改动。

package/skill-docs/references/report/report-baseinfo-defaults-guide.md

@@ -1,117 +1,117 @@
-# 报表基础字段默认值与命名规范（强制）
-
-> **权威来源**：`EdcReportDevBaseController.saveReportBaseInfo`（`@RequestParam defaultValue`） 
-> + `EdcReportDevBaseServiceImpl.buildNewReportDto` / `buildEmptySheetProp` / `resetReportListI18nName` 
-> **原则**：**对齐平台内置默认值**；禁止凭感觉改空、改哨兵值、或往 `name`/`nameLabelId` 塞特殊字符。
-
----
-
-## 一、baseInfo 内置默认值（设计器新建 API）
-
-`POST /api/bs/edc/report/baseInfo`（`weaver-edcreportd` · `EdcReportDevBaseController`）：
-
-| 参数 | 源码 `defaultValue` / 行为 | Agent / CLI **必须** |
-|------|---------------------------|----------------------|
-| `groupId` | **`"0"`** | 未指定分组时传 **`0`**。会出现在页面「全部」（`list?groupid=-1` 哨兵=查全部） |
-| `showOrder` | **`"1"`** | 未指定时传 **`1`**；勿传空 |
-| `name` | **必填**（无 default） | 非空；见 §二 |
-| `nameLabelId` | 可选（无 default） | **无多语言时显式传 `"-1"`**（与线上正常报表一致）；勿传空串、勿省略后写成脏值 |
-| `id` | `"0"` = 新建 | 新建用 `0`；更新用真实 reportId |
-| `appId` | `"0"`（须改为真实应用） | **必须**真实 appId |
-| `reportModel` | `"0"` | 无模板时保持 `0`；**模版创建**时传模板报表 ID（见 `report-create-modes-guide.md`） |
-| `quicklyParam` | 无（省略） | **快速构建-列表式**时传 QuicklyParam **JSON 字符串**；与 `reportModel>0` 互斥（模板优先） |
-| `systemType`（新建分支） | 服务端置 **`1`** | 普通 EB 报表勿擅自改成空/其它 |
-
-`buildNewReportDto` 其它落库默认：
-
-| 字段 | 默认 |
-|------|------|
-| `version` | `"1"` |
-| `enable` | `1` |
-| `configurable` | `0` |
-| `frontView` | `0` |
-| `enableInsight` | `0` |
-| `deleteType` | `0` |
-
-空 Sheet（`buildEmptySheetProp`）：`gridLine=0`、`rowHeaderVisible=0`、`colHeaderVisible=0`（与「页面布局默认关闭」一致）。
-
-### 1.1 哨兵值 ≠ 入库默认值（强制）
-
-| 值 | 用途 | Agent 行为 |
-|----|------|------------|
-| **`groupid=-1`（list 查询参数）** | 「查全部报表」哨兵 | 仅查询用 |
-| **`baseInfo.groupId=-1`** | 部分租户/应用下**默认分组展示值**（ 常见） | **原样保留**，禁止擅自改成其它 ID |
-| **`groupId=0`（Controller 新建 defaultValue）** | 新建 API 未指定分组时的入参默认 | 新建可显式传 `0`；**不要**事后乱改已有报表分组 |
-
-> **强制**：已有报表的 `groupId` **只认 `baseInfo` 回读**。保存 `saveReportDevInfo` 时把 `baseInfo.groupId` **原样写入 multipart**，禁止脚本硬编码 `0`/`-1`/臆造 ID。 
-> 改分组只能用户明确要求后走 `removeReport` 等换组接口。
-
-### 1.2 禁止随便改空 / 乱设分组
-
-| 禁止 | 说明 |
-|------|------|
-| 把 `groupId` / `showOrder` / `nameLabelId` 改成 `""` / `null` 指望「用默认」 | multipart 空串可能覆盖或落脏；应**显式传**上表默认值或 baseInfo 原值 |
-| **擅自改已有报表 `groupId`** | 以参考报表/`baseInfo` 为准；「默认分组」可能是 `0` 或展示为 `-1`，勿凭记忆改写 |
-| 更新 baseInfo 时清空已有合法默认字段 | `updateReportBase` 本就不改 `group_id`；改分组用 `removeReport` |
-| 为「好看」改 `frontView`/`configurable`/`gridLine` 等 | 未需求点名则保持平台默认 |
-
----
-
-## 二、name / nameLabelId 规范（强制）
-
-### 2.1 `name`（报表名称）
-
-| 规则 | 说明 |
-|------|------|
-| 非空 | 去掉首尾空白后长度 ≥ 1 |
-| **禁止**控制字符 | 不得含 `\r` `\n` `\t` 及其它 ISO 控制符（`\u0000-\u001F`、`\u007F`） |
-| 禁止首尾异常空白 | 写入前 `trim()`；勿保留仅空白名 |
-| 同名校验 | 服从平台 `checkReportName`（如 SAME_NAME） |
-
-### 2.2 `nameLabelId`（多语言标识）
-
-源码 `resetReportListI18nName`：
-
-```java
-if (StringUtils.isNotBlank(nameLabelId) && !"-1".equals(nameLabelId)) {
- Long.parseLong(nameLabelId); // 脏字符 → NumberFormatException →「报表内部错误」
-}
-```
-
-| 规则 | 说明 |
-|------|------|
-| 无多语言 | **必须** `"-1"`（字符串） |
-| 有多语言 | **纯数字**雪花 ID 字符串，无空白、无 `\r\n` |
-| **禁止** | `"-1\r\n"`、空串、`"null"`、带空格数字、任意非数字（除精确 `"-1"`） |
-
-### 2.3 事故对照
-
-`BBB` + `nameLabelId="-1\r\n"` → 应用报表页 `list?groupid=-1` 整页 500「报表内部错误」。
-
----
-
-## 三、CLI（优先）
-
-```bash
-# 落库前本地校验（不访问网络）
-e10-cli report validate base --name "资产信息统计" --name-label-id -1 --group-id 0
-
-# 线上报表元数据巡检
-e10-cli report verify meta <reportId> [appId]
-```
-
-校验失败 exit ≠ 0；Agent **禁止**跳过继续 save。
-
-内部错误根因与修复全流程：`report-internal-error-guide.md`。
-
-
----
-
-## 四、与其它文档
-
-| 文档 | 关系 |
-|------|------|
-| `api-report-build-fast-path.md` §2.1 | 建壳命名 + groupId/name 纪律 |
-| `e10-cli report -cli.md` | CLI 映射 |
-| `failure-cleanup-and-nonblocking-guide.md` | 失败空壳清理 |
-| `report-self-check-guide.md` | 布局/父格自检（本篇只管 base 元数据） |
+# 报表基础字段默认值与命名规范（强制）
+
+> **权威来源**：`EdcReportDevBaseController.saveReportBaseInfo`（`@RequestParam defaultValue`）
+> + `EdcReportDevBaseServiceImpl.buildNewReportDto` / `buildEmptySheetProp` / `resetReportListI18nName`
+> **原则**：**对齐平台内置默认值**；禁止凭感觉改空、改哨兵值、或往 `name`/`nameLabelId` 塞特殊字符。
+
+---
+
+## 一、baseInfo 内置默认值（设计器新建 API）
+
+`POST /api/bs/edc/report/baseInfo`（`weaver-edcreportd` · `EdcReportDevBaseController`）：
+
+| 参数 | 源码 `defaultValue` / 行为 | Agent / CLI **必须** |
+|------|---------------------------|----------------------|
+| `groupId` | **`"0"`** | 未指定分组时传 **`0`**。会出现在页面「全部」（`list?groupid=-1` 哨兵=查全部） |
+| `showOrder` | **`"1"`** | 未指定时传 **`1`**；勿传空 |
+| `name` | **必填**（无 default） | 非空；见 §二 |
+| `nameLabelId` | 可选（无 default） | **无多语言时显式传 `"-1"`**（与线上正常报表一致）；勿传空串、勿省略后写成脏值 |
+| `id` | `"0"` = 新建 | 新建用 `0`；更新用真实 reportId |
+| `appId` | `"0"`（须改为真实应用） | **必须**真实 appId |
+| `reportModel` | `"0"` | 无模板时保持 `0`；**模版创建**时传模板报表 ID（见 `report-create-modes-guide.md`） |
+| `quicklyParam` | 无（省略） | **快速构建-列表式**时传 QuicklyParam **JSON 字符串**；与 `reportModel>0` 互斥（模板优先） |
+| `systemType`（新建分支） | 服务端置 **`1`** | 普通 EB 报表勿擅自改成空/其它 |
+
+`buildNewReportDto` 其它落库默认：
+
+| 字段 | 默认 |
+|------|------|
+| `version` | `"1"` |
+| `enable` | `1` |
+| `configurable` | `0` |
+| `frontView` | `0` |
+| `enableInsight` | `0` |
+| `deleteType` | `0` |
+
+空 Sheet（`buildEmptySheetProp`）：`gridLine=0`、`rowHeaderVisible=0`、`colHeaderVisible=0`（与「页面布局默认关闭」一致）。
+
+### 1.1 哨兵值 ≠ 入库默认值（强制）
+
+| 值 | 用途 | Agent 行为 |
+|----|------|------------|
+| **`groupid=-1`（list 查询参数）** | 「查全部报表」哨兵 | 仅查询用 |
+| **`baseInfo.groupId=-1`** | 部分租户/应用下**默认分组展示值**（验证常见） | **原样保留**，禁止擅自改成其它 ID |
+| **`groupId=0`（Controller 新建 defaultValue）** | 新建 API 未指定分组时的入参默认 | 新建可显式传 `0`；**不要**事后乱改已有报表分组 |
+
+> **强制**：已有报表的 `groupId` **只认 `baseInfo` 回读**。保存 `saveReportDevInfo` 时把 `baseInfo.groupId` **原样写入 multipart**，禁止脚本硬编码 `0`/`-1`/臆造 ID。
+> 改分组只能用户明确要求后走 `removeReport` 等换组接口。
+
+### 1.2 禁止随便改空 / 乱设分组
+
+| 禁止 | 说明 |
+|------|------|
+| 把 `groupId` / `showOrder` / `nameLabelId` 改成 `""` / `null` 指望「用默认」 | multipart 空串可能覆盖或落脏；应**显式传**上表默认值或 baseInfo 原值 |
+| **擅自改已有报表 `groupId`** | 以参考报表/`baseInfo` 为准；「默认分组」可能是 `0` 或展示为 `-1`，勿凭记忆改写 |
+| 更新 baseInfo 时清空已有合法默认字段 | `updateReportBase` 本就不改 `group_id`；改分组用 `removeReport` |
+| 为「好看」改 `frontView`/`configurable`/`gridLine` 等 | 未需求点名则保持平台默认 |
+
+---
+
+## 二、name / nameLabelId 规范（强制）
+
+### 2.1 `name`（报表名称）
+
+| 规则 | 说明 |
+|------|------|
+| 非空 | 去掉首尾空白后长度 ≥ 1 |
+| **禁止**控制字符 | 不得含 `\r` `\n` `\t` 及其它 ISO 控制符（`\u0000-\u001F`、`\u007F`） |
+| 禁止首尾异常空白 | 写入前 `trim()`；勿保留仅空白名 |
+| 同名校验 | 服从平台 `checkReportName`（如 SAME_NAME） |
+
+### 2.2 `nameLabelId`（多语言标识）
+
+源码 `resetReportListI18nName`：
+
+```java
+if (StringUtils.isNotBlank(nameLabelId) && !"-1".equals(nameLabelId)) {
+    Long.parseLong(nameLabelId); // 脏字符 → NumberFormatException →「报表内部错误」
+}
+```
+
+| 规则 | 说明 |
+|------|------|
+| 无多语言 | **必须** `"-1"`（字符串） |
+| 有多语言 | **纯数字**雪花 ID 字符串，无空白、无 `\r\n` |
+| **禁止** | `"-1\r\n"`、空串、`"null"`、带空格数字、任意非数字（除精确 `"-1"`） |
+
+### 2.3 事故对照
+
+`BBB` + `nameLabelId="-1\r\n"` → 应用报表页 `list?groupid=-1` 整页 500「报表内部错误」。
+
+---
+
+## 三、CLI（优先）
+
+```bash
+# 落库前本地校验（不访问网络）
+e10-cli report validate base --name "资产信息统计" --name-label-id -1 --group-id 0
+
+# 线上报表元数据巡检
+e10-cli report verify meta <reportId> [appId]
+```
+
+校验失败 exit ≠ 0；Agent **禁止**跳过继续 save。
+
+内部错误根因与修复全流程：`report-internal-error-guide.md`。
+
+
+---
+
+## 四、与其它文档
+
+| 文档 | 关系 |
+|------|------|
+| `api-report-build-fast-path.md` §2.1 | 建壳命名 + groupId/name 纪律 |
+| `e10-cli report-cli.md` | CLI 映射 |
+| `failure-cleanup-and-nonblocking-guide.md` | 失败空壳清理 |
+| `report-self-check-guide.md` | 布局/父格自检（本篇只管 base 元数据） |

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

@@ -1,6 +1,6 @@
 # e-Builder 报表搭建实战指导手册
 
-> **冷启动禁止通读**：见 `cold-start-scan-guide.md`。仅需要界面逐步操作指导时再读。
+> **冷启动禁止通读**：见 `api-report-build-fast-path.md`。仅需要界面逐步操作指导时再读。
 > **设计器 UI 全景（开始/页面/公式 全菜单 + API 对照）**：见同目录 **`report-designer-feature-map.md`**。
 
 ## 文档定位
@@ -39,20 +39,20 @@
 设计器分为三大区域：
 
 - **左侧：数据集面板**
- - 显示已添加的数据集（如「分组报表数据源(内置)」）
- - 展开可看到字段列表
- - 右键数据集可执行：自定义名称、数据预览、筛选条件、数据聚合、数据排序、替换数据集、移除
- - 把字段拖到中间画布即可生成数据单元格
+  - 显示已添加的数据集（如「分组报表数据源(内置)」）
+  - 展开可看到字段列表
+  - 右键数据集可执行：自定义名称、数据预览、筛选条件、数据聚合、数据排序、替换数据集、移除
+  - 把字段拖到中间画布即可生成数据单元格
 
 - **中间：报表设计画布**
- - 类似 Excel 的网格区域
- - 选中单元格后，右侧属性面板会显示该单元格的属性
- - 顶部有「开始」「页面」「公式」三个主 Tab
+  - 类似 Excel 的网格区域
+  - 选中单元格后，右侧属性面板会显示该单元格的属性
+  - 顶部有「开始」「页面」「公式」三个主 Tab
 
 - **右侧：属性面板**
- - 「单元格」Tab：单元格类型、数据集合、字段、父格、扩展方向、显示方式、分组排序等
- - 「事件」Tab：配置 PC 链接地址、H5 链接地址、打开方式（弹出页 / 当前页 / 执行 JS 代码）
- - 「样式」Tab：主题模板、背景色、配色交替方式、文本样式
+  - 「单元格」Tab：单元格类型、数据集合、字段、父格、扩展方向、显示方式、分组排序等
+  - 「事件」Tab：配置 PC 链接地址、H5 链接地址、打开方式（弹出页 / 当前页 / 执行 JS 代码）
+  - 「样式」Tab：主题模板、背景色、配色交替方式、文本样式
 
 ### 2.2 顶部菜单关键入口
 
@@ -162,22 +162,22 @@
 2. 合并左侧维度列单元格，输入文字「大区合计」
 3. 在指标列输入公式，例如 `=SUM(F5)`（F5 为该组指标字段单元格）
 4. 选中「大区合计」文字单元格：
- - 左父格 = 自定义为分组字段单元格（如 B5）
- - 上父格 = 无
- - 扩展方向 = 不扩展
+   - 左父格 = 自定义为分组字段单元格（如 B5）
+   - 上父格 = 无
+   - 扩展方向 = 不扩展
 5. 选中指标合计单元格：
- - 左父格 = 自定义为分组字段单元格（如 B5）
- - 上父格 = 无
- - 扩展方向 = 不扩展
+   - 左父格 = 自定义为分组字段单元格（如 B5）
+   - 上父格 = 无
+   - 扩展方向 = 不扩展
 
 #### 总计行（报表最底部）
 
 1. 在报表最下方插入一行，输入「合计」
 2. 指标列输入公式，例如 `=SUM(F5)` 或 `=SUM(指标字段区域)`
 3. 选中「合计」文字单元格和指标合计单元格：
- - 左父格 = 无
- - 上父格 = 无
- - 扩展方向 = 不扩展
+   - 左父格 = 无
+   - 上父格 = 无
+   - 扩展方向 = 不扩展
 
 ### 步骤 6：添加查询条件
 
@@ -188,8 +188,8 @@
 弹窗中可配置：
 
 - **高级搜索显示形式**：默认样式 / 展开条件
- - 默认样式：预览页右上角显示搜索图标，点击后展开筛选条件
- - 展开条件：预览页顶部直接展示搜索栏
+  - 默认样式：预览页右上角显示搜索图标，点击后展开筛选条件
+  - 展开条件：预览页顶部直接展示搜索栏
 - **启用所有条件任一条件切换**：开启后查询条件之间从「and」变成「or」
 - **筛选下拉框无字段时不显示**：仅对筛选生效
 - **仅在查询时获取数据**：减少初始加载
@@ -221,10 +221,10 @@
 3. 默认值类型选「自定义」，默认值可填 `{thisweek}` 或留空
 4. 显示位置选「平铺」或「下拉」
 5. 点击「添加条件」，在下方的查询条件行中选择：
- - **选择类型**：默认选 **条件字段**（仅需求明确写 SQL 时才选 SQL）
- - 数据集 = 对应数据集合
- - 数据集字段 = 目标字段（fieldKey：`{dataSetId}.{sourceId}.{fieldName}`）
- - 条件 = 等于 / 区间等（与字段类型匹配）
+   - **选择类型**：默认选 **条件字段**（仅需求明确写 SQL 时才选 SQL）
+   - 数据集 = 对应数据集合
+   - 数据集字段 = 目标字段（fieldKey：`{dataSetId}.{sourceId}.{fieldName}`）
+   - 条件 = 等于 / 区间等（与字段类型匹配）
 6. **日期区间**：设计器「选项」默认全部勾选（全部/今天/本周/本月/…/自定义）；API 写入见下文
 7. 点击「确定」保存
 
@@ -299,23 +299,23 @@
 #### 配置步骤
 
 1. **页面 → 查询设置**
- - 高级搜索显示形式：选择「默认样式」或「展开条件」
- - 保存
+   - 高级搜索显示形式：选择「默认样式」或「展开条件」
+   - 保存
 2. **页面 → + 添加查询条件**
- - 显示名称：签约日期
- - 字段类型：日期区间
- - 显示位置：平铺
- - 条件必填：根据需要开启
- - 点击「添加条件」
- - 在查询条件行中：
- - 数据集字段 = 签约日期
- - 条件类型会自动匹配为日期区间
- - 点击「确定」
+   - 显示名称：签约日期
+   - 字段类型：日期区间
+   - 显示位置：平铺
+   - 条件必填：根据需要开启
+   - 点击「添加条件」
+   - 在查询条件行中：
+     - 数据集字段 = 签约日期
+     - 条件类型会自动匹配为日期区间
+   - 点击「确定」
 3. **预览测试**
- - 点击预览
- - 若选择「默认样式」，在右上角搜索图标中打开筛选面板
- - 若选择「展开条件」，筛选栏直接显示在顶部
- - 选择日期区间后点击查询，确认数据被过滤
+   - 点击预览
+   - 若选择「默认样式」，在右上角搜索图标中打开筛选面板
+   - 若选择「展开条件」，筛选栏直接显示在顶部
+   - 选择日期区间后点击查询，确认数据被过滤
 
 > 若用户希望默认显示「本月」或「今天」数据：默认值类型选 **自定义**，填系统参数 `{thismonth}` 或 `{date}`（今天区间写 `["{date}","{date}"]`）。详见 `query-condition-api-guide.md` §五。
 
@@ -326,13 +326,13 @@
 #### 配置步骤
 
 1. **页面 → + 添加查询条件**
- - 显示名称：所属部门
- - 字段类型：下拉框
- - 默认值类型：常规
- - 显示位置：平铺
+   - 显示名称：所属部门
+   - 字段类型：下拉框
+   - 默认值类型：常规
+   - 显示位置：平铺
 2. 点击「添加条件」
- - 数据集字段 = 部门字段
- - 条件 = 等于
+   - 数据集字段 = 部门字段
+   - 条件 = 等于
 3. 点击「确定」
 4. 预览时，下拉框会显示部门选项，选择后自动过滤
 
@@ -432,11 +432,11 @@
 ### 5. 添加查询条件
 - 页面 → 查询设置 → 高级搜索显示形式：默认样式 → 保存
 - 页面 → + 添加查询条件
- - 显示名称：签约日期
- - 字段类型：日期区间
- - 显示位置：平铺
- - 添加条件：数据集字段 = 签约日期
- - 确定
+  - 显示名称：签约日期
+  - 字段类型：日期区间
+  - 显示位置：平铺
+  - 添加条件：数据集字段 = 签约日期
+  - 确定
 
 ### 6. 预览保存
 - 点击右上角「预览」验证数据

package/skill-docs/references/report/report-case-prompts.md

@@ -0,0 +1,104 @@
+# 报表案例搭建提示语句速查（可复制粘贴）
+
+> 用法：按需求挑一条，把 `<>` 占位符替换成实际值，整段发给 AI 即可。
+> AI 按「识别边界」自动命中场景与通道；未命中时提示语句里点名的命令会强制路由。
+> 各场景机制细节见对应指南（每条末尾标注）。**覆盖 8 类：卡片 / 段落 / 档案 / 钻取 / 分页分组 / 分片冻结 / 高阶交叉 / 折叠树。**
+
+---
+
+## 1. 卡片式报表（一条记录=一张卡片，如发票）
+
+> 按卡片式格式搭一张报表：每条记录一张卡片，卡片内为标签/值网格（字段 A/B/C…，无对应字段的格用 Const 占位）；
+> 数据源表 `<sourceName>`（sourceId `<sid>`，appId `<appId>`）；卡片纵向堆叠同页不分页；
+> 用 `card example` 出模板改字段后 `card build`，dry-run 通过再 `--apply`，落库后回读验收。
+> —— 通道：`e10-cli report card build`；指南 `card-report-guide.md`
+
+## 2. 段落明细表（一条记录=一个段落块，块内多信息区）
+
+> 按段落明细表格式搭一张报表：每条记录一个段落块，块内分「XX信息 / YY信息 / ZZ信息」三个信息区，
+> 每区一条整行底色标题条 + 标签/值网格；数据源表 `<sourceName>`（sourceId `<sid>`，appId `<appId>`）；
+> 字段映射：区块1 用字段 A/B/C，区块2 用字段 D/E/F……；记录间空一行，同页堆叠不分页；
+> 用 `card example paragraph` 出模板改字段后 `card build`，dry-run 通过再 `--apply`，落库后回读验收并交设计器地址。
+> —— 通道：`e10-cli report card build --example paragraph`；指南 `card-report-guide.md` §3.1
+
+## 3. 档案式报表（一个实体+N个一对多明细带，如个人档案）
+
+> 按档案式报表搭一张「XX基本档案」：一个实体一份档案，纵向分区块——
+> 「基本信息」（标签/值网格，字段 A/B/C/D…）＋「教育经历」（表头：时间/性质/学历/学校/专业，一对多明细）
+> ＋「工作经历」（表头：…）＋「培训记录」（表头：…）；
+> 主表 sourceId `<sid0>`，各明细子表 sourceId `<sid1/sid2/…>`（appId `<appId>`）；
+> 保持 A4 自然分页；多源走 `rebuild from-blueprint`（datasets[]+datasetKey），
+> 落库后回读验收：各带锚点独立扩展、带标题/表头行父格齐全、check-ids 无外来 datasetId。
+> —— 通道：单源 `card build` / 多源 `rebuild from-blueprint`；指南 `dossier-report-guide.md`
+
+## 4. 数据钻取类报表（列表+行级钻取/排序）
+
+> 按数据钻取格式搭一张订单列表：列为 `<列清单>`，数据源 `<sid>`（appId `<appId>`）；
+> 点击「订单号」列钻取到明细报表 `<reportId>`（参数 `ddhh=SELF`），点击「客户名称」钻到 `<reportId2>`；
+> 点击「订购日期」按升序排序；钻取参数引用只允许左侧列，「导出明细」列放最右；
+> 用 `build spec`（columns[].link / columns[].sort）落库，落库后回读验收 pcHreflink。
+> —— 通道：`e10-cli report build` 场景 D；指南 `drilldown-report-guide.md`；
+>    ⚠️ 能力边界：「不预览直接导出」暂无已验证 API（先以钻取列替代）
+
+## 5. 分页分组报表（标题重复/分组编号/每页N行/条件预警）
+
+> 按分页分组格式搭一张产品信息统计表：分组两层（类别→产品，第二层编号用系统序号），
+> 标题行随类别动态重复；每页固定 10 行（`layout.pageRowCount:10`）；
+> 库存量小于订购量整行预警、订购金额超 1000 红字（`columns[].rule`）；
+> 数据源 `<sid>`（appId `<appId>`）；用 `build spec` 落库，回读验收分页配置与父格链。
+> —— 通道：`e10-cli report build` 场景 E + seq（场景B）；指南 `paged-group-report-guide.md`；
+>    ⚠️ 验证项：页内逐页汇总、跨格整行预警
+
+## 6. 多源分片与冻结表（左行维度+右侧多片交叉统计）
+
+> 按多源分片与冻结格式搭一张统计大表：左侧行维度「类别+名称」两列，
+> 右侧三片分别按「地区 / 供应商 / 雇员」交叉统计数量与金额，每片带小计，底部总计行；
+> 数据源 `<sid1/sid2/sid3>`（appId `<appId>`）；不分页（`layout.paginate:false`）、
+> 冻结左侧 2 列和上方表头（`freezeRows:1 + freezeCols:2`）、报表居左；
+> 多源走 `rebuild from-blueprint`，落库后回读验收：fixed=1 唯一且坐标正确、pagination=false、showLocation=1、check-ids 干净。
+> —— 通道：`e10-cli report build` 场景 F（单源/冻结/分页）+ `rebuild from-blueprint`（多源分片）；
+>    指南 `shard-freeze-report-guide.md`
+
+## 7. 高阶交叉表（多级行维度 × 多指标列组，如销售额等级分析）
+
+> 按高阶交叉格式搭一张销售额等级分析：行维度三级「一级品类→二级品类→品牌」逐级缩进，
+> 每级带小计行，底部总计；列侧多指标组「销量对比/销售额/…」（组内 2014/2015/占比/合计多列）；
+> 环比列红绿条件色（涨红/跌绿）；数据源 `<sid>`（appId `<appId>`）；
+> 多级行维度+多列组走 rebuild 直构路径（crosstab guide + 本指南 §一坐标模板），
+> 落库后回读验收父格拓扑与 Formula 存活。
+> —— 通道：`e10-cli report build` 直构（场景 H）；指南 `advanced-crosstab-tree-guide.md`
+
+## 8. 折叠树报表（左侧树形层级可收起展开，如地区应收汇总）
+
+> 按折叠树格式搭一张地区应收汇总：左侧「组织层级」树形列（可收起展开，`display:"tree"`），
+> 列侧多层费用组（组内小计/已上线/未上线 → 个数/金额子列），底部合计行；
+> 数据源 `<sid>`（自包含层级；跨表层级给 subordination 映射），appId `<appId>`；
+> 冻结左 1 列+上方表头、居左；单源用 `build spec`、多源列组用 rebuild 直构，
+> 落库后回读验收：树形格 displayType=Tree 且左父格 -1,-1、冻结锚点唯一、check-ids 干净。
+> —— 通道：`e10-cli report build` `columns[].display:"tree"`（场景 I）+ rebuild 直构（多层列组）；
+>    指南 `advanced-crosstab-tree-guide.md`；⚠️ 默认展开 sheetConfig 键名 = 设计器确认项
+
+## 9. 分栏报表四式（行分栏 / 列分栏 / 卡片分栏 / 行分栏汇总 · 场景 J）
+
+分栏 = 渲染级配置（页面→报表展示→分栏），设计带保持单带；spec 侧经 `layout.sheetConfig` /
+`spec.sheetConfig` 透传（**分栏键名待设计器确认回填**，验证法：设计器建分栏报表 → `getReportDevInfo`
+→ `sheetProps[0].sheetConfig`）。四式提示语句见 `column-split-report-guide.md` §三（J-1/J-2/J-3/J-4），
+要点：J-1/J-3 单源走 `build spec` / `card build`（卡片式可 `qrcode` 透传条码）；J-2/J-4 多级结构走 rebuild 直构。
+
+## 10. 财务统计表（同比/环比/占比/排名/累计 · 场景 K）
+
+> 按同比环比财务统计表搭一张报表：年份/月份两级分组，销售额按月汇总；
+> 指标列：月环比 / 年同比 / 年内占比 / 年内排名+总排名 / 年内累计+总累计；
+> **在数据加工 SQL 里用窗口函数预计算五类指标**（LAG 环比 / SUM OVER 占比累计 / RANK OVER 排名），
+> 报表纯绑字段（`build spec` 直出，百分比列 format:percent）；
+> 数据源 `<sid 或 SQL 视图>`（appId `<appId>`）；年份格分组缩进、冻结表头；
+> 落库后回读验收：字段绑定与格式、无公式列依赖。
+> —— 通道：`build spec` + 数据集预计算列（**语义正解**）；指南 `financial-stats-report-guide.md`；
+>    ⚠️ 报表侧 SpreadJS 相对引用（环比/同比/排名/累计）= 验证项；内置 COMB_* 组合公式捕获法见指南 §二
+
+---
+
+## 通用尾巴（任何一条都可追加）
+
+> 落库前给我 dry-run 结果；落库后回读验收（格数/字段数/父格链/目标键值三项）并贴设计器地址；
+> 改前先对现有报表 `getReportDevInfo` 快照留档，只动点名的 reportId。