epic-009-data-overview.md 14 KB
史诗009：数据概览统计面板
概述
为多租户电商平台后台开发数据概览统计面板，提供全面的销售数据监控和统计分析功能。面板支持时间筛选，展示总销售额、总订单数、微信支付与额度支付的分类统计，以及今日实时数据，帮助管理员快速了解业务状况。
业务背景
当前后台系统缺乏集中的数据概览功能，管理员需要分别查看不同模块才能获取销售数据，无法快速了解整体业务状况。随着信用额度支付功能的引入，需要区分微信支付和额度支付的统计数据，以便更好地分析支付方式分布和业务健康度。
目标
- 提供统一的数据概览统计面板，集成核心业务指标
- 支持灵活的时间筛选功能（今日、昨日、最近7天、最近30天、自定义时间范围）
- 展示总销售额和总订单数，并按支付方式分类统计
- 提供今日实时数据，包括今日销售额和今日订单数
- 区分微信支付和额度支付的金额和订单数量统计
- 确保数据准确性和实时性，支持多租户数据隔离
范围
包含的功能
数据概览统计模块 (
data-overview-module-mt)- 统计数据查询服务
- 时间筛选参数处理
- 多维度数据聚合计算
- 支付方式分类统计
- 实时数据更新机制
数据概览UI模块 (
data-overview-ui-mt)- 统计面板主界面
- 时间筛选组件
- 数据卡片展示组件
- 图表可视化组件（可选）
- 实时数据刷新功能
数据集成和计算
- 订单数据统计查询
- 支付方式分类统计
- 多租户数据隔离计算
- 缓存机制优化性能
不包含的功能
- 详细的财务报表和导出功能
- 用户行为分析和漏斗分析
- 商品销售排行和库存分析
- 复杂的数据可视化图表
用户故事
故事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筛选 - 添加数据库索引优化查询性能
- 实现数据缓存策略，减少数据库查询压力
技术设计
数据库查询设计
-- 总销售额和总订单数查询示例
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调用）
GET /api/data-overview/summary- 获取数据概览统计- 查询参数：
startDate,endDate(ISO格式日期字符串) 返回数据：
{ totalSales: number, // 总销售额 totalOrders: number, // 总订单数 wechatSales: number, // 微信支付总金额 wechatOrders: number, // 微信支付订单数 creditSales: number, // 额度支付总金额 creditOrders: number, // 额度支付订单数 todaySales: number, // 今日销售额 todayOrders: number, // 今日订单数 }
- 查询参数：
GET /api/data-overview/today- 获取今日实时数据（快速查询）- 返回今日销售额和今日订单数
时间筛选支持
今日：当天00:00:00到23:59:59昨日：前一天00:00:00到23:59:59最近7天：当前时间往前推7天最近30天：当前时间往前推30天自定义时间范围：用户选择的任意时间范围
数据指标定义
核心指标
- 总销售额：指定时间范围内所有已支付订单的
total_amount总和 - 总订单数：指定时间范围内所有已支付订单的数量
- 微信支付总金额：指定时间范围内支付方式为微信支付的订单金额总和
- 微信支付订单数量：指定时间范围内微信支付订单的数量
- 额度支付总金额：指定时间范围内支付方式为额度支付的订单金额总和
- 额度支付订单数量：指定时间范围内额度支付订单的数量
- 今日销售额：今天00:00:00到当前时间的订单金额总和
- 今日订单数：今天00:00:00到当前时间的订单数量
订单状态筛选
- 仅统计已支付的订单：
order_status IN ('PAID', 'COMPLETED') - 排除已取消的订单：
order_status != 'CANCELLED' - 排除已删除的订单：
deleted_at IS NULL
集成点
与现有系统集成
- 订单模块集成：查询
orders_mt表获取订单统计数据 - 多租户架构集成：基于
tenant_id实现数据隔离 - 支付模块集成：区分
pay_type字段统计不同支付方式 - 缓存系统集成：使用Redis缓存统计结果，减少数据库压力
数据流
- UI发起统计查询请求 → 传递时间筛选参数和租户上下文
- 数据概览服务处理请求 → 验证参数，构建查询条件
- 执行数据库查询 → 使用TypeORM或原生SQL查询订单数据
- 计算结果并返回 → 按支付方式分类统计，计算总额
- UI展示统计数据 → 渲染数据卡片，支持刷新
性能优化
查询优化
- 数据库索引：为
orders_mt表添加复合索引(tenant_id, created_at)用于时间范围查询(tenant_id, pay_type, created_at)用于支付方式统计
- 数据缓存：使用Redis缓存统计结果
- 今日数据缓存5分钟
- 历史数据缓存30分钟
- 缓存键包含租户ID和时间范围
- 分页和批量处理：大数据量时使用分页查询
实时性保证
- 今日数据实时性：今日数据缓存时间较短（5分钟）
- 手动刷新：UI提供手动刷新按钮强制更新数据
- 后台任务：可考虑定时任务预计算统计数据
兼容性要求
- API兼容性：新增API端点，不影响现有API
- 数据兼容性：正确处理历史订单数据
- UI兼容性：新增页面，遵循现有UI规范
- 多租户兼容性：严格遵循租户数据隔离
风险与缓解
风险1：大数据量查询性能问题
- 缓解措施：添加数据库索引，实现查询优化
- 缓存策略：使用Redis缓存统计结果
- 分页处理：大数据量时使用分页查询
风险2：统计数据不准确
- 缓解措施：明确定义统计规则和订单状态筛选条件
- 测试验证：编写详细的单元测试验证统计逻辑
- 数据审计：定期对比统计结果与原始数据
风险3：实时数据延迟
- 缓解措施：今日数据使用较短缓存时间（5分钟）
- 手动刷新：提供手动刷新功能
- 监控告警：监控数据更新时间，设置告警阈值
风险4：多租户数据混淆
- 缓解措施：严格验证租户上下文，确保查询包含
tenant_id条件 - 权限控制：集成现有权限系统
- 测试覆盖：编写多租户场景测试用例
测试策略
单元测试
- 时间筛选参数处理测试
- 统计数据计算逻辑测试
- 支付方式分类统计测试
- 多租户数据隔离测试
- 缓存逻辑测试
集成测试
- API接口测试
- 数据库查询测试
- 订单数据统计准确性测试
- 时间范围筛选测试
- 支付方式分类统计测试
E2E测试
- 数据概览面板功能测试
- 时间筛选功能测试
- 数据刷新功能测试
- 多租户数据隔离测试
- 移动端适配测试（如有）
部署计划
阶段1：开发环境部署
- 创建数据概览统计模块包
- 创建数据概览UI模块包
- 集成到后台管理系统
- 配置缓存策略
阶段2：测试环境验证
- 功能测试和集成测试
- 性能测试和压力测试
- 数据准确性验证
- 多租户场景测试
阶段3：生产环境部署
- 部署新模块
- 添加数据库索引
- 配置Redis缓存
- 监控系统运行状态
成功指标
功能指标：
- 数据概览面板正常显示所有统计指标
- 时间筛选功能正常工作
- 支付方式分类统计准确
- 实时数据更新及时
- 多租户数据隔离正确
性能指标：
- 统计数据查询响应时间 < 500ms
- 页面加载时间 < 2s
- 缓存命中率 > 80%
- 系统可用性 > 99.9%
业务指标：
- 管理员使用频率提升
- 数据决策支持度增强
- 业务监控效率提高
后续优化建议
- 添加图表可视化（折线图、柱状图）
- 支持数据导出功能（Excel、PDF）
- 添加更多统计维度（商品类别、用户分组）
- 实现实时数据推送（WebSocket）
- 添加预警和告警功能
创建时间：2025-12-26 负责人：产品经理 状态：待开始 优先级：中
开发进度
待完成
- 🔄 故事1：创建数据概览统计模块
- 🔄 故事2：创建数据概览UI模块
- 🔄 故事3：集成订单数据统计
技术实现要点
- 多租户架构：严格遵循项目多租户包架构模式，使用
-mt后缀和租户ID隔离 - 性能优化：数据库索引优化，Redis缓存策略
- 统计准确性：明确定义统计规则和订单状态筛选条件
- UI一致性：遵循现有后台UI设计规范
- 测试覆盖：编写全面的单元测试和集成测试