weaver-e10-builder 1.6.16 → 1.7.1

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

@@ -1,174 +1,180 @@
-# 报表命令速查
-
-> 全部挂在 `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`。
-
----
-
-## 建表
-
-| 命令 | 用途 |
-|---|---|
-| `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>` | 搜应用 |
-
-## 数据集侧栏
-
-| 命令 | 用途 |
-|---|---|
-| `report dataset add <reportId> --app-id (--form <名>\|--source-id <id>)` | 给已有报表**再挂一个数据源**（同源只挂一次） |
-| `report dataset list <reportId> --app-id` | 已挂载数据集 |
-| `report dataset rename --dataset-id --name` | 改显示名 |
-| `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 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` |
-
-## 查询条件
-
-| 命令 | 用途 |
-|---|---|
-| `report query list <reportId> --app-id` | 列出条件 |
-| `report query save <reportId> --app-id --item <f> [--show-where 高级搜索\|筛选]` | 保存一条 |
-| `report query type <reportId> --app-id [--show-where]` | 设显示方式（**报表级批量覆盖**） |
-| `report query check-echo <reportId> --app-id` | 回显体检 |
-| `report query fix-echo <reportId> --app-id` | 短码化修复 |
-| `report query verify <reportId> --app-id [--fix]` | Q1~Q10 合规体检 |
-| `report fix query-default <reportId> --app-id [--set ...] [--all] [--apply]` | 补默认值三件套 |
-| `report fix query-style <reportId> --app-id [--id ...] [--delete-id ...] [--apply]` | 清未点名的展示样式 |
-| `report validate query --map-show-where "顶部筛选"` | 显示方式说法映射 |
-
-## 单元格筛选 / 事件
-
-| 命令 | 用途 |
-|---|---|
-| `report cell-filter list <reportId> --app-id` | 列出所有带筛选的单元格（自定义筛选 / 结果筛选） |
-| `report cell-filter set <reportId> --app-id --cell <行,列> --op <算子> [--field <字段>] [--value <值>] [--kind custom\|result] [--append]` | 写入单元格筛选。`--cell` 坐标与 `fields[].x,y` 一致（**x=行，y=列**）；`--field` 缺省为该格自己的字段；选项类字段的值写选项名或 valueKey（逗号分隔多个） |
-| `report cell-filter remove <reportId> --app-id --cell <行,列> [--kind custom\|result]` | 清空该格筛选（缺省两类都清） |
-| `report cell-event list <reportId> --app-id` | 列出配置了链接的单元格 |
-| `report cell-event set <reportId> --app-id --cell <行,列> (--pc <链接> \| --h5 <链接>) [--open 弹出页\|当前页\|执行js代码]` | 写入单元格事件链接；`--pc` 可写 URL 或 JS（`--open 执行js代码`）；`--open` 缺省**保持原值**（新链接为弹出页）。全角 `？＆＝` 会直接报错 |
-| `report cell-event clear <reportId> --app-id --cell <行,列> [--pc\|--h5]` | 清链接（缺省 PC+H5 都清，打开方式复位为弹出页） |
-
-> **落库契约**：两组的写入都会改 `fields[]` 与 workbook `style.cellType`，双保存后**回读比对**，不一致即报错。
-> `saveReportDevInfo` 在 `designKey` 过期时会返回 **code=200 + `data:"您当前的数据不是最新的…"`**（静默失败）；命令会识别该文案并自动重读重写一次。
-
-## 权限
-
-| 命令 | 用途 |
-|---|---|
-| `report scope list <reportId> --app-id` | 读共享范围 |
-| `report scope set <reportId> --app-id --scope "all"` / `"部门:销售部,人员:张三"` | 设共享范围（全量替换 viewRight） |
-| `report scope matrix list\|save\|delete <reportId> --app-id [--type 1\|-1]` | 权责矩阵 |
-
-## 分组 / 生命周期 / 版本
-
-| 命令 | 用途 |
-|---|---|
-| `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` | 移到分组 |
-| `report lifecycle transfer --report-id <ids> (--app-id \| --app-name)` | 转移到别的应用 |
-| `report lifecycle recycle list\|restore\|purge --app-id / --report-id` | 回收站 |
-| `report version save\|list <reportId>` | 版本 |
-| `report snapshot set\|list <reportId> [--cron] [--snapshot-name]` | 定时快照 |
-| `report restore <reportId> --version <versionId>` | 从版本回滚 |
-| `report cleanup --app-id [--prefix] [--apply]` | 空壳报表清理 |
-
-## 校验 / 体检 / 修复
-
-| 命令 | 用途 |
-|---|---|
-| `report validate base --name ...` | 报表名等基础字段规范 |
-| `report validate condition (--file\|--inline\|--map\|--report-id)` | 条件格式白名单 |
-| `report validate format (--map\|--file\|--list)` | 数字格式 / 日期分组 / 字号 |
-| `report validate transform (--map\|--file\|--list)` | 转换面板 |
-| `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\|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]` | 上父格定点修正（交叉表合计列 → 列头格） |
-
-## 分析
-
-| 命令 | 用途 |
-|---|---|
-| `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`），定点修复时手工拼配置用 |
-
----
-
-## 退出码约定
-
-| 码 | 含义 |
-|---|---|
-| 0 | 成功 |
-| 1 | 失败（校验不通过 / 接口报错） |
-| 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`、`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` 时只预演并打印将要做的改动。
+# 报表命令速查
+
+> 全部挂在 `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`。
+
+---
+
+## 建表
+
+| 命令 | 用途 |
+|---|---|
+| `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>` | 搜应用 |
+
+## 数据集侧栏
+
+| 命令 | 用途 |
+|---|---|
+| `report dataset add <reportId> --app-id (--form <名>\|--source-id <id>)` | 给已有报表**再挂一个数据源**（同源只挂一次） |
+| `report dataset list <reportId> --app-id` | 已挂载数据集 |
+| `report dataset rename --dataset-id --name` | 改显示名 |
+| `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\|add\|remove\|clear --dataset-id [--file\|--inline] [--app-id]` | 左侧数据集菜单里的「数据聚合」（不是解析优化的预聚合）；本地校验结构，保存后回读比对 |
+| `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` |
+
+## 查询条件
+
+| 命令 | 用途 |
+|---|---|
+| `report query list <reportId> --app-id` | 列出条件 |
+| `report query save <reportId> --app-id --item <f> [--show-where 高级搜索\|筛选]` | 保存一条 |
+| `report query type <reportId> --app-id [--show-where]` | 设显示方式（**报表级批量覆盖**） |
+| `report query check-echo <reportId> --app-id` | 回显体检 |
+| `report query fix-echo <reportId> --app-id` | 短码化修复 |
+| `report query verify <reportId> --app-id [--fix]` | Q1~Q10 合规体检 |
+| `report fix query-default <reportId> --app-id [--set ...] [--all] [--apply]` | 补默认值三件套 |
+| `report fix query-style <reportId> --app-id [--id ...] [--delete-id ...] [--apply]` | 清未点名的展示样式 |
+| `report validate query --map-show-where "顶部筛选"` | 显示方式说法映射 |
+
+## 单元格筛选 / 事件
+
+| 命令 | 用途 |
+|---|---|
+| `report cell-filter list <reportId> --app-id` | 列出所有带筛选的单元格（自定义筛选 / 结果筛选） |
+| `report cell-filter set <reportId> --app-id --cell <行,列> --op <算子> [--field <字段>] [--value <值>] [--kind custom\|result] [--append]` | 写入单元格筛选。`--cell` 坐标与 `fields[].x,y` 一致（**x=行，y=列**）；`--field` 缺省为该格自己的字段；选项类字段的值写选项名或 valueKey（逗号分隔多个） |
+| `report cell-filter remove <reportId> --app-id --cell <行,列> [--kind custom\|result]` | 清空该格筛选（缺省两类都清） |
+| `report cell-event list <reportId> --app-id` | 列出配置了链接的单元格 |
+| `report cell-event set <reportId> --app-id --cell <行,列> (--pc <链接> \| --h5 <链接>) [--open 弹出页\|当前页\|执行js代码]` | 写入单元格事件链接；`--pc` 可写 URL 或 JS（`--open 执行js代码`）；`--open` 缺省**保持原值**（新链接为弹出页）。全角 `？＆＝` 会直接报错 |
+| `report cell-event clear <reportId> --app-id --cell <行,列> [--pc\|--h5]` | 清链接（缺省 PC+H5 都清，打开方式复位为弹出页） |
+| `report cell-transform show\|list <reportId> --app-id [--cell <行,列>]` | 读取单元格「转换」配置 / 列出非默认转换 |
+| `report cell-transform set <reportId> --app-id --cell <行,列> [--map <中文类型>] [--trans <transType>] [--browser <ids>] [--options <json>] [--html on\|off] [--qrcode no\|barcode\|qrcode] [--prefix <s>] [--suffix <s>] [--hidden on\|off] [--direction <方向>] [--inline\|--file <json>]` | 写转换：只改点名键，双写 `fields[]` + workbook `style.cellType`，回读逐键比对 |
+| `report cell-transform clear <reportId> --app-id --cell <行,列>` | 恢复「无转换」并回读确认 |
+| `report code-block get <reportId> --app-id [--sheet-id\|--sheet-index] [--out <file>]` | 读报表代码块（按 sheet；`cusCode` 为 UTF-8 base64，CLI 自动解码） |
+| `report code-block set <reportId> --app-id [--sheet-id\|--sheet-index] (--code <text>\|--file <file>\|--template)` | 写代码块，写后回读比对 |
+| `report code-block clear <reportId> --app-id [--sheet-id\|--sheet-index]` | 清空代码块（保存空串并回读确认） |
+
+> **落库契约**：两组的写入都会改 `fields[]` 与 workbook `style.cellType`，双保存后**回读比对**，不一致即报错。
+> `saveReportDevInfo` 在 `designKey` 过期时会返回 **code=200 + `data:"您当前的数据不是最新的…"`**（静默失败）；命令会识别该文案并自动重读重写一次。
+
+## 权限
+
+| 命令 | 用途 |
+|---|---|
+| `report scope list <reportId> --app-id` | 读共享范围 |
+| `report scope set <reportId> --app-id --scope "all"` / `"部门:销售部,人员:张三"` | 设共享范围（全量替换 viewRight） |
+| `report scope matrix list\|save\|delete <reportId> --app-id [--type 1\|-1]` | 权责矩阵 |
+
+## 分组 / 生命周期 / 版本
+
+| 命令 | 用途 |
+|---|---|
+| `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` | 移到分组 |
+| `report lifecycle transfer --report-id <ids> (--app-id \| --app-name)` | 转移到别的应用 |
+| `report lifecycle recycle list\|restore\|purge --app-id / --report-id` | 回收站 |
+| `report version save\|list <reportId>` | 版本 |
+| `report snapshot set\|list <reportId> [--cron] [--snapshot-name]` | 定时快照 |
+| `report restore <reportId> --version <versionId>` | 从版本回滚 |
+| `report cleanup --app-id [--prefix] [--apply]` | 空壳报表清理 |
+
+## 校验 / 体检 / 修复
+
+| 命令 | 用途 |
+|---|---|
+| `report validate base --name ...` | 报表名等基础字段规范 |
+| `report validate condition (--file\|--inline\|--map\|--report-id)` | 条件格式白名单 |
+| `report validate format (--map\|--file\|--list)` | 数字格式 / 日期分组 / 字号 |
+| `report validate transform (--map\|--file\|--list)` | 转换面板 |
+| `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\|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]` | 上父格定点修正（交叉表合计列 → 列头格） |
+
+## 分析
+
+| 命令 | 用途 |
+|---|---|
+| `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`），定点修复时手工拼配置用 |
+
+---
+
+## 退出码约定
+
+| 码 | 含义 |
+|---|---|
+| 0 | 成功 |
+| 1 | 失败（校验不通过 / 接口报错） |
+| 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`、`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 元数据） |