hailin
/
rwadurian
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
rwadurian/backend/services/reporting-service/docs/API.md

11 KiB
Raw Permalink Blame History

API 参考文档

1. 概述

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

Base URL: /api/v1

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

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

错误响应格式:

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

2. 健康检查 API

2.1 健康检查

Endpoint: GET /health

检查服务是否运行正常。

响应示例:

{
  "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

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

响应示例:

{
  "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

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

响应示例:

{
  "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)

响应示例:

{
  "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):

{
  "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

生成新的报表快照。

请求体:

{
  "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 否 额外筛选参数

响应示例:

{
  "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):

{
  "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

响应示例:

{
  "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

响应示例:

{
  "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 报表代码

响应示例:

{
  "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):

{
  "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

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

请求体:

{
  "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

响应示例:

{
  "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 否 每页数量

响应示例:

{
  "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):

{
  "statusCode": 401,
  "code": "UNAUTHORIZED",
  "message": "Unauthorized",
  "timestamp": "2024-01-15T10:30:00.000Z"
}

9. 限流

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

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