# 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. 测试错误处理和降级展示