Browse Source

📝 docs(stories): add financial data visualization dashboard story

- create story for implementing financial data visualization dashboard
- define acceptance criteria for main page and variation modal
- outline tasks for component creation and testing
- provide technical stack and project structure information
- include design references and testing requirements
yourname 2 tháng trước cách đây
mục cha
commit
8ce2d6e221
1 tập tin đã thay đổi với 131 bổ sung0 xóa
  1. 131 0
      docs/stories/006.002.实现财务数据可视化大屏页面.md

+ 131 - 0
docs/stories/006.002.实现财务数据可视化大屏页面.md

@@ -0,0 +1,131 @@
+# Story 006.002: 实现财务数据可视化大屏页面
+
+## Status
+Draft
+
+## Story
+**As a** 财务数据可视化大屏用户,
+**I want** 在 `src/client/home/pages/FinancialDashboard/` 下创建财务数据可视化大屏组件,包括主页面和变动幅度弹窗,
+**so that** 我可以在前端大屏中直观查看资产总额、资产净额、利润总额、净利润、收入和资产负债率等关键财务指标的可视化展示。
+
+## Acceptance Criteria
+1. 在 `src/client/home/pages/FinancialDashboard/` 下创建财务数据可视化大屏组件
+2. 实现主页面(参考:`node-id=1715-121572`)- 包含四个数据模块的可视化展示
+3. 实现变动幅度弹窗(参考四个层次构成:遮罩层、弹出框、弹出框数据、返回按钮)- 点击右下角浮动按钮后显示
+
+## Tasks / Subtasks
+- [ ] 创建财务数据可视化大屏主页面组件 `src/client/home/pages/FinancialDashboard/FinancialDashboard.tsx` (AC: 1, 2)
+  - [ ] 基于Figma设计实现主页面布局:`https://www.figma.com/design/mTu6gamzMFEybbSb8WssKK/可视化素材2-25?node-id=1715-121572&m=dev`
+  - [ ] 实现四个数据模块的容器布局
+  - [ ] 添加右下角浮动按钮用于触发变动幅度弹窗
+- [ ] 创建四个财务数据模块组件 (AC: 2)
+  - [ ] `src/client/home/pages/FinancialDashboard/components/AssetMetrics.tsx` - 资产负债率模块(资产总额与资产净额)
+  - [ ] `src/client/home/pages/FinancialDashboard/components/ProfitMetrics.tsx` - 利润总额与净利润模块
+  - [ ] `src/client/home/pages/FinancialDashboard/components/IncomeMetrics.tsx` - 收入模块
+  - [ ] `src/client/home/pages/FinancialDashboard/components/DebtRatioMetrics.tsx` - 资产负债率(百分比)模块
+- [ ] 创建变动幅度弹窗组件 `src/client/home/pages/FinancialDashboard/components/VariationModal.tsx` (AC: 3)
+  - [ ] 实现四个层次构成:遮罩层、弹出框、弹出框数据、返回按钮
+  - [ ] 基于Figma设计实现:
+    - 遮罩层:`https://www.figma.com/design/mTu6gamzMFEybbSb8WssKK/可视化素材2-25?node-id=1949-81702&m=dev`
+    - 弹出框:`https://www.figma.com/design/mTu6gamzMFEybbSb8WssKK/可视化素材2-25?node-id=1949-81703&m=dev`
+    - 弹出框数据:`https://www.figma.com/design/mTu6gamzMFEybbSb8WssKK/可视化素材2-25?node-id=1949-81714&m=dev`
+    - 返回按钮:`https://www.figma.com/design/mTu6gamzMFEybbSb8WssKK/可视化素材2-25?node-id=1949-82235&m=dev`
+  - [ ] 实现点击外部关闭功能
+- [ ] 创建组件单元测试 (AC: 1, 2, 3)
+  - [ ] `tests/unit/client/home/pages/FinancialDashboard/FinancialDashboard.test.tsx` - 主页面测试
+  - [ ] `tests/unit/client/home/pages/FinancialDashboard/components/AssetMetrics.test.tsx` - 资产模块测试
+  - [ ] `tests/unit/client/home/pages/FinancialDashboard/components/ProfitMetrics.test.tsx` - 利润模块测试
+  - [ ] `tests/unit/client/home/pages/FinancialDashboard/components/IncomeMetrics.test.tsx` - 收入模块测试
+  - [ ] `tests/unit/client/home/pages/FinancialDashboard/components/DebtRatioMetrics.test.tsx` - 资产负债率模块测试
+  - [ ] `tests/unit/client/home/pages/FinancialDashboard/components/VariationModal.test.tsx` - 弹窗组件测试
+
+## Dev Notes
+
+### 技术栈信息 [Source: architecture/tech-stack.md#现有技术栈维护]
+- **前端框架**: React 19.1.0 + TypeScript
+- **构建工具**: Vite 7.0.0
+- **样式**: Tailwind CSS 4.1.11
+- **状态管理**: React Query 5.83.0 (服务端状态) + Context (本地状态)
+- **UI组件库**: shadcn/ui (基于Radix UI)
+- **可视化组件**: Recharts (已集成在 `src/client/components/ui/chart.tsx`)
+
+### 项目结构信息 [Source: architecture/source-tree.md#实际项目结构]
+- **前端页面位置**: `src/client/home/pages/FinancialDashboard/` (新建独立页面)
+- **组件位置**: `src/client/home/pages/FinancialDashboard/components/` (新建组件结构)
+- **测试位置**:
+  - 单元测试: `tests/unit/client/home/pages/FinancialDashboard/`
+  - 组件测试: `tests/unit/client/home/pages/FinancialDashboard/components/`
+- **设计参考**: 基于Figma设计独立实现
+
+### 组件架构信息 [Source: architecture/component-architecture.md#前端组件架构]
+- **组件组织**: 遵循现有功能模块划分,主页面聚合子组件
+- **样式模式**: 使用Tailwind CSS原子化样式,遵循现有样式约定
+- **状态管理**: 使用React状态管理本地UI状态
+- **交互模式**: 遵循现有组件交互模式
+
+### 可视化组件信息 [Source: src/client/components/ui/chart.tsx]
+- **图表组件**: 使用Recharts库,已封装在 `ChartContainer`, `ChartTooltip`, `ChartLegend` 等组件中
+- **配置模式**: 使用 `ChartConfig` 类型定义图表配置
+- **主题支持**: 支持light/dark主题切换
+- **响应式**: 使用 `ResponsiveContainer` 实现响应式图表
+
+### 设计参考
+**主页面设计** [Source: Figma]:
+- **主页面**: `https://www.figma.com/design/mTu6gamzMFEybbSb8WssKK/可视化素材2-25?node-id=1715-121572&m=dev` - 财务数据可视化大屏主页面设计,包含四个数据模块
+
+**弹窗设计** [Source: Figma]:
+**四个层次构成**:
+1. **遮罩层** (Overlay) - `https://www.figma.com/design/mTu6gamzMFEybbSb8WssKK/可视化素材2-25?node-id=1949-81702&m=dev` - 背景遮罩,提供视觉隔离和点击外部关闭功能
+2. **弹出框** (Dialog Container) - `https://www.figma.com/design/mTu6gamzMFEybbSb8WssKK/可视化素材2-25?node-id=1949-81703&m=dev` - 弹窗主体容器,包含边框、阴影和圆角样式
+3. **弹出框数据** (Dialog Content) - `https://www.figma.com/design/mTu6gamzMFEybbSb8WssKK/可视化素材2-25?node-id=1949-81714&m=dev` - 弹窗内容区域,展示财务数据详情
+4. **返回按钮** (Action Controls) - `https://www.figma.com/design/mTu6gamzMFEybbSb8WssKK/可视化素材2-25?node-id=1949-82235&m=dev` - 弹窗操作控件,包含关闭按钮和交互元素
+
+### 数据模块定义
+基于API响应结构 [Source: docs/stories/006.001.创建财务数据API接口.md#数据模型参考]:
+- **资产总额与资产净额数据**: 2023-2024年数据,单位:元
+- **利润总额与净利润数据**: 2023-2024年数据,单位:元
+- **收入数据**: 2023-2024年数据,单位:元
+- **资产负债率数据**: 2023-2024年数据,单位:%
+
+### 编码标准 [Source: architecture/coding-standards.md#关键集成规则]
+- **现有API兼容性**: 确保组件不破坏现有API契约
+- **错误处理**: 实现适当的错误边界和加载状态
+- **样式一致性**: 遵循现有Tailwind CSS样式约定
+
+## Testing
+
+### 测试标准 [Source: architecture/testing-strategy.md#测试金字塔策略]
+- **测试框架**: Vitest + Testing Library
+- **测试位置**: `tests/unit/client/home/pages/FinancialDashboard/`
+- **测试类型**: 组件单元测试
+- **覆盖率目标**: ≥ 80%
+
+### 具体测试要求
+- 验证主页面正确渲染四个数据模块
+- 测试变动幅度弹窗的显示/隐藏功能
+- 验证弹窗四个层次构成的正确性
+- 测试点击外部关闭弹窗功能
+- 验证组件样式和布局正确性
+
+### 测试参考模式 [Source: tests/unit/client/home/pages/SupplyChainDashboards/GrainOilDashboard.test.tsx]
+- 使用 `render`, `screen`, `fireEvent` 进行组件测试
+- 使用 `vi.mock()` 模拟子组件
+- 验证样式类名和DOM结构
+- 测试用户交互和状态变化
+
+## Change Log
+| Date | Version | Description | Author |
+|------|---------|-------------|---------|
+| 2025-11-14 | 1.0 | 初始故事创建 | Bob (Scrum Master) |
+
+## Dev Agent Record
+
+### Agent Model Used
+
+### Debug Log References
+
+### Completion Notes List
+
+### File List
+
+## QA Results