feat: PLANNING体系首版（00路线图/02任务总表/03执行协议/I-03/I-04/registry42口径）+M1止血交付

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

@@ -0,0 +1,111 @@
+# 汇率转换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
+无