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实时更新

核心数据结构

前端期望的数据格式

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小时缓存

数据库优化

• 添加必要索引
• 使用聚合查询
• 考虑分表策略

查询优化

-- 建议的索引
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);

权限配置

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

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

API测试用例

测试接口连通性

# 获取完整仪表盘数据
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数据

// 原来的mock调用
const dashboardData = ref<DashboardData>(generateMockDashboardData())

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

2. 错误处理

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

3. 数据刷新

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

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

部署检查清单

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

---

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