604 lines
14 KiB
Markdown
604 lines
14 KiB
Markdown
# 统计功能API文档
|
||
|
||
## 概述
|
||
|
||
统计功能API提供了完整的统计数据分析和管理功能，包括指标管理、实时统计、历史统计、仪表板管理、报告生成、数据导出等功能。
|
||
|
||
## 基础信息
|
||
|
||
- **基础URL**: `/api/v1/statistics`
|
||
- **认证方式**: Bearer Token
|
||
- **内容类型**: `application/json`
|
||
- **字符编码**: `UTF-8`
|
||
|
||
## 认证和权限
|
||
|
||
### 认证方式
|
||
所有API请求都需要在请求头中包含有效的JWT令牌：
|
||
```
|
||
Authorization: Bearer <your-jwt-token>
|
||
```
|
||
|
||
### 权限级别
|
||
- **公开访问**: 无需认证的接口
|
||
- **用户权限**: 需要用户或管理员权限
|
||
- **管理员权限**: 仅管理员可访问
|
||
|
||
## API接口
|
||
|
||
### 1. 指标管理
|
||
|
||
#### 1.1 创建统计指标
|
||
- **URL**: `POST /api/v1/statistics/metrics`
|
||
- **权限**: 管理员
|
||
- **描述**: 创建新的统计指标
|
||
|
||
**请求体**:
|
||
```json
|
||
{
|
||
"metric_type": "api_calls",
|
||
"metric_name": "total_count",
|
||
"dimension": "realtime",
|
||
"value": 100.0,
|
||
"metadata": "{\"source\": \"api_gateway\"}",
|
||
"date": "2024-01-01T00:00:00Z"
|
||
}
|
||
```
|
||
|
||
**响应**:
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "指标创建成功",
|
||
"data": {
|
||
"id": "uuid",
|
||
"metric_type": "api_calls",
|
||
"metric_name": "total_count",
|
||
"dimension": "realtime",
|
||
"value": 100.0,
|
||
"metadata": "{\"source\": \"api_gateway\"}",
|
||
"date": "2024-01-01T00:00:00Z",
|
||
"created_at": "2024-01-01T00:00:00Z",
|
||
"updated_at": "2024-01-01T00:00:00Z"
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 1.2 更新统计指标
|
||
- **URL**: `PUT /api/v1/statistics/metrics`
|
||
- **权限**: 管理员
|
||
- **描述**: 更新现有统计指标的值
|
||
|
||
**请求体**:
|
||
```json
|
||
{
|
||
"id": "uuid",
|
||
"value": 150.0
|
||
}
|
||
```
|
||
|
||
#### 1.3 删除统计指标
|
||
- **URL**: `DELETE /api/v1/statistics/metrics`
|
||
- **权限**: 管理员
|
||
- **描述**: 删除指定的统计指标
|
||
|
||
**请求体**:
|
||
```json
|
||
{
|
||
"id": "uuid"
|
||
}
|
||
```
|
||
|
||
#### 1.4 获取单个指标
|
||
- **URL**: `GET /api/v1/statistics/metrics/{id}`
|
||
- **权限**: 用户
|
||
- **描述**: 根据ID获取指定的统计指标
|
||
|
||
#### 1.5 获取指标列表
|
||
- **URL**: `GET /api/v1/statistics/metrics`
|
||
- **权限**: 用户
|
||
- **描述**: 根据条件获取统计指标列表
|
||
|
||
**查询参数**:
|
||
- `metric_type` (string): 指标类型
|
||
- `metric_name` (string): 指标名称
|
||
- `dimension` (string): 统计维度
|
||
- `start_date` (string): 开始日期 (YYYY-MM-DD)
|
||
- `end_date` (string): 结束日期 (YYYY-MM-DD)
|
||
- `limit` (int): 限制数量 (默认20, 最大1000)
|
||
- `offset` (int): 偏移量 (默认0)
|
||
- `sort_by` (string): 排序字段 (默认created_at)
|
||
- `sort_order` (string): 排序顺序 (默认desc)
|
||
|
||
### 2. 实时统计
|
||
|
||
#### 2.1 获取实时指标
|
||
- **URL**: `GET /api/v1/statistics/realtime`
|
||
- **权限**: 公开
|
||
- **描述**: 获取指定类型的实时统计指标
|
||
|
||
**查询参数**:
|
||
- `metric_type` (string, 必需): 指标类型
|
||
- `time_range` (string): 时间范围 (last_hour, last_day, last_week)
|
||
- `dimension` (string): 统计维度
|
||
|
||
**响应**:
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "获取实时指标成功",
|
||
"data": {
|
||
"metric_type": "api_calls",
|
||
"metrics": {
|
||
"total_count": 1000,
|
||
"success_count": 950,
|
||
"failed_count": 50,
|
||
"success_rate": 95.0
|
||
},
|
||
"timestamp": "2024-01-01T12:00:00Z",
|
||
"metadata": {
|
||
"time_range": "last_hour",
|
||
"dimension": "realtime"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 3. 历史统计
|
||
|
||
#### 3.1 获取历史指标
|
||
- **URL**: `GET /api/v1/statistics/historical`
|
||
- **权限**: 公开
|
||
- **描述**: 获取指定时间范围的历史统计指标
|
||
|
||
**查询参数**:
|
||
- `metric_type` (string, 必需): 指标类型
|
||
- `metric_name` (string): 指标名称
|
||
- `dimension` (string): 统计维度
|
||
- `start_date` (string, 必需): 开始日期 (YYYY-MM-DD)
|
||
- `end_date` (string, 必需): 结束日期 (YYYY-MM-DD)
|
||
- `period` (string): 统计周期
|
||
- `limit` (int): 限制数量 (默认20)
|
||
- `offset` (int): 偏移量 (默认0)
|
||
- `aggregate_by` (string): 聚合维度
|
||
- `group_by` (string): 分组维度
|
||
|
||
**响应**:
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "获取历史指标成功",
|
||
"data": {
|
||
"metric_type": "api_calls",
|
||
"metric_name": "total_count",
|
||
"dimension": "daily",
|
||
"data_points": [
|
||
{
|
||
"date": "2024-01-01T00:00:00Z",
|
||
"value": 1000,
|
||
"label": "total_count"
|
||
}
|
||
],
|
||
"summary": {
|
||
"total": 30000,
|
||
"average": 1000,
|
||
"max": 1500,
|
||
"min": 500,
|
||
"count": 30,
|
||
"growth_rate": 5.2,
|
||
"trend": "increasing"
|
||
},
|
||
"metadata": {
|
||
"period": "daily",
|
||
"aggregate_by": "day",
|
||
"group_by": "metric_name"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 4. 仪表板管理
|
||
|
||
#### 4.1 创建仪表板
|
||
- **URL**: `POST /api/v1/statistics/dashboards`
|
||
- **权限**: 管理员
|
||
- **描述**: 创建新的统计仪表板
|
||
|
||
**请求体**:
|
||
```json
|
||
{
|
||
"name": "用户仪表板",
|
||
"description": "普通用户专用仪表板",
|
||
"user_role": "user",
|
||
"layout": "{\"columns\": 2, \"rows\": 3}",
|
||
"widgets": "[{\"type\": \"api_calls\", \"position\": {\"x\": 0, \"y\": 0}}]",
|
||
"settings": "{\"theme\": \"light\", \"auto_refresh\": false}",
|
||
"refresh_interval": 600,
|
||
"access_level": "private",
|
||
"created_by": "user_id"
|
||
}
|
||
```
|
||
|
||
#### 4.2 获取仪表板列表
|
||
- **URL**: `GET /api/v1/statistics/dashboards`
|
||
- **权限**: 用户
|
||
- **描述**: 根据条件获取统计仪表板列表
|
||
|
||
**查询参数**:
|
||
- `user_role` (string): 用户角色
|
||
- `is_default` (bool): 是否默认
|
||
- `is_active` (bool): 是否激活
|
||
- `access_level` (string): 访问级别
|
||
- `created_by` (string): 创建者ID
|
||
- `name` (string): 仪表板名称
|
||
- `limit` (int): 限制数量 (默认20)
|
||
- `offset` (int): 偏移量 (默认0)
|
||
- `sort_by` (string): 排序字段 (默认created_at)
|
||
- `sort_order` (string): 排序顺序 (默认desc)
|
||
|
||
#### 4.3 获取单个仪表板
|
||
- **URL**: `GET /api/v1/statistics/dashboards/{id}`
|
||
- **权限**: 用户
|
||
- **描述**: 根据ID获取指定的统计仪表板
|
||
|
||
#### 4.4 获取仪表板数据
|
||
- **URL**: `GET /api/v1/statistics/dashboards/data`
|
||
- **权限**: 公开
|
||
- **描述**: 获取指定角色的仪表板数据
|
||
|
||
**查询参数**:
|
||
- `user_role` (string, 必需): 用户角色
|
||
- `period` (string): 统计周期 (today, week, month)
|
||
- `start_date` (string): 开始日期 (YYYY-MM-DD)
|
||
- `end_date` (string): 结束日期 (YYYY-MM-DD)
|
||
- `metric_types` (string): 指标类型列表
|
||
- `dimensions` (string): 统计维度列表
|
||
|
||
**响应**:
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "获取仪表板数据成功",
|
||
"data": {
|
||
"api_calls": {
|
||
"total_count": 10000,
|
||
"success_count": 9500,
|
||
"failed_count": 500,
|
||
"success_rate": 95.0,
|
||
"avg_response_time": 150.5
|
||
},
|
||
"users": {
|
||
"total_count": 1000,
|
||
"certified_count": 800,
|
||
"active_count": 750,
|
||
"certification_rate": 80.0,
|
||
"retention_rate": 75.0
|
||
},
|
||
"finance": {
|
||
"total_amount": 50000.0,
|
||
"recharge_amount": 60000.0,
|
||
"deduct_amount": 10000.0,
|
||
"net_amount": 50000.0
|
||
},
|
||
"period": {
|
||
"start_date": "2024-01-01",
|
||
"end_date": "2024-01-01",
|
||
"period": "today"
|
||
},
|
||
"metadata": {
|
||
"generated_at": "2024-01-01 12:00:00",
|
||
"user_role": "user",
|
||
"data_version": "1.0"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 5. 报告管理
|
||
|
||
#### 5.1 生成报告
|
||
- **URL**: `POST /api/v1/statistics/reports`
|
||
- **权限**: 管理员
|
||
- **描述**: 生成指定类型的统计报告
|
||
|
||
**请求体**:
|
||
```json
|
||
{
|
||
"report_type": "summary",
|
||
"title": "月度汇总报告",
|
||
"period": "month",
|
||
"user_role": "admin",
|
||
"start_date": "2024-01-01T00:00:00Z",
|
||
"end_date": "2024-01-31T23:59:59Z",
|
||
"filters": {
|
||
"metric_types": ["api_calls", "users"],
|
||
"dimensions": ["daily", "weekly"]
|
||
},
|
||
"generated_by": "admin_id"
|
||
}
|
||
```
|
||
|
||
#### 5.2 获取报告列表
|
||
- **URL**: `GET /api/v1/statistics/reports`
|
||
- **权限**: 用户
|
||
- **描述**: 根据条件获取统计报告列表
|
||
|
||
**查询参数**:
|
||
- `report_type` (string): 报告类型
|
||
- `user_role` (string): 用户角色
|
||
- `status` (string): 报告状态
|
||
- `period` (string): 统计周期
|
||
- `start_date` (string): 开始日期 (YYYY-MM-DD)
|
||
- `end_date` (string): 结束日期 (YYYY-MM-DD)
|
||
- `limit` (int): 限制数量 (默认20)
|
||
- `offset` (int): 偏移量 (默认0)
|
||
- `sort_by` (string): 排序字段 (默认created_at)
|
||
- `sort_order` (string): 排序顺序 (默认desc)
|
||
- `generated_by` (string): 生成者ID
|
||
|
||
#### 5.3 获取单个报告
|
||
- **URL**: `GET /api/v1/statistics/reports/{id}`
|
||
- **权限**: 用户
|
||
- **描述**: 根据ID获取指定的统计报告
|
||
|
||
### 6. 统计分析
|
||
|
||
#### 6.1 计算增长率
|
||
- **URL**: `GET /api/v1/statistics/analysis/growth-rate`
|
||
- **权限**: 用户
|
||
- **描述**: 计算指定指标的增长率
|
||
|
||
**查询参数**:
|
||
- `metric_type` (string, 必需): 指标类型
|
||
- `metric_name` (string, 必需): 指标名称
|
||
- `current_period` (string, 必需): 当前周期 (YYYY-MM-DD)
|
||
- `previous_period` (string, 必需): 上一周期 (YYYY-MM-DD)
|
||
|
||
**响应**:
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "计算增长率成功",
|
||
"data": {
|
||
"growth_rate": 15.5,
|
||
"current_value": 1150,
|
||
"previous_value": 1000,
|
||
"period": "daily"
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 6.2 计算趋势
|
||
- **URL**: `GET /api/v1/statistics/analysis/trend`
|
||
- **权限**: 用户
|
||
- **描述**: 计算指定指标的趋势
|
||
|
||
**查询参数**:
|
||
- `metric_type` (string, 必需): 指标类型
|
||
- `metric_name` (string, 必需): 指标名称
|
||
- `start_date` (string, 必需): 开始日期 (YYYY-MM-DD)
|
||
- `end_date` (string, 必需): 结束日期 (YYYY-MM-DD)
|
||
|
||
**响应**:
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "计算趋势成功",
|
||
"data": {
|
||
"trend": "increasing",
|
||
"trend_strength": 0.8,
|
||
"data_points": 30,
|
||
"correlation": 0.75
|
||
}
|
||
}
|
||
```
|
||
|
||
### 7. 数据导出
|
||
|
||
#### 7.1 导出数据
|
||
- **URL**: `POST /api/v1/statistics/export`
|
||
- **权限**: 管理员
|
||
- **描述**: 导出指定格式的统计数据
|
||
|
||
**请求体**:
|
||
```json
|
||
{
|
||
"format": "excel",
|
||
"metric_type": "api_calls",
|
||
"start_date": "2024-01-01T00:00:00Z",
|
||
"end_date": "2024-01-31T23:59:59Z",
|
||
"dimension": "daily",
|
||
"group_by": "metric_name",
|
||
"filters": {
|
||
"status": "success"
|
||
},
|
||
"columns": ["date", "metric_name", "value"],
|
||
"include_charts": true,
|
||
"exported_by": "admin_id"
|
||
}
|
||
```
|
||
|
||
**响应**:
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "数据导出成功",
|
||
"data": {
|
||
"download_url": "https://api.example.com/downloads/export_123.xlsx",
|
||
"file_name": "api_calls_export_20240101_20240131.xlsx",
|
||
"file_size": 1024000,
|
||
"expires_at": "2024-01-02T12:00:00Z"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 8. 定时任务管理
|
||
|
||
#### 8.1 手动触发小时聚合
|
||
- **URL**: `POST /api/v1/statistics/cron/hourly-aggregation`
|
||
- **权限**: 管理员
|
||
- **描述**: 手动触发指定时间的小时级数据聚合
|
||
|
||
**查询参数**:
|
||
- `target_hour` (string, 必需): 目标小时 (YYYY-MM-DDTHH:MM:SSZ)
|
||
|
||
#### 8.2 手动触发日聚合
|
||
- **URL**: `POST /api/v1/statistics/cron/daily-aggregation`
|
||
- **权限**: 管理员
|
||
- **描述**: 手动触发指定时间的日级数据聚合
|
||
|
||
**查询参数**:
|
||
- `target_date` (string, 必需): 目标日期 (YYYY-MM-DD)
|
||
|
||
#### 8.3 手动触发数据清理
|
||
- **URL**: `POST /api/v1/statistics/cron/data-cleanup`
|
||
- **权限**: 管理员
|
||
- **描述**: 手动触发过期数据清理任务
|
||
|
||
## 错误码
|
||
|
||
| 错误码 | HTTP状态码 | 描述 |
|
||
|--------|------------|------|
|
||
| 400 | 400 Bad Request | 请求参数错误 |
|
||
| 401 | 401 Unauthorized | 未认证或认证失败 |
|
||
| 403 | 403 Forbidden | 权限不足 |
|
||
| 404 | 404 Not Found | 资源不存在 |
|
||
| 422 | 422 Unprocessable Entity | 参数验证失败 |
|
||
| 429 | 429 Too Many Requests | 请求频率过高 |
|
||
| 500 | 500 Internal Server Error | 服务器内部错误 |
|
||
|
||
## 响应格式
|
||
|
||
### 成功响应
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "操作成功",
|
||
"data": {
|
||
// 响应数据
|
||
}
|
||
}
|
||
```
|
||
|
||
### 错误响应
|
||
```json
|
||
{
|
||
"success": false,
|
||
"message": "错误描述",
|
||
"error": "详细错误信息"
|
||
}
|
||
```
|
||
|
||
### 列表响应
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "查询成功",
|
||
"data": [
|
||
// 数据列表
|
||
],
|
||
"pagination": {
|
||
"page": 1,
|
||
"page_size": 20,
|
||
"total": 100,
|
||
"pages": 5,
|
||
"has_next": true,
|
||
"has_prev": false
|
||
}
|
||
}
|
||
```
|
||
|
||
## 数据模型
|
||
|
||
### 统计指标 (StatisticsMetric)
|
||
```json
|
||
{
|
||
"id": "string",
|
||
"metric_type": "string",
|
||
"metric_name": "string",
|
||
"dimension": "string",
|
||
"value": "number",
|
||
"metadata": "string",
|
||
"date": "string",
|
||
"created_at": "string",
|
||
"updated_at": "string"
|
||
}
|
||
```
|
||
|
||
### 统计报告 (StatisticsReport)
|
||
```json
|
||
{
|
||
"id": "string",
|
||
"report_type": "string",
|
||
"title": "string",
|
||
"content": "string",
|
||
"period": "string",
|
||
"user_role": "string",
|
||
"status": "string",
|
||
"generated_by": "string",
|
||
"generated_at": "string",
|
||
"expires_at": "string",
|
||
"created_at": "string",
|
||
"updated_at": "string"
|
||
}
|
||
```
|
||
|
||
### 统计仪表板 (StatisticsDashboard)
|
||
```json
|
||
{
|
||
"id": "string",
|
||
"name": "string",
|
||
"description": "string",
|
||
"user_role": "string",
|
||
"is_default": "boolean",
|
||
"is_active": "boolean",
|
||
"layout": "string",
|
||
"widgets": "string",
|
||
"settings": "string",
|
||
"refresh_interval": "number",
|
||
"created_by": "string",
|
||
"access_level": "string",
|
||
"created_at": "string",
|
||
"updated_at": "string"
|
||
}
|
||
```
|
||
|
||
## 使用示例
|
||
|
||
### 获取今日API调用统计
|
||
```bash
|
||
curl -X GET "https://api.example.com/api/v1/statistics/realtime?metric_type=api_calls&time_range=last_hour" \
|
||
-H "Authorization: Bearer your-jwt-token"
|
||
```
|
||
|
||
### 获取历史用户数据
|
||
```bash
|
||
curl -X GET "https://api.example.com/api/v1/statistics/historical?metric_type=users&start_date=2024-01-01&end_date=2024-01-31" \
|
||
-H "Authorization: Bearer your-jwt-token"
|
||
```
|
||
|
||
### 生成月度报告
|
||
```bash
|
||
curl -X POST "https://api.example.com/api/v1/statistics/reports" \
|
||
-H "Authorization: Bearer your-jwt-token" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"report_type": "summary",
|
||
"title": "月度汇总报告",
|
||
"period": "month",
|
||
"user_role": "admin",
|
||
"generated_by": "admin_id"
|
||
}'
|
||
```
|
||
|
||
## 注意事项
|
||
|
||
1. **日期格式**: 所有日期参数都使用 `YYYY-MM-DD` 格式
|
||
2. **时间戳**: 所有时间戳都使用 ISO 8601 格式
|
||
3. **分页**: 默认每页20条记录，最大1000条
|
||
4. **限流**: API有请求频率限制，超出限制会返回429错误
|
||
5. **缓存**: 部分接口支持缓存，响应头会包含缓存信息
|
||
6. **权限**: 不同接口需要不同的权限级别，请确保有相应权限
|
||
7. **数据量**: 查询大量数据时建议使用分页和日期范围限制
|
||
|