new

2025-09-12 01:15:09 +08:00
parent c563b2266b
commit e05ad9e223
103 changed files with 20034 additions and 1041 deletions
--- a/docs/api/statistics/api_documentation.md
+++ b/docs/api/statistics/api_documentation.md
@@ -0,0 +1,603 @@
+# 统计功能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. **数据量**: 查询大量数据时建议使用分页和日期范围限制
+