From 02ba9ea77fb0b71cd0a7d0e91feb61001c383fa1 Mon Sep 17 00:00:00 2001
From: wangqifan <wangqifan@zhiyun.com>
Date: Mon, 25 Aug 2025 09:38:06 +0800
Subject: [PATCH] =?UTF-8?q?=E6=9B=B4=E6=96=B0=E5=89=8D=E7=AB=AF=E9=A1=B5?=
 =?UTF-8?q?=E9=9D=A2=E4=BB=A5=E6=94=AF=E6=8C=81=E6=8C=89=E4=BB=B7=E6=A0=BC?=
 =?UTF-8?q?=E6=8E=92=E5=BA=8F=E5=8A=9F=E8=83=BD?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 backend/API_DOCUMENTATION.md | 115 +++++++++++++++++++++++++++++++++++
 1 file changed, 115 insertions(+)
 create mode 100644 backend/API_DOCUMENTATION.md

diff --git a/backend/API_DOCUMENTATION.md b/backend/API_DOCUMENTATION.md
new file mode 100644
index 0000000..78f37c8
--- /dev/null
+++ b/backend/API_DOCUMENTATION.md
@@ -0,0 +1,115 @@
+# 云计算价格计算器 API 文档
+
+**描述:** 支持多云平台价格计算的服务。
+
+**基本 URL:** `/api`
+
+---
+
+## 端点
+
+### 1. 获取区域列表
+
+- **描述:** 获取指定平台的可用区域列表。
+- **路径:** `GET /regions`
+- **方法:** `GET`
+- **查询参数:**
+    - `platform` (string, optional, default: "aws"): 云平台。支持的值: "aws", "azure", "aliyun"。
+- **成功响应 (200):**
+    ```json
+    [
+      {
+        "code": "us-east-1",
+        "name": "US East (N. Virginia)"
+      }
+    ]
+    ```
+- **错误响应 (400):** 如果平台不受支持。
+
+---
+
+### 2. 获取实例类型
+
+- **描述:** 获取指定平台的可用实例类型。
+- **路径:** `GET /instance-types`
+- **方法:** `GET`
+- **查询参数:**
+    - `platform` (string, optional, default: "aws"): 云平台。
+- **成功响应 (200):** 包含实例类型及其信息的字典。
+- **错误响应 (400):** 如果平台不受支持。
+
+---
+
+### 3. 搜索实例
+
+- **描述:** 搜索符合指定条件的实例类型。
+- **路径:** `POST /search-instances`
+- **方法:** `POST`
+- **请求体:** `InstanceSearchRequest`
+- **成功响应 (200):** 匹配的实例列表，按月度总价排序。
+- **错误响应 (400):** 如果缺少必需的参数。
+- **错误响应 (500):** 内部服务器错误。
+
+---
+
+### 4. 搜索实例 V2
+
+- **描述:** 使用 MySQL 数据库搜索符合条件的 AWS 实例。
+- **路径:** `POST /search-instances-v2`
+- **方法:** `POST`
+- **请求体:** `InstanceSearchRequestV2`
+- **成功响应 (200):** 匹配的实例列表。
+- **错误响应 (500):** 内部服务器错误。
+
+---
+
+### 5. 比较价格
+
+- **描述:** 比较多种实例配置的价格。
+- **路径:** `POST /compare-prices`
+- **方法:** `POST`
+- **请求体:** `PriceComparison`
+- **成功响应 (200):** 包含配置及其计算价格的列表。
+- **错误响应 (500):** 内部服务器错误。
+
+---
+
+## 数据模型
+
+### `InstanceSearchRequest`
+
+| 字段 | 类型 | 描述 | 默认值 |
+|---|---|---|---|
+| `cpu_cores` | integer | CPU 核心数 | (optional) |
+| `memory_gb` | float | 内存 (GB) | (optional) |
+| `disk_gb` | integer | 磁盘大小 (GB) | (optional) |
+| `region` | string | 区域 | (optional) |
+| `operating_system` | string | 操作系统 | "Linux" |
+| `platform` | string | 云平台 | "aws" |
+
+### `InstanceSearchRequestV2`
+
+| 字段 | 类型 | 描述 | 默认值 |
+|---|---|---|---|
+| `cpu_cores` | integer | CPU 核心数 | (optional) |
+| `memory_gb` | float | 内存 (GB) | (optional) |
+| `disk_gb` | integer | 磁盘大小 (GB) | (optional) |
+| `region` | string | 区域 | (optional) |
+| `operating_system` | string | 操作系统 | "Linux" |
+
+### `PriceComparison`
+
+| 字段 | 类型 | 描述 |
+|---|---|---|
+| `configurations` | List[`PriceRequest`] | 价格请求配置列表 |
+
+### `PriceRequest`
+
+| 字段 | 类型 | 描述 | 默认值 |
+|---|---|---|---|
+| `instance_type` | string | 实例类型 (required) | |
+| `region` | string | 区域 (required) | |
+| `operating_system` | string | 操作系统 (required) | |
+| `purchase_option` | string | 购买选项 (required) | |
+| `duration` | integer | 持续时间 | 1 |
+| `disk_gb` | integer | 磁盘大小 (GB) | 0 |