203 lines
7.4 KiB
Markdown
203 lines
7.4 KiB
Markdown
# 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`
|
||
|
||
```typescript
|
||
// 仪表盘概览响应接口
|
||
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. 数据概览卡片配置
|
||
|
||
```typescript
|
||
// 卡片配置接口
|
||
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
|
||
|
||
### 后端响应模型（已存在）
|
||
|
||
```csharp
|
||
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; }
|
||
}
|
||
```
|
||
|
||
### 前端数据模型
|
||
|
||
```typescript
|
||
// 仪表盘状态
|
||
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请求错误
|
||
|
||
1. **网络错误**: 显示"网络连接失败，请检查网络"提示
|
||
2. **服务器错误(5xx)**: 显示"服务器繁忙，请稍后重试"提示
|
||
3. **权限错误(403)**: 显示"无权限访问此页面"提示
|
||
4. **其他错误**: 显示通用错误提示
|
||
|
||
### 数据展示降级
|
||
|
||
当API请求失败时，所有统计数值显示为默认值0，确保页面正常渲染。
|
||
|
||
## Testing Strategy
|
||
|
||
### 单元测试
|
||
|
||
1. **API模块测试**
|
||
- 测试API端点配置正确性
|
||
- 测试响应数据类型转换
|
||
|
||
2. **格式化函数测试**
|
||
- 测试金额格式化函数
|
||
- 测试边界值（0、负数、大数值）
|
||
|
||
### 属性测试
|
||
|
||
使用 Vitest 进行属性测试：
|
||
|
||
1. **Property 1**: 验证卡片配置完整性
|
||
2. **Property 2**: 验证金额格式化正确性
|
||
3. **Property 3**: 验证数据映射一致性
|
||
|
||
### 集成测试
|
||
|
||
1. 测试页面加载时API调用
|
||
2. 测试错误处理和降级展示
|
||
|