Story 009.001: 创建数据概览统计模块

Status

Ready for Review

Story

As a 系统开发人员， I want 实现数据概览统计服务， so that 为UI提供准确的统计数据

Acceptance Criteria

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

Tasks / Subtasks

[x] 创建多租户数据概览统计模块包结构 (AC: 1, 2, 3, 4, 5, 6, 7)
- 创建包目录：packages/data-overview-module-mt/ (参考：packages/advertisements-module-mt/)
- 配置package.json，包名：@d8d/data-overview-module-mt (参考：packages/advertisements-module-mt/package.json)
- 配置TypeScript和Vitest配置文件 (参考：packages/advertisements-module-mt/tsconfig.json, packages/advertisements-module-mt/vitest.config.ts)
- 创建核心模块结构：src/services/, src/schemas/, src/routes/, src/types/ (参考：packages/advertisements-module-mt/src/)
- 创建测试目录结构：tests/unit/, tests/integration/ (参考：packages/advertisements-module-mt/tests/)
[x] 实现数据概览统计服务 (AC: 1, 2, 3, 4, 5)
- 创建DataOverviewServiceMt服务类 (参考：packages/advertisements-module-mt/src/services/advertisement.service.ts)
- 实现时间筛选参数处理：getDateRange()方法，支持今日、昨日、最近7天、最近30天、自定义时间范围
- 实现统计查询方法：getSummaryStatistics()，基于史诗009的SQL查询设计
- 实现订单数据统计逻辑，区分微信支付(pay_type = 'WECHAT')和额度支付(pay_type = 'CREDIT')
- 添加多租户数据隔离：基于tenant_id筛选
- 实现Redis缓存机制：今日数据缓存5分钟，历史数据缓存30分钟
- 添加缓存键管理：包含租户ID和时间范围
[x] 实现数据验证Schema (AC: 2)
- 创建时间筛选Schema：TimeFilterSchema (参考：packages/advertisements-module-mt/src/schemas/advertisement.schema.ts)
- 定义时间筛选参数：startDate, endDate (ISO格式日期字符串)
- 添加参数验证和默认值处理
[x] 实现API路由 (AC: 1, 7)
- 创建路由文件：src/routes/index.mt.ts (参考：packages/advertisements-module-mt/src/routes/index.ts)
- 实现API端点：
- GET /api/data-overview/summary - 获取数据概览统计（支持时间筛选）
- GET /api/data-overview/today - 获取今日实时数据（快速查询）
- 添加数据验证Schema集成
- 添加权限控制和认证中间件
- 提供OpenAPI文档注释
[x] 编写单元测试 (AC: 6)
- 服务测试：测试数据概览统计逻辑 (参考：packages/file-module/tests/unit/file.service.test.ts)
- 测试时间筛选参数处理：今日、昨日、最近7天、最近30天、自定义时间范围
- 测试统计计算逻辑：总销售额、总订单数、支付方式分类统计
- 测试多租户数据隔离：验证tenant_id筛选
- 测试缓存逻辑：Redis缓存设置和获取
- 确保测试覆盖率 ≥ 80%
[x] 编写集成测试 (AC: 6)
- API集成测试：测试端点功能和验证 (参考：packages/advertisements-module-mt/tests/integration/advertisements.integration.test.ts)
- 测试GET /api/data-overview/summary端点，验证各种时间筛选参数
- 测试GET /api/data-overview/today端点，验证快速查询功能
- 测试缓存命中场景：验证缓存减少数据库查询
- 测试多租户场景：验证租户数据隔离
- 测试错误场景：无效时间参数、未授权访问等
[x] 配置包依赖和导出 (AC: 1, 7)
- 配置package.json依赖关系（TypeORM、Hono、Redis等） (参考：packages/advertisements-module-mt/package.json)
- 创建主入口文件：src/index.mt.ts 导出所有模块接口 (参考：packages/advertisements-module-mt/src/index.ts)
- 配置TypeScript编译选项 (参考：packages/advertisements-module-mt/tsconfig.json)
- 配置Vitest测试环境 (参考：packages/advertisements-module-mt/vitest.config.ts)
- 确保包可以正确导入和使用

Dev Notes

技术栈信息 [Source: architecture/tech-stack.md]

运行时: Node.js 20.18.3
框架: Hono 4.8.5 (Web框架和API路由，RPC类型安全)
数据库: PostgreSQL 17 (通过TypeORM进行数据持久化存储)
ORM: TypeORM 0.3.25 (数据库操作抽象，实体管理)
测试框架: Vitest 2.x (单元测试框架，更好的TypeORM支持)
API测试: hono/testing (内置，API端点测试，更好的类型安全)
缓存: Redis 7 (统计数据缓存)

项目结构信息 [Source: architecture/source-tree.md]

包管理: 使用pnpm workspace管理多包依赖关系
包架构层次:
- 基础设施层: shared-types → shared-utils → shared-crud
- 测试基础设施: shared-test-util
- 业务模块层: 多租户模块包（-mt后缀），支持租户数据隔离
- 应用层: server (重构后)
多租户架构:
- 包复制策略: 基于Epic-007方案，通过复制单租户包创建多租户版本
- 租户隔离: 通过租户ID实现数据隔离，支持多租户部署
- 后端包: 10个多租户模块包，支持租户数据隔离
文件命名: 保持现有kebab-case命名约定
模块化架构: 采用分层包结构，支持按需安装和独立开发

编码标准 [Source: architecture/coding-standards.md]

代码风格: TypeScript严格模式，一致的缩进和命名
测试位置: tests/ 文件夹与源码并列（实际使用tests/目录）
覆盖率目标: 核心业务逻辑 > 80%
测试类型: 单元测试、集成测试
现有API兼容性: 确保测试不破坏现有API契约
数据库集成: 使用测试数据库，避免污染生产数据

测试策略 [Source: architecture/testing-strategy.md]

单元测试范围: 单个函数、类或组件，验证独立单元的正确性
单元测试位置: packages/*-module/tests/unit/**/*.test.ts
集成测试范围: 多个组件/服务协作，验证模块间集成和交互
集成测试位置: packages/*-module/tests/integration/**/*.test.ts
测试框架: Vitest + Testing Library + hono/testing + shared-test-util
单元测试覆盖率目标: ≥ 80%
集成测试覆盖率目标: ≥ 60%
测试执行频率: 单元测试每次代码变更，集成测试每次API变更

API设计规范 [Source: architecture/api-design-integration.md]

API集成策略: 保持现有RESTful API设计，增强OpenAPI文档
认证: JWT Bearer Token，保持现有认证机制
版本控制: 使用v1前缀 (/api/v1/)，保持向后兼容
响应格式: 统一的数据响应格式，包含data和pagination字段
错误处理: 统一的错误响应格式

数据库查询设计 [Source: docs/prd/epic-009-data-overview.md#数据库查询设计]

总销售额和总订单数查询示例:

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;

模块结构 [Source: docs/prd/epic-009-data-overview.md#模块结构]

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

API设计 [Source: docs/prd/epic-009-data-overview.md#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天
自定义时间范围：用户选择的任意时间范围

数据指标定义 [Source: docs/prd/epic-009-data-overview.md#数据指标定义]

核心指标

总销售额：指定时间范围内所有已支付订单的total_amount总和
总订单数：指定时间范围内所有已支付订单的数量
微信支付总金额：指定时间范围内支付方式为微信支付的订单金额总和
微信支付订单数量：指定时间范围内微信支付订单的数量
额度支付总金额：指定时间范围内支付方式为额度支付的订单金额总和
额度支付订单数量：指定时间范围内额度支付订单的数量
今日销售额：今天00:00:00到当前时间的订单金额总和
今日订单数：今天00:00:00到当前时间的订单数量

订单状态筛选

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

性能优化 [Source: docs/prd/epic-009-data-overview.md#性能优化]

查询优化

数据库索引：为orders_mt表添加复合索引
- (tenant_id, created_at) 用于时间范围查询
- (tenant_id, pay_type, created_at) 用于支付方式统计
数据缓存：使用Redis缓存统计结果
- 今日数据缓存5分钟
- 历史数据缓存30分钟
- 缓存键包含租户ID和时间范围

集成点

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

技术约束

数据库查询：使用TypeORM或原生SQL查询订单数据
金额计算：统计total_amount字段，确保数值精度
租户隔离：严格验证租户上下文，确保查询包含tenant_id条件
缓存策略：实现缓存失效机制，确保数据实时性
事务处理：统计数据查询不需要事务，但需要确保查询性能

文件位置和命名约定

服务文件: packages/data-overview-module-mt/src/services/data-overview.service.mt.ts
路由文件: packages/data-overview-module-mt/src/routes/index.mt.ts
Schema文件: packages/data-overview-module-mt/src/schemas/index.mt.ts
类型文件: packages/data-overview-module-mt/src/types/index.mt.ts
主入口文件: packages/data-overview-module-mt/src/index.mt.ts (导出所有模块接口)

多租户实体命名模式

基于现有多租户模块观察：

服务类名: 以Mt结尾（如DataOverviewServiceMt）
文件命名: *.mt.ts 或 *.service.ts
必须包含: tenantId参数用于租户隔离

没有在架构文档中找到的特定指导

具体的TypeORM查询构建器配置示例
具体的Redis缓存实现示例
具体的时间范围计算工具函数实现
迁移脚本创建时机：根据项目架构，TypeORM迁移脚本应在server包中使用模块时创建，而不是在模块包中创建

Testing

测试标准 [Source: architecture/testing-strategy.md]

测试文件位置: packages/data-overview-module-mt/tests/ 目录下
单元测试位置: tests/unit/**/*.test.ts
集成测试位置: tests/integration/**/*.test.ts
测试框架: Vitest + hono/testing + shared-test-util
覆盖率要求: 单元测试 ≥ 80%，集成测试 ≥ 60%
测试模式: 使用测试数据工厂模式，避免硬编码测试数据
数据库测试: 使用专用测试数据库，事务回滚机制

测试策略要求

单元测试: 验证时间筛选参数处理、统计计算逻辑、缓存逻辑
集成测试: 验证API端点功能、数据库查询准确性、缓存效果
边界测试: 测试时间范围边界、空数据统计、大量数据统计
错误处理测试: 测试无效时间参数、未授权访问、缓存失效等场景
多租户测试: 测试租户数据隔离，确保租户A无法访问租户B的数据

测试数据管理

使用测试数据工厂模式创建测试订单数据
每个测试后清理测试数据（事务回滚）
使用唯一标识符确保测试数据隔离
模拟外部依赖（如Redis缓存服务）

Change Log

Date	Version	Description	Author
2025-12-26	1.0	初始故事创建	Bob (Scrum Master)
2025-12-26	1.1	实现数据概览统计模块包，完成所有核心功能	James (Developer)

Dev Agent Record

此部分由开发代理在实现过程中填写

Agent Model Used

Claude Code (d8d-model)

Debug Log References

Completion Notes List

✅ 模块包结构创建完成 - 基于advertisements-module-mt参考包创建了完整的包结构
✅ 数据概览统计服务实现完成 - 包含时间筛选、多租户隔离、Redis缓存、订单统计等功能
✅ 数据验证Schema实现完成 - 包含时间筛选参数验证和响应数据格式定义
✅ API路由实现完成 - 提供/api/data-overview/summary和/api/data-overview/today两个端点
✅ 包依赖配置完成 - 添加了必要的依赖项，包括@d8d/core-module-mt用于认证中间件
✅ 测试实现和调试完成 - 单元测试和集成测试全部通过，修复了模块模拟问题和时间范围计算逻辑
📝 OpenAPI文档已集成 - 通过@hono/zod-openapi提供完整的OpenAPI文档注释
🔧 缓存机制实现 - 今日数据缓存5分钟，历史数据缓存30分钟，支持租户隔离缓存键
🏗️ 多租户支持 - 所有查询都基于tenantId进行数据隔离，符合多租户架构要求
✅ 所有任务完成 - 所有任务和子任务均已标记为完成，故事状态更新为"Ready for Review"

File List

创建的文件：

packages/data-overview-module-mt/package.json - 包配置和依赖定义
packages/data-overview-module-mt/tsconfig.json - TypeScript配置
packages/data-overview-module-mt/vitest.config.ts - Vitest测试配置
packages/data-overview-module-mt/src/index.ts - 主入口文件
packages/data-overview-module-mt/src/services/data-overview.service.ts - 数据概览统计服务类
packages/data-overview-module-mt/src/services/index.ts - 服务导出
packages/data-overview-module-mt/src/schemas/index.ts - 数据验证Schema
packages/data-overview-module-mt/src/routes/index.ts - 路由聚合文件
packages/data-overview-module-mt/src/routes/summary.mt.ts - 数据概览统计API路由
packages/data-overview-module-mt/src/routes/today.mt.ts - 今日数据API路由
packages/data-overview-module-mt/src/types/index.ts - 类型定义导出
packages/data-overview-module-mt/tests/unit/data-overview.service.test.ts - 数据概览服务单元测试
packages/data-overview-module-mt/tests/integration/data-overview-routes.integration.test.ts - 数据概览路由集成测试
packages/data-overview-module-mt/tests/utils/test-data-factory.ts - 测试数据工厂

修改的文件：

docs/stories/009.001.data-overview-module-mt.story.md - 当前故事文件（更新任务完成状态和开发记录）

QA Results

此部分由QA代理在审查完成后填写

009.001.data-overview-module-mt.story.md 17 KB Histórico Raw