rwadurian/backend/services/reporting-service/docs/API.md

# API 参考文档

## 1. 概述

Reporting Service 提供 RESTful API，用于报表的生成、查询和导出。

**Base URL**: `/api/v1`

**响应格式**: 所有响应均使用统一的 JSON 格式

```json
{
  "success": true,
  "data": { ... },
  "timestamp": "2024-01-15T10:30:00.000Z"
}
```

**错误响应格式**:

```json
{
  "statusCode": 400,
  "code": "BAD_REQUEST",
  "message": "Validation failed",
  "timestamp": "2024-01-15T10:30:00.000Z"
}
```

## 2. 健康检查 API

### 2.1 健康检查

**Endpoint**: `GET /health`

检查服务是否运行正常。

**响应示例**:

```json
{
  "success": true,
  "data": {
    "status": "ok",
    "service": "reporting-service",
    "timestamp": "2024-01-15T10:30:00.000Z"
  },
  "timestamp": "2024-01-15T10:30:00.000Z"
}
```

### 2.2 就绪检查

**Endpoint**: `GET /health/ready`

检查服务是否准备好处理请求（包括数据库连接等）。

**响应示例**:

```json
{
  "success": true,
  "data": {
    "status": "ready",
    "service": "reporting-service",
    "timestamp": "2024-01-15T10:30:00.000Z"
  },
  "timestamp": "2024-01-15T10:30:00.000Z"
}
```

## 3. 报表定义 API

### 3.1 获取所有报表定义

**Endpoint**: `GET /reports/definitions`

获取所有可用的报表定义列表。

**响应示例**:

```json
{
  "success": true,
  "data": [
    {
      "id": "1",
      "reportCode": "RPT_LEADERBOARD",
      "reportName": "排行榜报表",
      "reportType": "LEADERBOARD_REPORT",
      "description": "用户排行榜数据报表",
      "parameters": {
        "required": ["startDate", "endDate"],
        "optional": ["limit", "offset"]
      },
      "isActive": true,
      "scheduleCron": "0 0 1 * * *",
      "createdAt": "2024-01-01T00:00:00.000Z"
    }
  ],
  "timestamp": "2024-01-15T10:30:00.000Z"
}
```

### 3.2 获取单个报表定义

**Endpoint**: `GET /reports/definitions/:code`

根据报表代码获取报表定义详情。

**路径参数**:

| 参数 | 类型 | 描述 |
|------|------|------|
| code | string | 报表代码 (如 `RPT_LEADERBOARD`) |

**响应示例**:

```json
{
  "success": true,
  "data": {
    "id": "1",
    "reportCode": "RPT_LEADERBOARD",
    "reportName": "排行榜报表",
    "reportType": "LEADERBOARD_REPORT",
    "description": "用户排行榜数据报表",
    "parameters": {
      "required": ["startDate", "endDate"],
      "optional": ["limit", "offset"]
    },
    "isActive": true,
    "scheduleCron": "0 0 1 * * *",
    "lastGeneratedAt": "2024-01-14T01:00:00.000Z",
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-14T01:00:00.000Z"
  },
  "timestamp": "2024-01-15T10:30:00.000Z"
}
```

**错误响应** (404):

```json
{
  "statusCode": 404,
  "code": "NOT_FOUND",
  "message": "Report definition not found: RPT_INVALID",
  "timestamp": "2024-01-15T10:30:00.000Z"
}
```

## 4. 报表生成 API

### 4.1 生成报表

**Endpoint**: `POST /reports/generate`

生成新的报表快照。

**请求体**:

```json
{
  "reportCode": "RPT_LEADERBOARD",
  "reportPeriod": "DAILY",
  "startDate": "2024-01-01",
  "endDate": "2024-01-01",
  "filterParams": {
    "limit": 100,
    "category": "all"
  }
}
```

**请求参数说明**:

| 参数 | 类型 | 必填 | 描述 |
|------|------|------|------|
| reportCode | string | 是 | 报表代码 |
| reportPeriod | enum | 是 | 报表周期: `DAILY`, `WEEKLY`, `MONTHLY`, `QUARTERLY`, `YEARLY`, `CUSTOM` |
| startDate | string | 是 | 开始日期 (ISO 8601 格式) |
| endDate | string | 是 | 结束日期 (ISO 8601 格式) |
| filterParams | object | 否 | 额外筛选参数 |

**响应示例**:

```json
{
  "success": true,
  "data": {
    "id": "12345",
    "reportCode": "RPT_LEADERBOARD",
    "reportType": "LEADERBOARD_REPORT",
    "reportPeriod": "DAILY",
    "periodKey": "2024-01-01",
    "rowCount": 100,
    "status": "COMPLETED",
    "generatedAt": "2024-01-15T10:30:00.000Z"
  },
  "timestamp": "2024-01-15T10:30:00.000Z"
}
```

**验证错误** (400):

```json
{
  "statusCode": 400,
  "code": "BAD_REQUEST",
  "message": "reportPeriod must be one of the following values: DAILY, WEEKLY, MONTHLY, QUARTERLY, YEARLY, CUSTOM",
  "timestamp": "2024-01-15T10:30:00.000Z"
}
```

## 5. 报表快照 API

### 5.1 查询报表快照列表

**Endpoint**: `GET /reports/snapshots`

查询报表快照列表，支持分页和筛选。

**查询参数**:

| 参数 | 类型 | 必填 | 描述 |
|------|------|------|------|
| reportCode | string | 否 | 按报表代码筛选 |
| reportPeriod | enum | 否 | 按报表周期筛选 |
| startDate | string | 否 | 开始日期范围 |
| endDate | string | 否 | 结束日期范围 |
| page | number | 否 | 页码 (默认: 1) |
| limit | number | 否 | 每页数量 (默认: 20, 最大: 100) |

**请求示例**:

```
GET /reports/snapshots?reportCode=RPT_LEADERBOARD&reportPeriod=DAILY&page=1&limit=10
```

**响应示例**:

```json
{
  "success": true,
  "data": [
    {
      "id": "12345",
      "reportCode": "RPT_LEADERBOARD",
      "reportType": "LEADERBOARD_REPORT",
      "reportPeriod": "DAILY",
      "periodKey": "2024-01-15",
      "rowCount": 100,
      "periodStartAt": "2024-01-15T00:00:00.000Z",
      "periodEndAt": "2024-01-15T23:59:59.999Z",
      "generatedAt": "2024-01-16T01:00:00.000Z"
    }
  ],
  "timestamp": "2024-01-15T10:30:00.000Z"
}
```

### 5.2 获取快照详情

**Endpoint**: `GET /reports/snapshots/:id`

根据快照ID获取详细数据。

**路径参数**:

| 参数 | 类型 | 描述 |
|------|------|------|
| id | string | 快照ID |

**响应示例**:

```json
{
  "success": true,
  "data": {
    "id": "12345",
    "reportCode": "RPT_LEADERBOARD",
    "reportType": "LEADERBOARD_REPORT",
    "reportPeriod": "DAILY",
    "periodKey": "2024-01-15",
    "snapshotData": {
      "rows": [
        { "rank": 1, "userId": 1001, "username": "user1", "score": 9850 },
        { "rank": 2, "userId": 1002, "username": "user2", "score": 9720 }
      ],
      "summary": {
        "totalEntries": 100,
        "averageScore": 5432,
        "maxScore": 9850
      }
    },
    "summaryData": {
      "totalEntries": 100,
      "generationTime": "2.5s"
    },
    "rowCount": 100,
    "dataSource": ["leaderboard-service"],
    "periodStartAt": "2024-01-15T00:00:00.000Z",
    "periodEndAt": "2024-01-15T23:59:59.999Z",
    "generatedAt": "2024-01-16T01:00:00.000Z"
  },
  "timestamp": "2024-01-15T10:30:00.000Z"
}
```

### 5.3 获取最新快照

**Endpoint**: `GET /reports/snapshots/:code/latest`

获取指定报表代码的最新快照。

**路径参数**:

| 参数 | 类型 | 描述 |
|------|------|------|
| code | string | 报表代码 |

**响应示例**:

```json
{
  "success": true,
  "data": {
    "id": "12345",
    "reportCode": "RPT_LEADERBOARD",
    "reportPeriod": "DAILY",
    "periodKey": "2024-01-15",
    "rowCount": 100,
    "generatedAt": "2024-01-16T01:00:00.000Z"
  },
  "timestamp": "2024-01-15T10:30:00.000Z"
}
```

**错误响应** (404):

```json
{
  "statusCode": 404,
  "code": "NOT_FOUND",
  "message": "No snapshot found for report: RPT_INVALID",
  "timestamp": "2024-01-15T10:30:00.000Z"
}
```

## 6. 导出 API

### 6.1 导出报表

**Endpoint**: `POST /export`

将报表快照导出为指定格式。

**请求体**:

```json
{
  "snapshotId": "12345",
  "format": "EXCEL",
  "options": {
    "includeCharts": true,
    "sheetName": "排行榜数据"
  }
}
```

**请求参数说明**:

| 参数 | 类型 | 必填 | 描述 |
|------|------|------|------|
| snapshotId | string | 是 | 快照ID |
| format | enum | 是 | 导出格式: `EXCEL`, `CSV`, `PDF`, `JSON` |
| options | object | 否 | 导出选项 |

**导出选项 (按格式)**:

**Excel 选项**:
| 选项 | 类型 | 描述 |
|------|------|------|
| includeCharts | boolean | 是否包含图表 |
| sheetName | string | 工作表名称 |

**PDF 选项**:
| 选项 | 类型 | 描述 |
|------|------|------|
| title | string | PDF标题 |
| orientation | string | 方向: `portrait`, `landscape` |

**响应示例**:

```json
{
  "success": true,
  "data": {
    "fileId": "file_67890",
    "fileName": "RPT_LEADERBOARD_2024-01-15.xlsx",
    "format": "EXCEL",
    "fileSize": 102400,
    "downloadUrl": "/api/v1/files/file_67890/download",
    "expiresAt": "2024-01-22T10:30:00.000Z",
    "createdAt": "2024-01-15T10:30:00.000Z"
  },
  "timestamp": "2024-01-15T10:30:00.000Z"
}
```

### 6.2 获取导出文件列表

**Endpoint**: `GET /export/files`

查询已导出的文件列表。

**查询参数**:

| 参数 | 类型 | 必填 | 描述 |
|------|------|------|------|
| snapshotId | string | 否 | 按快照ID筛选 |
| format | enum | 否 | 按格式筛选 |
| page | number | 否 | 页码 |
| limit | number | 否 | 每页数量 |

**响应示例**:

```json
{
  "success": true,
  "data": [
    {
      "fileId": "file_67890",
      "fileName": "RPT_LEADERBOARD_2024-01-15.xlsx",
      "format": "EXCEL",
      "fileSize": 102400,
      "snapshotId": "12345",
      "createdAt": "2024-01-15T10:30:00.000Z"
    }
  ],
  "timestamp": "2024-01-15T10:30:00.000Z"
}
```

### 6.3 下载文件

**Endpoint**: `GET /files/:fileId/download`

下载导出的文件。

**路径参数**:

| 参数 | 类型 | 描述 |
|------|------|------|
| fileId | string | 文件ID |

**响应**: 文件二进制流

**响应头**:
```
Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
Content-Disposition: attachment; filename="RPT_LEADERBOARD_2024-01-15.xlsx"
```

## 7. 错误码参考

| HTTP状态码 | 错误码 | 描述 |
|------------|--------|------|
| 400 | BAD_REQUEST | 请求参数验证失败 |
| 401 | UNAUTHORIZED | 未认证 |
| 403 | FORBIDDEN | 无权限访问 |
| 404 | NOT_FOUND | 资源不存在 |
| 409 | CONFLICT | 资源冲突 (如重复生成) |
| 422 | UNPROCESSABLE_ENTITY | 业务逻辑错误 |
| 500 | INTERNAL_ERROR | 服务器内部错误 |
| 503 | SERVICE_UNAVAILABLE | 服务不可用 |

## 8. 认证

API 支持 JWT Bearer Token 认证（可配置）。

**请求头**:
```
Authorization: Bearer <token>
```

**未认证响应** (401):
```json
{
  "statusCode": 401,
  "code": "UNAUTHORIZED",
  "message": "Unauthorized",
  "timestamp": "2024-01-15T10:30:00.000Z"
}
```

## 9. 限流

| 端点类型 | 限制 |
|----------|------|
| 读取操作 | 100 次/分钟 |
| 生成报表 | 10 次/分钟 |
| 导出操作 | 20 次/分钟 |

超出限制返回 HTTP 429 Too Many Requests。