# 汇率 API v0alpha - 技术文档

## 概述

本文档详细描述了汇率 API v0alpha 的规格。此 API 无需认证即可使用，提供核心的汇率查询与计算功能。

*   **API 根路径 (Base URL):** `https://fxifapi.stevencloudservices.com/v0alpha`
*   **版本:** `v0alpha`
*   **响应格式:** `JSON` (除特别说明的纯文本端点外)
*   **字符编码:** `UTF-8`

---

## 数据传输对象 (DTO)

#### 1. 错误响应 `ErrorDTO`

当 API 请求发生错误时，将返回此标准结构的响应体。

```json
{
  "error": "INVALID_CODE",
  "message": "一个或多个货币代码无效: 'USB'"
}
```

| 字段名       | 类型     | 描述                               |
|:----------|:-------|:---------------------------------|
| `error`   | string | 机器可读的错误代码枚举。详见 [错误代码](#错误代码) 章节。 |
| `message` | string | 人类可读的、关于错误的详细描述。                 |

#### 2. 汇率 `RateDTO`

描述两种货币之间的汇率关系。

```json
{
  "value": 7.32,
  "source": { "code": "USD" },
  "target": { "code": "CNY" },
  "timestamp": "2025-07-08T10:00:00Z"
}
```

| 字段名         | 类型     | 描述                          |
|:------------|:-------|:----------------------------|
| `value`     | number | 汇率值。                        |
| `source`    | string | 源货币（基础货币）的字母代码。             |
| `target`    | string | 目标货币的字母代码。                  |
| `timestamp` | string | 数据更新时的UTC时间戳 (ISO 8601 格式)。 |

#### 3. 计算结果 `CalculationDTO`

用于 `/convert` 端点的响应体。

```json
{
  "source_amount": 100,
  "result_amount": 732.00,
  "rate": { ...RateDTO... }
}
```

| 字段名             | 类型        | 描述              |
|:----------------|:----------|:----------------|
| `source_amount` | number    | 用户传入的源货币金额。     |
| `result_amount` | number    | 计算出的目标货币金额。     |
| `rate`          | `RateDTO` | 本次计算所使用的完整汇率信息。 |

---

## API 端点 (Endpoints)

### 获取单一汇率

**`GET /rate[/{pair}]`**

此端点用于获取单个货币对的最新汇率。支持两种传参方式，**不可混用**。

#### 方式一：路径传参

直接在路径中提供由源货币和目标货币代码拼接而成的6位字母对。

*   **路径参数:**
	*   `pair` (string): 6个字母的货币对代码，例如 `USDCNY`。**大小写不敏感**。
*   **示例请求:**
	`GET /v0alpha/rate/USDCNY`

#### 方式二：查询参数

当未使用路径传参时，可通过查询参数指定源货币和目标货币。

*   **查询参数:**
	*   `from` (string): 源货币的 ISO 4217 字母代码。**大小写不敏感**。
	*   `to` (string): 目标货币的 ISO 4217 字母代码。**大小写不敏感**。
*   **示例请求:**
	`GET /v0alpha/rate?from=USD&to=CNY`

---

**成功响应 (200 OK):**

```json
{
  "value": 7.32,
  "source": "USD",
  "target": "CNY",
  "timestamp": "2025-07-08T10:00:00Z"
}
```

**错误响应示例:**
*   **404 Not Found** (请求了无效的代码)
	```json
	{
	  "error": "INVALID_CODE",
	  "message": "一个或多个货币代码无效: 'USDD'。"
	}
	```

### 汇率计算器 (JSON)

**`GET /convert`**

将指定金额从一种货币转换为另一种，并返回结构化的 `CalculationDTO`。

*   **查询参数:**

	| 参数名      | 类型     | 描述                   | 是否必须 | 示例    |
	|:---------|:-------|:---------------------|:-----|:------|
	| `from`   | string | 源货币的 ISO 4217 字母代码。  | 是    | `EUR` |
	| `to`     | string | 目标货币的 ISO 4217 字母代码。 | 是    | `USD` |
	| `amount` | number | 要转换的金额。              | 是    | `100` |

*   **示例请求:**
	`GET /v0alpha/convert?from=EUR&to=USD&amount=100`

*   **成功响应 (200 OK):**
	```json
	{
	  "source_amount": 100,
	  "result_amount": 106.00,
	  "rate": {
		"value": 1.06,
		"source": "EUR",
		"target": "USD",
		"timestamp": "2025-07-08T10:00:00Z"
	  }
	}
	```
*   **错误响应 (400 Bad Request):**
	```json
	{
	  "error": "BAD_REQUEST",
	  "message": "缺少必要的查询参数: 'amount'"
	}
	```

### 汇率计算器 (纯文本)

**`GET /convert/text`**

功能同上，但直接返回纯文本格式的计算结果。

*   **查询参数:** (同 `/convert`)
*   **示例请求:**
	`GET /v0alpha/convert/text?from=GBP&to=JPY&amount=1`
*   **成功响应 (200 OK):**
	*   `Content-Type: text/plain`
	*   Response Body: `182.5`
*   **错误响应:**
	*   **HTTP 状态码:** `400`, `404` 等
	*   `Content-Type: text/plain`
	*   Response Body: `--`

---

## 错误代码

| 错误代码 (Error Enum)       | HTTP 状态码 | 描述                  |
|:------------------------|:---------|:--------------------|
| `BAD_REQUEST`           | 400      | 请求格式错误，例如缺少必要的查询参数。 |
| `INVALID_CODE`          | 404      | 请求的货币代码不可用或无效。      |
| `INTERNAL_SERVER_ERROR` | 500      | 服务器内部发生未知错误。        |
| `UNMATCHED`             | *        | 其他未匹配的错误。请检查响应消息。   |