# 仪表盘接口设计文档

## 概述

仪表盘模块提供系统核心数据的统计展示功能，包括用户统计、登录统计、存储统计、活跃度统计等信息的实时展示。

## 前端数据需求分析

基于前端仪表盘页面代码分析，仪表盘需要以下数据：

### 1. 核心统计卡片数据
- **用户统计**: 总用户数、今日新增用户、活跃用户数、在线用户数
- **登录统计**: 今日登录次数、累计登录次数
- **存储统计**: 总文件数、总图片数、总存储大小、今日上传数
- **今日活跃**: 今日访问量、今日操作数、活跃用户数、新增内容数

### 2. 登录趋势图表数据
- 最近7天的登录趋势数据
- 每日登录次数统计
- 趋势分析数据

## 权限说明

仪表盘接口需要相应的权限才能访问：

| 操作 | 权限码 | 说明 |
|------|--------|------|
| 查看仪表盘统计 | `dashboard:view` | 查看仪表盘统计数据权限 |

## 接口设计

### 1. 获取仪表盘统计数据

**接口地址**: `GET /coder/dashboard/getStatistics`

**接口描述**: 获取仪表盘核心统计数据

**是否需要认证**: 是

**权限要求**: `dashboard:view`

**请求头**:
```
Authorization: your-token-value
```

**请求参数**: 无

**响应示例**:

```json
{
  "status": 200,
  "msg": "SUCCESS",
  "data": {
    "userStats": {
      "totalUsers": 1286,
      "todayNewUsers": 23,
      "activeUsers": 856,
      "onlineUsers": 142
    },
    "loginStats": {
      "todayLogins": 468,
      "totalLogins": 45672
    },
    "storageStats": {
      "totalFiles": 8924,
      "totalImages": 3420,
      "totalSize": "2.3 GB",
      "todayUploads": 67,
      "storageUsage": 67.5,
      "availableSpace": "1.2 GB"
    },
    "dailyActivityStats": {
      "todayVisits": 1247,
      "todayOperations": 856,
      "activeUsers": 142,
      "newContent": 23,
      "apiCalls": 3420,
      "avgResponseTime": 235
    }
  },
  "traceId": "trace-123456"
}
```

**数据结构说明**:

#### UserStats 用户统计
| 字段名 | 类型 | 说明 |
|--------|------|------|
| totalUsers | Integer | 总用户数 |
| todayNewUsers | Integer | 今日新增用户数 |
| activeUsers | Integer | 活跃用户数 |
| onlineUsers | Integer | 当前在线用户数 |

#### LoginStats 登录统计
| 字段名 | 类型 | 说明 |
|--------|------|------|
| todayLogins | Integer | 今日登录次数 |
| totalLogins | Integer | 累计登录次数 |

#### StorageStats 存储统计
| 字段名 | 类型 | 说明 |
|--------|------|------|
| totalFiles | Integer | 总文件数 |
| totalImages | Integer | 总图片数 |
| totalSize | String | 总存储大小（格式化） |
| todayUploads | Integer | 今日上传文件数 |
| storageUsage | Double | 存储使用率（百分比） |
| availableSpace | String | 可用空间（格式化） |

#### DailyActivityStats 今日活跃统计
| 字段名 | 类型 | 说明 |
|--------|------|------|
| todayVisits | Integer | 今日访问量 |
| todayOperations | Integer | 今日操作数 |
| activeUsers | Integer | 活跃用户数 |
| newContent | Integer | 新增内容数 |
| apiCalls | Integer | API调用次数 |
| avgResponseTime | Integer | 平均响应时间（毫秒） |

**调用示例**:

```bash
curl -X GET \
  http://localhost:18099/coder/dashboard/getStatistics \
  -H "Authorization: your-token-value"
```

---

### 2. 获取登录趋势数据

**接口地址**: `GET /coder/dashboard/getLoginTrend`

**接口描述**: 获取最近7天的登录趋势数据

**是否需要认证**: 是

**权限要求**: `dashboard:view`

**请求参数**:

| 参数名 | 类型 | 必填 | 说明 | 默认值 |
|--------|------|------|------|--------|
| days | Integer | 否 | 查询天数 | 7 |

**响应示例**:

```json
{
  "status": 200,
  "msg": "SUCCESS",
  "data": {
    "loginTrend": [
      {
        "date": "2024-01-15",
        "count": 324,
        "label": "1月15日"
      },
      {
        "date": "2024-01-16",
        "count": 298,
        "label": "1月16日"
      },
      {
        "date": "2024-01-17",
        "count": 412,
        "label": "1月17日"
      },
      {
        "date": "2024-01-18",
        "count": 356,
        "label": "1月18日"
      },
      {
        "date": "2024-01-19",
        "count": 287,
        "label": "1月19日"
      },
      {
        "date": "2024-01-20",
        "count": 198,
        "label": "1月20日"
      },
      {
        "date": "2024-01-21",
        "count": 468,
        "label": "1月21日"
      }
    ]
  },
  "traceId": "trace-123456"
}
```

**数据结构说明**:

#### LoginTrendItem 登录趋势项
| 字段名 | 类型 | 说明 |
|--------|------|------|
| date | String | 日期（YYYY-MM-DD格式） |
| count | Integer | 当日登录次数 |
| label | String | 显示标签（用于图表展示） |

**调用示例**:

```bash
curl -X GET \
  "http://localhost:18099/coder/dashboard/getLoginTrend?days=7" \
  -H "Authorization: your-token-value"
```

---

### 3. 获取完整仪表盘数据

**接口地址**: `GET /coder/dashboard/getAllData`

**接口描述**: 一次性获取仪表盘所有数据（聚合接口）

**是否需要认证**: 是

**权限要求**: `dashboard:view`

**请求参数**:

| 参数名 | 类型 | 必填 | 说明 | 默认值 |
|--------|------|------|------|--------|
| includeTrend | Boolean | 否 | 是否包含趋势数据 | true |
| trendDays | Integer | 否 | 趋势数据天数 | 7 |

**响应示例**:

```json
{
  "status": 200,
  "msg": "SUCCESS",
  "data": {
    "userStats": {
      "totalUsers": 1286,
      "todayNewUsers": 23,
      "activeUsers": 856,
      "onlineUsers": 142
    },
    "loginStats": {
      "todayLogins": 468,
      "totalLogins": 45672,
      "loginTrend": [
        {
          "date": "2024-01-15",
          "count": 324,
          "label": "1月15日"
        }
      ]
    },
    "storageStats": {
      "totalFiles": 8924,
      "totalImages": 3420,
      "totalSize": "2.3 GB",
      "todayUploads": 67,
      "storageUsage": 67.5,
      "availableSpace": "1.2 GB"
    },
    "dailyActivityStats": {
      "todayVisits": 1247,
      "todayOperations": 856,
      "activeUsers": 142,
      "newContent": 23,
      "apiCalls": 3420,
      "avgResponseTime": 235
    }
  },
  "traceId": "trace-123456"
}
```

**调用示例**:

```bash
curl -X GET \
  "http://localhost:18099/coder/dashboard/getAllData?includeTrend=true&trendDays=7" \
  -H "Authorization: your-token-value"
```

---

## 数据来源分析

### 用户统计数据来源
- **总用户数**: 查询 `sys_login_user` 表总记录数
- **今日新增用户**: 查询 `sys_login_user` 表当日创建的记录数
- **活跃用户数**: 查询最近30天有登录记录的用户数
- **在线用户数**: 查询当前有效会话的用户数（通过Sa-Token获取）

### 登录统计数据来源
- **今日登录次数**: 查询 `sys_login_log` 表当日成功登录记录数
- **累计登录次数**: 查询 `sys_login_log` 表总成功登录记录数
- **登录趋势**: 查询 `sys_login_log` 表按日期分组的登录统计

### 存储统计数据来源
- **总文件数**: 查询 `sys_file` 表总记录数
- **总图片数**: 查询 `sys_picture` 表总记录数
- **存储大小**: 查询 `sys_file` 表文件大小字段求和
- **今日上传数**: 查询 `sys_file` 表当日上传的文件数

### 今日活跃统计数据来源
- **今日访问量**: 查询 `sys_oper_log` 表当日访问记录数
- **今日操作数**: 查询 `sys_oper_log` 表当日操作记录数
- **API调用次数**: 查询 `sys_oper_log` 表API调用统计
- **平均响应时间**: 查询 `sys_oper_log` 表响应时间字段平均值

---

## 建议的数据库查询优化

### 1. 索引优化
```sql
-- 用户表索引
CREATE INDEX idx_user_create_time ON sys_login_user(create_time);
CREATE INDEX idx_user_status ON sys_login_user(user_status);

-- 登录日志索引
CREATE INDEX idx_login_log_date ON sys_login_log(login_time);
CREATE INDEX idx_login_log_status ON sys_login_log(status);

-- 操作日志索引
CREATE INDEX idx_oper_log_date ON sys_oper_log(oper_time);
CREATE INDEX idx_oper_log_type ON sys_oper_log(business_type);

-- 文件表索引
CREATE INDEX idx_file_create_time ON sys_file(create_time);
CREATE INDEX idx_file_size ON sys_file(file_size);
```

### 2. 缓存策略
- **统计数据缓存**: 使用Redis缓存统计结果，每5分钟更新一次
- **趋势数据缓存**: 登录趋势数据每小时更新一次

### 3. 查询优化
- 使用聚合查询减少数据库访问次数
- 对于大表查询，考虑分表或定时统计
- 使用合适的时间范围避免全表扫描

---

## 错误码说明

| 错误码 | 错误信息 | 说明 |
|--------|----------|------|
| 400 | 参数错误 | 请求参数格式不正确 |
| 401 | 当前会话未登录 | 未登录或Token无效 |
| 403 | 权限不足 | 没有查看仪表盘的权限 |
| 500 | 统计数据获取失败 | 服务器内部错误 |

---

## 实现建议

### 1. Controller 层实现
```java
@RestController
@RequestMapping("/coder/dashboard")
@Tag(name = "仪表盘管理", description = "仪表盘统计数据接口")
public class DashboardController {
    
    @GetMapping("/getStatistics")
    @Operation(summary = "获取仪表盘统计数据")
    @SaCheckPermission("dashboard:view")
    public R<DashboardStatistics> getStatistics() {
        // 实现统计数据获取逻辑
    }
    
    @GetMapping("/getLoginTrend")
    @Operation(summary = "获取登录趋势数据")
    @SaCheckPermission("dashboard:view")
    public R<LoginTrendData> getLoginTrend(@RequestParam(defaultValue = "7") Integer days) {
        // 实现登录趋势数据获取逻辑
    }
    
    
    @GetMapping("/getAllData")
    @Operation(summary = "获取完整仪表盘数据")
    @SaCheckPermission("dashboard:view")
    public R<CompleteDashboardData> getAllData(
        @RequestParam(defaultValue = "true") Boolean includeTrend,
        @RequestParam(defaultValue = "7") Integer trendDays
    ) {
        // 实现完整数据获取逻辑
    }
}
```

### 2. Service 层实现建议
- `DashboardService`: 主要业务逻辑
- `DashboardStatisticsService`: 统计数据计算
- `CacheService`: 缓存管理

### 3. 数据传输对象 (DTO)
- `DashboardStatisticsVo`: 统计数据响应对象
- `LoginTrendVo`: 登录趋势响应对象
- `CompleteDashboardVo`: 完整仪表盘数据响应对象

### 4. 缓存键定义
```java
public class DashboardCacheConstants {
    public static final String DASHBOARD_STATISTICS = "dashboard:statistics";
    public static final String LOGIN_TREND = "dashboard:login_trend:";
    public static final String USER_ONLINE_COUNT = "dashboard:online_users";
}
```

---

## 前端集成指南

### 1. API客户端配置
在前端项目中创建仪表盘API模块：

```typescript
// src/service/api/dashboard/index.ts
import { request } from '../../http'
import type { DashboardData, LoginTrendData } from './types'

// 获取仪表盘统计数据
export function getDashboardStatistics() {
  return request.Get<Service.ResponseResult<DashboardData>>('/coder/dashboard/getStatistics')
}

// 获取登录趋势数据
export function getLoginTrend(days: number = 7) {
  return request.Get<Service.ResponseResult<LoginTrendData>>(`/coder/dashboard/getLoginTrend?days=${days}`)
}

// 获取完整仪表盘数据
export function getAllDashboardData(params?: {
  includeTrend?: boolean
  trendDays?: number
}) {
  return request.Get<Service.ResponseResult<DashboardData>>('/coder/dashboard/getAllData', { params })
}
```

### 2. 类型定义
```typescript
// src/service/api/dashboard/types.ts
export interface UserStats {
  totalUsers: number
  todayNewUsers: number
  activeUsers: number
  onlineUsers: number
}

export interface LoginStats {
  todayLogins: number
  totalLogins: number
  loginTrend?: Array<{
    date: string
    count: number
    label: string
  }>
}

export interface StorageStats {
  totalFiles: number
  totalImages: number
  totalSize: string
  todayUploads: number
  storageUsage: number
  availableSpace: string
}

export interface DailyActivityStats {
  todayVisits: number
  todayOperations: number
  activeUsers: number
  newContent: number
  apiCalls: number
  avgResponseTime: number
}

export interface DashboardData {
  userStats: UserStats
  loginStats: LoginStats
  storageStats: StorageStats
  dailyActivityStats: DailyActivityStats
}
```

### 3. 前端页面集成
更新现有的仪表盘页面以使用真实API：

```typescript
// src/views/dashboard/monitor/index.vue
import { getAllDashboardData } from '@/service/api/dashboard'

// 替换mockData的使用
const loadDashboardData = async () => {
  try {
    const { data } = await getAllDashboardData({
      includeTrend: true,
      trendDays: 7
    })
    dashboardData.value = data
  } catch (error) {
    console.error('获取仪表盘数据失败:', error)
    coiMsgError('获取仪表盘数据失败')
  }
}
```

---

## 注意事项

1. **性能考虑**: 统计查询可能较耗时，建议使用缓存和异步更新
2. **权限控制**: 不同角色可能需要查看不同的统计维度
3. **数据准确性**: 实时数据和缓存数据的平衡
4. **扩展性**: 预留接口扩展空间，支持更多统计维度
5. **数据安全**: 敏感统计数据的访问控制
6. **并发处理**: 大量用户同时访问仪表盘的性能优化
7. **定时任务**: 考虑使用定时任务预计算统计数据

---

## 更新日志

- **v1.0.0** (2025-01-23): 初始版本，定义仪表盘核心接口