# 数据平台服务API设计文档

## 1. 概述

本文档详细描述了数据平台服务(data-platform-service)提供的API接口，包括数据统计、报表生成、数据分析等核心功能。

## 2. 基础信息

- 基础路径: `/api/v1/data`
- 版本: v1
- 通信协议: HTTP/HTTPS
- 数据格式: JSON
- 状态码: 遵循HTTP状态码规范

## 3. 全局Headers

| Header名称 | 是否必填 | 描述 |
|------------|----------|------|
| Authorization | 是 | Bearer Token认证信息 |
| Content-Type | 是 | application/json |

## 4. 全局响应格式

### 4.1 成功响应
```json
{
  "code": 0,
  "message": "success",
  "data": {}
}
```

### 4.2 错误响应
```json
{
  "code": 40001,
  "message": "错误描述",
  "data": null
}
```

## 5. 数据统计接口

### 5.1 获取统计数据

**接口地址**: `GET /statistics`

**请求参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| stat_type | string | 是 | 统计类型(USER_COUNT, PRODUCT_COUNT, ORDER_COUNT, REVENUE等) |
| start_date | string | 否 | 开始日期(YYYY-MM-DD) |
| end_date | string | 否 | 结束日期(YYYY-MM-DD) |
| dimension1 | string | 否 | 维度1(如地区、品类等) |
| dimension2 | string | 否 | 维度2 |
| page | integer | 否 | 页码，默认1 |
| size | integer | 否 | 每页数量，默认10 |

**响应数据**:

| 字段名 | 类型 | 描述 |
|--------|------|------|
| total | integer | 总记录数 |
| page | integer | 当前页码 |
| size | integer | 每页数量 |
| items | array | 统计数据列表 |

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "total": 30,
    "page": 1,
    "size": 10,
    "items": [
      {
        "id": 1,
        "stat_type": "USER_COUNT",
        "stat_value": 12500.00,
        "stat_date": "2024-01-15",
        "dimension1": "北京",
        "dimension2": null,
        "created_at": "2024-01-15T00:00:00Z"
      }
    ]
  }
}
```

### 5.2 批量获取统计数据

**接口地址**: `POST /statistics/batch`

**请求参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| queries | array | 是 | 查询条件列表 |

**queries元素结构**:

| 字段名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| stat_type | string | 是 | 统计类型 |
| start_date | string | 否 | 开始日期(YYYY-MM-DD) |
| end_date | string | 否 | 结束日期(YYYY-MM-DD) |
| dimension1 | string | 否 | 维度1 |
| dimension2 | string | 否 | 维度2 |

**响应数据**:

| 字段名 | 类型 | 描述 |
|--------|------|------|
| results | array | 查询结果列表 |

**示例请求**:
```json
{
  "queries": [
    {
      "stat_type": "USER_COUNT",
      "start_date": "2024-01-01",
      "end_date": "2024-01-31"
    },
    {
      "stat_type": "ORDER_COUNT",
      "start_date": "2024-01-01",
      "end_date": "2024-01-31"
    }
  ]
}
```

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "results": [
      {
        "stat_type": "USER_COUNT",
        "data": [
          {
            "stat_value": 12500.00,
            "stat_date": "2024-01-31"
          }
        ]
      },
      {
        "stat_type": "ORDER_COUNT",
        "data": [
          {
            "stat_value": 3500.00,
            "stat_date": "2024-01-31"
          }
        ]
      }
    ]
  }
}
```

## 6. 报表管理接口

### 6.1 获取报表模板列表

**接口地址**: `GET /reports/templates`

**请求参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| template_type | string | 否 | 模板类型(DAILY, WEEKLY, MONTHLY等) |
| data_source | string | 否 | 数据源 |
| status | string | 否 | 模板状态(ACTIVE/INACTIVE) |
| page | integer | 否 | 页码，默认1 |
| size | integer | 否 | 每页数量，默认10 |

**响应数据**:

| 字段名 | 类型 | 描述 |
|--------|------|------|
| total | integer | 总记录数 |
| page | integer | 当前页码 |
| size | integer | 每页数量 |
| items | array | 报表模板列表 |

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "total": 5,
    "page": 1,
    "size": 10,
    "items": [
      {
        "id": 1,
        "name": "用户增长日报",
        "description": "每日用户增长情况统计报表",
        "template_type": "DAILY",
        "data_source": "user_center_service",
        "status": "ACTIVE",
        "created_at": "2024-01-01T00:00:00Z"
      }
    ]
  }
}
```

### 6.2 创建报表模板

**接口地址**: `POST /reports/templates`

**请求参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| name | string | 是 | 报表名称 |
| description | string | 否 | 报表描述 |
| template_type | string | 是 | 模板类型 |
| data_source | string | 是 | 数据源 |
| query_sql | string | 是 | 查询SQL |
| columns_config | object | 否 | 列配置信息 |

**响应数据**:

| 字段名 | 类型 | 描述 |
|--------|------|------|
| id | integer | 模板ID |
| name | string | 报表名称 |
| description | string | 报表描述 |
| template_type | string | 模板类型 |
| data_source | string | 数据源 |
| query_sql | string | 查询SQL |
| columns_config | object | 列配置信息 |
| status | string | 模板状态 |
| created_at | string | 创建时间 |

**示例请求**:
```json
{
  "name": "交易统计月报",
  "description": "每月交易情况统计报表",
  "template_type": "MONTHLY",
  "data_source": "trade_service",
  "query_sql": "SELECT DATE_FORMAT(created_at, '%Y-%m') as month, COUNT(*) as order_count, SUM(total_amount) as total_revenue FROM orders WHERE created_at >= :startDate AND created_at <= :endDate GROUP BY month",
  "columns_config": {
    "month": "月份",
    "order_count": "订单数量",
    "total_revenue": "总收入"
  }
}
```

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 2,
    "name": "交易统计月报",
    "description": "每月交易情况统计报表",
    "template_type": "MONTHLY",
    "data_source": "trade_service",
    "query_sql": "SELECT DATE_FORMAT(created_at, '%Y-%m') as month, COUNT(*) as order_count, SUM(total_amount) as total_revenue FROM orders WHERE created_at >= :startDate AND created_at <= :endDate GROUP BY month",
    "columns_config": {
      "month": "月份",
      "order_count": "订单数量",
      "total_revenue": "总收入"
    },
    "status": "ACTIVE",
    "created_at": "2024-01-15T10:30:00Z"
  }
}
```

### 6.3 生成报表

**接口地址**: `POST /reports/generate`

**请求参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| template_id | integer | 是 | 报表模板ID |
| start_date | string | 否 | 统计开始日期(YYYY-MM-DD) |
| end_date | string | 否 | 统计结束日期(YYYY-MM-DD) |
| report_format | string | 否 | 报表格式(PDF/EXCEL/CSV)，默认PDF |

**响应数据**:

| 字段名 | 类型 | 描述 |
|--------|------|------|
| id | integer | 生成记录ID |
| template_id | integer | 报表模板ID |
| report_name | string | 报表文件名 |
| report_format | string | 报表格式 |
| status | string | 生成状态 |
| created_at | string | 创建时间 |

**示例请求**:
```json
{
  "template_id": 2,
  "start_date": "2024-01-01",
  "end_date": "2024-01-31",
  "report_format": "PDF"
}
```

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1001,
    "template_id": 2,
    "report_name": "交易统计月报_2024-01.pdf",
    "report_format": "PDF",
    "status": "GENERATING",
    "created_at": "2024-01-15T10:30:00Z"
  }
}
```

### 6.4 查询报表生成状态

**接口地址**: `GET /reports/generations/{id}`

**请求参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| id | integer | 是 | 生成记录ID |

**响应数据**:

| 字段名 | 类型 | 描述 |
|--------|------|------|
| id | integer | 生成记录ID |
| template_id | integer | 报表模板ID |
| report_name | string | 报表文件名 |
| report_path | string | 报表文件路径 |
| report_format | string | 报表格式 |
| start_date | string | 统计开始日期 |
| end_date | string | 统计结束日期 |
| status | string | 生成状态 |
| generated_at | string | 生成完成时间 |
| created_at | string | 创建时间 |

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1001,
    "template_id": 2,
    "report_name": "交易统计月报_2024-01.pdf",
    "report_path": "/reports/交易统计月报_2024-01.pdf",
    "report_format": "PDF",
    "start_date": "2024-01-01",
    "end_date": "2024-01-31",
    "status": "SUCCESS",
    "generated_at": "2024-01-15T10:35:00Z",
    "created_at": "2024-01-15T10:30:00Z"
  }
}
```

### 6.5 下载报表

**接口地址**: `GET /reports/download/{id}`

**请求参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| id | integer | 是 | 生成记录ID |

**响应**:
- 成功：返回报表文件流
- 失败：返回错误信息

## 7. 数据分析接口

### 7.1 创建分析任务

**接口地址**: `POST /analysis/tasks`

**请求参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| name | string | 是 | 任务名称 |
| description | string | 否 | 任务描述 |
| analysis_type | string | 是 | 分析类型(TREND, CORRELATION, CLUSTER等) |
| data_source | string | 是 | 数据源 |
| parameters | object | 否 | 分析参数 |

**响应数据**:

| 字段名 | 类型 | 描述 |
|--------|------|------|
| id | integer | 任务ID |
| name | string | 任务名称 |
| description | string | 任务描述 |
| analysis_type | string | 分析类型 |
| data_source | string | 数据源 |
| parameters | object | 分析参数 |
| status | string | 任务状态 |
| created_at | string | 创建时间 |

**示例请求**:
```json
{
  "name": "用户增长趋势分析",
  "description": "分析近一年用户增长趋势",
  "analysis_type": "TREND",
  "data_source": "user_center_service",
  "parameters": {
    "period": "YEARLY",
    "metric": "user_count"
  }
}
```

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 2001,
    "name": "用户增长趋势分析",
    "description": "分析近一年用户增长趋势",
    "analysis_type": "TREND",
    "data_source": "user_center_service",
    "parameters": {
      "period": "YEARLY",
      "metric": "user_count"
    },
    "status": "PENDING",
    "created_at": "2024-01-15T10:30:00Z"
  }
}
```

### 7.2 查询分析任务列表

**接口地址**: `GET /analysis/tasks`

**请求参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| analysis_type | string | 否 | 分析类型 |
| status | string | 否 | 任务状态 |
| page | integer | 否 | 页码，默认1 |
| size | integer | 否 | 每页数量，默认10 |

**响应数据**:

| 字段名 | 类型 | 描述 |
|--------|------|------|
| total | integer | 总记录数 |
| page | integer | 当前页码 |
| size | integer | 每页数量 |
| items | array | 分析任务列表 |

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "total": 1,
    "page": 1,
    "size": 10,
    "items": [
      {
        "id": 2001,
        "name": "用户增长趋势分析",
        "description": "分析近一年用户增长趋势",
        "analysis_type": "TREND",
        "data_source": "user_center_service",
        "status": "SUCCESS",
        "started_at": "2024-01-15T10:31:00Z",
        "completed_at": "2024-01-15T10:35:00Z",
        "created_at": "2024-01-15T10:30:00Z"
      }
    ]
  }
}
```

### 7.3 查询分析任务详情

**接口地址**: `GET /analysis/tasks/{id}`

**请求参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| id | integer | 是 | 任务ID |

**响应数据**:

| 字段名 | 类型 | 描述 |
|--------|------|------|
| id | integer | 任务ID |
| name | string | 任务名称 |
| description | string | 任务描述 |
| analysis_type | string | 分析类型 |
| data_source | string | 数据源 |
| parameters | object | 分析参数 |
| result_data | object | 分析结果数据 |
| status | string | 任务状态 |
| started_at | string | 开始执行时间 |
| completed_at | string | 完成时间 |
| created_at | string | 创建时间 |
| updated_at | string | 更新时间 |

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 2001,
    "name": "用户增长趋势分析",
    "description": "分析近一年用户增长趋势",
    "analysis_type": "TREND",
    "data_source": "user_center_service",
    "parameters": {
      "period": "YEARLY",
      "metric": "user_count"
    },
    "result_data": {
      "trend_data": [
        {
          "date": "2023-01",
          "value": 8500
        },
        {
          "date": "2023-02",
          "value": 8750
        }
      ],
      "trend_chart": "base64_encoded_image_data"
    },
    "status": "SUCCESS",
    "started_at": "2024-01-15T10:31:00Z",
    "completed_at": "2024-01-15T10:35:00Z",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:35:00Z"
  }
}
```

## 8. 数据看板接口

### 8.1 创建看板配置

**接口地址**: `POST /dashboards`

**请求参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| name | string | 是 | 看板名称 |
| description | string | 否 | 看板描述 |
| layout_config | object | 是 | 布局配置 |
| widgets_config | object | 是 | 组件配置 |
| access_permissions | object | 否 | 访问权限配置 |

**响应数据**:

| 字段名 | 类型 | 描述 |
|--------|------|------|
| id | integer | 配置ID |
| name | string | 看板名称 |
| description | string | 看板描述 |
| layout_config | object | 布局配置 |
| widgets_config | object | 组件配置 |
| access_permissions | object | 访问权限配置 |
| status | string | 配置状态 |
| created_by | integer | 创建人用户ID |
| created_at | string | 创建时间 |

**示例请求**:
```json
{
  "name": "运营数据看板",
  "description": "展示核心运营数据",
  "layout_config": {
    "grid_columns": 12,
    "widgets": [
      {
        "id": "widget1",
        "x": 0,
        "y": 0,
        "width": 6,
        "height": 4
      }
    ]
  },
  "widgets_config": {
    "widget1": {
      "type": "statistic",
      "title": "用户总数",
      "data_source": "USER_COUNT",
      "time_range": "today"
    }
  }
}
```

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 3001,
    "name": "运营数据看板",
    "description": "展示核心运营数据",
    "layout_config": {
      "grid_columns": 12,
      "widgets": [
        {
          "id": "widget1",
          "x": 0,
          "y": 0,
          "width": 6,
          "height": 4
        }
      ]
    },
    "widgets_config": {
      "widget1": {
        "type": "statistic",
        "title": "用户总数",
        "data_source": "USER_COUNT",
        "time_range": "today"
      }
    },
    "access_permissions": null,
    "status": "ACTIVE",
    "created_by": 12345,
    "created_at": "2024-01-15T10:30:00Z"
  }
}
```

### 8.2 查询看板配置列表

**接口地址**: `GET /dashboards`

**请求参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| status | string | 否 | 配置状态 |
| page | integer | 否 | 页码，默认1 |
| size | integer | 否 | 每页数量，默认10 |

**响应数据**:

| 字段名 | 类型 | 描述 |
|--------|------|------|
| total | integer | 总记录数 |
| page | integer | 当前页码 |
| size | integer | 每页数量 |
| items | array | 看板配置列表 |

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "total": 1,
    "page": 1,
    "size": 10,
    "items": [
      {
        "id": 3001,
        "name": "运营数据看板",
        "description": "展示核心运营数据",
        "status": "ACTIVE",
        "created_by": 12345,
        "created_at": "2024-01-15T10:30:00Z"
      }
    ]
  }
}
```

### 8.3 获取看板数据

**接口地址**: `GET /dashboards/{id}/data`

**请求参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| id | integer | 是 | 看板配置ID |

**响应数据**:

| 字段名 | 类型 | 描述 |
|--------|------|------|
| id | integer | 配置ID |
| name | string | 看板名称 |
| widgets_data | object | 各组件数据 |

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 3001,
    "name": "运营数据看板",
    "widgets_data": {
      "widget1": {
        "title": "用户总数",
        "value": 12500,
        "change": 150
      }
    }
  }
}
```

## 9. 错误码定义

| 错误码 | 错误信息 | 描述 |
|--------|----------|------|
| 0 | success | 请求成功 |
| 40001 | 参数错误 | 请求参数不合法 |
| 40002 | 统计数据不存在 | 指定的统计数据不存在 |
| 40003 | 报表模板不存在 | 指定的报表模板不存在 |
| 40004 | 报表生成记录不存在 | 指定的报表生成记录不存在 |
| 40005 | 分析任务不存在 | 指定的分析任务不存在 |
| 40006 | 看板配置不存在 | 指定的看板配置不存在 |
| 40007 | 报表生成失败 | 报表生成过程中发生错误 |
| 40008 | 数据分析失败 | 数据分析过程中发生错误 |
| 40009 | 报表文件不存在 | 指定的报表文件不存在 |
| 40010 | SQL查询错误 | 报表模板中的SQL查询存在错误 |
| 50001 | 权限不足 | 用户权限不足，无法访问该资源 |
| 50002 | 认证失败 | 用户认证失败 |
| 99999 | 系统错误 | 服务器内部错误 |