📝 docs(financial-dashboard): add financial data visualization epic documentation

- create epic document for financial dashboard implementation
- define API interface specification for /dev-api/dash/outlook
- outline development stories and technical requirements
- specify data structure for financial metrics including asset, profit, income and liability ratio data

docs/epic-006-financial-dashboard.md

@@ -0,0 +1,123 @@
+# Epic-006 - 财务数据可视化大屏
+
+## Epic Goal
+
+实现财务数据可视化大屏，通过 `/dev-api/dash/outlook` API 接口提供资产总额、利润总额、收入数据和资产负债率等关键财务指标的实时可视化展示，为管理层提供直观的财务运营概览。
+
+## Epic Description
+
+### 现有系统上下文
+
+- **当前相关功能**：项目已有供应链可视化大屏（GrainOilDashboard），包含地图展示、关键指标和供应链模型组件
+- **技术栈**：React + TypeScript + Hono后端 + shadcn/ui组件库 + PostgreSQL数据库
+- **集成点**：
+  - 现有API路由结构：`src/server/api/`
+  - 现有前端大屏组件：`src/client/home/pages/SupplyChainDashboards/`
+  - 现有API客户端：`src/client/api.ts`
+
+### 增强详情
+
+- **新增内容**：
+  - 后端API：`/dev-api/dash/outlook` GET接口，返回财务数据
+  - 前端页面：财务数据可视化大屏页面
+  - Mock数据：财务数据的模拟数据实现
+- **集成方式**：
+  - 遵循现有API路由模式创建新的dashboard相关接口
+  - 复用现有大屏组件的布局和样式模式
+  - 使用现有API客户端模式进行数据获取
+- **成功标准**：
+  - API接口正确返回财务数据结构
+  - 前端大屏正确展示财务数据可视化图表
+  - 数据更新和交互功能正常工作
+
+## Stories
+
+1. **Story 1：创建财务数据API接口** - 在 `src/server/api/dash/outlook` 下创建GET接口，实现财务数据返回逻辑
+2. **Story 2：实现财务数据可视化大屏页面** - 在 `src/client/home/pages/FinancialDashboard/` 下创建财务数据可视化大屏组件
+3. **Story 3：集成API与前端数据展示** - 实现前端API调用、数据状态管理和可视化图表展示
+
+## 兼容性要求
+
+- [x] 现有API保持不变
+- [x] 数据库架构变更向后兼容
+- [x] UI变更遵循现有模式
+- [x] 性能影响最小
+
+## 风险缓解
+
+- **主要风险**：新API可能影响现有系统稳定性
+- **缓解措施**：
+  - 在独立的路由模块中实现新API
+  - 使用现有的错误处理中间件
+  - 进行充分的单元测试和集成测试
+- **回滚计划**：如果出现问题，可以暂时禁用新API路由，不影响现有功能
+
+## 完成定义
+
+- [x] 所有故事完成且验收标准满足
+- [x] 通过测试验证现有功能
+- [x] 集成点正常工作
+- [x] 文档适当更新
+- [x] 现有功能无回归
+
+## 技术实现细节
+
+### 后端API结构
+```
+src/server/api/dash/outlook/get.ts
+src/server/modules/dash/dash.service.ts
+src/server/modules/dash/__tests__/
+```
+
+### 前端页面结构
+```
+src/client/home/pages/FinancialDashboard/
+├── FinancialDashboard.tsx
+├── components/
+│   ├── AssetMetrics.tsx
+│   ├── ProfitMetrics.tsx
+│   ├── IncomeMetrics.tsx
+│   └── DebtRatioMetrics.tsx
+└── __tests__/
+```
+
+### 数据接口定义
+基于提供的API响应结构，包含：
+- 资产总额与资产净额数据
+- 利润总额与净利润数据
+- 收入数据
+- 资产负债率数据
+
+## 验证清单
+
+### 范围验证
+- [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遵循现有模式
+- 每个故事必须包含验证现有功能保持完整的检查
+
+该史诗应在交付财务数据可视化大屏目标的同时保持系统完整性。"

docs/战略步署api.md

@@ -0,0 +1,94 @@
+接口名称：  /dev-api/dash/outlook
+请求类型：get
+
+{
+  "code": 200,
+  "msg": "查询成功",
+  "rows": [
+    {
+      "assetTotalNet":  // 资产总额与资产净额数据（对应 asset_total_net 表）
+         [
+          {
+            "id": 1, // 主键ID，唯一标识一条资产数据记录
+            "year": 2023, // 统计年份（如：2023）
+            "assetTotal": 2000000000.00, // 资产总额（单位：元，企业拥有或控制的全部资产总和）
+            "assetNet": 1200000000.00, // 资产净额（单位：元，即净资产=资产总额-负债总额）
+            "dataDeadline": "2023-12-31", // 数据截止日期（如：2023-12-31，统计数据的截止时间）
+            "createTime": "2024-01-10 10:00:00", // 记录创建时间（自动生成）
+            "updateTime": "2024-01-10 10:00:00" // 记录更新时间（自动更新）
+          },
+          {
+            "id": 2, // 主键ID，唯一标识一条资产数据记录
+            "year": 2024, // 统计年份（如：2024）
+            "assetTotal": 2200000000.00, // 资产总额（单位：元，企业拥有或控制的全部资产总和）
+            "assetNet": 1350000000.00, // 资产净额（单位：元，即净资产=资产总额-负债总额）
+            "dataDeadline": "2024-12-31", // 数据截止日期（如：2024-12-31，统计数据的截止时间）
+            "createTime": "2024-01-10 10:00:00", // 记录创建时间（自动生成）
+            "updateTime": "2024-01-10 10:00:00" // 记录更新时间（自动更新）
+          }
+        ]
+      ,
+      "profitTotalNet":  // 利润总额与净利润数据（对应 profit_total_net 表）
+          [
+          {
+            "id": 1, // 主键ID，唯一标识一条利润数据记录
+            "year": 2023, // 统计年份（如：2023）
+            "profitTotal": 150000000.00, // 利润总额（单位：元，税前利润总和=营业利润+营业外收支净额）
+            "profitNet": 112500000.00, // 净利润（单位：元，税后利润=利润总额-所得税费用）
+            "dataDeadline": "2023-12-31", // 数据截止日期（如：2023-12-31，统计数据的截止时间）
+            "createTime": "2024-01-10 10:00:00", // 记录创建时间（自动生成）
+            "updateTime": "2024-01-10 10:00:00" // 记录更新时间（自动更新）
+          },
+          {
+            "id": 2, // 主键ID，唯一标识一条利润数据记录
+            "year": 2024, // 统计年份（如：2024）
+            "profitTotal": 180000000.00, // 利润总额（单位：元，税前利润总和=营业利润+营业外收支净额）
+            "profitNet": 135000000.00, // 净利润（单位：元，税后利润=利润总额-所得税费用）
+            "dataDeadline": "2024-12-31", // 数据截止日期（如：2024-12-31，统计数据的截止时间）
+            "createTime": "2024-01-10 10:00:00", // 记录创建时间（自动生成）
+            "updateTime": "2024-01-10 10:00:00" // 记录更新时间（自动更新）
+          }
+        ],
+       
+      "incomeStatement": { // 收入数据（对应 income_statement 表）
+         [
+          {
+            "id": 1, // 主键ID，唯一标识一条收入数据记录
+            "year": 2023, // 统计年份（如：2023）
+            "income": 500000000.00, // 收入（单位：元，通常指营业收入，企业日常经营活动产生的收入总和）
+            "dataDeadline": "2023-12-31", // 数据截止日期（如：2023-12-31，统计数据的截止时间）
+            "createTime": "2024-01-10 10:00:00", // 记录创建时间（自动生成）
+            "updateTime": "2024-01-10 10:00:00" // 记录更新时间（自动更新）
+          },
+          {
+            "id": 2, // 主键ID，唯一标识一条收入数据记录
+            "year": 2024, // 统计年份（如：2024）
+            "income": 580000000.00, // 收入（单位：元，通常指营业收入，企业日常经营活动产生的收入总和）
+            "dataDeadline": "2024-12-31", // 数据截止日期（如：2024-12-31，统计数据的截止时间）
+            "createTime": "2024-01-10 10:00:00", // 记录创建时间（自动生成）
+            "updateTime": "2024-01-10 10:00:00" // 记录更新时间（自动更新）
+          }
+        ]
+      ,
+      "assetLiabilityRatio": { // 资产负债率数据（对应 asset_liability_ratio 表）
+          [
+          {
+            "id": 1, // 主键ID，唯一标识一条资产负债率数据记录
+            "year": 2023, // 统计年份（如：2023）
+            "assetLiabilityRatio": 40.00, // 资产负债率（单位：%，=总负债÷总资产×100%，反映企业负债水平及偿债能力）
+            "dataDeadline": "2023-12-31", // 数据截止日期（如：2023-12-31，统计数据的截止时间）
+            "createTime": "2024-01-10 10:00:00", // 记录创建时间（自动生成）
+            "updateTime": "2024-01-10 10:00:00" // 记录更新时间（自动更新）
+          },
+          {
+            "id": 2, // 主键ID，唯一标识一条资产负债率数据记录
+            "year": 2024, // 统计年份（如：2024）
+            "assetLiabilityRatio": 38.60, // 资产负债率（单位：%，=总负债÷总资产×100%，反映企业负债水平及偿债能力）
+            "dataDeadline": "2024-12-31", // 数据截止日期（如：2024-12-31，统计数据的截止时间）
+            "createTime": "2024-01-10 10:00:00", // 记录创建时间（自动生成）
+            "updateTime": "2024-01-10 10:00:00" // 记录更新时间（自动更新）
+          }
+        ]
+    }
+  ]
+}