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

✅ Story 1：创建财务数据API接口 - 在 src/server/api/dash/outlook 下创建GET接口，实现财务数据返回逻辑，包含四个数据模块：资产总额与资产净额、利润总额与净利润、收入、资产负债率
- 状态: 已完成
- 故事文件: docs/stories/006.001.创建财务数据API接口.md
- 完成时间: 2025-11-14
- API端点: GET /api/v1/dash/outlook
Story 2：实现财务数据可视化大屏页面 - 在 src/client/home/pages/FinancialDashboard/ 下创建财务数据可视化大屏组件，包括：
- 主页面（参考：node-id=1715-121572）- 包含四个数据模块的可视化展示
- 变动幅度弹窗（参考四个层次构成：遮罩层、弹出框、弹出框数据、返回按钮）- 点击右下角浮动按钮后显示
Story 3：集成API与前端数据展示 - 实现前端API调用、数据状态管理和可视化图表展示，使用Recharts组件库实现柱状图可视化

兼容性要求

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

风险缓解

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

完成定义

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

完成进度

当前进度：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两年的财务数据，为前端可视化提供测试数据。

验证清单

范围验证

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

风险评估

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

完整性检查

Epic目标清晰可实现
故事范围适当
成功标准可衡量
依赖关系已识别

故事经理交接：

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

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

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

epic-006-financial-dashboard.md 7.7 KB Постоянная ссылка История Исходник