7.4 KiB
7.4 KiB
Design Document: 仪表盘数据概览卡片
Overview
本设计文档描述仪表盘数据概览卡片模块的技术实现方案。该模块是后台管理系统的首页核心组件，展示关键业务统计数据。
后端API已完成实现（DashboardController.GetOverview），本次迁移主要是前端页面的开发和集成。
Architecture
┌─────────────────────────────────────────────────────────────┐
│ Dashboard Page │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ Overview Cards Section │ │
│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐│ │
│ │ │ 今日注册 │ │ 今日消费 │ │ 当日消费 │ │ 总消费 ││ │
│ │ │ 用户数 │ │ 用户数 │ │ 总金额 │ │ 金额 ││ │
│ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘│ │
│ └─────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ API Layer │
│ src/api/business/dashboard.ts │
│ - getDashboardOverview(): Promise<DashboardOverview> │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Backend API │
│ GET /api/admin/business/dashboard │
│ Response: DashboardOverviewResponse │
└─────────────────────────────────────────────────────────────┘
Components and Interfaces
1. 前端API模块
文件: src/api/business/dashboard.ts
// 仪表盘概览响应接口
export interface DashboardOverview {
todayRegistrations: number; // 今日注册用户数
todayConsumption: number; // 今日消费金额
todayNewConsumers: number; // 今日消费用户数
totalAdRevenue: number; // 总广告收入
totalUsers: number; // 总用户数
totalOrders: number; // 总订单数
totalConsumption: number; // 总消费金额
}
// 获取仪表盘概览数据
export function getDashboardOverview(): Promise<DashboardOverview>;
2. 仪表盘页面组件
文件: src/views/dashboard/index.vue
组件结构:
- 数据概览卡片区域（4个卡片）
- 欢迎信息区域（保留现有）
- 系统信息区域（保留现有）
- 快捷操作区域（保留现有）
3. 数据概览卡片配置
// 卡片配置接口
interface OverviewCardConfig {
key: string; // 数据字段名
label: string; // 显示标签
icon: Component; // 图标组件
gradient: string; // 渐变背景色
isCurrency: boolean; // 是否为金额类型
}
// 卡片配置列表
const cardConfigs: OverviewCardConfig[] = [
{
key: 'todayRegistrations',
label: '今日注册用户',
icon: UserFilled,
gradient: 'linear-gradient(-125deg, #57bdbf, #2f9de2)',
isCurrency: false
},
{
key: 'todayNewConsumers',
label: '今日消费用户',
icon: ShoppingCart,
gradient: 'linear-gradient(-125deg, #e91dab, #ffd026)',
isCurrency: false
},
{
key: 'todayConsumption',
label: '当日消费总金额',
icon: Money,
gradient: 'linear-gradient(-125deg, #ff7d7d, #fb2c95)',
isCurrency: true
},
{
key: 'totalConsumption',
label: '总消费金额',
icon: Wallet,
gradient: 'linear-gradient(-125deg, #999, #999)',
isCurrency: true
}
];
Data Models
后端响应模型（已存在）
public class DashboardOverviewResponse
{
public int TodayRegistrations { get; set; }
public decimal TodayConsumption { get; set; }
public int TodayNewConsumers { get; set; }
public decimal TotalAdRevenue { get; set; }
public int TotalUsers { get; set; }
public int TotalOrders { get; set; }
public decimal TotalConsumption { get; set; }
}
前端数据模型
// 仪表盘状态
interface DashboardState {
loading: boolean;
error: string | null;
overview: DashboardOverview | null;
}
Correctness Properties
A property is a characteristic or behavior that should hold true across all valid executions of a system-essentially, a formal statement about what the system should do. Properties serve as the bridge between human-readable specifications and machine-verifiable correctness guarantees.
Property 1: 卡片结构完整性
For any 数据概览卡片，该卡片 SHALL 包含图标、数值和标签三个必要元素。
Validates: Requirements 2.2
Property 2: 金额格式化正确性
For any 金额类型的数值，格式化后的字符串 SHALL 包含货币符号且数值部分与原始数值相等。
Validates: Requirements 2.4
Property 3: API响应数据展示一致性
For any 有效的API响应数据，所有统计字段 SHALL 被正确映射到对应的卡片并展示。
Validates: Requirements 3.2
Error Handling
API请求错误
- 网络错误: 显示"网络连接失败，请检查网络"提示
- 服务器错误(5xx): 显示"服务器繁忙，请稍后重试"提示
- 权限错误(403): 显示"无权限访问此页面"提示
- 其他错误: 显示通用错误提示
数据展示降级
当API请求失败时，所有统计数值显示为默认值0，确保页面正常渲染。
Testing Strategy
单元测试
-
API模块测试
- 测试API端点配置正确性
- 测试响应数据类型转换
-
格式化函数测试
- 测试金额格式化函数
- 测试边界值（0、负数、大数值）
属性测试
使用 Vitest 进行属性测试：
- Property 1: 验证卡片配置完整性
- Property 2: 验证金额格式化正确性
- Property 3: 验证数据映射一致性
集成测试
- 测试页面加载时API调用
- 测试错误处理和降级展示