# 史诗009：数据概览统计面板

## 概述
为多租户电商平台后台开发数据概览统计面板，提供全面的销售数据监控和统计分析功能。面板支持时间筛选，展示总销售额、总订单数、微信支付与额度支付的分类统计，以及今日实时数据，帮助管理员快速了解业务状况。

## 业务背景
当前后台系统缺乏集中的数据概览功能，管理员需要分别查看不同模块才能获取销售数据，无法快速了解整体业务状况。随着信用额度支付功能的引入，需要区分微信支付和额度支付的统计数据，以便更好地分析支付方式分布和业务健康度。

## 目标
1. 提供统一的数据概览统计面板，集成核心业务指标
2. 支持灵活的时间筛选功能（今日、昨日、最近7天、最近30天、自定义时间范围）
3. 展示总销售额和总订单数，并按支付方式分类统计
4. 提供今日实时数据，包括今日销售额和今日订单数
5. 区分微信支付和额度支付的金额和订单数量统计
6. 确保数据准确性和实时性，支持多租户数据隔离

## 范围
### 包含的功能
1. **数据概览统计模块** (`data-overview-module-mt`)
   - 统计数据查询服务
   - 时间筛选参数处理
   - 多维度数据聚合计算
   - 支付方式分类统计
   - 实时数据更新机制

2. **数据概览UI模块** (`data-overview-ui-mt`)
   - 统计面板主界面
   - 时间筛选组件
   - 数据卡片展示组件
   - 图表可视化组件（可选）
   - 实时数据刷新功能

3. **数据集成和计算**
   - 订单数据统计查询
   - 支付方式分类统计
   - 多租户数据隔离计算
   - 缓存机制优化性能

### 不包含的功能
1. 详细的财务报表和导出功能
2. 用户行为分析和漏斗分析
3. 商品销售排行和库存分析
4. 复杂的数据可视化图表

## 用户故事
### 故事1：创建数据概览统计模块
**作为** 系统开发人员
**我希望** 实现数据概览统计服务
**以便** 为UI提供准确的统计数据

**验收标准：**
- [ ] 创建`data_overview_service_mt`服务类，提供统计查询方法
- [ ] 支持时间筛选参数：今日、昨日、最近7天、最近30天、自定义时间范围
- [ ] 实现以下统计指标：
  - 总销售额（所有支付方式）
  - 总订单数（所有支付方式）
  - 微信支付总金额
  - 微信支付订单数量
  - 额度支付总金额
  - 额度支付订单数量
  - 今日销售额
  - 今日订单数
- [ ] 支持多租户数据隔离查询
- [ ] 添加数据缓存机制优化查询性能
- [ ] 编写单元测试覆盖统计逻辑
- [ ] 提供OpenAPI文档

### 故事2：创建数据概览UI模块
**作为** 后台管理员
**我希望** 有一个直观的数据概览面板
**以便** 快速了解业务状况

**验收标准：**
- [ ] 创建数据概览统计面板主界面
- [ ] 实现时间筛选组件，支持以下选项：
  - 今日（默认）
  - 昨日
  - 最近7天
  - 最近30天
  - 自定义时间范围选择器
- [ ] 设计数据卡片展示布局，包含以下卡片：
  - 总销售额卡片（显示总金额，可切换显示微信支付和额度支付细分）
  - 总订单数卡片（显示总订单数，可切换显示微信支付和额度支付细分）
  - 今日销售额卡片（实时数据）
  - 今日订单数卡片（实时数据）
- [ ] 实现数据刷新功能（手动刷新按钮）
- [ ] 添加加载状态和错误处理
- [ ] 界面风格与现有后台保持一致
- [ ] 编写集成测试验证UI功能

### 故事3：集成订单数据统计
**作为** 系统架构师
**我希望** 数据概览模块能正确统计订单数据
**以便** 确保统计数据的准确性

**验收标准：**
- [ ] 集成订单模块数据源，正确统计订单相关数据
- [ ] 区分支付方式统计：
  - 微信支付：`pay_type = 'WECHAT'`的订单
  - 额度支付：`pay_type = 'CREDIT'`的订单
- [ ] 处理订单状态筛选：只统计已支付且未取消的订单（`order_status`为已支付状态）
- [ ] 实现金额计算：统计`total_amount`字段
- [ ] 支持多租户数据隔离：基于`tenant_id`筛选
- [ ] 添加数据库索引优化查询性能
- [ ] 实现数据缓存策略，减少数据库查询压力

## 技术设计
### 数据库查询设计
```sql
-- 总销售额和总订单数查询示例
SELECT
  COUNT(*) as total_orders,
  SUM(total_amount) as total_sales,
  SUM(CASE WHEN pay_type = 'WECHAT' THEN total_amount ELSE 0 END) as wechat_sales,
  SUM(CASE WHEN pay_type = 'CREDIT' THEN total_amount ELSE 0 END) as credit_sales,
  COUNT(CASE WHEN pay_type = 'WECHAT' THEN 1 END) as wechat_orders,
  COUNT(CASE WHEN pay_type = 'CREDIT' THEN 1 END) as credit_orders
FROM orders_mt
WHERE tenant_id = :tenantId
  AND order_status IN ('PAID', 'COMPLETED') -- 已支付或已完成状态
  AND created_at BETWEEN :startDate AND :endDate
  AND deleted_at IS NULL;
```

### 模块结构
```
packages/
├── @d8d/data-overview-module-mt/     # 数据概览统计模块
│   ├── src/
│   │   ├── services/                  # 服务层
│   │   │   ├── data-overview.service.ts
│   │   │   └── index.ts
│   │   ├── schemas/                   # 数据验证
│   │   │   ├── time-filter.schema.ts
│   │   │   └── index.ts
│   │   ├── routes/                    # API路由
│   │   │   └── index.ts
│   │   ├── types/                     # 类型定义
│   │   │   ├── data-overview.types.ts
│   │   │   └── index.ts
│   │   └── index.ts                   # 主入口文件
│   ├── tests/                         # 测试文件
│   ├── tsconfig.json                  # TypeScript配置
│   ├── vitest.config.ts               # 测试配置
│   └── package.json
└── @d8d/data-overview-ui-mt/          # 数据概览UI模块
    ├── src/
    │   ├── api/                       # API客户端
    │   │   ├── index.ts
    │   │   └── dataOverviewClient.ts
    │   ├── components/                # 组件
    │   │   ├── DataOverviewPanel.tsx
    │   │   ├── TimeFilter.tsx
    │   │   ├── StatCard.tsx
    │   │   └── index.ts
    │   ├── hooks/                     # React hooks
    │   │   ├── useDataOverview.ts
    │   │   └── index.ts
    │   ├── types/                     # 类型定义
    │   │   ├── index.ts
    │   │   └── dataOverview.ts
    │   └── index.ts                   # 主入口文件
    ├── tests/                         # 测试文件
    ├── eslint.config.js               # ESLint配置
    ├── tsconfig.json                  # TypeScript配置
    ├── vitest.config.ts               # 测试配置
    └── package.json
```

### API设计
#### 对外API（供UI调用）
1. `GET /api/data-overview/summary` - 获取数据概览统计
   - 查询参数：`startDate`, `endDate` (ISO格式日期字符串)
   - 返回数据：
     ```typescript
     {
       totalSales: number,           // 总销售额
       totalOrders: number,          // 总订单数
       wechatSales: number,          // 微信支付总金额
       wechatOrders: number,         // 微信支付订单数
       creditSales: number,          // 额度支付总金额
       creditOrders: number,         // 额度支付订单数
       todaySales: number,           // 今日销售额
       todayOrders: number,          // 今日订单数
     }
     ```

2. `GET /api/data-overview/today` - 获取今日实时数据（快速查询）
   - 返回今日销售额和今日订单数

#### 时间筛选支持
- `今日`：当天00:00:00到23:59:59
- `昨日`：前一天00:00:00到23:59:59
- `最近7天`：当前时间往前推7天
- `最近30天`：当前时间往前推30天
- `自定义时间范围`：用户选择的任意时间范围

## 数据指标定义
### 核心指标
1. **总销售额**：指定时间范围内所有已支付订单的`total_amount`总和
2. **总订单数**：指定时间范围内所有已支付订单的数量
3. **微信支付总金额**：指定时间范围内支付方式为微信支付的订单金额总和
4. **微信支付订单数量**：指定时间范围内微信支付订单的数量
5. **额度支付总金额**：指定时间范围内支付方式为额度支付的订单金额总和
6. **额度支付订单数量**：指定时间范围内额度支付订单的数量
7. **今日销售额**：今天00:00:00到当前时间的订单金额总和
8. **今日订单数**：今天00:00:00到当前时间的订单数量

### 订单状态筛选
- 仅统计已支付的订单：`order_status IN ('PAID', 'COMPLETED')`
- 排除已取消的订单：`order_status != 'CANCELLED'`
- 排除已删除的订单：`deleted_at IS NULL`

## 集成点
### 与现有系统集成
1. **订单模块集成**：查询`orders_mt`表获取订单统计数据
2. **多租户架构集成**：基于`tenant_id`实现数据隔离
3. **支付模块集成**：区分`pay_type`字段统计不同支付方式
4. **缓存系统集成**：使用Redis缓存统计结果，减少数据库压力

### 数据流
1. UI发起统计查询请求 → 传递时间筛选参数和租户上下文
2. 数据概览服务处理请求 → 验证参数，构建查询条件
3. 执行数据库查询 → 使用TypeORM或原生SQL查询订单数据
4. 计算结果并返回 → 按支付方式分类统计，计算总额
5. UI展示统计数据 → 渲染数据卡片，支持刷新

## 性能优化
### 查询优化
1. **数据库索引**：为`orders_mt`表添加复合索引
   - `(tenant_id, created_at)` 用于时间范围查询
   - `(tenant_id, pay_type, created_at)` 用于支付方式统计
2. **数据缓存**：使用Redis缓存统计结果
   - 今日数据缓存5分钟
   - 历史数据缓存30分钟
   - 缓存键包含租户ID和时间范围
3. **分页和批量处理**：大数据量时使用分页查询

### 实时性保证
1. **今日数据实时性**：今日数据缓存时间较短（5分钟）
2. **手动刷新**：UI提供手动刷新按钮强制更新数据
3. **后台任务**：可考虑定时任务预计算统计数据

## 兼容性要求
1. **API兼容性**：新增API端点，不影响现有API
2. **数据兼容性**：正确处理历史订单数据
3. **UI兼容性**：新增页面，遵循现有UI规范
4. **多租户兼容性**：严格遵循租户数据隔离

## 风险与缓解
### 风险1：大数据量查询性能问题
- **缓解措施**：添加数据库索引，实现查询优化
- **缓存策略**：使用Redis缓存统计结果
- **分页处理**：大数据量时使用分页查询

### 风险2：统计数据不准确
- **缓解措施**：明确定义统计规则和订单状态筛选条件
- **测试验证**：编写详细的单元测试验证统计逻辑
- **数据审计**：定期对比统计结果与原始数据

### 风险3：实时数据延迟
- **缓解措施**：今日数据使用较短缓存时间（5分钟）
- **手动刷新**：提供手动刷新功能
- **监控告警**：监控数据更新时间，设置告警阈值

### 风险4：多租户数据混淆
- **缓解措施**：严格验证租户上下文，确保查询包含`tenant_id`条件
- **权限控制**：集成现有权限系统
- **测试覆盖**：编写多租户场景测试用例

## 测试策略
### 单元测试
- 时间筛选参数处理测试
- 统计数据计算逻辑测试
- 支付方式分类统计测试
- 多租户数据隔离测试
- 缓存逻辑测试

### 集成测试
- API接口测试
- 数据库查询测试
- 订单数据统计准确性测试
- 时间范围筛选测试
- 支付方式分类统计测试

### E2E测试
- 数据概览面板功能测试
- 时间筛选功能测试
- 数据刷新功能测试
- 多租户数据隔离测试
- 移动端适配测试（如有）

## 部署计划
### 阶段1：开发环境部署
1. 创建数据概览统计模块包
2. 创建数据概览UI模块包
3. 集成到后台管理系统
4. 配置缓存策略

### 阶段2：测试环境验证
1. 功能测试和集成测试
2. 性能测试和压力测试
3. 数据准确性验证
4. 多租户场景测试

### 阶段3：生产环境部署
1. 部署新模块
2. 添加数据库索引
3. 配置Redis缓存
4. 监控系统运行状态

## 成功指标
1. **功能指标**：
   - 数据概览面板正常显示所有统计指标
   - 时间筛选功能正常工作
   - 支付方式分类统计准确
   - 实时数据更新及时
   - 多租户数据隔离正确

2. **性能指标**：
   - 统计数据查询响应时间 < 500ms
   - 页面加载时间 < 2s
   - 缓存命中率 > 80%
   - 系统可用性 > 99.9%

3. **业务指标**：
   - 管理员使用频率提升
   - 数据决策支持度增强
   - 业务监控效率提高

## 后续优化建议
1. 添加图表可视化（折线图、柱状图）
2. 支持数据导出功能（Excel、PDF）
3. 添加更多统计维度（商品类别、用户分组）
4. 实现实时数据推送（WebSocket）
5. 添加预警和告警功能

---
**创建时间**：2025-12-26
**负责人**：产品经理
**状态**：待开始
**优先级**：中

## 开发进度
### 待完成
1. 🔄 **故事1：创建数据概览统计模块**
2. 🔄 **故事2：创建数据概览UI模块**
3. 🔄 **故事3：集成订单数据统计**

### 技术实现要点
1. **多租户架构**：严格遵循项目多租户包架构模式，使用`-mt`后缀和租户ID隔离
2. **性能优化**：数据库索引优化，Redis缓存策略
3. **统计准确性**：明确定义统计规则和订单状态筛选条件
4. **UI一致性**：遵循现有后台UI设计规范
5. **测试覆盖**：编写全面的单元测试和集成测试