weaver-e10-builder 1.1.8 → 1.2.2

package/skill-docs/references/report/report-self-check-guide.md

@@ -0,0 +1,164 @@
+# 报表落库自检（强制）
+
+> **适用**：API/脚本保存布局后、交付设计器链接前（可后台跑，但**不得跳过**）。 
+> **目标**：尽早发现字段丢失、伪父格、绑定失败、超链接被冲掉，避免「设计器看着有格、取数/父格全错」。
+
+---
+
+## 一、父格坐标语义（勿混）
+
+| API `leftX/leftY` 或 `topX/topY` | 设计器含义 | 说明 |
+|----------------------------------|------------|------|
+| **`-1, -1`** | **默认** 或 **无** | 普通 Const / 单数据集 Field 的常见正确态 |
+| **`0, 0`** | **自定义 → 原点 (0,0)** | **不是默认**；写成 0,0 会显示父格「不对」 |
+| **其它 `x,y`** | **自定义** 指向该坐标 | 多数据集入口、交叉、**超链接占位依赖**等 |
+
+---
+
+## 二、按单元格类型的父格规则
+
+### 2.1 普通 Const（表头 / 标题 / 无链接）
+
+| 项 | 规则 |
+|----|------|
+| 左父格 | **`-1,-1`** |
+| 上父格 | **`-1,-1`** |
+| 禁止 | `(0,0)`；勿把「默认」误写成原点 |
+
+### 2.2 超链接 Const（`pcHreflink` / `h5Hreflink`，URL 含 `{L4}` `{C4}` 等）
+
+> **事故**：把「左父格默认」套到「点击查看」上 → 设计器左/上显示不对，且 `{L4}` 无法解析；或重建 workbook 时丢掉 `ConstCellType.cellText` → 保存后 `cellText` 变空、`pcHreflink` 丢失。
+
+| 项 | 规则 | 例（供应商表 M4） |
+|----|------|-------------------|
+| **上父格** | 无横向扩展时必须 **`topX=topY=-1`**（不需要上父格） | `(-1,-1)` |
+| **左父格** | **禁止**一律改成默认；须指向占位符依赖的数据格 | `{L4}` → 左父格 **`(3,11)`**（同行「数据ID」） |
+| **链接元数据** | 须进 **workbook `ConstCellType`**（`pcHreflink`/`openType`/`cellText`/`left*`/`top*`）；仅写 `fields[]` **不够** | `/sp/ebdfpage/card/0/{sourceId}/{L4}` |
+| **workbook** | `ConstCellType` 必须含：`cellText`、`leftX/leftY/topX/topY`、有链接时还要 `pcHreflink` | 服务端 `saveReportDevInfo` **从 cellType 回写 fields**；缺 `leftX` → Java int **0** → 伪 `(0,0)`；缺 `pcHreflink` → 链接丢失 |
+| **禁止** | 只塞 `{typeName,cellText}` 的残 ConstCellType；禁止左=`(0,0)`；禁止有 `{Ln}` 却左=`-1,-1` |
+
+**占位符 → 左父格**（自检算法）：
+
+1. 从 `pcHreflink`/`h5Hreflink` 提取 `{L4}` / `{C4}` / `{Ln}` 等。
+2. `{L4}`：同行纵向扩展语境下，左父格应指向同列（或约定列）上提供 ID 的 Field（本需求为 `(3,11)`）。
+3. 若 URL 含占位而 `leftX/leftY === -1` → **FAIL**（不是「默认正确」）。
+4. 若 `topX/topY !== -1` 且无横向交叉需求 → **FAIL**。
+
+### 2.3 Field（单数据集、无指定计算）
+
+| 场景 | 左父格 |
+|------|--------|
+| **新建**报表 | 优先 **`-1,-1`（默认）** |
+| **已有**报表 | **禁止**用户未点名时批量改父格 |
+
+---
+
+## 三、保存门禁（每次 `saveReportDevInfo`）
+
+### 保存前
+
+1. `fields` 中 `cellType=Field` 数量 ≥ 保存前（或与预期列数一致）。
+2. workbook `dataTable` 内 `FieldCellType` 数量 ≥ Field 数。
+3. 每个 **Const**：workbook `ConstCellType` 须含 `cellText`（有文案时）以及显式 **`leftX/leftY/topX/topY`（常用 -1，禁止省略）**。
+4. 每个 **超链接 Const**：`ConstCellType` 须含非空 `pcHreflink`、`openType`，且父格与 `fields` 一致（服务端以 workbook 为准回写）。
+5. 每个 Field：`name` ∈ `fieldsAndOriginFields.fieldsKey[].name`（须带 `field_`；禁止裸雪花 ID）。 
+ - 拉 fieldsKey 参数名用 **`datasetId`**（不是 `dataSetId`）。
+
+### 保存后立刻回读
+
+| 检查项 | 失败标准 |
+|--------|----------|
+| Field 数量 | 比保存前减少 → **立即失败**，禁止再改，优先恢复 |
+| Field.`name` | 裸 ID 或不在 fieldsKey → FAIL（`e10-cli report verify bind`） |
+| 普通 Const 父格 | `left=top=(0,0)` → FAIL（伪自定义 A1） |
+| 超链接 Const | 缺 `pcHreflink` / `cellText` 空 / `top≠-1` / 含 `{L*}` 但 `left=-1` 或 `left=(0,0)` → FAIL |
+| 同数据集 leftFilterField | Field 上仍有跨源 leftFilter → WARN/FAIL |
+
+```bash
+e10-cli report verify bind <reportId> [appId] # 字段绑定
+e10-cli report verify self <reportId> [appId] # 父格/超链接自检
+e10-cli report verify all <reportId> [appId] # 自检 + 绑定（推荐）
+```
+
+---
+
+## 四、Agent 自检脚本逻辑（摘要）
+
+```javascript
+function assertParents(fields) {
+ for (const f of fields) {
+ if (f.cellType !== 'Const') continue;
+ const origin =
+ f.leftX === 0 && f.leftY === 0 && f.topX === 0 && f.topY === 0;
+ const href = f.pcHreflink || f.h5Hreflink || '';
+ if (origin && !href) {
+ throw new Error(`Const(${f.x},${f.y}) 父格(0,0)=伪自定义A1，应为-1,-1`);
+ }
+ if (!href) continue;
+ // 超链接：上父格默认无
+ if (f.topX !== -1 || f.topY !== -1) {
+ throw new Error(`链接格(${f.x},${f.y}) 不需要上父格，top 应为 -1,-1`);
+ }
+ if (!f.cellText) {
+ throw new Error(`链接格(${f.x},${f.y}) cellText 为空（workbook 可能未写 ConstCellType）`);
+ }
+ // URL 占位依赖左父格，禁止「默认」
+ if (/\{L\d+\}|\{C\d+\}/.test(href)) {
+ if (f.leftX === -1 && f.leftY === -1) {
+ throw new Error(`链接格(${f.x},${f.y}) 含占位符但左父格为默认，应指向依赖数据格`);
+ }
+ if (f.leftX === 0 && f.leftY === 0) {
+ throw new Error(`链接格(${f.x},${f.y}) 左父格不能为(0,0)`);
+ }
+ }
+ }
+}
+
+function assertWorkbookConstCellType(dataTable, fields) {
+ for (const f of fields) {
+ if (f.cellType !== 'Const') continue;
+ const cell = dataTable?.[String(f.x)]?.[String(f.y)];
+ const ct = cell?.style?.cellType;
+ if (!ct || ct.typeName !== 'ConstCellType') {
+ throw new Error(`workbook 缺 ConstCellType @(${f.x},${f.y})`);
+ }
+ if ((f.cellText || f.text) && !ct.cellText) {
+ throw new Error(`workbook 缺 cellText @(${f.x},${f.y})，保存会冲掉文案`);
+ }
+ // 缺 leftX 时服务端写成 0 → 伪自定义 A1
+ for (const k of ['leftX', 'leftY', 'topX', 'topY']) {
+ if (ct[k] === undefined || ct[k] === null) {
+ throw new Error(`workbook ConstCellType 缺 ${k} @(${f.x},${f.y})，会落成 0`);
+ }
+ }
+ if (f.pcHreflink && ct.pcHreflink !== f.pcHreflink) {
+ throw new Error(`workbook 缺/错 pcHreflink @(${f.x},${f.y})（服务端只认 cellType）`);
+ }
+ }
+}
+
+function assertFieldPreserved(before, after) {
+ const n = (fs) => fs.filter((f) => f.cellType === 'Field').length;
+ if (n(after) < n(before)) throw new Error('Field 被冲掉，禁止继续改');
+}
+```
+
+---
+
+## 五、与交付节奏
+
+- 布局落库成功 → **先交设计器地址**（`report-delivery-contract.md` §〇）。
+- 本节自检可后台跑；**FAIL 必须补丁修复并告知**，不得假装完成。
+- **禁止**：为修一格 Const 父格而提交残缺 workbook（会导致 Field 全变 Const，或 Const 文案/超链接被冲掉）。修父格必须 **整表 Field + ConstCellType 完整写入 workbook**。
+
+---
+
+## 六、相关文档
+
+| 文档 | 关系 |
+|------|------|
+| `field-bind-exact-match-guide.md` | name ∈ fieldsKey |
+| `datasource-selection-and-parent-filter-guide.md` §〇 | 单数据集左父格默认；**勿**套用到超链接 Const；勿擅自改已有表 |
+| `safe-partial-save-guide.md` | 禁止空 workbook；须从 fields 重建 dataTable |
+| `e10-cli report verify bind` | 绑定门禁 |
+| `targeted-fix-guide.md` | 用户点名某处不对时禁止整表重扫 |

package/skill-docs/references/report/safe-partial-save-guide.md

@@ -0,0 +1,151 @@
+# 局部功能保存 · 设计区保护规范
+
+> **适用场景**：通过 API / 脚本修改**快照、权限、查询条件、数据集筛选、页面布局**等「非布局主体」能力时。 
+> **事故根因（已验证）**：对 `saveReportDevInfo` 提交**空 workbook** 或 **workbookProps.sheets 无单元格** 的 payload，会**全量替换** `edc_reportsheetfield_dev` 等表，导致设计器字段与单元格配置被清空。 
+> **硬约束**：除非用户**明确要求删除/清除字段**，否则设计区域内容**不得被置空**。
+
+---
+
+## 一、核心原则
+
+| 原则 | 说明 |
+|------|------|
+| **布局不可丢** | `getReportDevInfo.fields.length > 0` 是保存前最低门槛；保存后必须回读验证 |
+| **禁止空 workbook 落库** | `workbookProps.sheets` 为空 **且** `fields` 为空 → **禁止**调用 `saveReportDevInfo`；`fields>0` 但 sheets 空 → **必须从 fields 重建**（含 spans）后再存 |
+| **剔除 `(0,0)` 空 Const** | `x=0,y=0` 且文案空的 Const 为异常幽灵格，保存前删除 |
+| **workbookProps 不可盲信** | 线上常见 `fields=12` 但 `workbookProps.dataTable` 为空；此时必须从 **fields 重建** dataTable |
+| **groupId 原样回传** | `saveReportDevInfo` 的 `groupId`/`nameLabelId` 取自 `baseInfo`，禁止硬编码改分组 |
+| **专用接口优先** | 权限 → `savePermissions`；查询 → `saveQueryItem`；数据集筛选 → `queryInfoSave`；版本还原 → `rollbackReport` |
+| **快照是唯一例外需写 workbook** | 快照配置挂在 `workbook.snapshot`，必须走 `saveReportDevInfo`，但须套用 **§三 安全合并** |
+| **快照 ID 禁 Number()** | `sheetId`/`id`/`jobId` 必须 **String(雪花)**；`Number(reportId)` 截断 → **设计区空白**（见 `designer-blank-prevention-guide.md`） |
+| **快照默认名** | 未指定时 **`{报表名}-{date}-{time}`** |
+| **showLocation 禁 0** | 合并 workbook 时若为 0 → 改为 **2**（或用户点名居左则 1） |
+| **保存前快照版本** | 对已有报表做任意 `saveReportDevInfo` 前，建议 `saveAsVersion --list-only` 确认有版本可还原 |
+
+---
+
+## 二、接口与布局影响矩阵
+
+| 操作 | 推荐接口 | 是否触及 layout/fields | 备注 |
+|------|----------|------------------------|------|
+| 使用/禁用权限 | `permission/table/savePermissions` | **否** | 全量替换权限 JSON，不动 fields |
+| 矩阵权限 | `permission/matrix/save` | **否** | |
+| 查询条件 | `saveQueryItem` / `saveQueryConfig` | **否** | |
+| 数据集筛选 | `queryInfoSave` | **否** | |
+| 存为新版本 | `saveAsVersion` | **否**（复制快照） | |
+| 还原版本 | `GET rollbackReport` | **是**（整表替换） | 用户显式还原；会重置快照配置 |
+| 页面布局/分页 | `allPageSetting` | **否**（pageSetting 独立） | |
+| 定时快照 | `saveReportDevInfo` + `workbook.snapshot` | **是（若 workbook 空则灾难）** | 必须 §三 |
+| 修改单元格/父格 | `saveReportDevInfo` +（可选）`saveReportWithCacheConfig` | **是** | **新空报表必须先 dev 后 cache**；见 `api-report-build-fast-path.md` |
+
+---
+
+## 三、saveReportDevInfo 安全合并流程（强制）
+
+凡必须调用 `saveReportDevInfo` 且**不是**「从零新建报表」或「用户要求清空」：
+
+```
+1. GET getReportDevInfo?reportId=
+2. fields = data.fields || []
+3. IF fields.length === 0 → ABORT（提示先 rollbackReport 或从版本还原）
+4. wb = mergeWorkbookSafe(data, patchFn)
+ ├─ 若 countCells(workbookProps) > 0 → 深拷贝 workbookProps
+ └─ 否则 → buildWorkbookFromFields(fields, sheetProps) // 禁止提交空 sheets
+5. patchFn(wb) // 仅改 snapshot / 必要字段，勿删 sheets/dataTable
+6. POST saveReportDevInfo（带当前 designKey + ebBusinessId）
+7. GET getReportDevInfo 回读：
+ - fields.length 不得小于保存前
+ - 若用户未要求删除，fields.length === 0 → 视为事故，立即 rollbackReport
+```
+
+### 3.1 buildWorkbookFromFields 最低要求
+
+从 `fields[]` 重建时，每个 field 须写入 `data.dataTable[x][y].style`（含 `cellType` 关键属性：父格、fieldKey、leftFilterField 等）。 
+**禁止**只提交 `{ version, sheets: {} }` 或 `{ sheets: { Sheet1: { data: { dataTable: {} } } } }`。
+
+**Const（强制）**：`style.cellType` 须为完整 `ConstCellType`，至少包含：
+
+| 属性 | 说明 |
+|------|------|
+| `cellText` | 有展示文案时必填 |
+| `leftX/leftY/topX/topY` | **禁止省略**（省略 → Java int 默认 0 → 伪自定义 A1） |
+| `pcHreflink` / `openType` | 超链接 Const 必填；服务端**只认 workbook cellType**，不只认 `fields[]` 顶层 |
+
+普通 Const 父格写 `-1`；超链接含 `{L4}` 时左父格指向依赖数据格。见 `report-self-check-guide.md` §2.2。
+
+**定点修改**：用户只点一格时，语义上只改该格，但仍须整表 fields 原样写回 + 完整 workbook（见 `targeted-fix-guide.md`）。
+
+### 3.2 快照配置 patch 示例
+
+```javascript
+const wb = mergeWorkbookSafe(dev.data, (wb) => {
+ wb.snapshot = {
+ enableSnapshot: true,
+ cron: '0 0 0 * * ?',
+ // 未指定名称时的平台默认
+ snapshotName: `${reportName}-{date}-{time}`,
+ params: JSON.stringify({ searchCondition: {} }),
+ // 雪花 ID 必须字符串，禁止 Number(reportId)（超 MAX_SAFE_INTEGER 会截断，设计器空白）
+ sheetId: String(reportId),
+ // 更新已有配置时可带 id/jobId（同样用 String）；rollback 后建议 omit 让服务端重建调度
+ };
+ // 禁止 showLocation=0
+ for (const sh of Object.values(wb.sheets || {})) {
+ if (!sh.tag) sh.tag = {};
+ if (!sh.tag.showLocation || sh.tag.showLocation === 0) sh.tag.showLocation = 2;
+ }
+});
+```
+
+### 3.3 保存后验证清单
+
+| 检查项 | 通过标准 |
+|--------|----------|
+| `fields.length` | ≥ 保存前数量（允许只增不减，除非用户要求删格） |
+| 关键单元格抽样 | 如 `(1,0)` 供应商等级 `(1,5)` 进货单编号 仍存在 |
+| `snapshot.enableSnapshot` | 若本次任务为开快照，回读为 true |
+| 设计器肉眼 | 提示用户 Ctrl+F5 强刷 |
+
+---
+
+## 四、事故恢复
+
+| 现象 | 处理 |
+|------|------|
+| 设计器空白、`fields.length===0` | `GET rollbackReport?sheetId={版本snapshotId}&originSheetId={reportId}` |
+| 无版本 | 查 `getVersionWithPage`；或本地 `inspect_*.json` / 脚本备份 |
+| 快照误伤后 layout 已还原 | 快照需在设计器 **页面→快照设置** 重配，或 `set_snapshot_schedule.js`（已含保护） |
+
+**版本 ID 来源**：`save_as_version.js --list-only` → `snapshotId` 列。
+
+---
+
+## 五、脚本与模块
+
+| 文件 | 用途 |
+|------|------|
+| `e10-cli report fix（内部走安全局部保存）` | **安全合并 workbook**、保存前断言、保存后验证 |
+| `e10-cli report snapshot set` | 定时快照（默认名 `{报表名}-{date}-{time}`；ID 字符串；依赖 safe_report_save） |
+| `e10-cli report verify blank` | 防设计区空白门禁（sheetId/showLocation/scrollPage） |
+| `e10-cli report restore` | 从版本 snapshotId 还原 layout |
+| `references/designer-blank-prevention-guide.md` | **设计区空白禁令与定位** |
+| `已由 CLI 取代` | `merge_workbook_safe` / `assert_layout_not_empty` / `verify_layout_preserved` |
+
+---
+
+## 六、Agent 硬约束（写入 SKILL 摘要）
+
+1. **默认禁止**对已有报表提交空 workbook 或 0 fields 的 `saveReportDevInfo`。
+2. 设置权限 / 查询 / 数据集筛选 / 菜单 / 复制 → **不得**调用 `saveReportDevInfo`。
+3. 设置快照 → **必须** `mergeWorkbookSafe` + 保存前后 `fields.length` 校验。
+4. 用户未说「删除」「清空」「重置布局」→ **任何步骤不得使 fields 归零**。
+5. 保存前：`saveAsVersion` 或确认 `getVersionWithPage` 有可用版本。
+6. 保存后：`getReportDevInfo` 回读失败 → **停止后续操作**，优先 `rollbackReport`。
+
+---
+
+## 七、源码依据
+
+- `EdcReportDevDesignServiceImpl.saveReportDevInfoLast`：解压 workbook → `getFieldsFromWorkbook(wb)` → **全量** `saveFields` 覆盖 DB。
+- `Workbook.snapshot`：`saveSnapshot(wb, reportId)` 仅在 workbook 含 snapshot 对象时执行；与 fields 同一保存事务。
+- `workbookProps` 与 `fields` 分离存储；API 返回的 `workbookProps.sheets` 常不含 dataTable，**不能**作为唯一布局来源。

package/skill-docs/references/report/snowflake-id-precision-guide.md

@@ -0,0 +1,84 @@
+# 雪花 ID 精度安全指南
+
+> **适用场景**：复制报表、权限绑定、添加到菜单、删除/回收站等一切涉及 `reportId` / `pageId` 的 API 链路。 
+> **事故案例**：`copySheet` 返回 `1311221384923619328`，Node `JSON.parse` 后变为 `1311221384923619300`（末位差 28），导致权限与菜单绑到不存在的 ID。
+
+---
+
+## 一、根因
+
+| 项 | 值 |
+|----|-----|
+| E10 ID 类型 | 64 位雪花 ID（19 位十进制） |
+| JS 安全整数上限 | `Number.MAX_SAFE_INTEGER = 9007199254740991`（16 位） |
+| 后果 | `JSON.parse('{"id":1311221384923619328}')` → `id === 1311221384923619300` |
+
+**Python 注意**：`json.loads` 大整数默认可保留，但 `int(report_id)` 传给部分接口仍会溢出；**全程用 `str` 承载 ID**。
+
+---
+
+## 二、强制规则（Agent）
+
+1. **禁止**对含 `id` / `reportId` / `pageId` 的 API 响应裸用 `JSON.parse` / `json.loads` 后直接当数字用。
+2. **必须**使用 Skill 工具：
+ - Node：`内置雪花安全解析` → `parseJsonSnowflakeSafe` / `extractIdFromRaw`
+ - Python：`内置雪花安全解析` → 同名函数
+3. **copySheet 后取新 ID 双保险**：
+ ```javascript
+ const newId = extractIdFromRaw(copyRes.raw) || stringifyId(copyRes.json.data?.id);
+ ```
+ ```python
+ new_id = extract_id_from_raw(cli.last_raw) or str((result.get("data") or {}).get("id", ""))
+ ```
+4. **后续 API 一律字符串**：`pageId`、`sourceId`、`reportId`、`sheetId` 参数禁止 `Number(id)`。
+5. **交付给用户/手册的 reportId** 必须来自 raw 提取或 snowflake 安全解析，禁止直接打印 `json.data.id`（未安全解析时）。
+
+---
+
+## 三、安全解析原理
+
+仅对**已知 ID 字段名**的 ≥16 位数字加引号后再 `JSON.parse`，**不**对嵌套 JSON 字符串内数字做全局替换（避免破坏 `tabs` 等字段）。
+
+```javascript
+// 内置雪花安全解析
+parseJsonSnowflakeSafe(rawText)
+extractIdFromRaw(rawText, ['id', 'reportId', 'pageId'])
+```
+
+```python
+# 内置雪花安全解析
+parse_json_snowflake_safe(raw_text)
+extract_id_from_raw(raw_text, keys=("id", "reportId", "pageId"))
+```
+
+---
+
+## 四、受影响 API（必用安全 ID）
+
+| 操作 | API | ID 字段 |
+|------|-----|---------|
+| 复制 | `GET copySheet?sheetId=` | 响应 `data.id` |
+| 权限 | `POST savePermissions` | body key、`sourceId` |
+| 添加到菜单 | `POST savePublishMenu` | `page.pageId` |
+| 删除 | `GET deleteReport?id=` | query `id` |
+| 设计器 | `GET baseInfo?id=` | query `id` |
+| 列表 | `GET report/list` | 每项 `id` |
+
+---
+
+## 五、验证清单
+
+- [ ] copySheet 后 `newReportId` 与设计器 URL 中 ID 一致（末四位无漂移）
+- [ ] `baseInfo?id={newId}` 能返回报表名称
+- [ ] 菜单 `allMenus` 中 `pageId` 与报表 ID 字符串完全一致
+- [ ] 权限 `getQueryItem` / `permission/table/list/new` 的 `sourceId` 正确
+
+---
+
+## 六、相关文档
+
+| 文件 | 用途 |
+|------|------|
+| `report-lifecycle-api-guide.md` | 复制 / 权限 / 添加到菜单 API |
+| `已由 CLI 取代` | Python 客户端（已接入 snowflake 解析） |
+| `内置雪花安全解析` / `.py` | 跨语言安全解析 |