# Story 006.001: 创建财务数据API接口

## Status
Ready for Review

## Story
**As a** 财务数据可视化大屏用户，
**I want** 通过 `/dev-api/dash/outlook` API 接口获取财务数据，
**so that** 我可以在前端大屏中查看资产总额、资产净额、利润总额、净利润、收入和资产负债率等关键财务指标的实时可视化展示。

**重要说明**: 这是一个公开API，不需要认证，不需要数据库访问，直接返回固定的mock数据。

## Acceptance Criteria
1. 在 `src/server/api/dash/outlook` 下创建GET接口
2. 实现财务数据返回逻辑，包含四个数据模块：
   - 资产总额与资产净额
   - 利润总额与净利润
   - 收入
   - 资产负债率
3. API接口正确返回财务数据结构
4. 数据更新和交互功能正常工作

## Tasks / Subtasks
- [x] 创建API路由文件 `src/server/api/dash/outlook/get.ts` (AC: 1)
  - [x] 参考 `src/server/api/auth/me/get.ts` 实现GET路由处理函数
  - [x] 使用 `@hono/zod-openapi` 创建路由定义
  - [x] **不需要认证中间件** - 这是一个公开API
  - [x] **不需要数据库访问** - 直接返回固定的mock数据
  - [x] 配置路由导出
- [x] 创建业务模块 `src/server/modules/dash/dash.service.ts` (AC: 2)
  - [x] 实现财务数据获取逻辑
  - [x] **使用固定的mock数据** - 不需要数据库查询
  - [x] 定义财务数据接口类型
- [x] 实现四个数据模块的数据结构 (AC: 2)
  - [x] 资产总额与资产净额数据结构
  - [x] 利润总额与净利润数据结构
  - [x] 收入数据结构
  - [x] 资产负债率数据结构
- [x] 创建集成测试 `tests/integration/server/api/dash/outlook/get.test.ts` (AC: 3, 4)
  - [x] 参考现有API集成测试实现测试用例
  - [x] 测试API端点响应
  - [x] 测试错误处理

## Dev Notes

### 技术栈信息 [Source: architecture/tech-stack.md#现有技术栈维护]
- **后端框架**: Hono 4.8.5 (Web框架和API路由，RPC类型安全)
- **数据库**: PostgreSQL 17 (通过TypeORM)
- **ORM**: TypeORM 0.3.25 (数据库操作抽象，实体管理)
- **测试框架**: Vitest + hono/testing (API端点测试)

### 项目结构信息 [Source: architecture/source-tree.md#实际项目结构]
- **API路由位置**: `src/server/api/dash/outlook/` (遵循现有API路由模式)
- **业务模块位置**: `src/server/modules/dash/` (遵循现有模块结构)
- **测试位置**:
  - 单元测试: `tests/server/modules/dash/`
  - 集成测试: `tests/server/api/dash/outlook/`

### API设计规范 [Source: architecture/api-design-integration.md#API集成策略]
- **认证**: **不需要认证** - 这是一个公开API
- **版本控制**: 使用v1前缀 (`/api/v1/`)，保持向后兼容
- **响应格式**: 遵循现有API响应模式
- **数据来源**: 使用固定的mock数据，不需要数据库访问

### 可参考的现有API路径
- **用户管理API**: `src/server/api/users/index.ts` - 使用通用CRUD路由模式
- **文件管理API**: `src/server/api/files/index.ts` - 聚合多个子路由的模式
- **认证API**: `src/server/api/auth/me/get.ts` - 简单的GET接口实现模式

**推荐参考模式**:
- 使用 `src/server/api/auth/me/get.ts` 的简单GET接口模式
- 使用 `@hono/zod-openapi` 创建路由定义
- 遵循现有的响应格式和错误处理模式

### API集成测试参考路径
- **认证API集成测试**: `tests/integration/server/auth.integration.test.ts` - 完整的API集成测试示例
- **文件管理API集成测试**: `tests/integration/server/files/files.integration.test.ts` - 文件相关API测试
- **用户管理API集成测试**: `tests/integration/server/users.integration.test.ts` - 用户相关API测试

**推荐参考测试模式**:
- 使用 `tests/integration/server/auth.integration.test.ts` 作为主要参考
- 使用 `hono/testing` 创建测试客户端
- 使用集成测试数据库钩子
- 遵循现有的测试结构和断言模式

### 数据模型参考 [Source: docs/战略步署api.md]
财务数据接口响应结构：
```typescript
interface FinancialDashboardResponse {
  code: 200;
  msg: "查询成功";
  rows: [{
    assetTotalNet: Array<{
      id: number;
      year: number;
      assetTotal: number; // 资产总额（单位：元）
      assetNet: number;   // 资产净额（单位：元）
      dataDeadline: string;
      createTime: string;
      updateTime: string;
    }>;
    profitTotalNet: Array<{
      id: number;
      year: number;
      profitTotal: number; // 利润总额（单位：元）
      profitNet: number;   // 净利润（单位：元）
      dataDeadline: string;
      createTime: string;
      updateTime: string;
    }>;
    incomeStatement: Array<{
      id: number;
      year: number;
      income: number;      // 收入（单位：元）
      dataDeadline: string;
      createTime: string;
      updateTime: string;
    }>;
    assetLiabilityRatio: Array<{
      id: number;
      year: number;
      assetLiabilityRatio: number; // 资产负债率（单位：%）
      dataDeadline: string;
      createTime: string;
      updateTime: string;
    }>;
  }];
}
```

### 编码标准 [Source: architecture/coding-standards.md#关键集成规则]
- **现有API兼容性**: 确保测试不破坏现有API契约
- **错误处理**: 测试各种错误场景和边界条件
- **日志一致性**: 测试日志格式和错误信息

### 测试要求 [Source: architecture/testing-strategy.md#测试金字塔策略]
- **集成测试**: 使用hono/testing框架，验证API功能和集成
- **测试位置**: `tests/server/api/dash/outlook/`
- **测试数据**: **不需要数据库测试** - 直接验证mock数据返回

### 项目结构对齐
- ✅ API路由位置 `src/server/api/dash/outlook/` 符合现有结构
- ✅ 业务模块位置 `src/server/modules/dash/` 符合现有结构
- ✅ 测试位置 `tests/server/api/dash/outlook/` 符合现有结构
- ✅ 文件命名遵循现有kebab-case命名约定

## Testing
### 测试标准 [Source: architecture/testing-strategy.md#测试金字塔策略]
- **测试框架**: Vitest + hono/testing
- **测试位置**: `tests/server/api/dash/outlook/`
- **测试类型**: API集成测试

### 具体测试要求
- 验证API端点正确返回财务数据结构
- 测试四个数据模块的数据完整性
- 验证错误处理机制
- 确保现有API保持不变

## Change Log
| Date | Version | Description | Author |
|------|---------|-------------|---------|
| 2025-11-14 | 1.3 | 明确说明API为公开、不需要认证、不需要数据库、使用mock数据 | Bob (Scrum Master) |
| 2025-11-14 | 1.2 | 移除单元测试，添加API集成测试参考路径 | Bob (Scrum Master) |
| 2025-11-14 | 1.1 | 添加可参考的现有API路径信息 | Bob (Scrum Master) |
| 2025-11-14 | 1.0 | 初始故事创建 | Bob (Scrum Master) |

## Dev Agent Record

### Agent Model Used
- Claude Code (Developer Agent)

### Debug Log References
- 测试文件路径问题：将测试文件从 `tests/server/api/dash/outlook/get.test.ts` 移动到 `tests/integration/server/api/dash/outlook/get.test.ts`
- 类型错误修复：API错误响应格式与ErrorSchema保持一致
- 导入路径修复：从server/api.ts引入路由
- 客户端路径修复：从 `client.outlook.$get()` 改为 `client.dash.outlook.$get()`
- 数据库配置：创建测试数据库 `test_d8dai`

### Completion Notes List
- ✅ 成功创建财务数据API接口 `/api/v1/dash/outlook`
- ✅ 实现公开API，无需认证和数据库访问
- ✅ 返回固定的mock财务数据，包含四个数据模块
- ✅ 集成测试全部通过，验证API功能和数据结构
- ✅ 代码检查通过，符合项目编码标准
- ✅ 正确集成到主API路由系统
- ✅ 创建测试数据库并配置测试环境

### File List
- **新增文件**:
  - `src/server/api/dash/outlook/get.ts` - API路由文件
  - `src/server/api/dash/index.ts` - Dash路由聚合文件
  - `src/server/modules/dash/dash.service.ts` - 业务服务模块
  - `tests/integration/server/api/dash/outlook/get.test.ts` - 集成测试文件

- **修改文件**:
  - `src/server/api.ts` - 添加dash路由注册

## QA Results
