# 汇率转换API Spec

## Why
当前系统缺少货币汇率转换功能，用户无法进行实时汇率查询和货币换算。需要开发汇率转换API后端及前端详情页，提供实时汇率查询和货币转换能力。

## What Changes

### 后端变更
- 新增 `currency/` Django应用，实现汇率转换API视图
- 调用免费汇率API（使用 https://open.er-api.com，无需API Key）
- 添加Redis缓存机制，缓存汇率数据15分钟以减少外部API调用
- 添加Swagger文档支持
- 注册URL路由 `/api/currency/`

### 前端变更
- 新增 `CurrencyDetail` 页面，提供汇率查询和货币转换功能
- 包含API文档标签页和在线测试标签页
- 支持选择源货币和目标货币
- 显示实时汇率和转换结果
- 添加路由配置

### 配置变更
- 添加汇率API基础URL到Django settings（可选配置）
- 无需额外第三方库（使用已有的requests库）

## Impact
- Affected specs: 无
- Affected code:
  - `chunyu_project/currency/` (新增Django应用)
  - `chunyu_project/api/urls.py` (修改，添加currency路由)
  - `chunyu_project_react/src/pages/CurrencyDetail/` (新增)
  - `chunyu_project_react/src/utils/request.ts` (修改，添加currency API)
  - `chunyu_project_react/src/routes/` (修改，添加路由)

## ADDED Requirements

### Requirement: 汇率查询API
The system SHALL provide a currency exchange rate API that returns real-time exchange rates for a given base currency.

#### Scenario: 成功查询汇率
- **WHEN** 用户发送 GET 请求到 `/api/currency/rates/`，携带 `base` 参数（如 USD）
- **THEN** 系统返回 200 状态码及汇率数据（基础货币、汇率日期、各货币汇率）

#### Scenario: 查询所有支持的货币列表
- **WHEN** 用户发送 GET 请求到 `/api/currency/currencies/`
- **THEN** 系统返回 200 状态码及支持的货币列表（货币代码、货币名称）

#### Scenario: 货币转换计算
- **WHEN** 用户发送 POST 请求到 `/api/currency/convert/`，携带 `from`、`to`、`amount` 参数
- **THEN** 系统返回 200 状态码及转换结果（源货币、目标货币、金额、汇率、转换结果）

#### Scenario: 缺少必填参数
- **WHEN** 用户发送请求但未携带必填参数
- **THEN** 系统返回 400 状态码及错误提示

#### Scenario: 无效的货币代码
- **WHEN** 用户请求中携带无效的货币代码
- **THEN** 系统返回 400 状态码及错误提示

#### Scenario: 外部API不可用
- **WHEN** 外部汇率服务暂时不可用
- **THEN** 系统返回 503 状态码及友好错误提示

### Requirement: Redis缓存
The system SHALL cache exchange rate data in Redis to reduce external API calls.

#### Scenario: 缓存命中
- **WHEN** 用户查询汇率且缓存中存在有效数据
- **THEN** 系统直接返回缓存数据，不调用外部API

#### Scenario: 缓存未命中
- **WHEN** 用户查询汇率且缓存中无有效数据
- **THEN** 系统调用外部API获取数据，存入缓存后返回

#### Scenario: 缓存过期
- **WHEN** 缓存数据超过15分钟
- **THEN** 系统重新调用外部API获取最新数据

### Requirement: API文档集成
The currency API SHALL be automatically included in the Swagger API documentation.

#### Scenario: Swagger文档显示
- **WHEN** 管理员访问 `/swagger/` 或 `/api-docs/`
- **THEN** 汇率转换API出现在API文档列表中，包含参数说明和响应示例

### Requirement: 前端汇率详情页
The frontend SHALL provide a CurrencyDetail page for currency exchange rate query and conversion.

#### Scenario: 查看API文档
- **WHEN** 用户访问汇率详情页
- **THEN** 系统显示API接口文档，包含请求参数、响应示例、错误码说明

#### Scenario: 在线测试API
- **WHEN** 用户在测试标签页选择货币和金额，点击发送请求
- **THEN** 系统向 `/api/currency/` 相关接口发起真实请求并显示响应结果

#### Scenario: 货币转换
- **WHEN** 用户选择源货币、目标货币和输入金额
- **THEN** 系统显示实时汇率和转换后的金额

## MODIFIED Requirements

### Requirement: ApiDetail页面路由
The frontend routing SHALL include the new CurrencyDetail page.

#### Scenario: 访问汇率详情页
- **WHEN** 用户访问 `/api-detail/currency`
- **THEN** 系统显示汇率转换API详情页

## REMOVED Requirements
无