weaver-work-cli 0.1.24 → 0.1.26

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

@@ -0,0 +1,392 @@
+# 报表列表页 · 生命周期管理 API 指南
+
+> **页面场景**：`/sp/ebdapp/detail/{appId}/report` 报表卡片「…」菜单
+> **源码依据**：`EdcReportDevBaseController.java`、`EdcDataPermissionController.java`、`EdcReportDevDesignController.java`（weaver-edcreportd）
+> **菜单 HTTP 封装**：e10-cli `menu.js` → `POST /api/cusapp/app/savePublishMenu`
+> **鉴权**：必须走 e10-login，请求头见 `api-auth-headers.md`（Cookie.raw + eteamsid + User-Agent 三项）
+
+---
+
+## 一、页面加载（进入报表列表）
+
+| 接口 | 方法 | 说明 |
+|------|------|------|
+| `/api/bs/edc/report/group/list?appid={appId}` | GET | 报表分组树 |
+| `/api/bs/edc/report/appRight?appId={appId}` | GET | 当前用户在应用下的报表操作权限（增删改） |
+| `/api/bs/edc/report/list?appid={appId}&groupid=-1&objId=-1` | GET | 报表卡片列表（含 deletePermission 等） |
+| `/api/bs/edc/report/getReportModels` | GET | **模版创建**：系统模板列表（见 `report-create-modes-guide.md`） |
+
+**单张报表操作前（可选校验）**
+
+| 接口 | 方法 | 说明 |
+|------|------|------|
+| `/api/bs/edc/report/appReportRight?appId={appId}&reportId={reportId}` | GET | 单报表 EDIT/DELETE/ADD 权限 |
+
+---
+
+## 一附、新建报表对话框 · 三种模式（强制）
+
+> 页面「新建报表」三卡片 → 同一 `POST /api/bs/edc/report/baseInfo`，靠 **`reportModel` / `quicklyParam`** 分支。
+> **完整载荷与 QuicklyParam 结构** → **`report-create-modes-guide.md`**。
+> CLI：`e10-cli report create blank|template|quick` · `e10-cli report create models`
+
+| UI 卡片 | 关键字段 | 说明 |
+|---------|----------|------|
+| 从空白创建 | `reportModel=0`，无 `quicklyParam` | 空壳；再 `addDataset` + `saveReportDevInfo` |
+| **模版创建** | **`reportModel={模板ID}`** | 先 `GET getReportModels`；服务端 `copySheet` |
+| **快速构建-列表式** | **`quicklyParam` JSON 串**（`reportModel=0`） | 服务端挂数据集 + 生成列表字段；默认 `simpleList` |
+
+服务端优先级：`reportModel>0` → 模版；否则 `quicklyParam` 非空 → 快速构建；否则空白。
+
+**勿混淆** Skill `assets/template-*-report.json`（Agent 脚手架）与平台 `getReportModels` 模板。
+
+---
+
+## 一附 B、列表页其它操作（分组 / 视图 / 移动 / 转移 / 矩阵）
+
+> **完整规则与 CLI** → **`report-list-page-ops-guide.md`** · `e10-cli report --help-page`
+
+| UI | API / 机制 | CLI |
+|----|------------|-----|
+| 新建/删除分组 | `group/list` + `group/save`（删=从 JSON 去掉） | `e10-cli report group list\|add\|delete` |
+| 卡片/列表视图 + 快速排序 | **localStorage / 内存**，无服务端写 | 仅文档；可读 `tableView` |
+| 权限矩阵增删 | `matrix/list` + `savePermissions` / `matrix/save` | `e10-cli report scope matrix …` |
+| 移动到 | `POST removeReport`（改 group_id）；**无自建分组则不可选** | `e10-cli report lifecycle move` |
+| 转移到 | `app/list` 选启用应用 + `transferReport`；**重名须确认** | `e10-cli report app-search` · `lifecycle transfer` |
+
+---
+
+## 二、菜单项 → API 对照（核心）
+
+```mermaid
+flowchart LR
+ subgraph listPage["报表列表页"]
+ A[报表权限]
+ B[编辑]
+ C[添加到菜单]
+ D[复制]
+ E[删除]
+ end
+ A --> P1["permission/table/*"]
+ B --> P2["GET baseInfo + 设计器 getReportDevInfo"]
+ C --> P3["POST cusapp/app/savePublishMenu"]
+ D --> P4["GET copySheet"]
+ E --> P5["GET deleteReport"]
+```
+
+### 1. 报表权限设置
+
+> **完整对象类型 / 禁用范围 / 矩阵配置** → 必加载 **`report-permission-guide.md`**（九种通用对象 + 矩阵 + 运行时判定）。
+
+**弹窗 UI 结构**
+
+| 顶层 Tab | 子 Tab | 写入字段 / 接口 |
+|----------|--------|-----------------|
+| **使用范围** | 通用 | `savePermissions.viewRight`（`permissionType: 1`） |
+| **使用范围** | 矩阵相关 | `savePermissions.viewMatrixRight` 或 `matrix/save`（`rightsType: "1"`） |
+| **禁用范围** | 通用 | `savePermissions.disableRight`（`permissionType: -1`） |
+| **禁用范围** | 矩阵相关 | `matrix/save`（`rightsType: "-1"`；**不在** savePermissions 内） |
+
+**打开弹窗（读）**
+
+| 步骤 | 接口 | 方法 | Body / Query |
+|------|------|------|----------------|
+| 列表（使用/禁用通用） | `/api/bs/edc/report/permission/table/list/new` | POST | `permissionType`: **`1`**=使用范围，**`-1`**=禁用范围；含 `permissionId`、`id`=reportId、`params.appId` |
+| 矩阵（使用/禁用） | `/api/bs/edc/report/permission/matrix/list` | POST | `type`: **`"1"`**=使用矩阵，**`"-1"`**=禁用矩阵 |
+| 详情 | `/api/bs/edc/report/permission/table/info` | POST | `permissionId` + `id` |
+| 兼容读 | `/api/bs/edc/report/permission?id={reportId}` | GET | 旧接口，当前实现常返回空 map；**以 table/list/new 为准** |
+
+**保存（写）**
+
+| 接口 | 方法 | Content-Type | Body |
+|------|------|--------------|------|
+| `/api/bs/edc/report/permission/table/savePermissions` | POST | `application/json` | 见下方 JSON 结构 |
+| `/api/bs/edc/report/permission` | POST | `multipart/form-data` | `id` + `permission`（JSON 字符串，含 viewRight/disableRight） |
+| `/api/bs/edc/report/permission/matrix/save` | POST | `application/json` | 矩阵权限行列表 |
+
+**savePermissions 请求体结构**（`EdcDataPermissionController.savePermissions`）：
+
+```json
+{
+ "<reportId>": {
+ "viewRight": [
+ {
+ "sourceId": "<reportId>",
+ "permissionId": "<DataRightType.REPORT_VIEW>",
+ "targetType": 1,
+ "targetId": "<userOrDeptId>",
+ "permissionType": 1,
+ "objType": "resource",
+ "seclevel": { "min": -999, "max": 999 }
+ }
+ ],
+ "viewMatrixRight": [],
+ "disableRight": []
+ }
+}
+```
+
+> 权限对象字段与前端 **shareBrowser** 一致。九种通用类型（人员 `resource`、部门、分部、角色、群组、岗位、所有人、外部联系人、所有外部人）及 targetType 对照见 **`report-permission-guide.md` §三**。
+
+---
+
+### 2. 编辑报表
+
+编辑 = **打开设计器** + **读写布局**，不是单一接口。
+
+| 阶段 | 接口 | 方法 | 说明 |
+|------|------|------|------|
+| 读基础信息 | `/api/bs/edc/report/baseInfo?id={reportId}&version=1.0.0&useTag=backend` | GET | 编辑前加载名称/分组等 |
+| 读布局 | `/api/bs/edc/report/getReportDevInfo?reportId={reportId}` | GET | 设计器 workbook |
+| 写布局 | `/api/bs/edc/report/saveReportDevInfo` | POST | multipart：`reportId`、`workbook`(gzip+base64)、`designKey` 等 |
+| 写基础信息 | `/api/bs/edc/report/baseInfo` | POST | multipart：带 `id={reportId}` 更新名称/分组/permission |
+| 缓存双保存 | `/api/bs/edc/report/saveReportWithCacheConfig` | POST | 与 saveReportDevInfo 配合（跨表筛选等） |
+
+**设计器 URL**：`https://{host}/sp/edc/report/designer/{reportId}`
+
+---
+
+### 3. 添加到菜单
+
+对应设计器 **报表列表页 → 报表卡片「…」→ 添加到菜单**（与「报表权限」「复制」同级）。
+
+走 **eBuilder 应用菜单** API（非 edc/report 前缀）：
+
+| 接口 | 方法 | Content-Type |
+|------|------|--------------|
+| `/api/cusapp/app/savePublishMenu` | POST | `multipart/form-data` |
+
+**表单字段**
+
+| 字段 | 值 |
+|------|-----|
+| `appId` | 应用 ID |
+| `navigation` | JSON 字符串（见下） |
+| `isThirdParty` | `"true"` |
+| `terminalType` | `"PC"` |
+
+**navigation 模板**（`pageType=REPORT`，源自 `ReportAIController` / AI 建表）：
+
+```json
+{
+ "content": "销售经营分析报表",
+ "id": "",
+ "openMode": "1",
+ "pid": "0",
+ "type": "0",
+ "params": [],
+ "showType": "1",
+ "showOrder": 1,
+ "firstTabChange": false,
+ "nameLabelId": "-1",
+ "nameAlias": "",
+ "tabs": "{}",
+ "combinationId": "",
+ "shareMap": [{
+ "id": "0",
+ "content": "所有人",
+ "permissionId": "sys_view",
+ "targetId": 0,
+ "targetType": 11,
+ "sourceType": 1,
+ "objIdList": ["所有人"]
+ }],
+ "showRightBtn": "1",
+ "urlLinkType": "0",
+ "page": {
+ "pageId": "<reportId>",
+ "pageName": "销售经营分析报表",
+ "pageType": "REPORT",
+ "terminalScopes": "",
+ "appid": "<appId>"
+ },
+ "unitFill": "0"
+}
+```
+
+**请求头**：`ebbusinessid` = **应用 appId**（与 e10-cli menu 命令一致）。
+
+**新建 vs 更新**
+
+| 场景 | `navigation.id` | 说明 |
+|------|-----------------|------|
+| **新建菜单**（UI 点「添加到菜单」） | `""`（空字符串） | 服务端分配 `sysMenuId` |
+| **更新已有菜单** | 菜单项 **`sysMenuId`**（如 `6248849252234836444`） | **不是** `navId`（如 `7976632164040757328`） |
+
+> 常见错误：更新时填 `navId` → `savePublishMenu` 500；或 `pageId` 精度丢失 → 菜单打开空白报表。
+
+**pageId 必须精确**
+
+- `page.pageId` = **字符串**报表 ID，来自 `copySheet` 的 `extractIdFromRaw(raw)` 或 snowflake 安全解析。
+- 禁止 `Number(pageId)` 或未经安全解析的 `json.data.id`。
+
+**shareMap（菜单可见范围）**
+
+- 所有人：`targetType: 11`, `targetId: 0`, `permissionId: "sys_view"`
+- 与报表「使用范围」独立；菜单 shareMap 控制**谁能看到菜单入口**。
+
+**验证**
+
+```http
+GET /api/cusapp/app/allMenus?appId={appId}&terminalType=PC&isFront=0
+```
+
+回读 `cusAppMenus[]` 中 `menuName` / `pageId` / `id`（sysMenuId）是否与预期一致。
+
+**CLI / 脚本**
+
+- Python：`ReportApiClient.add_report_to_menu(report_id, menu_name, menu_sys_id="")`
+- Node：参考 `e10-cli report lifecycle` → `addReportToMenu()`
+- 复制+权限+菜单一条龙：`node e10-cli report lifecycle copy-and-menu --app-id ... --source-name ...`
+
+**相关读接口**：`GET /api/cusapp/app/allMenus?appId={appId}&terminalType=PC&isFront=0`
+
+> 完整精度说明见 `snowflake-id-precision-guide.md`。
+
+---
+
+### 4. 复制
+
+| 接口 | 方法 | Query |
+|------|------|-------|
+| `/api/bs/edc/report/copySheet` | GET | `sheetId={reportId}` |
+
+**响应**：`data` 为 Map，含 **`id`**（新报表 ID）、名称等。服务端自动命名为 `原名称(复制N)`。
+
+> **⚠ JS/Node 精度陷阱（必读）**
+> 详见 **`snowflake-id-precision-guide.md`**（完整规范）。摘要：
+
+**另存为系统/自定义**：`GET /api/bs/edc/report/saveAs?sheetId={id}&systemType={0|1|2}`
+
+---
+
+### 5. 删除（进回收站）
+
+| 接口 | 方法 | Query |
+|------|------|-------|
+| `/api/bs/edc/report/deleteReport` | GET | `id={reportId}`（支持逗号分隔批量） |
+
+**说明**：逻辑删除（`delete_type=1`），报表进入左侧「回收站」；**非物理删除**。
+
+---
+
+## 三、回收站（左侧「回收站」Tab）
+
+```mermaid
+flowchart LR
+ subgraph deleteFlow["删除生命周期"]
+ L[列表页删除] -->|deleteReport delete_type=1| R[回收站]
+ R -->|revertRecycleReport delete_type=0| L
+ R -->|deleteRecycleReport delete_type=3| X[彻底删除不可还原]
+ end
+```
+
+| delete_type | 含义 |
+|-------------|------|
+| `0` | 正常（报表列表可见） |
+| `1` | 回收站中（可还原） |
+| `3` | 物理删除（不可还原） |
+
+### 1. 回收站列表
+
+| 接口 | 方法 | Content-Type | 参数 |
+|------|------|--------------|------|
+| `/api/bs/edc/report/getRecycleReportWithPage` | POST | `application/x-www-form-urlencoded` | 见下 |
+
+**表单参数**
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `pageNo` | int | 页码，从 1 开始 |
+| `pageSize` | int | 每页条数 |
+| `appId` | long | 应用 ID |
+| `dateRange` | string | JSON 数组字符串，删除时间范围 `["开始","结束"]`；不限时传 `["",""]` |
+| `name` | string | 报表名称模糊搜索，空串表示不限 |
+| `creators` | string | JSON 数组字符串，创建人 ID 列表；不限时传 `[]` |
+
+**响应**：MyBatis-Plus 分页，`data.records[]` 含 `id`、`name`、`createTime`、`updateTime`、`creator`、`otherParams.creatorName` 等；`data.total` 为总数。
+
+**yunteams **（appId=`1310076187728674816`）：回收站含 `1310085722612146177`（销售经营分析报表_20260901100141）。
+
+### 2. 还原
+
+| 接口 | 方法 | Query |
+|------|------|-------|
+| `/api/bs/edc/report/revertRecycleReport` | GET | `id={reportId}`（支持逗号分隔批量） |
+
+**说明**：`delete_type` 从 `1` 恢复为 `0`，报表回到列表；同步还原映射关系与历史版本。
+
+**权限**：走 `wrapEbRightCheck`，`HandleType.EDIT`。
+
+### 3. 彻底删除（回收站内「删除」）
+
+| 接口 | 方法 | Query |
+|------|------|-------|
+| `/api/bs/edc/report/deleteRecycleReport` | GET | `id={reportId}`（支持逗号分隔批量） |
+
+**说明**：物理删除（`delete_type=3`），**不可还原**；与列表页「删除进回收站」不同。
+
+**权限**：走 `wrapEbRightCheck`，`HandleType.DELETE`。
+
+### 4. 批量操作
+
+回收站顶栏「删除」「还原」与行内操作相同接口，**id 逗号分隔**即可批量。
+
+---
+
+## 四、Python 客户端
+
+`已由 CLI 取代` 已封装：
+
+```python
+from report_api_client import ReportApiClient
+
+cli = ReportApiClient(host, eteamsid, ebbusinessid, cookie, group_id, app_id, agent_type="Agent")
+
+cli.get_report_list() # 列表页
+cli.get_app_report_right(report_id) # 单报表权限
+cli.get_report_base_info(report_id) # 编辑前读基础信息
+cli.copy_sheet(report_id) # 复制（读 _newReportId）
+cli.delete_report(report_id) # 删除（进回收站）
+cli.list_recycle_reports(...) # 回收站列表
+cli.revert_recycle_report(report_id) # 还原
+cli.delete_recycle_report(report_id) # 回收站彻底删除
+cli.save_permissions(report_id, {...}) # 报表权限
+cli.add_report_to_menu(report_id, name, menu_sys_id="") # 添加到菜单（空 id=新建）
+cli.get_report_detail(report_id) # 设计器布局（编辑）
+cli.save_report_layout(...) # 保存布局（编辑）
+
+# Node 一条龙（复制+权限+菜单）：
+# node e10-cli report lifecycle copy-and-menu --app-id {appId} --source-name "报表名"
+```
+
+凭证来源：`e10-cli auth status`（CLI 自动解析）
+
+---
+
+## 五、与本 Skill 其它 API 的关系
+
+| 能力 | 文档 |
+|------|------|
+| 新建报表外壳（三模式） | `create_report_shell` / `create_from_model` / `create_from_quickly_param` → `POST baseInfo`；CLI `e10-cli report create` |
+| 分组增删 / 移动 / 转移 | `list/save_report_groups` · `move_report` · `transfer_report` / `list_eb_apps`；CLI `group` · `lifecycle move\|transfer` · `app search` |
+| 布局/workbook | `formula-cell-api-guide.md`、`cross-dataset-filter-guide.md` |
+| **局部保存 · 设计区保护** | **`safe-partial-save-guide.md`** · `safe_report_save.js` |
+| **使用/禁用权限** | **`report-permission-guide.md`** |
+| **定时快照** | **`set_snapshot_schedule.js`** / `e10-cli report snapshot set`（默认名 `{报表名}-{date}-{time}`；禁 Number sheetId；依赖 safe_report_save） |
+| **空白门禁** | **`validate_designer_blank_guard.js`** / `e10-cli report verify blank` |
+| **存为新版本 / 还原** | **`report-designer-feature-map.md` §8.1** · `save_as_version.js` · `GET rollbackReport` |
+| 鉴权 | `api-auth-headers.md`、`e10-login-integration.md` |
+| e10-cli 菜单 | `e10-cli/references/menu/system-menus.md` |
+
+---
+
+## 六、yunteams 页面参数
+
+| 项 | 值 |
+|----|-----|
+| 页面 | `https://weapp.yunteams.cn/sp/ebdapp/detail/1310076187728674816/report` |
+| appId | `1310076187728674816` |
+| 示例报表 | 销售经营分析报表（卡片菜单与截图一致） |
+
+> 浏览器未登录时无法 live 实际请求；上表接口来自 **edcreportd 源码 + 历史 yunteams 列表页实际请求 + e10-cli savePublishMenu ** 三方对齐。

package/skills/weaver-e10-builder/references/report/report-list-page-ops-guide.md

@@ -0,0 +1,191 @@
+# 报表列表页操作（分组 / 视图 / 权限矩阵 / 移动 / 转移）
+
+> **页面**：`/sp/ebdapp/detail/{appId}/report`
+> **源码**：`MenuGroupController` · `EdcReportDevBaseController.removeReport|transferReport` · `EdcDataPermissionController` · 前端 `localStorage edc_report_view_type`
+> **CLI**：`e10-cli report group|lifecycle move|lifecycle transfer|app search|scope matrix|policy list-page`
+> **鉴权**：e10-login 三项头（`api-auth-headers.md`）
+
+---
+
+## 〇、能力总表
+
+| # | UI | 是否服务端 API | Skill/CLI |
+|---|-----|----------------|-----------|
+| 1 | 新建/删除分组（分组设置） | ✅ `group/list` + `group/save` | ✅ |
+| 2 | 视图切换卡片/列表 + 快速排序 | ❌ 纯前端 localStorage / 内存排序 | 文档化（无服务端写） |
+| 3 | 报表权限 · 矩阵添加/删除 | ✅ `matrix/list` + `savePermissions.viewMatrixRight` / `matrix/save` | ✅（补齐 CLI） |
+| 4 | 移动到其他分组 | ✅ `removeReport`（改 `group_id`） | ✅；无自建分组则不可选 |
+| 5 | 转移到其他应用 | ✅ `transferReport` + `ebuilder/app/list` | ✅；重名须用户确认 |
+
+---
+
+## 一、分组：新建 / 删除（强制）
+
+### 1.1 接口
+
+| 动作 | 方法 | 路径 | 参数 |
+|------|------|------|------|
+| 列表 | GET | `/api/bs/edc/report/group/list` | `appid` · `groupType`（后台默认 **0**） |
+| 保存 | POST | `/api/bs/edc/report/group/save` | multipart/form：`appid` · `groupType` · **`groups`=JSON 字符串** |
+
+**无单独 delete API**。删除 = 从 `groups` 数组中**去掉**该分组后全量 `save`（替换语义）。
+
+侧栏哨兵（**不是**可保存/可移动目标）：
+
+| id | 含义 |
+|----|------|
+| `-1` | 全部 |
+| `-2` | 我创建 |
+| `-3` | 未分组（部分租户） |
+
+`save` 前须过滤掉 `id === "-1"` 等哨兵；只提交用户自建分组。
+
+### 1.2 新建流程
+
+1. `group list` 取当前自建分组
+2. 追加一项：`{ "id": "", "name": "<新名称>", "showOrder": <max+1>, "nameLabelId": "-1" }`（字段以 list 回包为准透传）
+3. `group save`
+4. 再 list 确认拿到真实 id
+
+```bash
+e10-cli report group list --app-id <appId>
+e10-cli report group add --app-id <appId> --name "销售组"
+e10-cli report group delete --app-id <appId> --group-id <id>
+```
+
+### 1.3 禁令
+
+- 禁止把 `-1/-2/-3` 当自建分组写入 save
+- 禁止未读 list 就臆造整表 groups（丢分组）
+- 删除分组前若组内有报表，先 `move` 走或告知用户（产品侧行为以页面为准）
+
+---
+
+## 二、视图切换与快速排序（无服务端写）
+
+| 能力 | 机制 | 说明 |
+|------|------|------|
+| 卡片视图 | `localStorage.edc_report_view_type = "grid"` | 默认 |
+| 列表视图 | `localStorage.edc_report_view_type = "table"` | 列表数据另调 `GET /api/bs/edc/report/tableView` |
+| 快速排序 | 前端内存 `sortBy` / `sortType` | 字段常见：`UpdateTime` / `CreateTime` / `Name` / `Creator`；**不落库** |
+
+Agent：
+
+- **不要**发明「保存视图偏好」的报表 API
+- 用户若要「列表视图数据」：可调 `tableView?appId=&groupId=&filterStr=&pageNo=&pageSize=`
+- 卡片列表仍用 `GET /api/bs/edc/report/list?appid=&groupid=&objId=`
+
+```bash
+e10-cli report --help-page # 打印本节政策
+```
+
+---
+
+## 三、报表权限 · 矩阵添加 / 删除
+
+完整对象类型与通用 Tab 见 **`report-permission-guide.md`**。本节只强调矩阵 CRUD。
+
+### 3.1 读
+
+```http
+POST /api/bs/edc/report/permission/matrix/list
+{ "target": "<reportId>", "type": "1" } # 使用范围矩阵
+{ "target": "<reportId>", "type": "-1" } # 禁用范围矩阵
+```
+
+### 3.2 添加
+
+| 范围 | 写接口 |
+|------|--------|
+| **使用范围 · 矩阵** | `POST .../permission/table/savePermissions`，带完整 `viewRight`/`disableRight`/`viewMatrixRight`（全量）；服务端先把使用矩阵 `deleteType=1` 再插入新行 |
+| **禁用范围 · 矩阵** | **单独** `POST .../permission/matrix/save`，`rightsType:"-1"`；**不要**只靠 savePermissions |
+
+矩阵行字段：`selectedType` · `dataId` · `matrixConditionData` · `matrixValueRelation` · `targetId` · `rightsType` · `rightsName`
+**条件/取值字段 JSON 必须以设计器 Network 实际请求为准**，禁止臆造键名。
+
+### 3.3 删除
+
+| 范围 | 做法 |
+|------|------|
+| 使用矩阵 | `matrix/list` → 去掉目标行 → `savePermissions` 提交剩余 `viewMatrixRight`（可空数组=全清使用矩阵） |
+| 禁用矩阵 | `matrix/list type=-1` → 对目标行 `matrix/save` 且 **`deleteType: 1`**（或只保留要留下的行再 save；以实际请求为准） |
+
+```bash
+e10-cli report scope matrix list --report-id <id> --app-id <appId> [--type 1|-1]
+e10-cli report scope matrix save --report-id <id> --app-id <appId> --file matrix-row.json [--type 1|-1]
+e10-cli report scope matrix delete --report-id <id> --app-id <appId> --matrix-id <id> [--type 1|-1]
+```
+
+---
+
+## 四、移动到其他分组（强制规则）
+
+### 4.1 接口
+
+```http
+POST /api/bs/edc/report/removeReport
+Content-Type: multipart/form-data
+reportId=<id>&groupId=<目标分组ID>
+```
+
+> 名称是历史遗留：**不是删除报表**，只改 `edc_report_dev.group_id`。
+
+### 4.2 可选目标规则（产品硬约束）
+
+1. 先 `GET group/list?appid=&groupType=0`
+2. **可移动目标 = 用户自己创建的分组**（真实雪花/数字 id）
+3. **排除** 哨兵 `-1/-2/-3`
+4. 若过滤后 **列表为空** → **无可选移动位置**，Agent 须提示用户先「分组设置 → 添加分组」，**禁止**瞎传 groupId
+
+```bash
+e10-cli report lifecycle move --app-id <appId> --report-id <id> --group-id <gid>
+# 无自建分组时 exit≠0，message 提示先建分组
+```
+
+---
+
+## 五、转移到其他应用（强制规则）
+
+### 5.1 转移接口
+
+```http
+POST /api/bs/edc/report/transferReport
+reportIds=<id>[&reportIds=<id2>]&appId=<目标应用ID>
+```
+
+服务端副作用：目标应用下报表 **`group_id = -1`**（未分组）；同步版本与菜单 remote appId。
+
+### 5.2 应用选择框（UI：选择 e-Builder 应用）
+
+| 步骤 | API / 规则 |
+|------|------------|
+| 检索应用 | `GET /api/bs/ebuilder/app/list?name={关键字}&pageNo=1&pageSize=20`（可翻页） |
+| 范围 | **当前用户有权限且启用**的 EB 应用（以 list 回包 `enable`/`status` 等字段过滤；禁用应用勿作目标） |
+| 重名 | **同名多条 → 必须 AskUserQuestion** 让用户确认到底是哪一个 `appId`，禁止自动挑第一条 |
+| 可选校验 | `GET /api/bs/edc/report/appRight?appId={目标}` 确认可操作 |
+
+```bash
+e10-cli report app-search --name "办公" [--page 1] [--size 20]
+e10-cli report lifecycle transfer --report-id <id> --app-id <目标appId>
+e10-cli report lifecycle transfer --report-id <id> --app-name "xxx"
+# --app-name 命中多条 → 输出 candidates，要求 --confirm-app-id
+```
+
+---
+
+## 六、Agent 检查清单
+
+- [ ] 分组增删走 `group/save` 全量，未丢其它分组
+- [ ] 未把视图/快速排序当成服务端配置去「保存」
+- [ ] 矩阵：使用走 savePermissions / 禁用走 matrix/save；删除未臆造 DSL
+- [ ] 移动前 list 自建分组；空则提示先建组
+- [ ] 转移前 app/list；重名用户确认；目标为启用且有权限应用
+
+---
+
+## 关联
+
+- `report-lifecycle-api-guide.md` — 列表页总览
+- `report-permission-guide.md` — 权限对象类型与通用 Tab
+- `report-create-modes-guide.md` — 新建报表三模式
+- `api-auth-headers.md` — 鉴权