HaniBlindBox/.kiro/specs/dashboard-statistics/design.md

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 今日订单数据模型

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 货币信息数据模型

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 收入汇总数据模型

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 用户统计数据模型

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

// 今日订单统计响应接口
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. 测试刷新按钮功能