# Epic-006 - 财务数据可视化大屏

## Epic Goal

实现财务数据可视化大屏，通过 `/dev-api/dash/outlook` API 接口提供资产总额、资产净额、利润总额、净利润、收入数据和资产负债率等关键财务指标的实时可视化展示，为管理层提供直观的财务运营概览。大屏设计包含四个主要数据模块：资产负债率、收入、利润总额与净利润、资产负债率（百分比）。

## Epic Description

### 现有系统上下文

- **当前相关功能**：项目已有供应链可视化大屏（GrainOilDashboard），包含地图展示、关键指标和供应链模型组件
- **技术栈**：React + TypeScript + Hono后端 + shadcn/ui组件库 + Tailwind CSS + PostgreSQL数据库
- **集成点**：
  - 现有API路由结构：`src/server/api/`
  - 现有前端大屏组件：`src/client/home/pages/SupplyChainDashboards/`
  - 现有API客户端：`src/client/api.ts`
  - 现有可视化组件：`src/client/components/ui/chart.tsx` (基于Recharts)
- **参考文档**：
  - API接口规范：`/mnt/code/182-169-template-6/docs/战略步署api.md` - 包含财务数据API的完整接口定义和数据结构
  - UI设计原型：
    - 主页面：`https://www.figma.com/design/mTu6gamzMFEybbSb8WssKK/可视化素材2-25?node-id=1715-121572&m=dev` - 财务数据可视化大屏主页面设计，包含四个数据模块
    - 弹窗层构成：

      **弹窗由四个层次组合构成**：

      1. **遮罩层** (Overlay) - 背景遮罩，提供视觉隔离和点击外部关闭功能
         @https://www.figma.com/design/mTu6gamzMFEybbSb8WssKK/%E5%8F%AF%E8%A7%86%E5%8C%96%E7%B4%A0%E6%9D%902-25?node-id=1949-81702&m=dev

      2. **弹出框** (Dialog Container) - 弹窗主体容器，包含边框、阴影和圆角样式
         @https://www.figma.com/design/mTu6gamzMFEybbSb8WssKK/%E5%8F%AF%E8%A7%86%E5%8C%96%E7%B4%A0%E6%9D%902-25?node-id=1949-81703&m=dev

      3. **弹出框数据** (Dialog Content) - 弹窗内容区域，展示财务数据详情
         @https://www.figma.com/design/mTu6gamzMFEybbSb8WssKK/%E5%8F%AF%E8%A7%86%E5%8C%96%E7%B4%A0%E6%9D%902-25?node-id=1949-81714&m=dev

      4. **返回按钮** (Action Controls) - 弹窗操作控件，包含关闭按钮和交互元素
         @https://www.figma.com/design/mTu6gamzMFEybbSb8WssKK/%E5%8F%AF%E8%A7%86%E5%8C%96%E7%B4%A0%E6%9D%902-25?node-id=1949-82235&m=dev

      - 点击变动幅度按钮后弹出的弹窗设计，基于上述四个层次构成实现

### 增强详情

- **新增内容**：
  - 后端API：`/dev-api/dash/outlook` GET接口，返回财务数据
  - 前端页面：财务数据可视化大屏页面，包含四个数据模块
  - Mock数据：财务数据的模拟数据实现
  - 可视化组件：基于Recharts的柱状图组件，支持多数据系列展示
- **集成方式**：
  - 遵循现有API路由模式创建新的dashboard相关接口
  - 复用现有大屏组件的布局和样式模式
  - 使用现有API客户端模式进行数据获取
  - 使用现有Recharts组件库实现数据可视化
- **成功标准**：
  - API接口正确返回财务数据结构
  - 前端大屏正确展示四个数据模块的可视化图表
  - 数据更新和交互功能正常工作
  - 变动幅度弹窗功能正常

## Stories

1. **✅ Story 1：创建财务数据API接口** - 在 `src/server/api/dash/outlook` 下创建GET接口，实现财务数据返回逻辑，包含四个数据模块：资产总额与资产净额、利润总额与净利润、收入、资产负债率
   - **状态**: 已完成
   - **故事文件**: `docs/stories/006.001.创建财务数据API接口.md`
   - **完成时间**: 2025-11-14
   - **API端点**: `GET /api/v1/dash/outlook`

2. **Story 2：实现财务数据可视化大屏页面** - 在 `src/client/home/pages/FinancialDashboard/` 下创建财务数据可视化大屏组件，包括：
   - 主页面（参考：`node-id=1715-121572`）- 包含四个数据模块的可视化展示
   - 变动幅度弹窗（参考四个层次构成：遮罩层、弹出框、弹出框数据、返回按钮）- 点击右下角浮动按钮后显示

3. **Story 3：集成API与前端数据展示** - 实现前端API调用、数据状态管理和可视化图表展示，使用Recharts组件库实现柱状图可视化

## 兼容性要求

- [x] 现有API保持不变
- [x] 数据库架构变更向后兼容
- [x] UI变更遵循现有模式
- [x] 性能影响最小

## 风险缓解

- **主要风险**：新API可能影响现有系统稳定性
- **缓解措施**：
  - 在独立的路由模块中实现新API
  - 使用现有的错误处理中间件
  - 进行充分的单元测试和集成测试
- **回滚计划**：如果出现问题，可以暂时禁用新API路由，不影响现有功能

## 完成定义

- [ ] 所有故事完成且验收标准满足
- [x] 通过测试验证现有功能
- [x] 集成点正常工作
- [x] 文档适当更新
- [x] 现有功能无回归

## 完成进度

### 当前进度：33% (1/3 故事完成)

**已完成**:
- ✅ Story 1: 财务数据API接口
  - API端点: `GET /api/v1/dash/outlook`
  - 状态: 已完成并测试通过
  - 功能: 返回四个财务数据模块的mock数据

**待完成**:
- ⏳ Story 2: 财务数据可视化大屏页面
- ⏳ Story 3: 集成API与前端数据展示

## 技术实现细节

### 后端API结构
```
src/server/api/dash/outlook/get.ts ✅ 已完成
src/server/api/dash/index.ts ✅ 已完成
src/server/modules/dash/dash.service.ts ✅ 已完成
tests/integration/server/api/dash/outlook/get.test.ts ✅ 已完成
```

### 前端页面结构
```
src/client/home/pages/FinancialDashboard/
├── FinancialDashboard.tsx
├── components/
│   ├── AssetMetrics.tsx          # 资产负债率模块（资产总额与资产净额）
│   ├── ProfitMetrics.tsx         # 利润总额与净利润模块
│   ├── IncomeMetrics.tsx         # 收入模块
│   ├── DebtRatioMetrics.tsx      # 资产负债率（百分比）模块
│   └── VariationModal.tsx        # 变动幅度弹窗组件（基于四个层次构成：遮罩层、弹出框、弹出框数据、返回按钮）
tests/client/home/pages/FinancialDashboard/
```

### 数据接口定义
基于提供的API响应结构（详细定义见 `/mnt/code/182-169-template-6/docs/战略步署api.md`），包含：
- **资产总额与资产净额数据**：2023-2024年数据，单位：元 ✅ 已实现
- **利润总额与净利润数据**：2023-2024年数据，单位：元 ✅ 已实现
- **收入数据**：2023-2024年数据，单位：元 ✅ 已实现
- **资产负债率数据**：2023-2024年数据，单位：% ✅ 已实现

**当前实现状态**: 使用固定的mock数据，包含2023-2024两年的财务数据，为前端可视化提供测试数据。

## 验证清单

### 范围验证
- [x] Epic可在1-3个故事内完成
- [x] 不需要架构文档
- [x] 增强遵循现有模式
- [x] 集成复杂度可控

### 风险评估
- [x] 对现有系统风险低
- [x] 回滚计划可行
- [x] 测试方法覆盖现有功能
- [x] 团队对集成点有足够了解

### 完整性检查
- [x] Epic目标清晰可实现
- [x] 故事范围适当
- [x] 成功标准可衡量
- [x] 依赖关系已识别

---

**故事经理交接：**

"请为此棕地史诗开发详细的用户故事。关键考虑因素：

- 这是对运行 React + TypeScript + Hono + PostgreSQL 技术栈的现有系统的增强
- 集成点：现有API路由结构、现有大屏组件模式、现有API客户端
- 要遵循的现有模式：kebab-case文件命名、模块化API路由、组件化前端架构
- 关键兼容性要求：现有API保持不变、数据库架构向后兼容、UI遵循现有模式
- 每个故事必须包含验证现有功能保持完整的检查

该史诗应在交付财务数据可视化大屏目标的同时保持系统完整性。"