# 史诗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. **测试覆盖**：编写全面的单元测试和集成测试