# 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`
  - [ ] **严格按照1920*1080分辨率实现布局**，确保在大屏设备上完美显示
  - [ ] 实现四个数据模块的容器布局：资产负债率、收入、利润总额与净利润、资产负债率（百分比）
  - [ ] 添加右下角浮动按钮用于触发变动幅度弹窗
  - [ ] 实现完整的页面背景和网格系统
  - [ ] 集成所有基础组件构建完整页面
  - [ ] **集成财务数据API调用** - 调用 `/api/v1/dash/outlook` 接口获取财务数据 [Source: docs/stories/006.001.创建财务数据API接口.md#L86-L129]
- [ ] 创建基础组件 (AC: 2)
  - [ ] `src/client/home/pages/FinancialDashboard/components/Icon.tsx` - 返回按钮图标组件（包含旋转和缩放变换）
  - [ ] `src/client/home/pages/FinancialDashboard/components/ReportHeader.tsx` - 报表头部组件（包含渐变背景和标题）
  - [ ] `src/client/home/pages/FinancialDashboard/components/BaseContainer.tsx` - 底框和头部容器组件（作为模块容器背景）
  - [ ] `src/client/home/pages/FinancialDashboard/components/BarElement.tsx` - 柱形元素组件（支持多种颜色变体：资产总额、资产净额、利润总额、净利润、资产负债率）
    - [ ] **添加动画效果** - 实现数据柱从底部向上生长的动画效果
    - [ ] **添加悬停效果** - 鼠标悬停时柱形轻微放大和阴影变化
    - [ ] **添加加载动画** - 数据加载时的骨架屏动画
  - [ ] `src/client/home/pages/FinancialDashboard/components/DataLabel.tsx` - 定位数据组件（包含数值显示和装饰元素）
  - [ ] `src/client/home/pages/FinancialDashboard/components/TimeIcon.tsx` - 时间图标组件
  - [ ] `src/client/home/pages/FinancialDashboard/components/GridBackground.tsx` - 底部网格组件（包含背景网格图案）
  - [ ] `src/client/home/pages/FinancialDashboard/components/BackgroundOverlay.tsx` - 常规界面组件（包含背景图片和遮罩层）
- [ ] 创建四个财务数据模块组件 (AC: 2)
  - [ ] `src/client/home/pages/FinancialDashboard/components/AssetMetrics.tsx` - 资产负债率模块（资产总额与资产净额）
    - [ ] **集成API数据** - 使用 `assetTotalNet` 数据渲染资产总额与资产净额图表 [Source: docs/stories/006.001.创建财务数据API接口.md#L93-L101]
    - [ ] **添加图表动画** - 实现图表数据加载时的渐入动画和柱形生长动画
  - [ ] `src/client/home/pages/FinancialDashboard/components/ProfitMetrics.tsx` - 利润总额与净利润模块
    - [ ] **集成API数据** - 使用 `profitTotalNet` 数据渲染利润总额与净利润图表 [Source: docs/stories/006.001.创建财务数据API接口.md#L102-L110]
    - [ ] **添加图表动画** - 实现图表数据加载时的渐入动画和柱形生长动画
  - [ ] `src/client/home/pages/FinancialDashboard/components/IncomeMetrics.tsx` - 收入模块
    - [ ] **集成API数据** - 使用 `incomeStatement` 数据渲染收入图表 [Source: docs/stories/006.001.创建财务数据API接口.md#L111-L118]
    - [ ] **添加图表动画** - 实现图表数据加载时的渐入动画和柱形生长动画
  - [ ] `src/client/home/pages/FinancialDashboard/components/DebtRatioMetrics.tsx` - 资产负债率（百分比）模块
    - [ ] **集成API数据** - 使用 `assetLiabilityRatio` 数据渲染资产负债率图表 [Source: docs/stories/006.001.创建财务数据API接口.md#L119-L126]
    - [ ] **添加图表动画** - 实现图表数据加载时的渐入动画和柱形生长动画
- [ ] 创建变动幅度弹窗组件 (AC: 3)
  - [ ] `src/client/home/pages/FinancialDashboard/components/VariationModal.tsx` - 弹窗主组件 [Source: docs/战略部署主页面+弹窗figma-jsx.md#L2135-L2148]
    - [ ] 聚合所有弹窗子组件
    - [ ] 实现点击外部关闭功能
    - [ ] **添加弹窗动画** - 实现弹窗从中心缩放出现和消失的动画效果
  - [ ] 创建弹窗基础组件
    - [ ] `src/client/home/pages/FinancialDashboard/components/ModalOverlay.tsx` - 遮罩层组件 [Source: docs/战略部署主页面+弹窗figma-jsx.md#L2143]
    - [ ] `src/client/home/pages/FinancialDashboard/components/ModalDialog.tsx` - 弹出框容器组件 [Source: docs/战略部署主页面+弹窗figma-jsx.md#L460-L511]
    - [ ] `src/client/home/pages/FinancialDashboard/components/ModalContent.tsx` - 弹出框数据内容组件 [Source: docs/战略部署主页面+弹窗figma-jsx.md#L2145-L2148]
    - [ ] `src/client/home/pages/FinancialDashboard/components/ModalHeader.tsx` - 弹窗头部组件（包含"变动幅度"标题）
    - [ ] `src/client/home/pages/FinancialDashboard/components/ModalDataRow.tsx` - 弹窗数据行组件（包含财务指标和数值）
    - [ ] `src/client/home/pages/FinancialDashboard/components/ModalCloseButton.tsx` - 返回按钮组件
- [ ] 创建组件单元测试 (AC: 1, 2, 3)
  - [ ] `tests/unit/client/home/pages/FinancialDashboard/FinancialDashboard.test.tsx` - 主页面测试
    - [ ] **测试API数据集成** - 验证主页面正确调用 `/api/v1/dash/outlook` 接口并渲染数据
  - [ ] `tests/unit/client/home/pages/FinancialDashboard/components/Icon.test.tsx` - 图标组件测试
  - [ ] `tests/unit/client/home/pages/FinancialDashboard/components/ReportHeader.test.tsx` - 报表头部测试
  - [ ] `tests/unit/client/home/pages/FinancialDashboard/components/BarElement.test.tsx` - 柱形元素测试
    - [ ] **测试动画效果** - 验证柱形生长动画、悬停效果和加载动画正常工作
  - [ ] `tests/unit/client/home/pages/FinancialDashboard/components/DataLabel.test.tsx` - 数据标签测试
  - [ ] `tests/unit/client/home/pages/FinancialDashboard/components/AssetMetrics.test.tsx` - 资产模块测试
    - [ ] **测试API数据渲染** - 验证 `assetTotalNet` 数据正确渲染为资产总额与资产净额图表
  - [ ] `tests/unit/client/home/pages/FinancialDashboard/components/ProfitMetrics.test.tsx` - 利润模块测试
    - [ ] **测试API数据渲染** - 验证 `profitTotalNet` 数据正确渲染为利润总额与净利润图表
  - [ ] `tests/unit/client/home/pages/FinancialDashboard/components/IncomeMetrics.test.tsx` - 收入模块测试
    - [ ] **测试API数据渲染** - 验证 `incomeStatement` 数据正确渲染为收入图表
  - [ ] `tests/unit/client/home/pages/FinancialDashboard/components/DebtRatioMetrics.test.tsx` - 资产负债率模块测试
    - [ ] **测试API数据渲染** - 验证 `assetLiabilityRatio` 数据正确渲染为资产负债率图表
  - [ ] `tests/unit/client/home/pages/FinancialDashboard/components/VariationModal.test.tsx` - 弹窗主组件测试
    - [ ] 测试弹窗显示/隐藏功能
    - [ ] 测试点击外部关闭功能
    - [ ] **测试弹窗动画** - 验证弹窗缩放动画正常工作
  - [ ] `tests/unit/client/home/pages/FinancialDashboard/components/ModalOverlay.test.tsx` - 遮罩层组件测试
  - [ ] `tests/unit/client/home/pages/FinancialDashboard/components/ModalDialog.test.tsx` - 弹出框容器测试
  - [ ] `tests/unit/client/home/pages/FinancialDashboard/components/ModalContent.test.tsx` - 弹出框数据内容测试
  - [ ] `tests/unit/client/home/pages/FinancialDashboard/components/ModalHeader.test.tsx` - 弹窗头部组件测试
  - [ ] `tests/unit/client/home/pages/FinancialDashboard/components/ModalDataRow.test.tsx` - 弹窗数据行组件测试
  - [ ] `tests/unit/client/home/pages/FinancialDashboard/components/ModalCloseButton.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)
- **动画库**: Framer Motion (推荐) - 为图表数据柱添加流畅的动画效果
- **图表实现**: **自定义React组件** (基于Figma设计，不使用Recharts)

### 图表实现技术决策
**选择自定义React组件而非Recharts的原因**:

1. **设计还原度**: Figma设计包含复杂的渐变、装饰元素和精确的视觉效果，Recharts难以完全还原
2. **动画控制**: 自定义组件可以精确控制每个柱形的生长动画、悬停效果和过渡动画
3. **性能优化**: 针对大屏展示优化，避免Recharts的通用性带来的性能开销
4. **维护性**: 完全控制组件结构和样式，便于后续定制和维护

**基于Figma设计的组件特点** [Source: docs/战略部署主页面figma-jsx.md#L130-L317]:
- 每个柱形元素都是独立的React组件
- 支持多种颜色变体：蓝色渐变、黄色渐变、紫色渐变等
- 包含复杂的装饰元素和渐变效果
- 使用绝对定位和精确像素控制

### 动画效果规范
**推荐动画库**: Framer Motion (性能优秀，API简洁)

**动画效果要求**:
- **柱形生长动画**: 数据柱从底部向上生长，持续0.5-1秒
- **悬停交互效果**: 鼠标悬停时柱形轻微放大(1.05倍)和阴影加深
- **加载骨架动画**: 数据加载时显示骨架屏，有脉动效果
- **弹窗缩放动画**: 弹窗从中心缩放出现，持续0.3秒
- **渐入动画**: 图表整体渐入显示，持续0.5秒

**性能要求**:
- 动画帧率保持60fps
- 避免过度动画影响页面性能
- 支持用户偏好设置（减少动画选项）

### 设计组件规范 [Source: docs/战略部署主页面figma-jsx.md#L1-L1330]
基于Figma设计文档，需要实现以下核心组件：

**基础组件** [Source: docs/战略部署主页面figma-jsx.md#L73-L347]:
- `icon` - 返回按钮图标组件，包含旋转和缩放变换 [Source: docs/战略部署主页面figma-jsx.md#L73-L96]
- `Component` - 报表头部组件，包含渐变背景和标题 [Source: docs/战略部署主页面figma-jsx.md#L98-L117]
- `Component1` - 底框组件，作为容器背景 [Source: docs/战略部署主页面figma-jsx.md#L119-L125]
- `Component2` - 头部组件，作为容器顶部 [Source: docs/战略部署主页面figma-jsx.md#L127-L129]
- `Component3` - 柱形元素组件，支持多种颜色变体 [Source: docs/战略部署主页面figma-jsx.md#L130-L317]:
  - `property2="1-1"` - 资产总额柱形（蓝色渐变）[Source: docs/战略部署主页面figma-jsx.md#L210-L246]
  - `property2="1-2"` - 资产净额柱形（黄色渐变）[Source: docs/战略部署主页面figma-jsx.md#L173-L209]
  - `property2="2-1"` - 利润总额柱形（黄色渐变）[Source: docs/战略部署主页面figma-jsx.md#L283-L317]
  - `property2="2-3"` - 净利润柱形（紫色渐变）[Source: docs/战略部署主页面figma-jsx.md#L247-L282]
  - `property2="2-4"` - 资产负债率柱形（蓝色渐变）[Source: docs/战略部署主页面figma-jsx.md#L136-L172]
- `Component7` - 定位数据组件，包含数值显示和装饰元素 [Source: docs/战略部署主页面figma-jsx.md#L318-L336]
- `IconTime` - 时间图标组件 [Source: docs/战略部署主页面figma-jsx.md#L338-L347]
- `Component4` - 底部网格组件，包含背景网格图案 [Source: docs/战略部署主页面figma-jsx.md#L349-L362]
- `Component5` - 常规界面组件，包含背景图片和遮罩层 [Source: docs/战略部署主页面figma-jsx.md#L363-L378]

**主页面组件结构** [Source: docs/战略部署主页面figma-jsx.md#L380-L1329]:
- `Component6` - 战略部署主页面，聚合所有子组件 [Source: docs/战略部署主页面figma-jsx.md#L380-L1329]
- 包含四个主要数据模块：资产负债率、收入、利润总额与净利润、资产负债率（百分比）
- 每个模块包含：头部标题、数据表格、柱形图、坐标轴、数值标签

**样式规范**:
- **字体**: HarmonyOS_Sans_SC:Regular, PingFang_SC:Regular, PingFang_SC:Medium, PingFang_SC:Heavy
- **颜色**: 白色文本，半透明文本，渐变背景
- **布局**: 绝对定位，精确像素控制
- **特效**: 阴影、模糊、渐变、旋转变换

### 项目结构信息 [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: docs/战略部署主页面figma-jsx.md#L380-L1329]:
- **主页面**: `https://www.figma.com/design/mTu6gamzMFEybbSb8WssKK/可视化素材2-25?node-id=1715-121572&m=dev` - 财务数据可视化大屏主页面设计，包含四个数据模块

### 分辨率要求
**严格遵循1920*1080分辨率**:
- 所有布局和尺寸必须严格按照1920*1080分辨率实现
- 确保在大屏设备上完美显示，无缩放或变形
- 组件位置和间距必须精确匹配Figma设计
- 字体大小、图标尺寸等视觉元素必须保持设计比例

**弹窗设计** [Source: docs/战略部署主页面+弹窗figma-jsx.md#L2135-L2148]:
**四个层次构成**:
1. **遮罩层** (Overlay) - `https://www.figma.com/design/mTu6gamzMFEybbSb8WssKK/可视化素材2-25?node-id=1949-81702&m=dev` - 背景遮罩，提供视觉隔离和点击外部关闭功能 [Source: docs/战略部署主页面+弹窗figma-jsx.md#L2137-L2140]
2. **弹出框** (Dialog Container) - `https://www.figma.com/design/mTu6gamzMFEybbSb8WssKK/可视化素材2-25?node-id=1949-81703&m=dev` - 弹窗主体容器，包含边框、阴影和圆角样式 [Source: docs/战略部署主页面+弹窗figma-jsx.md#L2144]
3. **弹出框数据** (Dialog Content) - `https://www.figma.com/design/mTu6gamzMFEybbSb8WssKK/可视化素材2-25?node-id=1949-81714&m=dev` - 弹窗内容区域，展示财务数据详情 [Source: docs/战略部署主页面+弹窗figma-jsx.md#L2145-L2148]
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年数据，单位：%

### 技术转换说明
**Figma转JSX代码转换要求** [Source: docs/战略部署主页面figma-jsx.md#L1331-L1340]:
- **技术栈适配**: 将生成的React+Tailwind代码转换为项目现有技术栈
- **样式系统转换**: 将Tailwind类名转换为项目现有样式系统，同时保持精确的视觉设计
- **组件模式**: 遵循项目现有的组件模式和约定
- **依赖管理**: 不安装Tailwind作为依赖，除非用户明确指示

**关键转换规则**:
- 分析目标代码库以识别：技术栈、样式方法、组件模式、设计标记
- 将React语法转换为目标框架/库
- 将所有Tailwind类转换为目标样式系统，同时保持精确的视觉设计
- 遵循项目的现有模式和约定

### 图片资源规范
**图片下载和引用规范**:
- **图片位置**: 所有静态图片统一放在 `public/financial-dashboard/` 目录下
- **下载方法**: 使用 `wget` 直接从Figma提供的图片URL下载
- **引用方式**: 使用绝对路径 `/financial-dashboard/{图片文件名}` 引用
- **命名规范**: 保持Figma文档中的原始图片变量名作为文件名

**图片下载示例**:
```bash
# 在 public/financial-dashboard/ 目录下执行
wget -O ellipse4119.png "https://www.figma.com/api/mcp/asset/fcf74522-1000-42fd-8999-d2f9337c522e"
wget -O icon-path.png "https://www.figma.com/api/mcp/asset/6e33453e-bfea-4c73-abb8-93813828acd2"
```

**组件引用示例**:
```jsx
<img alt="" className="block max-w-none size-full" src="/financial-dashboard/ellipse4119.png" />
```

### 编码标准 [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.7 | 引入前端动画库，为图表数据柱和弹窗添加动画效果任务 | Bob (Scrum Master) |
| 2025-11-14 | 1.6 | 按照Figma设计将弹窗分解为多个组件，添加详细的弹窗组件任务 | Bob (Scrum Master) |
| 2025-11-14 | 1.5 | 集成财务数据API接口调用任务，为四个数据模块添加API数据集成和测试 | Bob (Scrum Master) |
| 2025-11-14 | 1.4 | 添加详细的Figma转JSX文档引用位置，标识准确的代码行号 | Bob (Scrum Master) |
| 2025-11-14 | 1.3 | 重写主页面组件任务，细化基础组件实现要求 | Bob (Scrum Master) |
| 2025-11-14 | 1.2 | 基于战略部署主页面Figma设计文档更新组件规范和任务列表 | Bob (Scrum Master) |
| 2025-11-14 | 1.1 | 添加严格的1920*1080分辨率要求 | Bob (Scrum Master) |
| 2025-11-14 | 1.0 | 初始故事创建 | Bob (Scrum Master) |

## Dev Agent Record

### Agent Model Used

### Debug Log References

### Completion Notes List

### File List

## QA Results