weaver-e10-builder 1.6.10 → 1.6.12

package/skill-docs/references/report/datasource-metadata-guide.md

@@ -1,24 +1,24 @@
 # 数据源元数据获取指南（DataSetAction 接口）
 
-> **冷启动禁止通读**：找表优先 `app-datasource-lookup-guide.md` + `e10-cli report find`。本文仅需全接口手册时再读。
+> **冷启动禁止通读**：找表优先 `app-datasource-lookup-guide.md` + `e10-cli report find form`。本文仅需全接口手册时再读。
 > 对应 Java 文件：`DataSetAction.java`
 > 统一前缀：`/api/{module}/{submodule}/ds` 或 `/api/{module}/ds`
 > 认证方式：受 `@WeaPermission(publicPermission = true)` 保护，需携带 E10 标准登录态（`ebbusinessid`、`eteamsid`、`Cookie`）。
 
 ## 1. 用户指令到接口的路由规则
 
-| 用户意图 / 指令 | 路由接口 | 前置依赖 |
+| 用户意图 / 指令                          | 路由接口                                           | 前置依赖                                   |
 | ---------------------------------------- | -------------------------------------------------- | ------------------------------------------ |
-| "列出某个数据源下的所有数据集（不分页）" | `GET /ds/list` | 需已知 `sourceType` 与 `groupId` |
-| "分页查询数据集列表" | `GET /ds/listByPage` | 需已知 `sourceType`、`groupId` |
-| "获取数据源分组树" | `GET /ds/group` | 需已知 `sourceType` |
-| "查看某数据集的字段列表" | `GET /ds/fields` | 需已知 `sourceId`、`sourceType` |
-| "下拉选项/枚举值取数" | `GET /ds/options` | 需已知字段 `fieldName`、所属数据集 `objId` |
-| "批量取多个字段的选项" | `GET /ds/optionsList` | 需字段集合 JSON |
-| "校验 where 条件/函数公式是否可执行" | `POST /ds/conditionCheck`、`GET /ds/checkFunction` | 需完整 SQL/条件 JSON |
-| "执行接口数据源的调用" | `GET /ds/callApi`、`GET /ds/getApiInfo` | 需 `queryDto`（含 queryType） |
-| "根据 URL 解析数据源配置" | `GET /ds/pareDataSourceInfo` | 需目标页面/报表 URL |
-| "获取 ESB 字段类型" | `GET /ds/queryForField`、`POST /ds/saveFieldsType` | 用于 ESB 动作流字段映射 |
+| "列出某个数据源下的所有数据集（不分页）" | `GET /ds/list`                                     | 需已知 `sourceType` 与 `groupId`           |
+| "分页查询数据集列表"                     | `GET /ds/listByPage`                               | 需已知 `sourceType`、`groupId`             |
+| "获取数据源分组树"                       | `GET /ds/group`                                    | 需已知 `sourceType`                        |
+| "查看某数据集的字段列表"                 | `GET /ds/fields`                                   | 需已知 `sourceId`、`sourceType`            |
+| "下拉选项/枚举值取数"                    | `GET /ds/options`                                  | 需已知字段 `fieldName`、所属数据集 `objId` |
+| "批量取多个字段的选项"                   | `GET /ds/optionsList`                              | 需字段集合 JSON                            |
+| "校验 where 条件/函数公式是否可执行"     | `POST /ds/conditionCheck`、`GET /ds/checkFunction` | 需完整 SQL/条件 JSON                       |
+| "执行接口数据源的调用"                   | `GET /ds/callApi`、`GET /ds/getApiInfo`            | 需 `queryDto`（含 queryType）              |
+| "根据 URL 解析数据源配置"                | `GET /ds/pareDataSourceInfo`                       | 需目标页面/报表 URL                        |
+| "获取 ESB 字段类型"                      | `GET /ds/queryForField`、`POST /ds/saveFieldsType` | 用于 ESB 动作流字段映射                    |
 
 ## 2. 典型业务场景组合调用
 
@@ -43,7 +43,7 @@
 
 应用内步骤（已指定 app，推荐）：
 
-1. `e10-cli report find {appId} {表单名}` 或 `GET /api/datasource/ds/listByPage?sourceType=logic&appid={appId}&condition={name}` → `sourceId`
+1. `e10-cli report find form {appId} {表单名}` 或 `GET /api/datasource/ds/listByPage?sourceType=logic&appid={appId}&condition={name}` → `sourceId`
 2. 报表内：`addDataset` → `fieldsAndOriginFields?isFront=true`（fieldKey 用 `data.fieldsKey`）
 3. 字段核对走 fieldsKey / DataSetAction（本包不用 e10-cli）
 
@@ -69,18 +69,18 @@
 ## 3. 接口间前后置依赖
 
 ```
-GET /ds/group (获取分组树)
- │
- ▼
-GET /ds/listByPage (选定数据集，拿到 sourceId)
- │
- ├──────────────────────────┐
- ▼ ▼
-GET /ds/fields GET /ds/list (全量)
- │
- ├──────────────┐
- ▼ ▼
-GET /ds/options GET /ds/optionsList (获取下拉选项)
+GET /ds/group  (获取分组树)
+    │
+    ▼
+GET /ds/listByPage  (选定数据集，拿到 sourceId)
+    │
+    ├──────────────────────────┐
+    ▼                          ▼
+GET /ds/fields              GET /ds/list (全量)
+    │
+    ├──────────────┐
+    ▼              ▼
+GET /ds/options  GET /ds/optionsList  (获取下拉选项)
 ```
 
 - **所有查询接口** 必须先获取正确的 `sourceType`（枚举见下表）与 `groupId`。
@@ -91,35 +91,44 @@ GET /ds/options GET /ds/optionsList (获取下拉选项)
 
 ## 4. sourceType 枚举速查
 
-| sourceType | 含义 | 典型用途 |
+| sourceType       | 含义               | 典型用途                         |
 | ---------------- | ------------------ | -------------------------------- |
-| `ETEAMS` | E10 数仓 | 数仓报表，需 `permission` 校验 |
-| `FORM` | EB 表单 | 表单数据集，最常用 |
-| `BIZ` | 业务模块 | 业务数据集 |
-| `LOGIC` | 逻辑数据源 | 跨表单组合视图 |
-| `EXTERNAL` | 外部数据库 | MySQL/Oracle/PG/达梦等外部连接 |
-| `INNERAPI` | 内部接口 | 平台内部 REST API 数据源 |
-| `EXTERNALDATASET`| 外部数据集 | 外部系统自定义数据集 |
-| `LOCALDS` | 本地数据源 | 本地文件/CSV |
-| `BIDS` | 标书数据源 | 招投标场景 |
-| `INTEGRATION` | 集成数据源 | 集成平台数据 |
+| `ETEAMS`         | E10 数仓           | 数仓报表，需 `permission` 校验   |
+| `FORM`           | EB 表单            | 表单数据集，最常用               |
+| `BIZ`            | 业务模块           | 业务数据集                       |
+| `LOGIC`          | 逻辑数据源         | 跨表单组合视图                   |
+| `EXTERNAL`       | 外部数据库         | MySQL/Oracle/PG/达梦等外部连接   |
+| `INNERAPI`       | 内部接口           | 平台内部 REST API 数据源         |
+| `EXTERNALDATASET`| 外部数据集         | 外部系统自定义数据集             |
+| `LOCALDS`        | 本地数据源         | 本地文件/CSV                     |
+| `BIDS`           | 标书数据源         | 招投标场景                       |
+| `INTEGRATION`    | 集成数据源         | 集成平台数据                     |
+
+> ⚠️ **别把上表的枚举值当左侧面板的显示后缀（2026-09-16 · 注意点 BUILD-36）**
+> 设计器左侧「数据集」面板的显示名 = **数据源名 + (添加类型标签)**，标签按**添加类型**自动拼：
+> `业务模块 / 表单 / 数据加工 / 外部数据源 / 内置数据集 / 数据集合 / 系统字段 …`。
+> 它是**平台渲染时拼的**，不来自 `sourceType` 枚举、也不是报表脚本能写死的 ——
+> 所以 `addDataset.sourceName` / `edc_dataset_dev.name` 必须传**裸名**；
+> 自己拼 `(业务模块)` 会让面板显示 `采购入库(业务模块)(业务模块)`。存量脏值：`e10-cli report fix dataset-name`。
+> **CLI 预演（2026-09-16 新增）**：`e10-cli report dataset list --report-id <rid> --app-id <appId>` 逐行打出面板显示名，
+> 脏名标 ⚠；已实证标签只有 `logic→业务模块 / form→表单 / systemField→系统字段`，其余类型提示「未实证」不猜。
 
 ## 5. 关键参数速查
 
-| 参数 | 含义 | 典型值 |
+| 参数                   | 含义                        | 典型值                                      |
 | ---------------------- | --------------------------- | ------------------------------------------- |
-| `sourceType` | 数据源类型枚举 | `FORM` / `LOGIC` / `ETEAMS` / `EXTERNAL` 等 |
-| `groupId` | 数据源分组或连接 ID | 由 `/ds/group` 返回 |
-| `sourceId` / `tableId` | 数据集 ID | 由 `/ds/listByPage` 返回 |
-| `appId` | 所属应用 ID | eBuilder 应用 ID |
-| `pageNo` | 当前页码（**注意**：不是 `current`） | 默认 1，≥1 |
-| `pageSize` | 每页大小 | 默认 10，1~100 |
-| `name` | 模糊搜索关键字 | 可为空 |
-| `needPermission` | 是否开启权限校验 | 默认 false |
-| `isPublic` | 是否支持外发 | 默认 false |
-| `otherParams` | 扩展参数，JSON 字符串 | 含 `isPublic`、`dataUsage` 等 |
-| `queryDto` | 查询结构体（JSON 字符串） | 含 `queryType`，用于 SQL 拼接 |
-| `fieldInfo` | 字段映射入参（JSON 字符串） | 字段 ID + 选项集合 |
+| `sourceType`           | 数据源类型枚举              | `FORM` / `LOGIC` / `ETEAMS` / `EXTERNAL` 等 |
+| `groupId`              | 数据源分组或连接 ID         | 由 `/ds/group` 返回                         |
+| `sourceId` / `tableId` | 数据集 ID                   | 由 `/ds/listByPage` 返回                    |
+| `appId`                | 所属应用 ID                 | eBuilder 应用 ID                            |
+| `pageNo`               | 当前页码（**注意**：不是 `current`） | 默认 1，≥1                       |
+| `pageSize`             | 每页大小                    | 默认 10，1~100                              |
+| `name`                 | 模糊搜索关键字               | 可为空                                       |
+| `needPermission`       | 是否开启权限校验             | 默认 false                                   |
+| `isPublic`             | 是否支持外发                | 默认 false                                   |
+| `otherParams`          | 扩展参数，JSON 字符串       | 含 `isPublic`、`dataUsage` 等               |
+| `queryDto`             | 查询结构体（JSON 字符串）   | 含 `queryType`，用于 SQL 拼接               |
+| `fieldInfo`            | 字段映射入参（JSON 字符串） | 字段 ID + 选项集合                          |
 
 ## 6. 核心接口详情
 
@@ -129,53 +138,53 @@ GET /ds/options GET /ds/optionsList (获取下拉选项)
 
 **请求参数**：
 
-| 字段 | 类型 | 必填 | 传递位置 | 约束 | 说明 |
+| 字段           | 类型         | 必填 | 传递位置 | 约束                                                         | 说明                                |
 | -------------- | ------------ | ---- | -------- | ------------------------------------------------------------ | ----------------------------------- |
-| sourceType | enum | 是 | query | `ETEAMS`/`FORM`/`BIZ`/`LOGIC`/`EXTERNAL`/`INNERAPI`/`EXTERNALDATASET`/`LOCALDS`/`BIDS`/`INTEGRATION` | 数据源类型 |
-| groupId | string | 是 | query | 长度 ≤ 64 | 数据连接 ID 或分组 ID |
-| name | string | 否 | query | 默认空串 | 按名称模糊搜索 |
-| pageNo | int | 否 | query | 默认 1，≥1 | 当前页码 |
-| pageSize | int | 否 | query | 默认 10，1~100 | 每页大小 |
-| tableId | string | 否 | query | - | 指定表 ID |
-| dataUsage | array | 否 | query | - | 数据用途过滤，如列表/图表 |
-| needPermission | boolean | 否 | query | 默认 false | 是否开启权限校验 |
-| appId | string | 否 | query | - | 应用 ID |
-| comName | string | 否 | query | - | 组件名称 |
-| isPublic | boolean | 否 | query | 默认 false | 是否支持外发 |
-| otherParams | string(JSON) | 否 | query | 需 JSON 序列化 | 扩展参数，内部会自动追加 `isPublic` |
-| dynamicParams | string(JSON) | 否 | query | 需 JSON 序列化 | 动态参数，解析为 `DynamicParamDto` |
+| sourceType     | enum         | 是   | query    | `ETEAMS`/`FORM`/`BIZ`/`LOGIC`/`EXTERNAL`/`INNERAPI`/`EXTERNALDATASET`/`LOCALDS`/`BIDS`/`INTEGRATION` | 数据源类型                          |
+| groupId        | string       | 是   | query    | 长度 ≤ 64                                                    | 数据连接 ID 或分组 ID               |
+| name           | string       | 否   | query    | 默认空串                                                     | 按名称模糊搜索                      |
+| pageNo         | int          | 否   | query    | 默认 1，≥1                                                   | 当前页码                            |
+| pageSize       | int          | 否   | query    | 默认 10，1~100                                               | 每页大小                            |
+| tableId        | string       | 否   | query    | -                                                            | 指定表 ID                           |
+| dataUsage      | array        | 否   | query    | -                                                            | 数据用途过滤，如列表/图表           |
+| needPermission | boolean      | 否   | query    | 默认 false                                                   | 是否开启权限校验                    |
+| appId          | string       | 否   | query    | -                                                            | 应用 ID                             |
+| comName        | string       | 否   | query    | -                                                            | 组件名称                            |
+| isPublic       | boolean      | 否   | query    | 默认 false                                                   | 是否支持外发                        |
+| otherParams    | string(JSON) | 否   | query    | 需 JSON 序列化                                               | 扩展参数，内部会自动追加 `isPublic` |
+| dynamicParams  | string(JSON) | 否   | query    | 需 JSON 序列化                                               | 动态参数，解析为 `DynamicParamDto`  |
 
 **响应示例**：
 
 ```json
 {
- "code": 200,
- "message": "success",
- "data": {
- "list": [
- {
- "id": "87123",
- "name": "demo_form",
- "label": "演示表单",
- "groupId": "1001",
- "sourceType": "FORM",
- "appId": "2001"
- }
- ],
- "total": 1,
- "pageNo": 1,
- "pageSize": 10
- },
- "success": true
+  "code": 200,
+  "message": "success",
+  "data": {
+    "list": [
+      {
+        "id": "87123",
+        "name": "demo_form",
+        "label": "演示表单",
+        "groupId": "1001",
+        "sourceType": "FORM",
+        "appId": "2001"
+      }
+    ],
+    "total": 1,
+    "pageNo": 1,
+    "pageSize": 10
+  },
+  "success": true
 }
 ```
 
 **错误码**：
 
-| code | 说明 |
+| code | 说明                                 |
 | ---- | ------------------------------------ |
-| 200 | 成功 |
-| 500 | 服务器异常，`message` 含具体异常信息 |
+| 200  | 成功                                 |
+| 500  | 服务器异常，`message` 含具体异常信息 |
 
 **请求示例**：
 
@@ -202,25 +211,25 @@ GET /api/ebuilder/ds/listByPage?sourceType=FORM&groupId=1001&name=&pageNo=1&page
 
 **请求参数**：
 
-| 字段 | 类型 | 必填 | 说明 |
+| 字段       | 类型 | 必填 | 说明         |
 | ---------- | ---- | ---- | ------------ |
-| sourceType | enum | 是 | 数据源类型 |
-| appId | string | 否 | 应用 ID |
+| sourceType | enum | 是   | 数据源类型   |
+| appId      | string | 否   | 应用 ID      |
 
 **响应示例**：
 
 ```json
 {
- "code": 200,
- "data": [
- {
- "id": "weaver-ebuilder-form-service",
- "name": "EB表单服务",
- "children": [
- { "id": "form_001", "name": "人事表单组" }
- ]
- }
- ]
+  "code": 200,
+  "data": [
+    {
+      "id": "weaver-ebuilder-form-service",
+      "name": "EB表单服务",
+      "children": [
+        { "id": "form_001", "name": "人事表单组" }
+      ]
+    }
+  ]
 }
 ```
 
@@ -230,26 +239,26 @@ GET /api/ebuilder/ds/listByPage?sourceType=FORM&groupId=1001&name=&pageNo=1&page
 
 **请求参数**：
 
-| 字段 | 类型 | 必填 | 说明 |
+| 字段       | 类型   | 必填 | 说明                       |
 | ---------- | ------ | ---- | -------------------------- |
-| sourceType | enum | 是 | 数据源类型 |
-| sourceId | string | 是 | 数据集 ID（来自 listByPage） |
-| groupId | string | 否 | 分组 ID |
+| sourceType | enum   | 是   | 数据源类型                 |
+| sourceId   | string | 是   | 数据集 ID（来自 listByPage） |
+| groupId    | string | 否   | 分组 ID                    |
 
 **响应示例**：
 
 ```json
 {
- "code": 200,
- "data": [
- {
- "fieldId": "field_001",
- "fieldName": "f_emp_name",
- "label": "员工姓名",
- "type": "TEXT",
- "dbType": "VARCHAR"
- }
- ]
+  "code": 200,
+  "data": [
+    {
+      "fieldId": "field_001",
+      "fieldName": "f_emp_name",
+      "label": "员工姓名",
+      "type": "TEXT",
+      "dbType": "VARCHAR"
+    }
+  ]
 }
 ```
 
@@ -259,11 +268,11 @@ GET /api/ebuilder/ds/listByPage?sourceType=FORM&groupId=1001&name=&pageNo=1&page
 
 **请求参数**：
 
-| 字段 | 类型 | 必填 | 说明 |
+| 字段       | 类型   | 必填 | 说明             |
 | ---------- | ------ | ---- | ---------------- |
-| sourceType | enum | 是 | 数据源类型 |
-| objId | string | 是 | 数据集 ID |
-| fieldName | string | 是 | 字段名 |
+| sourceType | enum   | 是   | 数据源类型       |
+| objId      | string | 是   | 数据集 ID        |
+| fieldName  | string | 是   | 字段名           |
 
 ### 6.5 GET /ds/optionsList — 批量获取字段选项
 
@@ -271,9 +280,9 @@ GET /api/ebuilder/ds/listByPage?sourceType=FORM&groupId=1001&name=&pageNo=1&page
 
 **请求参数**：
 
-| 字段 | 类型 | 必填 | 说明 |
+| 字段      | 类型   | 必填 | 说明                   |
 | --------- | ------ | ---- | ---------------------- |
-| fieldList | string | 是 | 字段集合 JSON 字符串 |
+| fieldList | string | 是   | 字段集合 JSON 字符串   |
 
 ### 6.6 GET /ds/checkFunction — 校验函数公式
 
@@ -358,8 +367,8 @@ GET /api/ebuilder/ds/listByPage?sourceType=FORM&groupId=1001&name=&pageNo=1&page
 
 ## 10. 变更记录
 
-| 版本 | 日期 | 变更说明 |
+| 版本 | 日期       | 变更说明                                                                                                                    |
 | ---- | ---------- | --------------------------------------------------------------------------------------------------------------------------- |
 | v1.0 | 2026-08-03 | 基于 `DataSetAction.java` 初版生成，覆盖 list / listByPage / group / fields / options / optionsList / permission / getDataSourceName / queryForField / callApi / getApiInfo / fieldConvert / checkFunction / conditionCheck / getFinalSql / getFinalSqlByType / getGroupsForEteams / pareDataSourceInfo / baseDataSourceInfo / saveFieldsType 共 20 个接口 |
-| v1.1 | 2026-08-03 | 整合到 report-builder-assistant 技能，补充场景 B/C/D、接口依赖图、sourceType 枚举速查、与浏览器接口对比表、分页参数差异说明 |
+| v1.1 | 2026-08-03 | 整合到 report-builder-assistant 技能，补充场景 B/C/D、接口依赖图、sourceType 枚举速查、与浏览器接口对比表、分页参数差异说明    |
 | v1.3 | 2026-09-04 | 场景 A 分支：已指定 app → 应用内查找；新增 §7 应用内 vs 全系统规则，链至 app-datasource-lookup-guide.md |