docs: 添加完整项目文档

- universal_fetcher_README.md：统一数据获取接口完整文档 - universal_fetcher_QUICKSTART.md：5分钟快速上手指南 - universal_fetcher_ARCHITECTURE.md：架构设计说明 - universal_fetcher_TEST_REPORT.md：测试报告与修复记录 - flask_api_README.md：Flask API 完整文档 - FLASK_SERVICE_SUMMARY.md：项目实现总结总计 2000+ 行文档，涵盖 API 说明、使用示例、架构设计
2026-05-07 21:20:03 +08:00
parent cc2f7cb6c8
commit 0e531a1876
6 changed files with 1926 additions and 0 deletions
--- a/docs/flask_api_README.md
+++ b/docs/flask_api_README.md
@@ -0,0 +1,404 @@
+# Universal Data Fetcher API 文档
+
+## 概述
+
+提供统一的 RESTful API 接口，支持获取各类资产的 K 线数据（OHLCV）。
+
+## 支持的资产类型
+
+- **A股指数**: `000300.SH`, `399006.SZ`, `H30269.CSI`
+- **A股ETF**: `510300.SH`, `159915.SZ`, `513100.SH`
+- **A股股票**: `600000.SH`, `000001.SZ`
+- **港股指数**: `HSI`, `HSTECH.HK`
+- **美股指数**: `NDX`, `SPX`, `DJI`, `N225`, `GDAXI`
+- **美股股票**: `AAPL`, `MSFT`, `GOOGL`, `AMZN`, `TSLA`
+- **期货合约**: `AU.SHF`, `CU.SHF`
+- **加密货币**: `BTC`, `ETH`
+
+## 快速开始
+
+### 1. 启动服务
+
+```bash
+# 基础启动（仅支持A股）
+./start_flask_server.sh
+
+# 启用 SSH 隧道（支持港美股）
+./start_flask_server.sh --with-ssh
+
+# 指定端口
+./start_flask_server.sh --port 8080 --with-ssh
+
+# 调试模式
+./start_flask_server.sh --debug --with-ssh
+```
+
+### 2. 测试 API
+
+```bash
+# 健康检查
+curl http://localhost:5000/health
+
+# 获取K线数据
+curl 'http://localhost:5000/api/v1/ohlcv?code=000300.SH&start=2024-01-01&end=2024-03-31'
+
+# 批量获取
+curl -X POST http://localhost:5000/api/v1/ohlcv/batch \
+  -H "Content-Type: application/json" \
+  -d '{
+    "codes": ["000300.SH", "NDX", "HSI"],
+    "start": "2024-01-01",
+    "end": "2024-03-31"
+  }'
+```
+
+## API 端点
+
+### 1. 健康检查
+
+```http
+GET /health
+```
+
+**响应**:
+```json
+{
+  "status": "healthy",
+  "timestamp": "2024-01-15T10:30:00",
+  "ssh_configured": true
+}
+```
+
+### 2. 检测资产类型
+
+```http
+GET /api/v1/asset-type?code={code}
+```
+
+**参数**:
+- `code` (required): 标的代码
+
+**响应**:
+```json
+{
+  "code": "000300.SH",
+  "asset_type": "china_index",
+  "description": "A股指数"
+}
+```
+
+**示例**:
+```bash
+curl 'http://localhost:5000/api/v1/asset-type?code=000300.SH'
+curl 'http://localhost:5000/api/v1/asset-type?code=NDX'
+curl 'http://localhost:5000/api/v1/asset-type?code=BTC'
+```
+
+### 3. 获取K线数据
+
+```http
+GET /api/v1/ohlcv?code={code}&start={start}&end={end}&retry={retry}
+```
+
+**参数**:
+- `code` (required): 标的代码
+- `start` (optional): 开始日期，格式 `YYYY-MM-DD`，默认90天前
+- `end` (optional): 结束日期，格式 `YYYY-MM-DD`，默认今天
+- `retry` (optional): 重试次数，默认3
+
+**响应**:
+```json
+{
+  "code": "000300.SH",
+  "asset_type": "china_index",
+  "data": [
+    {
+      "date": "2024-01-02",
+      "open": 3538.7244,
+      "high": 3542.9624,
+      "low": 3502.7866,
+      "close": 3502.7866,
+      "volume": 128626763.0,
+      "code": "000300.SH"
+    },
+    ...
+  ],
+  "count": 58,
+  "date_range": {
+    "start": "2024-01-02",
+    "end": "2024-03-29"
+  },
+  "columns": ["date", "open", "high", "low", "close", "volume", "code"]
+}
+```
+
+**示例**:
+```bash
+# 获取沪深300指数
+curl 'http://localhost:5000/api/v1/ohlcv?code=000300.SH&start=2024-01-01&end=2024-03-31'
+
+# 获取纳斯达克100指数（需要SSH隧道）
+curl 'http://localhost:5000/api/v1/ohlcv?code=NDX&start=2024-01-01&end=2024-03-31'
+
+# 获取黄金期货
+curl 'http://localhost:5000/api/v1/ohlcv?code=AU.SHF&start=2024-01-01&end=2024-03-31'
+```
+
+### 4. 批量获取K线数据
+
+```http
+POST /api/v1/ohlcv/batch
+```
+
+**请求体**:
+```json
+{
+  "codes": ["000300.SH", "NDX", "HSI"],
+  "start": "2024-01-01",
+  "end": "2024-03-31",
+  "retry": 3
+}
+```
+
+**响应**:
+```json
+{
+  "results": {
+    "000300.SH": {
+      "code": "000300.SH",
+      "asset_type": "china_index",
+      "data": [...],
+      "count": 58,
+      "date_range": {...}
+    },
+    "NDX": {
+      "code": "NDX",
+      "asset_type": "us_index",
+      "data": [...],
+      "count": 61,
+      "date_range": {...}
+    },
+    "HSI": {
+      "code": "HSI",
+      "asset_type": "hk_index",
+      "error": "No data available",
+      "data": [],
+      "count": 0
+    }
+  },
+  "success_count": 2,
+  "failed_count": 1,
+  "total": 3,
+  "start": "2024-01-01",
+  "end": "2024-03-31"
+}
+```
+
+**示例**:
+```bash
+curl -X POST http://localhost:5000/api/v1/ohlcv/batch \
+  -H "Content-Type: application/json" \
+  -d '{
+    "codes": ["000300.SH", "510300.SH", "NDX", "HSI", "AU.SHF"],
+    "start": "2024-01-01",
+    "end": "2024-03-31"
+  }'
+```
+
+### 5. 获取支持的代码示例
+
+```http
+GET /api/v1/supported-codes
+```
+
+**响应**:
+```json
+{
+  "china_index": {
+    "description": "A股指数",
+    "examples": ["000300.SH", "399006.SZ", "000016.SH", "H30269.CSI"]
+  },
+  "china_etf": {
+    "description": "A股ETF",
+    "examples": ["510300.SH", "159915.SZ", "510500.SH", "513100.SH"]
+  },
+  ...
+}
+```
+
+## Python 客户端
+
+### 安装
+
+```bash
+pip install requests
+```
+
+### 使用示例
+
+```python
+import requests
+
+# 基础配置
+BASE_URL = "http://localhost:5000"
+
+# 1. 健康检查
+response = requests.get(f"{BASE_URL}/health")
+print(response.json())
+
+# 2. 获取单只标的
+def get_ohlcv(code, start, end):
+    response = requests.get(
+        f"{BASE_URL}/api/v1/ohlcv",
+        params={"code": code, "start": start, "end": end}
+    )
+    return response.json()
+
+# 获取沪深300
+data = get_ohlcv("000300.SH", "2024-01-01", "2024-03-31")
+print(f"获取到 {data['count']} 条数据")
+
+# 3. 批量获取
+def batch_ohlcv(codes, start, end):
+    response = requests.post(
+        f"{BASE_URL}/api/v1/ohlcv/batch",
+        json={"codes": codes, "start": start, "end": end}
+    )
+    return response.json()
+
+# 批量获取
+results = batch_ohlcv(
+    ["000300.SH", "NDX", "HSI"],
+    "2024-01-01",
+    "2024-03-31"
+)
+
+for code, result in results['results'].items():
+    if 'error' not in result:
+        print(f"✓ {code}: {result['count']} 条")
+    else:
+        print(f"✗ {code}: {result['error']}")
+```
+
+## 错误处理
+
+### 错误响应格式
+
+```json
+{
+  "error": "错误描述",
+  "code": "000300.SH",
+  "start": "2024-01-01",
+  "end": "2024-03-31"
+}
+```
+
+### 常见错误码
+
+| HTTP 状态码 | 说明 | 解决方案 |
+|------------|------|---------|
+| 400 | 参数错误 | 检查请求参数格式 |
+| 404 | 数据不存在 | 检查代码是否正确，日期范围是否合理 |
+| 500 | 服务器内部错误 | 查看服务器日志 |
+
+### 常见错误
+
+**1. 代码不存在**
+```json
+{
+  "error": "No data available for the specified code and date range",
+  "code": "INVALID",
+  "start": "2024-01-01",
+  "end": "2024-03-31"
+}
+```
+
+**2. 日期格式错误**
+```json
+{
+  "error": "Invalid date format. Use YYYY-MM-DD",
+  "start": "2024-01-01",
+  "end": "2024/03/31"
+}
+```
+
+**3. 缺少必需参数**
+```json
+{
+  "error": "Missing required parameter: code",
+  "example": "/api/v1/ohlcv?code=000300.SH&start=2024-01-01&end=2024-03-31"
+}
+```
+
+## 环境配置
+
+### 必需环境变量
+
+```bash
+# Tushare Token（获取A股数据必需）
+export TUSHARE_TOKEN=your_token_here
+```
+
+### 可选环境变量（SSH隧道）
+
+```bash
+# 启用 SSH 隧道（支持港美股）
+export SSH_ENABLED=true
+export SSH_HOST=8.218.167.69
+export SSH_PORT=22
+export SSH_USERNAME=root
+export SSH_KEY_PATH=hk_ecs.pem
+export SSH_LOCAL_PORT=1080
+```
+
+### .env 文件示例
+
+```env
+# Tushare
+TUSHARE_TOKEN=your_tushare_token_here
+
+# SSH 隧道（可选）
+SSH_ENABLED=true
+SSH_HOST=8.218.167.69
+SSH_PORT=22
+SSH_USERNAME=root
+SSH_KEY_PATH=hk_ecs.pem
+SSH_LOCAL_PORT=1080
+```
+
+## 性能说明
+
+### 响应时间
+
+- A股数据: ~500ms/只
+- 港美股数据: ~1-2s/只（通过SSH隧道）
+- 批量获取: 并发处理，总体时间取决于最慢的数据源
+
+### 限流说明
+
+- Tushare: 受 API 频率限制
+- YFinance: 建议添加延迟避免限流
+- 批量获取: 自动添加 0.5s 延迟
+
+## 注意事项
+
+1. **SSH 隧道**: 获取港美股数据需要配置 SSH 隧道
+2. **Tushare Token**: 获取A股数据需要有效的 Tushare Token
+3. **日期范围**: 建议单次查询不超过 1 年数据
+4. **网络环境**: 中国大陆直接访问 YFinance 可能受限
+
+## 示例代码
+
+查看完整示例:
+- [Python 客户端](../examples/flask_api_client.py)
+- [API 测试](../tests/test_flask_api.py)
+
+## 更新日志
+
+### v1.0.0 (2024-XX-XX)
+
+- 初始版本
+- 支持8种资产类型
+- RESTful API 接口
+- Python 客户端
+- SSH 隧道支持