预测数据集模块 API 文档

基础前缀：/external/private/api 鉴权：DEFrame-UserId、DEFrame-TenantId、DEFrame-ExtendedInfo 文档版本基准：4f46278（2026-08-11）

统一响应体结构：

{
  "code": 0,
  "message": "success",
  "data": {},
  "ext": null
}

---

1. 查询 KaiwuDB 预测数据集目录

名称：KaiwuDB 数据集目录 作用：返回 KaiwuDB 数据源的库 / schema / 表目录（支持关键字过滤）。

• 请求方式：GET
• 路径：/external/private/api/forecast-datasets/kaiwudb/catalog
• 查询参数：keyword（可选）

说明：依赖 KaiwuDB 连接，未连接时返回 500。

响应体：

{
  "code": 0,
  "message": "success",
  "data": {
    "dataSourceId": "ds-001",
    "dataSourceName": "kaiwudb-prod",
    "databases": [
      {
        "databaseIdentifier": "energy",
        "displayName": "能源库",
        "schemas": [
          {
            "schemaIdentifier": "public",
            "displayName": "public",
            "tables": [
              {
                "tableIdentifier": "power_load",
                "displayName": "电力负荷表",
                "columns": [
                  {
                    "name": "time",
                    "type": "TIMESTAMP",
                    "description": "时间"
                  },
                  {
                    "name": "load",
                    "type": "DOUBLE",
                    "description": "负荷"
                  }
                ]
              }
            ]
          }
        ]
      }
    ]
  },
  "ext": null
}

---

2. 创建预测数据集

名称：创建预测数据集 作用：在指定会话下创建预测用数据集（绑定数据源或文件），返回资源引用与版本。

• 请求方式：POST
• 路径：/external/private/api/conversations/{conversationId}/forecast-datasets
• 请求体：

{
  "name": "电力负荷预测集",
  "sourceType": "FILE",
  "sources": [
    {
      "databaseIdentifier": null,
      "schemaIdentifier": null,
      "tableIdentifier": null,
      "timeFieldKey": null,
      "selectedFieldKeys": [],
      "tagFilter": null,
      "resourceId": "file-001",
      "uploadFileType": "CSV",
      "minioUrl": "minio://bucket/path/负荷曲线.csv",
      "displayName": "负荷曲线.csv",
      "mimeType": "text/csv",
      "fileSize": 102400,
      "sourceModule": "CONVERSATION_ATTACHMENT",
      "metadata": {}
    }
  ],
  "timeField": {
    "fieldKey": "time",
    "dataType": "TIMESTAMP",
    "unit": null
  },
  "targetField": {
    "fieldKey": "load",
    "dataType": "DOUBLE",
    "unit": "kW"
  },
  "covariateFields": [],
  "joinPlan": {},
  "missingValuePolicy": {}
}

说明：会写入数据库并创建内部数据集版本，本文档未实测执行，字段结构依据 DTO。

响应体：

{
  "code": 0,
  "message": "success",
  "data": {
    "resourceRefId": "ref-001",
    "resourceType": "DATASET",
    "resourceId": "ds-001",
    "displayName": "电力负荷预测集",
    "sourceModule": "FORECAST",
    "metadata": {},
    "datasetVersion": 1
  },
  "ext": null
}

---

3. 查询预测数据集详情

名称：预测数据集详情 作用：返回指定数据集版本的结构、来源与预测 schema 信息。

• 请求方式：GET
• 路径：/external/private/api/conversations/{conversationId}/forecast-datasets/{datasetVersionId}

响应体：

{
  "code": 0,
  "message": "success",
  "data": {
    "resourceRefId": "ref-001",
    "datasetId": "ds-001",
    "datasetVersion": 1,
    "sourceType": "FILE",
    "displayName": "电力负荷预测集",
    "sources": [
      {
        "databaseIdentifier": null,
        "schemaIdentifier": null,
        "tableIdentifier": null,
        "timeFieldKey": null,
        "selectedFieldKeys": ["load"],
        "tagFilter": null
      }
    ],
    "forecastSchema": {},
    "createdAt": "2026-08-12T10:00:00"
  },
  "ext": null
}