team/tyapi-server

Fork 0

Files

liangzai e05ad9e223 new

2025-09-12 01:15:09 +08:00

14 KiB

Raw Permalink Blame History

统计功能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
权限: 管理员
描述: 创建新的统计指标

请求体:

{
  "metric_type": "api_calls",
  "metric_name": "total_count",
  "dimension": "realtime",
  "value": 100.0,
  "metadata": "{\"source\": \"api_gateway\"}",
  "date": "2024-01-01T00:00:00Z"
}

响应:

{
  "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
权限: 管理员
描述: 更新现有统计指标的值

请求体:

{
  "id": "uuid",
  "value": 150.0
}

1.3 删除统计指标

URL: DELETE /api/v1/statistics/metrics
权限: 管理员
描述: 删除指定的统计指标

请求体:

{
  "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): 统计维度

响应:

{
  "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): 分组维度

响应:

{
  "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
权限: 管理员
描述: 创建新的统计仪表板

请求体:

{
  "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): 统计维度列表

响应:

{
  "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
权限: 管理员
描述: 生成指定类型的统计报告

请求体:

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

响应:

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

响应:

{
  "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
权限: 管理员
描述: 导出指定格式的统计数据

请求体:

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

响应:

{
  "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	服务器内部错误

响应格式

成功响应

{
  "success": true,
  "message": "操作成功",
  "data": {
    // 响应数据
  }
}

错误响应

{
  "success": false,
  "message": "错误描述",
  "error": "详细错误信息"
}

列表响应

{
  "success": true,
  "message": "查询成功",
  "data": [
    // 数据列表
  ],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total": 100,
    "pages": 5,
    "has_next": true,
    "has_prev": false
  }
}

数据模型

统计指标 (StatisticsMetric)

{
  "id": "string",
  "metric_type": "string",
  "metric_name": "string",
  "dimension": "string",
  "value": "number",
  "metadata": "string",
  "date": "string",
  "created_at": "string",
  "updated_at": "string"
}

统计报告 (StatisticsReport)

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

{
  "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调用统计

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"

获取历史用户数据

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"

生成月度报告

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"
  }'

注意事项

日期格式: 所有日期参数都使用 YYYY-MM-DD 格式
时间戳: 所有时间戳都使用 ISO 8601 格式
分页: 默认每页20条记录，最大1000条
限流: API有请求频率限制，超出限制会返回429错误
缓存: 部分接口支持缓存，响应头会包含缓存信息
权限: 不同接口需要不同的权限级别，请确保有相应权限
数据量: 查询大量数据时建议使用分页和日期范围限制

14 KiB Raw Permalink Blame History Unescape Escape

统计功能API文档

概述

基础信息

认证和权限

认证方式

权限级别

API接口

1. 指标管理

1.1 创建统计指标

1.2 更新统计指标

1.3 删除统计指标

1.4 获取单个指标

1.5 获取指标列表

2. 实时统计

2.1 获取实时指标

3. 历史统计

3.1 获取历史指标

4. 仪表板管理

4.1 创建仪表板

4.2 获取仪表板列表

4.3 获取单个仪表板

4.4 获取仪表板数据

5. 报告管理

5.1 生成报告

5.2 获取报告列表

5.3 获取单个报告

6. 统计分析

6.1 计算增长率

6.2 计算趋势

7. 数据导出

7.1 导出数据

8. 定时任务管理

8.1 手动触发小时聚合

8.2 手动触发日聚合

8.3 手动触发数据清理

错误码

响应格式

成功响应

错误响应

列表响应

数据模型

统计指标 (StatisticsMetric)

统计报告 (StatisticsReport)

统计仪表板 (StatisticsDashboard)

使用示例

获取今日API调用统计

获取历史用户数据

生成月度报告

注意事项

14 KiB

Raw Permalink Blame History