coder-common-thin-frontend/doc/dashborad/仪表盘接口实现清单.md

# 仪表盘接口实现清单

## 需要实现的接口总览

后端需要实现以下3个核心接口来支持前端仪表盘功能：

### 1. 获取仪表盘统计数据
- **接口**: `GET /coder/dashboard/getStatistics`
- **权限**: `dashboard:view`
- **功能**: 获取用户、登录、存储、活跃度等核心统计数据

### 2. 获取登录趋势数据
- **接口**: `GET /coder/dashboard/getLoginTrend`
- **权限**: `dashboard:view`
- **功能**: 获取最近N天的登录趋势图表数据

### 3. 获取完整仪表盘数据（推荐）
- **接口**: `GET /coder/dashboard/getAllData`
- **权限**: `dashboard:view`
- **功能**: 一次性获取所有仪表盘数据，减少前端请求次数

## 实现优先级

### 🔴 高优先级（必须实现）
1. **getAllData接口** - 前端仪表盘主要依赖此接口
2. **用户统计数据** - 核心统计卡片必需
3. **登录趋势数据** - 登录趋势图表必需

### 🟡 中优先级（建议实现）
4. **存储统计数据** - 存储相关统计卡片
5. **今日活跃统计** - 活跃度统计卡片

### 🟢 低优先级（可选实现）
6. **单独的统计接口** - 可根据需要拆分实现
7. **高级缓存策略** - 性能优化
8. **实时数据推送** - WebSocket实时更新

## 核心数据结构

### 前端期望的数据格式
```typescript
interface DashboardData {
  userStats: {
    totalUsers: number        // 总用户数
    todayNewUsers: number     // 今日新增
    activeUsers: number       // 活跃用户
    onlineUsers: number       // 在线用户
  }
  loginStats: {
    todayLogins: number       // 今日登录
    totalLogins: number       // 累计登录
    loginTrend: Array<{       // 登录趋势
      date: string            // 日期
      count: number           // 登录次数
      label: string           // 显示标签
    }>
  }
  storageStats: {
    totalFiles: number        // 总文件数
    totalImages: number       // 总图片数
    totalSize: string         // 总大小
    todayUploads: number      // 今日上传
    storageUsage: number      // 使用率%
    availableSpace: string    // 可用空间
  }
  dailyActivityStats: {
    todayVisits: number       // 今日访问
    todayOperations: number   // 今日操作
    activeUsers: number       // 活跃用户
    newContent: number        // 新增内容
    apiCalls: number          // API调用
    avgResponseTime: number   // 平均响应时间
  }
  systemStatus?: {
    diskUsage: number         // 磁盘使用率%
    memoryUsage: number       // 内存使用率%
    cpuUsage: number          // CPU使用率%
    systemHealth: string      // 系统健康状态
    uptime: string            // 运行时间
    lastBackup: string        // 最后备份时间
  }
}
```

## 数据来源映射

### 用户统计 (userStats)
- `totalUsers`: `SELECT COUNT(*) FROM sys_login_user`
- `todayNewUsers`: `SELECT COUNT(*) FROM sys_login_user WHERE DATE(create_time) = CURDATE()`
- `activeUsers`: `SELECT COUNT(DISTINCT user_id) FROM sys_login_log WHERE login_time >= DATE_SUB(NOW(), INTERVAL 30 DAY)`
- `onlineUsers`: 通过Sa-Token获取当前在线会话数

### 登录统计 (loginStats)
- `todayLogins`: `SELECT COUNT(*) FROM sys_login_log WHERE DATE(login_time) = CURDATE() AND status = 'success'`
- `totalLogins`: `SELECT COUNT(*) FROM sys_login_log WHERE status = 'success'`
- `loginTrend`: `SELECT DATE(login_time) as date, COUNT(*) as count FROM sys_login_log WHERE login_time >= DATE_SUB(NOW(), INTERVAL 7 DAY) GROUP BY DATE(login_time)`

### 存储统计 (storageStats)
- `totalFiles`: `SELECT COUNT(*) FROM sys_file`
- `totalImages`: `SELECT COUNT(*) FROM sys_picture`
- `totalSize`: `SELECT SUM(file_size) FROM sys_file` (转换为GB/MB格式)
- `todayUploads`: `SELECT COUNT(*) FROM sys_file WHERE DATE(create_time) = CURDATE()`
- `storageUsage`: 计算已用空间百分比
- `availableSpace`: 计算剩余可用空间

### 今日活跃统计 (dailyActivityStats)
- `todayVisits`: `SELECT COUNT(*) FROM sys_oper_log WHERE DATE(oper_time) = CURDATE()`
- `todayOperations`: `SELECT COUNT(*) FROM sys_oper_log WHERE DATE(oper_time) = CURDATE() AND business_type != 'SELECT'`
- `activeUsers`: 与用户统计中的activeUsers相同
- `newContent`: 今日新增的内容数量（文件、图片等）
- `apiCalls`: `SELECT COUNT(*) FROM sys_oper_log WHERE DATE(oper_time) = CURDATE()`
- `avgResponseTime`: `SELECT AVG(cost_time) FROM sys_oper_log WHERE DATE(oper_time) = CURDATE()`



## 建议的实现步骤

### 第一阶段：基础统计功能
1. ✅ 创建 `DashboardController`
2. ✅ 创建 `DashboardService`
3. ✅ 实现用户统计查询
4. ✅ 实现登录统计查询
5. ✅ 实现 `getAllData` 接口
6. ✅ 前端集成测试

### 第二阶段：扩展功能
1. ✅ 实现存储统计查询
2. ✅ 实现活跃度统计查询
3. ✅ 实现登录趋势图表数据
4. ✅ 添加缓存支持

### 第三阶段：性能优化
1. ✅ 添加Redis缓存支持
2. ✅ 优化数据库查询
3. ✅ 实现定时统计任务
4. ✅ 添加监控日志

## 性能优化建议

### 缓存策略
- 统计数据：5分钟缓存
- 趋势数据：1小时缓存

### 数据库优化
- 添加必要索引
- 使用聚合查询
- 考虑分表策略

### 查询优化
```sql
-- 建议的索引
CREATE INDEX idx_user_create_time ON sys_login_user(create_time);
CREATE INDEX idx_login_log_time_status ON sys_login_log(login_time, status);
CREATE INDEX idx_oper_log_time ON sys_oper_log(oper_time);
CREATE INDEX idx_file_create_time ON sys_file(create_time);
```

## 权限配置

需要在权限系统中添加以下权限：

```sql
-- 权限数据插入
INSERT INTO sys_menu (menu_name, perms, menu_type) VALUES 
('仪表盘查看', 'dashboard:view', 'F');
```

## API测试用例

### 测试接口连通性
```bash
# 获取完整仪表盘数据
curl -X GET \
  "http://localhost:18099/coder/dashboard/getAllData" \
  -H "Authorization: your-token-value"

# 获取登录趋势
curl -X GET \
  "http://localhost:18099/coder/dashboard/getLoginTrend?days=7" \
  -H "Authorization: your-token-value"
```

### 验证数据格式
确保返回的JSON格式与前端类型定义完全匹配。

## 前端集成要点

### 1. 替换Mock数据
```typescript
// 原来的mock调用
const dashboardData = ref<DashboardData>(generateMockDashboardData())

// 替换为API调用
const loadDashboardData = async () => {
  const { data } = await getAllDashboardData()
  dashboardData.value = data
}
```

### 2. 错误处理
```typescript
try {
  const { data } = await getAllDashboardData()
  dashboardData.value = data
} catch (error) {
  coiMsgError('获取仪表盘数据失败')
  // 可选：降级到mock数据
}
```

### 3. 数据刷新
```typescript
// 手动刷新
const refreshData = async () => {
  await loadDashboardData()
  coiMsgSuccess('数据已刷新')
}

// 自动刷新（可选）
setInterval(loadDashboardData, 5 * 60 * 1000) // 每5分钟刷新
```

## 部署检查清单

- [ ] 后端接口实现完成
- [ ] 权限配置正确
- [ ] 数据库索引已创建
- [ ] 缓存配置已启用
- [ ] 前端API集成完成
- [ ] 接口联调测试通过
- [ ] 性能测试通过
- [ ] 权限测试通过

---

**总结**: 实现这3个接口即可完全支持前端仪表盘功能，其中`getAllData`接口是核心，建议优先实现。