112 lines
4.3 KiB
Markdown
112 lines
4.3 KiB
Markdown
# 汇率转换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
|
||
无
|