# 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 │ │ - getCurrencyInfoStats(): Promise │ │ - getIncomeSummaryStats(): Promise │ │ - getUserStats(): Promise │ └─────────────────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────────────────┐ │ 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; export function getCurrencyInfoStats(): Promise; export function getIncomeSummaryStats(): Promise; export function getUserStats(): Promise; ``` ### 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. 测试刷新按钮功能