weaver-e10-builder 1.6.14 → 1.6.16

package/skill-docs/references/report/report-create-modes-guide.md

@@ -1,220 +1,220 @@
-# 新建报表 · 三种创建模式（强制）
-
-> **页面**：`/sp/ebdapp/detail/{appId}/report` → **新建报表** 对话框
-> **UI 三卡片**：从空白创建 · **模版创建** · **快速构建-列表式**
-> **源码**：`EdcReportDevBaseController.saveReportBaseInfo` + `EdcReportDevBaseServiceImpl.addReportBaseInfo`
-> **CLI**：`e10-cli report create blank|template|quick` · `e10-cli report create models`
-
----
-
-## 〇、结论（Agent 必读）
-
-| UI 卡片 | 是否支持 | 怎么走 |
-|---------|----------|--------|
-| **从空白创建** | ✅ 已支持 | `POST baseInfo`，`reportModel=0`，不传 `quicklyParam` |
-| **模版创建** | ✅ **本指南 / CLI 已支持** | `GET getReportModels` 选模板 → `POST baseInfo` 且 **`reportModel={模板报表ID}`** |
-| **快速构建-列表式** | ✅ **本指南 / CLI 已支持** | `POST baseInfo` 且 **`quicklyParam={QuicklyParam JSON 串}`**（`reportModel=0`） |
-
-服务端分支（**互斥，模板优先**）：
-
-```text
-modelId > 0           → 模版创建（copySheet）
-else quicklyParam 非空 → 快速构建-列表式
-else                  → 从空白创建（空 workbook + sheet）
-```
-
-**禁止混淆**：Skill 自带的 `assets/template-*-report.json` 是 **Agent 布局脚手架**，**不是**平台「模版创建」的 `getReportModels` 模板池。
-
----
-
-## 〇.1 ★★ 建壳顺序（强制 · 注意点 BUILD-50）
-
-`baseInfo` 只写 baseInfo 行；**`edc_report_dev` 记录由「设计器页首次加载」惰性创建**。故建壳后、
-**addDataset 之前**，必须 GET 一次设计器页：
-
-```text
-create blank → POST baseInfo → ★ GET /sp/edc/report/design/<id> → addDataset → (remap) → save
-```
-
-| 步骤 | 说明 |
-|------|------|
-| `POST baseInfo` | 得到 `reportId` |
-| **`GET /sp/edc/report/design/<reportId>?appId=<appId>`** | **初始化 dev 记录**（返回值是 HTML，可忽略）。构建层 / CLI 已内置 |
-| `addDataset` | 见 `add-dataset-registration-guide.md` |
-| `save` | 见 `report-internal-error-guide.md`（ENV-11 载荷矩阵 + R7/R8/R9 防御层） |
-
-**后果**（缺这一步 / 顺序颠倒）：
-- 缺 GET → dev 记录没建起来 → 后续 `saveReportDevInfo` **落不进去**；
-- **「先 save 后 addDataset」的壳会永久废掉** —— dev 与 baseInfo 状态不一致，无法修复，只能删表重建。
-
-已内置：`e10-cli report build`（`e10-cli report build spec`）在 `baseInfo` 之后自动调 `initReportDev`；
-`e10-cli report create blank` 同样自动执行；`e10-cli report card build` 新建分支同样。可用 `EB_SKIP_INIT_DEV=1` 跳过（仅定位）。
-失败时**降级为告警不阻断**（环境差异兜底）。
-
----
-
-## 一、共享入口
-
-`POST /api/bs/edc/report/baseInfo`（`multipart/form-data`，`id=0` 新建）
-
-| 参数 | 空白 | 模版创建 | 快速构建-列表式 |
-|------|------|----------|-----------------|
-| `appId` | 必填 | 必填 | 必填 |
-| `id` | `0` | `0` | `0` |
-| `name` | 必填 | 必填 | 必填 |
-| `nameLabelId` | `-1` | `-1` | `-1` |
-| `groupId` | `0` | `0` | `0` |
-| `showOrder` | `1` | `1` | `1` |
-| `permission` | `[]` | `[]` | `[]` |
-| **`reportModel`** | **`0`** | **模板报表 ID（>0）** | **`0`** |
-| **`quicklyParam`** | **省略** | **省略** | **QuicklyParam JSON 字符串** |
-
-返回 `data` = 新报表 ID（雪花字符串）。
-
-设计器地址：
-
-```text
-{host}/sp/edc/report/design/{reportId}?appId={appId}&type=1&from=management
-```
-
----
-
-## 二、模版创建
-
-### 2.1 列模板
-
-```http
-GET /api/bs/edc/report/getReportModels
-```
-
-系统模板池（`getReportList(-999, -1, user)`）。Agent 须把列表展示给用户或按名称精确匹配后再创建。
-
-### 2.2 创建
-
-```bash
-e10-cli report create models
-e10-cli report create template --app-id <appId> --name "新报表" --model-id <模板ID>
-```
-
-> 建表前会自动**精确查重**：同名已存在 → `exit 3` 且**不创建**（返回已有 reportId / 设计器地址）。
-> 确需同名再建（用户明确要求）才加 `--allow-duplicate`。见 §五。
-
-Python：
-
-```python
-models = client.get_report_models()
-rid, obj = client.create_report_shell(name, report_model=str(model_id))
-# 或
-rid, obj = client.create_from_model(name, model_id)
-```
-
-服务端：`addReportByModel` → `copySheet(modelId)`，布局/字段随模板复制。
-
----
-
-## 三、快速构建-列表式
-
-### 3.1 QuicklyParam 结构（源码 `quicklycreate.bean.QuicklyParam`）
-
-```json
-{
-  "dataSetList": [
-    {
-      "id": "<临时UUID，与 showField[].dataSetId 一致>",
-      "sourceType": "1",
-      "sourceId": "<表单/数据源 ID>",
-      "sourceName": "表单名",
-      "sourceGroup": ""
-    }
-  ],
-  "showField": [
-    {
-      "dataSetId": "<同上临时UUID>",
-      "tableId": "...",
-      "name": "fieldKey",
-      "text": "显示名"
-    }
-  ],
-  "fieldConfig": {
-    "<dataSetId>.<tableId>.<name>": {
-      "colName": "列标题",
-      "colWidth": "170",
-      "vAlign": "1",
-      "hAlign": "1",
-      "group": "0",
-      "hideCol": "0",
-      "lockCell": "0",
-      "textWrap": "0"
-    }
-  },
-  "theme": "-1",
-  "sheetIndex": 0,
-  "startRow": 0,
-  "startCol": 0
-}
-```
-
-要点：
-
-- `showField[].dataSetId` 必须与 `dataSetList[].id` **同一临时 ID**（同数据源多选时靠临时 id 区分）。
-- `fieldConfig` 的 key = `{dataSetId}.{tableId}.{name}`。
-- 任一字段 `group=1` → 服务端 **关闭** `simpleList`；否则默认 **开启** `simpleList:true`（列表加速）。
-- `theme` 默认 `"-1"`（无主题样式）。
-
-示例文件：`assets/quickly-param.example.json`
-
-### 3.2 CLI
-
-```bash
-e10-cli report create quick --app-id <appId> --name "列表报表" --quickly-file assets/quickly-param.example.json
-# 或
-e10-cli report create quick --app-id <appId> --name "列表报表" --quickly-json "{...}"
-```
-
-Python：`client.create_from_quickly_param(name, quickly_param_dict_or_str)`
-
-### 3.3 与设计器内「快速构建」的区别
-
-| | 列表页「快速构建-列表式」 | 设计器「更多 → 快速构建」 |
-|--|--------------------------|---------------------------|
-| 时机 | **新建** `baseInfo` + `quicklyParam` | **已有报表** 设计保存 `quicklyParamList` |
-| 本指南 | §三 | 见 `report-help-guide.md` §13.2；不走 create CLI |
-
----
-
-## 四、Agent 选型
-
-| 用户意图 | 模式 |
-|----------|------|
-| 从零搭布局 / API 细粒度单元格 | **从空白创建** + `api-report-build-fast-path.md` |
-| 「用某某模板」「系统模板」 | **模版创建** |
-| 「选表选字段一键列表」「快速构建」 | **快速构建-列表式** |
-| 未说明 | 默认空白；或 AskUserQuestion 三选一 |
-
----
-
-## 五、禁令
-
-- **★ 禁止重复建报表（强制 · 2026-10-09）**：建表前**必须精确查重**
-  （`spec_lib.findReportsByName(appId, name)` = `listAppReports` + 名称归一化比对）；
-  同名已存在 → **不建新表**，把已有 `reportId` / 设计器地址交回，**`exit 3`**。
-  `build spec` 与 `create blank|template|quick` 均已内置该门禁（默认拒绝同名）；
-  仅当用户**明确要求**才加 `--allow-duplicate`。
-  **禁止**为绕过查重而「先删旧表再建同名」（旧表可能已被使用 → 数据丢失风险）。注意点 **BUILD-40**。
-- **★ 禁止空壳（强制）**：`blank` 只产出空报表 → 必须**同流程立刻填满**（`addDataset` → `saveReportDevInfo`），
-  失败/中止即 `lifecycle delete` 回收；正式搭表走 `e10-cli report build spec`（一条命令出表）。
-  自查：`e10-cli report cleanup shells --app-id <appId> --list`。
-- 禁止同时依赖 `reportModel>0` 与 `quicklyParam` 指望「都生效」——服务端 **模板优先**，快速构建被跳过。
-- 禁止把 `assets/template-list-report.json` 当成平台 `getReportModels` 模板去传 `reportModel`。
-- 禁止未登录乱扫前端 bundle 猜参数；以本指南 + 源码 bean 为准。
-
----
-
-## 六、相关文档
-
-| 文档 | 用途 |
-|------|------|
-| `report-lifecycle-api-guide.md` | 列表页生命周期；含新建三模式入口 |
-| `report-baseinfo-defaults-guide.md` | baseInfo 默认值 + `reportModel` / `quicklyParam` |
-| `api-report-build-fast-path.md` | 空白创建后的细粒度搭建 |
-| `report-help-guide.md` §十三 | 产品 UX 说明 |
+# 新建报表 · 三种创建模式（强制）
+
+> **页面**：`/sp/ebdapp/detail/{appId}/report` → **新建报表** 对话框
+> **UI 三卡片**：从空白创建 · **模版创建** · **快速构建-列表式**
+> **源码**：`EdcReportDevBaseController.saveReportBaseInfo` + `EdcReportDevBaseServiceImpl.addReportBaseInfo`
+> **CLI**：`e10-cli report create blank|template|quick` · `e10-cli report create models`
+
+---
+
+## 〇、结论（Agent 必读）
+
+| UI 卡片 | 是否支持 | 怎么走 |
+|---------|----------|--------|
+| **从空白创建** | ✅ 已支持 | `POST baseInfo`，`reportModel=0`，不传 `quicklyParam` |
+| **模版创建** | ✅ **本指南 / CLI 已支持** | `GET getReportModels` 选模板 → `POST baseInfo` 且 **`reportModel={模板报表ID}`** |
+| **快速构建-列表式** | ✅ **本指南 / CLI 已支持** | `POST baseInfo` 且 **`quicklyParam={QuicklyParam JSON 串}`**（`reportModel=0`） |
+
+服务端分支（**互斥，模板优先**）：
+
+```text
+modelId > 0           → 模版创建（copySheet）
+else quicklyParam 非空 → 快速构建-列表式
+else                  → 从空白创建（空 workbook + sheet）
+```
+
+**禁止混淆**：Skill 自带的 `assets/template-*-report.json` 是 **Agent 布局脚手架**，**不是**平台「模版创建」的 `getReportModels` 模板池。
+
+---
+
+## 〇.1 ★★ 建壳顺序（强制 · 注意点 BUILD-50）
+
+`baseInfo` 只写 baseInfo 行；**`edc_report_dev` 记录由「设计器页首次加载」惰性创建**。故建壳后、
+**addDataset 之前**，必须 GET 一次设计器页：
+
+```text
+create blank → POST baseInfo → ★ GET /sp/edc/report/design/<id> → addDataset → (remap) → save
+```
+
+| 步骤 | 说明 |
+|------|------|
+| `POST baseInfo` | 得到 `reportId` |
+| **`GET /sp/edc/report/design/<reportId>?appId=<appId>`** | **初始化 dev 记录**（返回值是 HTML，可忽略）。构建层 / CLI 已内置 |
+| `addDataset` | 见 `add-dataset-registration-guide.md` |
+| `save` | 见 `report-internal-error-guide.md`（ENV-11 载荷矩阵 + R7/R8/R9 防御层） |
+
+**后果**（缺这一步 / 顺序颠倒）：
+- 缺 GET → dev 记录没建起来 → 后续 `saveReportDevInfo` **落不进去**；
+- **「先 save 后 addDataset」的壳会永久废掉** —— dev 与 baseInfo 状态不一致，无法修复，只能删表重建。
+
+已内置：`e10-cli report build`（`e10-cli report build spec`）在 `baseInfo` 之后自动调 `initReportDev`；
+`e10-cli report create blank` 同样自动执行；`e10-cli report card build` 新建分支同样。可用 `EB_SKIP_INIT_DEV=1` 跳过（仅定位）。
+失败时**降级为告警不阻断**（环境差异兜底）。
+
+---
+
+## 一、共享入口
+
+`POST /api/bs/edc/report/baseInfo`（`multipart/form-data`，`id=0` 新建）
+
+| 参数 | 空白 | 模版创建 | 快速构建-列表式 |
+|------|------|----------|-----------------|
+| `appId` | 必填 | 必填 | 必填 |
+| `id` | `0` | `0` | `0` |
+| `name` | 必填 | 必填 | 必填 |
+| `nameLabelId` | `-1` | `-1` | `-1` |
+| `groupId` | `0` | `0` | `0` |
+| `showOrder` | `1` | `1` | `1` |
+| `permission` | `[]` | `[]` | `[]` |
+| **`reportModel`** | **`0`** | **模板报表 ID（>0）** | **`0`** |
+| **`quicklyParam`** | **省略** | **省略** | **QuicklyParam JSON 字符串** |
+
+返回 `data` = 新报表 ID（雪花字符串）。
+
+设计器地址：
+
+```text
+{host}/sp/edc/report/design/{reportId}?appId={appId}&type=1&from=management
+```
+
+---
+
+## 二、模版创建
+
+### 2.1 列模板
+
+```http
+GET /api/bs/edc/report/getReportModels
+```
+
+系统模板池（`getReportList(-999, -1, user)`）。Agent 须把列表展示给用户或按名称精确匹配后再创建。
+
+### 2.2 创建
+
+```bash
+e10-cli report create models
+e10-cli report create template --app-id <appId> --name "新报表" --model-id <模板ID>
+```
+
+> 建表前会自动**精确查重**：同名已存在 → `exit 3` 且**不创建**（返回已有 reportId / 设计器地址）。
+> 确需同名再建（用户明确要求）才加 `--allow-duplicate`。见 §五。
+
+Python：
+
+```python
+models = client.get_report_models()
+rid, obj = client.create_report_shell(name, report_model=str(model_id))
+# 或
+rid, obj = client.create_from_model(name, model_id)
+```
+
+服务端：`addReportByModel` → `copySheet(modelId)`，布局/字段随模板复制。
+
+---
+
+## 三、快速构建-列表式
+
+### 3.1 QuicklyParam 结构（源码 `quicklycreate.bean.QuicklyParam`）
+
+```json
+{
+  "dataSetList": [
+    {
+      "id": "<临时UUID，与 showField[].dataSetId 一致>",
+      "sourceType": "1",
+      "sourceId": "<表单/数据源 ID>",
+      "sourceName": "表单名",
+      "sourceGroup": ""
+    }
+  ],
+  "showField": [
+    {
+      "dataSetId": "<同上临时UUID>",
+      "tableId": "...",
+      "name": "fieldKey",
+      "text": "显示名"
+    }
+  ],
+  "fieldConfig": {
+    "<dataSetId>.<tableId>.<name>": {
+      "colName": "列标题",
+      "colWidth": "170",
+      "vAlign": "1",
+      "hAlign": "1",
+      "group": "0",
+      "hideCol": "0",
+      "lockCell": "0",
+      "textWrap": "0"
+    }
+  },
+  "theme": "-1",
+  "sheetIndex": 0,
+  "startRow": 0,
+  "startCol": 0
+}
+```
+
+要点：
+
+- `showField[].dataSetId` 必须与 `dataSetList[].id` **同一临时 ID**（同数据源多选时靠临时 id 区分）。
+- `fieldConfig` 的 key = `{dataSetId}.{tableId}.{name}`。
+- 任一字段 `group=1` → 服务端 **关闭** `simpleList`；否则默认 **开启** `simpleList:true`（列表加速）。
+- `theme` 默认 `"-1"`（无主题样式）。
+
+示例文件：`assets/quickly-param.example.json`
+
+### 3.2 CLI
+
+```bash
+e10-cli report create quick --app-id <appId> --name "列表报表" --quickly-file assets/quickly-param.example.json
+# 或
+e10-cli report create quick --app-id <appId> --name "列表报表" --quickly-json "{...}"
+```
+
+Python：`client.create_from_quickly_param(name, quickly_param_dict_or_str)`
+
+### 3.3 与设计器内「快速构建」的区别
+
+| | 列表页「快速构建-列表式」 | 设计器「更多 → 快速构建」 |
+|--|--------------------------|---------------------------|
+| 时机 | **新建** `baseInfo` + `quicklyParam` | **已有报表** 设计保存 `quicklyParamList` |
+| 本指南 | §三 | 见 `report-help-guide.md` §13.2；不走 create CLI |
+
+---
+
+## 四、Agent 选型
+
+| 用户意图 | 模式 |
+|----------|------|
+| 从零搭布局 / API 细粒度单元格 | **从空白创建** + `api-report-build-fast-path.md` |
+| 「用某某模板」「系统模板」 | **模版创建** |
+| 「选表选字段一键列表」「快速构建」 | **快速构建-列表式** |
+| 未说明 | 默认空白；或 AskUserQuestion 三选一 |
+
+---
+
+## 五、禁令
+
+- **★ 禁止重复建报表（强制 · 2026-10-09）**：建表前**必须精确查重**
+  （`spec_lib.findReportsByName(appId, name)` = `listAppReports` + 名称归一化比对）；
+  同名已存在 → **不建新表**，把已有 `reportId` / 设计器地址交回，**`exit 3`**。
+  `build spec` 与 `create blank|template|quick` 均已内置该门禁（默认拒绝同名）；
+  仅当用户**明确要求**才加 `--allow-duplicate`。
+  **禁止**为绕过查重而「先删旧表再建同名」（旧表可能已被使用 → 数据丢失风险）。注意点 **BUILD-40**。
+- **★ 禁止空壳（强制）**：`blank` 只产出空报表 → 必须**同流程立刻填满**（`addDataset` → `saveReportDevInfo`），
+  失败/中止即 `lifecycle delete` 回收；正式搭表走 `e10-cli report build spec`（一条命令出表）。
+  自查：`e10-cli report cleanup shells --app-id <appId> --list`。
+- 禁止同时依赖 `reportModel>0` 与 `quicklyParam` 指望「都生效」——服务端 **模板优先**，快速构建被跳过。
+- 禁止把 `assets/template-list-report.json` 当成平台 `getReportModels` 模板去传 `reportModel`。
+- 禁止未登录乱扫前端 bundle 猜参数；以本指南 + 源码 bean 为准。
+
+---
+
+## 六、相关文档
+
+| 文档 | 用途 |
+|------|------|
+| `report-lifecycle-api-guide.md` | 列表页生命周期；含新建三模式入口 |
+| `report-baseinfo-defaults-guide.md` | baseInfo 默认值 + `reportModel` / `quicklyParam` |
+| `api-report-build-fast-path.md` | 空白创建后的细粒度搭建 |
+| `report-help-guide.md` §十三 | 产品 UX 说明 |