Story 009.002: 创建数据概览UI模块

Status

Ready for Review

Story

As a 后台管理员， I want 有一个直观的数据概览面板， so that 快速了解业务状况

Acceptance Criteria

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

Tasks / Subtasks

[x] 创建多租户数据概览UI模块包结构 (AC: 1, 2, 3, 4, 5, 6)
- 创建包目录：packages/data-overview-ui-mt/
- 配置package.json依赖关系（参考：packages/user-management-ui-mt/package.json）
- 配置TypeScript编译选项（参考：packages/user-management-ui-mt/tsconfig.json）
- 配置Vitest测试环境（参考：packages/user-management-ui-mt/vitest.config.ts）
- 配置ESLint配置（参考：packages/user-management-ui-mt/eslint.config.js）
[x] 创建API客户端 (AC: 1, 2, 3, 4)
- 创建API客户端文件：src/api/dataOverviewClient.ts（参考：packages/user-management-ui-mt/src/api/userClient.ts）
- 实现数据概览统计查询API客户端方法
- 实现今日实时数据查询API客户端方法
- 实现错误处理和重试逻辑
[x] 创建类型定义 (AC: 1, 2, 3, 4)
- 创建类型文件：src/types/dataOverview.ts（参考：packages/user-management-ui-mt/src/types/index.ts）
- 定义数据概览统计响应类型
- 定义时间筛选参数类型
- 定义数据卡片配置类型
[x] 在组件中实现API调用逻辑 (AC: 1, 2, 3, 4)
- 在数据概览主组件中直接使用React Query的useQuery和useMutation
- 实现数据概览统计查询逻辑
- 实现今日实时数据查询逻辑
- 实现数据刷新逻辑
- 实现错误处理和加载状态管理
[x] 创建数据概览面板主组件 (AC: 1, 2, 3, 4, 5, 6)
- 创建主组件：src/components/DataOverviewPanel.tsx（参考：packages/user-management-ui-mt/src/components/UserManagement.tsx）
- 实现时间筛选组件：支持今日、昨日、最近7天、最近30天、自定义时间范围
- 实现数据卡片布局：总销售额、总订单数、今日销售额、今日订单数
- 实现支付方式切换功能：微信支付和额度支付细分显示
- 实现手动刷新按钮和自动刷新逻辑
- 添加加载状态指示器和错误提示
- 界面风格与现有后台保持一致（使用shadcn/ui组件库）
[x] 创建时间筛选组件 (AC: 2)
- 创建组件：src/components/TimeFilter.tsx
- 实现预设时间选项：今日、昨日、最近7天、最近30天
- 实现自定义时间范围选择器（日期选择器）
- 支持默认选中今日选项
- 触发时间变更时重新查询数据
[x] 创建数据卡片组件 (AC: 3)
- 创建组件：src/components/StatCard.tsx
- 支持显示不同统计指标：销售额、订单数等
- 支持格式化数字显示（千位分隔符、货币符号等）
- 支持支付方式细分切换显示
- 添加趋势指示器（可选）
[x] 实现权限控制 (AC: 1, 6)
- 添加管理员权限检查（参考：packages/user-management-ui-mt/src/components/UserManagement.tsx中的权限控制）
- 实现只有管理员角色才能访问数据概览界面
- 添加权限不足时的错误提示
[x] 编写集成测试 (AC: 7)
- 集成测试：测试完整功能流程，包括API集成、权限控制、时间筛选、数据刷新等（参考：packages/user-management-ui-mt/tests/integration/userManagement.integration.test.tsx）
- 权限测试：测试管理员和非管理员访问权限
- 时间筛选测试：测试各种时间选项功能
- 数据刷新测试：测试手动刷新功能
- 确保集成测试覆盖主要功能场景
[x] 配置包导出和集成 (AC: 1, 6)
- 创建主入口文件：src/index.ts 导出所有模块接口（参考：packages/user-management-ui-mt/src/index.ts）
- 配置包导出，确保可以正确导入和使用
- 更新根package.json的workspace配置（已包含在pnpm-workspace.yaml中）
- 集成到后台管理系统路由中（需要外部集成）

Dev Notes

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

前端框架: React 19.1.0 + TypeScript
路由: React Router v7
状态管理: @tanstack/react-query (服务端状态) + Context (本地状态)
UI组件库: shadcn/ui (基于Radix UI)
构建工具: Vite 7.0.0
样式: Tailwind CSS 4.1.11
HTTP客户端: 基于Hono Client的封装 + axios适配器

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

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

组件架构信息 [Source: architecture/component-architecture.md]

实际项目组件组织:

src/client/
├── admin/                 # 管理后台应用
│   ├── components/        # 管理后台专用组件
│   ├── hooks/            # 管理后台Hooks
│   ├── layouts/          # 布局组件
│   ├── pages/            # 页面组件
│   ├── routes.tsx        # 路由配置
│   └── index.tsx         # 管理后台入口
├── home/                 # 用户前台应用
├── components/           # 共享UI组件
│   └── ui/              # shadcn/ui组件库（50+组件）
├── hooks/               # 共享Hooks
├── lib/                 # 工具库
├── utils/               # 工具函数
└── api.ts               # API客户端配置

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

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

从故事004.002学到的经验教训

RPC客户端管理器使用: 在组件中应使用clientManager.get().api.$method而非直接使用导出的客户端实例
表单验证: 使用react-hook-form + zod进行表单验证，添加中文错误消息
权限控制: 只有管理员角色可以访问管理界面
错误处理: 区分API错误类型（如404用户额度账户不存在），提供友好的错误提示
测试数据管理: 使用测试数据工厂模式，避免硬编码测试数据
API模拟: 在测试中使用MSW或Vitest的mock功能模拟API调用
组件集成: 对话框组件模式，支持通过props控制打开/关闭

数据概览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天
自定义时间范围：用户选择的任意时间范围

文件位置和命名约定

UI模块包: packages/data-overview-ui-mt/
API客户端文件: packages/data-overview-ui-mt/src/api/dataOverviewClient.ts
类型文件: packages/data-overview-ui-mt/src/types/dataOverview.ts
主组件文件: packages/data-overview-ui-mt/src/components/DataOverviewPanel.tsx
时间筛选组件文件: packages/data-overview-ui-mt/src/components/TimeFilter.tsx
数据卡片组件文件: packages/data-overview-ui-mt/src/components/StatCard.tsx
测试文件: packages/data-overview-ui-mt/tests/ 目录下
主入口文件: packages/data-overview-ui-mt/src/index.ts (导出主组件)

参考的现有UI模块文件路径

用户管理UI模块: packages/user-management-ui-mt/ - 主要参考
- src/components/UserManagement.tsx - 主组件实现（直接在组件中使用useQuery）
- src/api/userClient.ts - API客户端实现
- src/types/index.ts - 类型定义
- tests/integration/userManagement.integration.test.tsx - 集成测试
信用额度管理UI模块: packages/credit-balance-management-ui-mt/ - 对话框组件参考
- src/components/CreditBalanceDialog.tsx - 对话框组件实现
- src/api/creditBalanceClient.ts - RPC客户端实现
- 权限控制、错误处理、表单验证等实现参考

权限控制要求

只有管理员角色（admin）可以访问数据概览界面
需要在组件中添加权限检查逻辑
权限不足时显示错误提示或重定向到登录页面

界面设计要求

使用shadcn/ui组件库，保持与现有后台界面风格一致
时间筛选组件位于面板顶部，提供预设选项和自定义选择器
数据卡片使用网格布局，4个卡片均匀分布
每个数据卡片显示主要统计指标，支持支付方式细分切换
添加手动刷新按钮，支持自动刷新可选
显示加载状态和错误提示
响应式设计，支持不同屏幕尺寸

技术约束

多租户支持: 组件需要支持多租户上下文，通过租户ID进行数据隔离
API集成: 使用RPC风格的Hono Client进行API调用，确保类型安全
状态管理: 使用React Query进行服务端状态管理，确保数据同步
错误处理: 完整的错误处理机制，显示友好的错误提示
加载状态: 显示加载状态，提升用户体验
时间处理: 使用dayjs或date-fns处理时间格式和计算

集成点

数据概览模块集成: 调用@d8d/data-overview-module-mt的API接口
权限系统集成: 集成现有权限控制系统，确保只有管理员可访问
UI组件库集成: 使用@d8d/shared-ui-components共享UI组件
后台路由集成: 集成到后台管理系统路由中，作为独立页面

Testing

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

测试文件位置: packages/data-overview-ui-mt/tests/ 目录下
单元测试位置: tests/unit/**/*.test.tsx
集成测试位置: tests/integration/**/*.test.tsx
测试框架: Vitest + Testing Library + React Testing Library
覆盖率要求: 单元测试 ≥ 80%，集成测试 ≥ 60%
测试模式: 使用测试数据工厂模式，避免硬编码测试数据
API模拟: 使用MSW或Vitest的mock功能模拟API调用

测试策略要求

单元测试: 验证单个组件功能、hooks逻辑、工具函数
集成测试: 验证API集成、权限控制、组件间协作
权限测试: 测试管理员和非管理员访问权限
时间筛选测试: 测试各种时间选项功能
数据刷新测试: 测试手动刷新和自动刷新功能
错误处理测试: 测试各种错误场景和异常情况

测试数据管理

使用测试数据工厂模式创建测试数据
模拟API响应，避免真实API调用
使用唯一标识符确保测试数据隔离
模拟用户认证和权限状态

Change Log

Date	Version	Description	Author
2025-12-29	1.0	初始故事创建	Bob (Scrum Master)
2025-12-29	1.1	完成故事实现，创建data-overview-ui-mt包	Claude Sonnet 4.5

Dev Agent Record

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

Agent Model Used

Claude Sonnet 4.5 (claude-sonnet-4-5-20250929)

Debug Log References

无

Completion Notes List

成功创建了多租户数据概览UI模块包 @d8d/data-overview-ui-mt
实现了完整的API客户端，支持数据概览统计和今日实时数据查询
创建了完整的TypeScript类型定义
实现了主组件DataOverviewPanel，包含时间筛选、数据卡片、支付方式切换、刷新功能
实现了独立的TimeFilter和StatCard组件
添加了权限控制支持（通过onPermissionCheck回调）
编写了完整的集成测试，覆盖主要功能场景
配置了包导出和构建配置
修复了集成测试中的问题（多元素匹配、lucide-react模拟等）
修复了TimeFilter组件构建错误（类型名称冲突）
验证了测试通过（8个测试全部通过）
验证了构建成功
参考了credit-balance-management-ui-mt包的最佳实践
已验证实现完整性：运行所有测试通过（8个测试），构建成功，代码结构完整

File List

新建文件:

packages/data-overview-ui-mt/ (包根目录)
packages/data-overview-ui-mt/package.json (包配置)
packages/data-overview-ui-mt/tsconfig.json (TypeScript配置)
packages/data-overview-ui-mt/vitest.config.ts (测试配置)
packages/data-overview-ui-mt/.eslintrc.js (ESLint配置)
packages/data-overview-ui-mt/build.config.ts (构建配置)
packages/data-overview-ui-mt/tests/setup.ts (测试设置)

源代码文件:

packages/data-overview-ui-mt/src/index.ts (主入口)
packages/data-overview-ui-mt/src/api/dataOverviewClient.ts (API客户端)
packages/data-overview-ui-mt/src/api/index.ts (API导出)
packages/data-overview-ui-mt/src/types/dataOverview.ts (类型定义)
packages/data-overview-ui-mt/src/types/index.ts (类型导出)
packages/data-overview-ui-mt/src/components/DataOverviewPanel.tsx (主组件)
packages/data-overview-ui-mt/src/components/TimeFilter.tsx (时间筛选组件)
packages/data-overview-ui-mt/src/components/StatCard.tsx (数据卡片组件)
packages/data-overview-ui-mt/src/components/index.ts (组件导出)
packages/data-overview-ui-mt/src/hooks/index.ts (hooks导出)

测试文件:

packages/data-overview-ui-mt/tests/integration/dataOverview.integration.test.tsx (集成测试)

修改文件:

docs/stories/009.002.data-overview-ui-mt.story.md (更新任务状态和开发记录)

QA Results

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

009.002.data-overview-ui-mt.story.md 16 KB История Исходник