weaver-e10-builder 1.6.9 → 1.6.11

package/skill-docs/references/report/report-lifecycle-api-guide.md

@@ -3,7 +3,7 @@
 > **页面场景**：`/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 三项）
+> **鉴权**：必须走 e10-cli auth，请求头见 `api-auth-headers.md`（Cookie.raw + eteamsid + User-Agent 三项）
 
 ---
 
@@ -44,7 +44,7 @@
 
 ## 一附 B、列表页其它操作（分组 / 视图 / 移动 / 转移 / 矩阵）
 
-> **完整规则与 CLI** → **`report-list-page-ops-guide.md`** · `e10-cli report --help-page`
+> **完整规则与 CLI** → **`report-list-page-ops-guide.md`** ·
 
 | UI | API / 机制 | CLI |
 |----|------------|-----|
@@ -52,7 +52,7 @@
 | 卡片/列表视图 + 快速排序 | **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` |
+| 转移到 | `app/list` 选启用应用 + `transferReport`；**重名须确认** | `e10-cli report app search` · `lifecycle transfer` |
 
 ---
 
@@ -60,18 +60,18 @@
 
 ```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"]
+  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. 报表权限设置
@@ -108,21 +108,21 @@ flowchart LR
 
 ```json
 {
- "<reportId>": {
- "viewRight": [
- {
- "sourceId": "<reportId>",
- "permissionId": "<DataRightType.REPORT_VIEW>",
- "targetType": 1,
- "targetId": "<userOrDeptId>",
- "permissionType": 1,
- "objType": "resource",
- "seclevel": { "min": -999, "max": 999 }
- }
- ],
- "viewMatrixRight": [],
- "disableRight": []
- }
+  "<reportId>": {
+    "viewRight": [
+      {
+        "sourceId": "<reportId>",
+        "permissionId": "<DataRightType.REPORT_VIEW>",
+        "targetType": 1,
+        "targetId": "<userOrDeptId>",
+        "permissionType": 1,
+        "objType": "resource",
+        "seclevel": { "min": -999, "max": 999 }
+      }
+    ],
+    "viewMatrixRight": [],
+    "disableRight": []
+  }
 }
 ```
 
@@ -169,38 +169,38 @@ flowchart LR
 
 ```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"
+  "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"
 }
 ```
 
@@ -237,7 +237,7 @@ GET /api/cusapp/app/allMenus?appId={appId}&terminalType=PC&isFront=0
 
 - 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 ...`
+- 复制+权限+菜单一条龙：`e10-cli report lifecycle copy-and-menu --app-id ... --source-name ...`
 
 **相关读接口**：`GET /api/cusapp/app/allMenus?appId={appId}&terminalType=PC&isFront=0`
 
@@ -274,11 +274,11 @@ GET /api/cusapp/app/allMenus?appId={appId}&terminalType=PC&isFront=0
 
 ```mermaid
 flowchart LR
- subgraph deleteFlow["删除生命周期"]
- L[列表页删除] -->|deleteReport delete_type=1| R[回收站]
- R -->|revertRecycleReport delete_type=0| L
- R -->|deleteRecycleReport delete_type=3| X[彻底删除不可还原]
- end
+  subgraph deleteFlow["删除生命周期"]
+    L[列表页删除] -->|deleteReport delete_type=1| R[回收站]
+    R -->|revertRecycleReport delete_type=0| L
+    R -->|deleteRecycleReport delete_type=3| X[彻底删除不可还原]
+  end
 ```
 
 | delete_type | 含义 |
@@ -287,6 +287,38 @@ flowchart LR
 | `1` | 回收站中（可还原） |
 | `3` | 物理删除（不可还原） |
 
+### 0. 只有 reportId 时：先反查所属应用（★ 必读）
+
+> 用户常直接给一条设计器地址 `https://<host>/sp/edc/report/designer/<reportId>` —— **URL 里没有 appId**，
+> 而回收站接口**按应用维度**查。**别现场手写临时脚本**，用固化命令：
+
+```bash
+e10-cli report locate --report-id <rid> [--app-id <id> | --app-name "应用名"] [--json]
+```
+
+判定口径（2026-09-15 实证）：
+
+| 步骤 | 接口 | 结论 |
+|------|------|------|
+| ① | `GET /api/bs/edc/report/baseInfo?id=<rid>&useTag=backend`（**无需 appId 头**） | 回出 `data.appId` → **正常态**，直接收工 |
+| ② | 同上，`data` 为空（响应体**恰好 54 字节**：`{"code":200,"msg":"接口返回成功","status":true,"fail":false}`） | **已删除信号** → 扫回收站 |
+| ③ | `POST /api/bs/edc/report/getRecycleReportWithPage`（并发扫，先 `--app-name` 收窄） | 命中 → 确认在该应用回收站 |
+| ④ | `GET /api/bs/edc/report/list?appId=&appid=&groupid=-1&objId=-1` → `data.reportList[]` | 含该 id = 正常态；不含 = 非正常态 |
+
+> ⚠️ **不要只看 `deleteType`**：验证报表 `1313903463073415168`「招标项目进度跟踪表」在回收站中
+> `deleteType` 仍返回 **0**，与实际删除态不同步。必须靠「回收站列表命中 + live list 未命中」双判。
+> `exit 3` = 既非正常态、也不在已扫应用回收站（可能已**彻底删除** `delete_type=3`，或当前账号无权限）。
+
+**CLI**
+
+```bash
+e10-cli report locate --report-id <rid> [--app-name "采购招标管理"] [--json]
+e10-cli report lifecycle recycle-list    --app-id <id> [--name "模糊"] [--json]
+e10-cli report lifecycle recycle-restore --app-id <id> --report-id <rid> [--apply]   # 默认 dry-run
+```
+
+还原后自动三重校验：①回收站列表不再含该 id；②`baseInfo` 恢复出 name/appId；③live list 已含该 id。
+
 ### 1. 回收站列表
 
 | 接口 | 方法 | Content-Type | 参数 |
@@ -306,7 +338,7 @@ flowchart LR
 
 **响应**：MyBatis-Plus 分页，`data.records[]` 含 `id`、`name`、`createTime`、`updateTime`、`creator`、`otherParams.creatorName` 等；`data.total` 为总数。
 
-**yunteams **（appId=`1310076187728674816`）：回收站含 `1310085722612146177`（销售经营分析报表_20260901100141）。
+**官方 SaaS 环境验证**（appId=`1310076187728674816`）：回收站含 `1310085722612146177`（销售经营分析报表_20260901100141）。
 
 ### 2. 还原
 
@@ -336,31 +368,31 @@ flowchart LR
 
 ## 四、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(...) # 保存布局（编辑）
+cli = ReportApiClient(host, eteamsid, ebbusinessid, cookie, group_id, app_id, agent_type="WorkBuddy")
+
+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 report lifecycle copy-and-menu --app-id {appId} --source-name "报表名"
 ```
 
-凭证来源：`e10-cli auth status`（CLI 自动解析）
+凭证来源：`e10-cli report creds --appid {appId}`
 
 ---
 
@@ -371,22 +403,22 @@ cli.save_report_layout(...) # 保存布局（编辑）
 | 新建报表外壳（三模式） | `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` |
+| **局部保存 · 设计区保护** | **`safe-partial-save-guide.md`** · `` |
 | **使用/禁用权限** | **`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 report snapshot`** / `e10-cli report snapshot set`（默认名 `{报表名}-{date}-{time}`；禁 Number sheetId；依赖 safe_report_save） |
+| **空白门禁** | **`e10-cli report validate blank`** / `e10-cli report verify blank` |
+| **存为新版本 / 还原** | **`report-designer-feature-map.md` §8.1** · `e10-cli report version` · `GET rollbackReport` |
+| 鉴权 | `api-auth-headers.md`、`e10-cli auth` 文档 |
 | e10-cli 菜单 | `e10-cli/references/menu/system-menus.md` |
 
 ---
 
-## 六、yunteams 页面参数
+## 六、官方 SaaS 环境验证页面参数
 
 | 项 | 值 |
 |----|-----|
-| 页面 | `https://weapp.yunteams.cn/sp/ebdapp/detail/1310076187728674816/report` |
+| 页面 | `https://<平台地址>/sp/ebdapp/detail/<appId>/report` |
 | appId | `1310076187728674816` |
 | 示例报表 | 销售经营分析报表（卡片菜单与截图一致） |
 
-> 浏览器未登录时无法 live 实际请求；上表接口来自 **edcreportd 源码 + 历史 yunteams 列表页实际请求 + e10-cli savePublishMenu ** 三方对齐。
+> 浏览器未登录时无法 live 接口返回；上表接口来自 **edcreportd 源码 + 历史官方 SaaS 列表页接口返回 + e10-cli savePublishMenu 验证** 三方对齐。

package/skill-docs/references/report/report-list-page-ops-guide.md

@@ -3,7 +3,7 @@
 > **页面**：`/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`）
+> **鉴权**：e10-cli auth 三项头（`api-auth-headers.md`）
 
 ---
 
@@ -34,9 +34,55 @@
 
 | id | 含义 |
 |----|------|
-| `-1` | 全部 |
+| `-1` | 全部（侧栏筛选）／**报表行上的 `groupId=-1` = 未分组桶（UI 建表的默认值）** |
 | `-2` | 我创建 |
 | `-3` | 未分组（部分租户） |
+| `0` | **★ 孤儿分组 —— 不要写**（见下节） |
+
+### 1.1.1 ★ 报表行的 `groupId`：`-1` 才是「默认桶」，`0` 是孤儿分组（2026-09-15 实证）
+
+**症状**：应用里点「菜单选取」时整个应用的报表都列不出来，只有手动建的能选到
+—— 根因往往是这些报表的 `group_id = 0`：
+
+- UI 建表写 `groupId = -1`（未分组桶）；脚本历史把 `baseInfo` 表单的 `groupId` 硬编码成 `"0"`；
+- **自建分组 id 是服务端分配的雪花号，不可能是 0** → `group_id=0` 指向一个不存在的分组；
+- 后果：上游按「默认分组 / 未分组」枚举时看不到这些报表（就是菜单选取那条路）。
+
+验证对照（同一应用，`group/list` 为空）：
+
+| 报表 | group_id | 菜单/按分组枚举能否看到 |
+|------|----------|------------------------|
+| 手动建（UI） | `-1` | ✅ 能 |
+| AI/脚本建 | `0` | ❌ 看不到 |
+
+> ⚠️ **归因更正（2026-09-15 二次实证）**：**卡片菜单里的「复制」报 500「报表内部错误」与 `group_id` 无关** ——
+> 把 `groupId=0` 的表改成 `-1` 之后复制**仍然 500**。
+> **复制 500 的真因 = 数据集 `type` 是大写 `LOGIC`**（设计器/手动建表写的是小写 `logic`）：
+> 同应用同表单两张空壳，唯一差别 `--source-type logic` / `--source-type LOGIC` → 复制 **200 / 500**。
+> 详见 `report-internal-error-guide.md` 速查表 · 注意点 **BUILD-29**。分组只影响「列表 / 菜单能否枚举到」。
+
+```bash
+# 只读体检：标出孤儿分组（命中 exit 3）
+e10-cli report group audit --app-id <appId> [--json]
+
+# 批量对齐到「页面手动建表」口径（不传 --report-id = 自动全量孤儿；默认 dry-run）
+e10-cli report group sync --app-id <appId> [--report-id <rid>]... [--apply]
+
+# 单张改：移回「未分组」默认桶（默认 dry-run）
+e10-cli report group set --app-id <appId> --report-id <rid> --group-id -1 [--apply]
+
+# ★ 复制报 500 时走这条（诊断 + 修复），不要再用分组解释复制失败
+e10-cli report copy-health --report-id <rid> --app-id <appId> [--clean]
+e10-cli report dataset heal --report-id <rid> --app-id <appId> [--purge] --apply
+
+# ★ 应用级批量（一个应用逐张过一遍；禁再写外层 shell 循环）
+e10-cli report copy-health --app-id <appId> [--probe] [--clean]   # 复制合规矩阵，BAD 行自带修复命令（exit 3）
+e10-cli report dataset heal --app-id <appId> [--purge] [--apply]  # 批量修复，只对有阻断项的报表落库
+e10-cli report cleanup shells --app-id <appId> --match "__诊断" [--apply]  # 清诊断/对照临时表（默认 dry-run）
+```
+
+> **建表侧铁律**：新建 `groupId` 用 `-1`；保存已有报表一律原样回传 `baseInfo.groupId`。
+> 需要覆盖默认值：环境变量 `EB_EDC_NEW_REPORT_GROUP_ID`。
 
 `save` 前须过滤掉 `id === "-1"` 等哨兵；只提交用户自建分组。
 
@@ -76,7 +122,7 @@ Agent：
 - 卡片列表仍用 `GET /api/bs/edc/report/list?appid=&groupid=&objId=`
 
 ```bash
-e10-cli report --help-page # 打印本节政策
+   # 打印本节政策
 ```
 
 ---
@@ -89,8 +135,8 @@ e10-cli report --help-page # 打印本节政策
 
 ```http
 POST /api/bs/edc/report/permission/matrix/list
-{ "target": "<reportId>", "type": "1" } # 使用范围矩阵
-{ "target": "<reportId>", "type": "-1" } # 禁用范围矩阵
+{ "target": "<reportId>", "type": "1" }   # 使用范围矩阵
+{ "target": "<reportId>", "type": "-1" }  # 禁用范围矩阵
 ```
 
 ### 3.2 添加
@@ -101,14 +147,14 @@ POST /api/bs/edc/report/permission/matrix/list
 | **禁用范围 · 矩阵** | **单独** `POST .../permission/matrix/save`，`rightsType:"-1"`；**不要**只靠 savePermissions |
 
 矩阵行字段：`selectedType` · `dataId` · `matrixConditionData` · `matrixValueRelation` · `targetId` · `rightsType` · `rightsName`
-**条件/取值字段 JSON 必须以设计器 Network 实际请求为准**，禁止臆造键名。
+**条件/取值字段 JSON 必须以设计器 Network 接口返回为准**，禁止臆造键名。
 
 ### 3.3 删除
 
 | 范围 | 做法 |
 |------|------|
 | 使用矩阵 | `matrix/list` → 去掉目标行 → `savePermissions` 提交剩余 `viewMatrixRight`（可空数组=全清使用矩阵） |
-| 禁用矩阵 | `matrix/list type=-1` → 对目标行 `matrix/save` 且 **`deleteType: 1`**（或只保留要留下的行再 save；以实际请求为准） |
+| 禁用矩阵 | `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]
@@ -165,7 +211,7 @@ reportIds=<id>[&reportIds=<id2>]&appId=<目标应用ID>
 | 可选校验 | `GET /api/bs/edc/report/appRight?appId={目标}` 确认可操作 |
 
 ```bash
-e10-cli report app-search --name "办公" [--page 1] [--size 20]
+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