|
@@ -0,0 +1,280 @@
|
|
|
|
|
+# Story 009.002: 创建数据概览UI模块
|
|
|
|
|
+
|
|
|
|
|
+## Status
|
|
|
|
|
+Draft
|
|
|
|
|
+
|
|
|
|
|
+## Story
|
|
|
|
|
+**As a** 后台管理员,
|
|
|
|
|
+**I want** 有一个直观的数据概览面板,
|
|
|
|
|
+**so that** 快速了解业务状况
|
|
|
|
|
+
|
|
|
|
|
+## Acceptance Criteria
|
|
|
|
|
+1. 创建数据概览统计面板主界面
|
|
|
|
|
+2. 实现时间筛选组件,支持以下选项:
|
|
|
|
|
+ - 今日(默认)
|
|
|
|
|
+ - 昨日
|
|
|
|
|
+ - 最近7天
|
|
|
|
|
+ - 最近30天
|
|
|
|
|
+ - 自定义时间范围选择器
|
|
|
|
|
+3. 设计数据卡片展示布局,包含以下卡片:
|
|
|
|
|
+ - 总销售额卡片(显示总金额,可切换显示微信支付和额度支付细分)
|
|
|
|
|
+ - 总订单数卡片(显示总订单数,可切换显示微信支付和额度支付细分)
|
|
|
|
|
+ - 今日销售额卡片(实时数据)
|
|
|
|
|
+ - 今日订单数卡片(实时数据)
|
|
|
|
|
+4. 实现数据刷新功能(手动刷新按钮)
|
|
|
|
|
+5. 添加加载状态和错误处理
|
|
|
|
|
+6. 界面风格与现有后台保持一致
|
|
|
|
|
+7. 编写集成测试验证UI功能
|
|
|
|
|
+
|
|
|
|
|
+## Tasks / Subtasks
|
|
|
|
|
+- [ ] **创建多租户数据概览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`)
|
|
|
|
|
+
|
|
|
|
|
+- [ ] **创建API客户端** (AC: 1, 2, 3, 4)
|
|
|
|
|
+ - [ ] 创建API客户端文件:`src/api/dataOverviewClient.ts`(参考:`packages/user-management-ui-mt/src/api/userClient.ts`)
|
|
|
|
|
+ - [ ] 实现数据概览统计查询API客户端方法
|
|
|
|
|
+ - [ ] 实现今日实时数据查询API客户端方法
|
|
|
|
|
+ - [ ] 实现错误处理和重试逻辑
|
|
|
|
|
+
|
|
|
|
|
+- [ ] **创建类型定义** (AC: 1, 2, 3, 4)
|
|
|
|
|
+ - [ ] 创建类型文件:`src/types/dataOverview.ts`(参考:`packages/user-management-ui-mt/src/types/index.ts`)
|
|
|
|
|
+ - [ ] 定义数据概览统计响应类型
|
|
|
|
|
+ - [ ] 定义时间筛选参数类型
|
|
|
|
|
+ - [ ] 定义数据卡片配置类型
|
|
|
|
|
+
|
|
|
|
|
+- [ ] **在组件中实现API调用逻辑** (AC: 1, 2, 3, 4)
|
|
|
|
|
+ - [ ] 在数据概览主组件中直接使用React Query的useQuery和useMutation
|
|
|
|
|
+ - [ ] 实现数据概览统计查询逻辑
|
|
|
|
|
+ - [ ] 实现今日实时数据查询逻辑
|
|
|
|
|
+ - [ ] 实现数据刷新逻辑
|
|
|
|
|
+ - [ ] 实现错误处理和加载状态管理
|
|
|
|
|
+
|
|
|
|
|
+- [ ] **创建数据概览面板主组件** (AC: 1, 2, 3, 4, 5, 6)
|
|
|
|
|
+ - [ ] 创建主组件:`src/components/DataOverviewPanel.tsx`(参考:`packages/user-management-ui-mt/src/components/UserManagement.tsx`)
|
|
|
|
|
+ - [ ] 实现时间筛选组件:支持今日、昨日、最近7天、最近30天、自定义时间范围
|
|
|
|
|
+ - [ ] 实现数据卡片布局:总销售额、总订单数、今日销售额、今日订单数
|
|
|
|
|
+ - [ ] 实现支付方式切换功能:微信支付和额度支付细分显示
|
|
|
|
|
+ - [ ] 实现手动刷新按钮和自动刷新逻辑
|
|
|
|
|
+ - [ ] 添加加载状态指示器和错误提示
|
|
|
|
|
+ - [ ] 界面风格与现有后台保持一致(使用shadcn/ui组件库)
|
|
|
|
|
+
|
|
|
|
|
+- [ ] **创建时间筛选组件** (AC: 2)
|
|
|
|
|
+ - [ ] 创建组件:`src/components/TimeFilter.tsx`
|
|
|
|
|
+ - [ ] 实现预设时间选项:今日、昨日、最近7天、最近30天
|
|
|
|
|
+ - [ ] 实现自定义时间范围选择器(日期选择器)
|
|
|
|
|
+ - [ ] 支持默认选中今日选项
|
|
|
|
|
+ - [ ] 触发时间变更时重新查询数据
|
|
|
|
|
+
|
|
|
|
|
+- [ ] **创建数据卡片组件** (AC: 3)
|
|
|
|
|
+ - [ ] 创建组件:`src/components/StatCard.tsx`
|
|
|
|
|
+ - [ ] 支持显示不同统计指标:销售额、订单数等
|
|
|
|
|
+ - [ ] 支持格式化数字显示(千位分隔符、货币符号等)
|
|
|
|
|
+ - [ ] 支持支付方式细分切换显示
|
|
|
|
|
+ - [ ] 添加趋势指示器(可选)
|
|
|
|
|
+
|
|
|
|
|
+- [ ] **实现权限控制** (AC: 1, 6)
|
|
|
|
|
+ - [ ] 添加管理员权限检查(参考:`packages/user-management-ui-mt/src/components/UserManagement.tsx`中的权限控制)
|
|
|
|
|
+ - [ ] 实现只有管理员角色才能访问数据概览界面
|
|
|
|
|
+ - [ ] 添加权限不足时的错误提示
|
|
|
|
|
+
|
|
|
|
|
+- [ ] **编写集成测试** (AC: 7)
|
|
|
|
|
+ - [ ] **集成测试**:测试完整功能流程,包括API集成、权限控制、时间筛选、数据刷新等(参考:`packages/user-management-ui-mt/tests/integration/userManagement.integration.test.tsx`)
|
|
|
|
|
+ - [ ] **权限测试**:测试管理员和非管理员访问权限
|
|
|
|
|
+ - [ ] **时间筛选测试**:测试各种时间选项功能
|
|
|
|
|
+ - [ ] **数据刷新测试**:测试手动刷新功能
|
|
|
|
|
+ - [ ] 确保集成测试覆盖主要功能场景
|
|
|
|
|
+
|
|
|
|
|
+- [ ] **配置包导出和集成** (AC: 1, 6)
|
|
|
|
|
+ - [ ] 创建主入口文件:`src/index.ts` 导出所有模块接口(参考:`packages/user-management-ui-mt/src/index.ts`)
|
|
|
|
|
+ - [ ] 配置包导出,确保可以正确导入和使用
|
|
|
|
|
+ - [ ] 更新根package.json的workspace配置
|
|
|
|
|
+ - [ ] 集成到后台管理系统路由中
|
|
|
|
|
+
|
|
|
|
|
+## 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]
|
|
|
|
|
+**实际项目组件组织**:
|
|
|
|
|
+```text
|
|
|
|
|
+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学到的经验教训
|
|
|
|
|
+1. **RPC客户端管理器使用**: 在组件中应使用`clientManager.get().api.$method`而非直接使用导出的客户端实例
|
|
|
|
|
+2. **表单验证**: 使用react-hook-form + zod进行表单验证,添加中文错误消息
|
|
|
|
|
+3. **权限控制**: 只有管理员角色可以访问管理界面
|
|
|
|
|
+4. **错误处理**: 区分API错误类型(如404用户额度账户不存在),提供友好的错误提示
|
|
|
|
|
+5. **测试数据管理**: 使用测试数据工厂模式,避免硬编码测试数据
|
|
|
|
|
+6. **API模拟**: 在测试中使用MSW或Vitest的mock功能模拟API调用
|
|
|
|
|
+7. **组件集成**: 对话框组件模式,支持通过props控制打开/关闭
|
|
|
|
|
+
|
|
|
|
|
+### 数据概览API设计 [Source: docs/prd/epic-009-data-overview.md#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天
|
|
|
|
|
+- `自定义时间范围`:用户选择的任意时间范围
|
|
|
|
|
+
|
|
|
|
|
+### 文件位置和命名约定
|
|
|
|
|
+- **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模块文件路径
|
|
|
|
|
+1. **用户管理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` - 集成测试
|
|
|
|
|
+
|
|
|
|
|
+2. **信用额度管理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处理时间格式和计算
|
|
|
|
|
+
|
|
|
|
|
+### 集成点
|
|
|
|
|
+1. **数据概览模块集成**: 调用`@d8d/data-overview-module-mt`的API接口
|
|
|
|
|
+2. **权限系统集成**: 集成现有权限控制系统,确保只有管理员可访问
|
|
|
|
|
+3. **UI组件库集成**: 使用`@d8d/shared-ui-components`共享UI组件
|
|
|
|
|
+4. **后台路由集成**: 集成到后台管理系统路由中,作为独立页面
|
|
|
|
|
+
|
|
|
|
|
+## 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) |
|
|
|
|
|
+
|
|
|
|
|
+## Dev Agent Record
|
|
|
|
|
+*此部分由开发代理在实现过程中填写*
|
|
|
|
|
+
|
|
|
|
|
+### Agent Model Used
|
|
|
|
|
+
|
|
|
|
|
+### Debug Log References
|
|
|
|
|
+
|
|
|
|
|
+### Completion Notes List
|
|
|
|
|
+
|
|
|
|
|
+### File List
|
|
|
|
|
+
|
|
|
|
|
+## QA Results
|
|
|
|
|
+*此部分由QA代理在审查完成后填写*
|