310 lines
15 KiB
Markdown
310 lines
15 KiB
Markdown
# Design Document: 仪表盘数据看板
|
||
|
||
## Overview
|
||
|
||
本设计文档描述仪表盘数据看板模块的技术实现方案。该模块是后台管理系统的核心运营分析页面，包含4个主要卡片区域：今日订单、今日货币信息、今日收入汇总、用户数据统计。
|
||
|
||
需要验证后端API是否已完成，如未完成需要新增对应的接口。
|
||
|
||
## Architecture
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────────────────┐
|
||
│ Data Stand Page (数据看板) │
|
||
│ ┌─────────────────────────────┐ ┌─────────────────────────────┐ │
|
||
│ │ Today Order Card │ │ Currency Info Card │ │
|
||
│ │ (今日订单卡片) │ │ (今日货币信息卡片) │ │
|
||
│ │ - 发起订单数 │ │ - 今日/昨日发放钻石 │ │
|
||
│ │ - 支付订单数 │ │ - 今日/昨日消费钻石 │ │
|
||
│ │ - 消费人数 │ │ - 今日/昨日发放UU币 │ │
|
||
│ │ - 订单总金额 │ │ - 今日/昨日消费UU币 │ │
|
||
│ │ - 出货总金额 │ │ - 今日/昨日发放达达券 │ │
|
||
│ │ - 各支付方式金额 │ │ - 今日/昨日消费达达券 │ │
|
||
│ └─────────────────────────────┘ └─────────────────────────────┘ │
|
||
│ ┌─────────────────────────────┐ ┌─────────────────────────────┐ │
|
||
│ │ Income Summary Card │ │ User Stats Card │ │
|
||
│ │ (今日收入汇总卡片) │ │ (用户数据统计卡片) │ │
|
||
│ │ - 订单收入 │ │ - 绑定手机号人数 │ │
|
||
│ │ - RMB收入 │ │ - 抽奖人数 │ │
|
||
│ │ - 钻石商城收入 │ │ - 用户剩余货币 │ │
|
||
│ │ - 其他收入 │ │ - 微信支付金额 │ │
|
||
│ │ - 支出/发货金额 │ │ - 订单支付数量 │ │
|
||
│ │ - 利润 │ │ - 出货/发货金额 │ │
|
||
│ └─────────────────────────────┘ └─────────────────────────────┘ │
|
||
└─────────────────────────────────────────────────────────────────────────────┘
|
||
│
|
||
▼
|
||
┌─────────────────────────────────────────────────────────────────────────────┐
|
||
│ API Layer │
|
||
│ src/api/business/statistics.ts │
|
||
│ - getTodayOrderStats(): Promise<TodayOrderStats> │
|
||
│ - getCurrencyInfoStats(): Promise<CurrencyInfoStats> │
|
||
│ - getIncomeSummaryStats(): Promise<IncomeSummaryStats> │
|
||
│ - getUserStats(): Promise<UserStats> │
|
||
└─────────────────────────────────────────────────────────────────────────────┘
|
||
│
|
||
▼
|
||
┌─────────────────────────────────────────────────────────────────────────────┐
|
||
│ Backend API │
|
||
│ GET /api/admin/business/statistics/today-order │
|
||
│ GET /api/admin/business/statistics/currency-info │
|
||
│ GET /api/admin/business/statistics/income-summary │
|
||
│ GET /api/admin/business/statistics/user-stats │
|
||
└─────────────────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
## Components and Interfaces
|
||
|
||
### 1. 后端API模型
|
||
|
||
#### 1.1 今日订单数据模型
|
||
|
||
```csharp
|
||
public class TodayOrderStatsResponse
|
||
{
|
||
public int InitiateOrderCount { get; set; } // 发起订单数
|
||
public int PaidOrderCount { get; set; } // 支付订单数
|
||
public int UserCount { get; set; } // 消费人数
|
||
public decimal OrderZheTotal { get; set; } // 订单总金额（折后）
|
||
public decimal GoodsTotalAmount { get; set; } // 出货总金额
|
||
public decimal UseCoupon { get; set; } // 优惠券抵扣
|
||
public decimal Price { get; set; } // RMB支付
|
||
public decimal UseMoney { get; set; } // 钻石支付
|
||
public decimal UseIntegral { get; set; } // UU币支付
|
||
public decimal UseMoney2 { get; set; } // 达达券支付
|
||
}
|
||
```
|
||
|
||
#### 1.2 货币信息数据模型
|
||
|
||
```csharp
|
||
public class CurrencyInfoStatsResponse
|
||
{
|
||
public decimal TodayAddMoney { get; set; } // 今日发放钻石
|
||
public decimal TodayUseMoney { get; set; } // 今日消费钻石
|
||
public decimal YesterdayAddMoney { get; set; } // 昨日发放钻石
|
||
public decimal YesterdayUseMoney { get; set; } // 昨日消费钻石
|
||
public decimal TodayAddIntegral { get; set; } // 今日发放UU币
|
||
public decimal TodayUseIntegral { get; set; } // 今日消费UU币
|
||
public decimal YesterdayAddIntegral { get; set; }// 昨日发放UU币
|
||
public decimal YesterdayUseIntegral { get; set; }// 昨日消费UU币
|
||
public decimal TodayAddMoney2 { get; set; } // 今日发放达达券
|
||
public decimal TodayUseMoney2 { get; set; } // 今日消费达达券
|
||
public decimal YesterdayAddMoney2 { get; set; } // 昨日发放达达券
|
||
public decimal YesterdayUseMoney2 { get; set; } // 昨日消费达达券
|
||
}
|
||
```
|
||
|
||
#### 1.3 收入汇总数据模型
|
||
|
||
```csharp
|
||
public class IncomeSummaryStatsResponse
|
||
{
|
||
public decimal TodayIncome { get; set; } // 订单收入（RMB+钻石）
|
||
public decimal RmbIncome { get; set; } // RMB收入
|
||
public decimal DiamondIncome { get; set; } // 钻石商城收入
|
||
public decimal OtherIncome { get; set; } // 其他收入
|
||
public decimal ShippedToday { get; set; } // 订单出货
|
||
public decimal Expenses { get; set; } // 支出
|
||
public decimal TodayShipped { get; set; } // 当天发货金额
|
||
public decimal RemainingCoupon { get; set; } // 当天用户剩余达达券
|
||
public decimal BoxRemaining { get; set; } // 盒柜剩余价值
|
||
public decimal Profit { get; set; } // 利润
|
||
public string Formula { get; set; } // 利润计算公式
|
||
}
|
||
```
|
||
|
||
#### 1.4 用户统计数据模型
|
||
|
||
```csharp
|
||
public class UserStatsResponse
|
||
{
|
||
public int UserRegisterCount { get; set; } // 绑定手机号人数
|
||
public int ConsumingUserCount { get; set; } // 抽奖人数
|
||
public decimal UserMoney { get; set; } // 用户剩余钻石
|
||
public decimal UserIntegral { get; set; } // 用户剩余UU币
|
||
public decimal UserMoney2 { get; set; } // 用户剩余达达券
|
||
public decimal OrderPriceTotal { get; set; } // 微信支付金额
|
||
public int OrderTotalCount { get; set; } // 订单支付数量
|
||
public decimal TotalGoodsAmount { get; set; } // 用户出货总金额
|
||
public decimal BoxRemainingValue { get; set; } // 用户盒柜剩余价值
|
||
public decimal ExchangedCoupon { get; set; } // 用户已兑换的达达券
|
||
public decimal ShippedAmount { get; set; } // 用户已发货金额
|
||
}
|
||
```
|
||
|
||
### 2. 前端API模块
|
||
|
||
**文件**: `src/api/business/statistics.ts`
|
||
|
||
```typescript
|
||
// 今日订单统计响应接口
|
||
export interface TodayOrderStats {
|
||
initiateOrderCount: number; // 发起订单数
|
||
paidOrderCount: number; // 支付订单数
|
||
userCount: number; // 消费人数
|
||
orderZheTotal: number; // 订单总金额
|
||
goodsTotalAmount: number; // 出货总金额
|
||
useCoupon: number; // 优惠券抵扣
|
||
price: number; // RMB支付
|
||
useMoney: number; // 钻石支付
|
||
useIntegral: number; // UU币支付
|
||
useMoney2: number; // 达达券支付
|
||
}
|
||
|
||
// 货币信息统计响应接口
|
||
export interface CurrencyInfoStats {
|
||
todayAddMoney: number; // 今日发放钻石
|
||
todayUseMoney: number; // 今日消费钻石
|
||
yesterdayAddMoney: number; // 昨日发放钻石
|
||
yesterdayUseMoney: number; // 昨日消费钻石
|
||
todayAddIntegral: number; // 今日发放UU币
|
||
todayUseIntegral: number; // 今日消费UU币
|
||
yesterdayAddIntegral: number; // 昨日发放UU币
|
||
yesterdayUseIntegral: number; // 昨日消费UU币
|
||
todayAddMoney2: number; // 今日发放达达券
|
||
todayUseMoney2: number; // 今日消费达达券
|
||
yesterdayAddMoney2: number; // 昨日发放达达券
|
||
yesterdayUseMoney2: number; // 昨日消费达达券
|
||
}
|
||
|
||
// 收入汇总统计响应接口
|
||
export interface IncomeSummaryStats {
|
||
todayIncome: number; // 订单收入
|
||
rmbIncome: number; // RMB收入
|
||
diamondIncome: number; // 钻石商城收入
|
||
otherIncome: number; // 其他收入
|
||
shippedToday: number; // 订单出货
|
||
expenses: number; // 支出
|
||
todayShipped: number; // 当天发货金额
|
||
remainingCoupon: number; // 当天用户剩余达达券
|
||
boxRemaining: number; // 盒柜剩余价值
|
||
profit: number; // 利润
|
||
formula: string; // 利润计算公式
|
||
}
|
||
|
||
// 用户统计响应接口
|
||
export interface UserStats {
|
||
userRegisterCount: number; // 绑定手机号人数
|
||
consumingUserCount: number; // 抽奖人数
|
||
userMoney: number; // 用户剩余钻石
|
||
userIntegral: number; // 用户剩余UU币
|
||
userMoney2: number; // 用户剩余达达券
|
||
orderPriceTotal: number; // 微信支付金额
|
||
orderTotalCount: number; // 订单支付数量
|
||
totalGoodsAmount: number; // 用户出货总金额
|
||
boxRemainingValue: number; // 用户盒柜剩余价值
|
||
exchangedCoupon: number; // 用户已兑换的达达券
|
||
shippedAmount: number; // 用户已发货金额
|
||
}
|
||
|
||
// API函数
|
||
export function getTodayOrderStats(): Promise<TodayOrderStats>;
|
||
export function getCurrencyInfoStats(): Promise<CurrencyInfoStats>;
|
||
export function getIncomeSummaryStats(): Promise<IncomeSummaryStats>;
|
||
export function getUserStats(): Promise<UserStats>;
|
||
```
|
||
|
||
### 3. 前端组件结构
|
||
|
||
```
|
||
views/business/statistics/
|
||
├── data-stand.vue # 数据看板主页面
|
||
├── components/
|
||
│ ├── TodayOrderCard.vue # 今日订单卡片
|
||
│ ├── CurrencyInfoCard.vue # 货币信息卡片
|
||
│ ├── IncomeSummaryCard.vue # 收入汇总卡片
|
||
│ └── UserStatsCard.vue # 用户统计卡片
|
||
```
|
||
|
||
## Data Models
|
||
|
||
### 数据库表依赖
|
||
|
||
| 表名 | 用途 |
|
||
|------|------|
|
||
| orders | 订单表，存储订单信息 |
|
||
| order_list | 订单商品表，存储中奖记录 |
|
||
| users | 用户表，存储用户信息 |
|
||
| profit_money | 钻石流水表 |
|
||
| profit_integral | UU币流水表 |
|
||
| profit_money2 | 达达券流水表 |
|
||
| diamond_orders | 钻石商城订单表 |
|
||
| profit_revenue | 其他收入表 |
|
||
| profit_expenses | 支出表 |
|
||
|
||
## 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 小于等于发起订单数，消费人数 SHALL 小于等于支付订单数。
|
||
|
||
**Validates: Requirements 1.2, 1.3, 1.4**
|
||
|
||
### Property 2: 货币信息数据非负性
|
||
|
||
*For any* 货币信息统计数据，所有发放和消费数值 SHALL 大于等于0。
|
||
|
||
**Validates: Requirements 2.2-2.13**
|
||
|
||
### Property 3: 利润计算正确性
|
||
|
||
*For any* 收入汇总统计数据，利润 SHALL 等于 订单收入 - 当天发货金额 - 当天用户剩余达达券 - 盒柜剩余价值。
|
||
|
||
**Validates: Requirements 3.11**
|
||
|
||
### Property 4: 用户统计数据非负性
|
||
|
||
*For any* 用户统计数据，所有数值 SHALL 大于等于0。
|
||
|
||
**Validates: Requirements 4.2-4.12**
|
||
|
||
### Property 5: API响应格式一致性
|
||
|
||
*For any* 有效的API响应，所有统计字段 SHALL 被正确映射到对应的卡片并展示。
|
||
|
||
**Validates: Requirements 5.5**
|
||
|
||
## Error Handling
|
||
|
||
### API请求错误
|
||
|
||
1. **网络错误**: 显示"网络连接失败，请检查网络"提示
|
||
2. **服务器错误(5xx)**: 显示"服务器繁忙，请稍后重试"提示
|
||
3. **权限错误(403)**: 显示"无权限访问此页面"提示
|
||
4. **其他错误**: 显示通用错误提示
|
||
|
||
### 数据展示降级
|
||
|
||
当API请求失败时，所有统计数值显示为默认值0或"-"，确保页面正常渲染。
|
||
|
||
## Testing Strategy
|
||
|
||
### 单元测试
|
||
|
||
1. **API模块测试**
|
||
- 测试API端点配置正确性
|
||
- 测试响应数据类型转换
|
||
|
||
2. **格式化函数测试**
|
||
- 测试金额格式化函数
|
||
- 测试边界值（0、负数、大数值）
|
||
|
||
### 属性测试
|
||
|
||
使用 xUnit + FsCheck 进行属性测试：
|
||
|
||
1. **Property 1**: 验证今日订单数据一致性
|
||
2. **Property 2**: 验证货币信息数据非负性
|
||
3. **Property 3**: 验证利润计算正确性
|
||
4. **Property 4**: 验证用户统计数据非负性
|
||
5. **Property 5**: 验证API响应格式一致性
|
||
|
||
### 集成测试
|
||
|
||
1. 测试页面加载时API调用
|
||
2. 测试错误处理和降级展示
|
||
3. 测试刷新按钮功能
|