vscode-workbench/.trae/specs/currency-exchange-api/spec.md

汇率转换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

无