tyapi-server/docs/api/statistics/api_documentation.md

# 统计功能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. **数据量**: 查询大量数据时建议使用分页和日期范围限制