docs: 将英文文件名重命名为中文
重命名13个英文文档为中文： - etf_pool_selection.md → ETF候选池筛选报告.md - etf_tracking_error_calculation.md → ETF跟踪误差计算方法.md - FLASK_SERVICE_SUMMARY.md → Flask服务总结.md - flask_api_README.md → Flask_API接口说明.md - cross_market_effectiveness_survey.md → 跨市场有效性调研.md - etf_rotation_deep_analysis.md → ETF轮动深度分析.md - etf_rotation_framework.md → ETF轮动框架.md - momentum_rotation_survey.md → 动量轮动调研.md - strategy_evolution_report.md → 策略演进报告.md - universal_fetcher_*.md → 通用数据源*.md 同时更新文档内部的交叉引用链接
This commit is contained in:
361
docs/Flask服务总结.md
Normal file
361
docs/Flask服务总结.md
Normal file
@@ -0,0 +1,361 @@
|
||||
# Flask 数据服务实现总结
|
||||
|
||||
## 📦 已完成的组件
|
||||
|
||||
### 1. 核心服务 (flask_server.py)
|
||||
**文件**: `core/datasource/flask_server.py` (541行)
|
||||
|
||||
**功能**:
|
||||
- ✅ RESTful API 接口
|
||||
- ✅ 支持8种资产类型
|
||||
- ✅ 自动资产类型检测
|
||||
- ✅ SSH 隧道集成
|
||||
- ✅ 单只/批量数据获取
|
||||
- ✅ 统一的 JSON 响应格式
|
||||
- ✅ 完善的错误处理
|
||||
|
||||
**API 端点**:
|
||||
```
|
||||
GET / - API 信息
|
||||
GET /health - 健康检查
|
||||
GET /api/v1/asset-type - 检测资产类型
|
||||
GET /api/v1/ohlcv - 获取K线数据
|
||||
POST /api/v1/ohlcv/batch - 批量获取K线
|
||||
GET /api/v1/supported-codes - 支持的代码示例
|
||||
```
|
||||
|
||||
### 2. 启动脚本 (start_flask_server.sh)
|
||||
**文件**: `start_flask_server.sh` (128行)
|
||||
|
||||
**功能**:
|
||||
- ✅ 环境检查（Python、依赖、Token）
|
||||
- ✅ SSH 私钥权限自动修复
|
||||
- ✅ 命令行参数解析
|
||||
- ✅ 彩色输出提示
|
||||
- ✅ 帮助文档
|
||||
|
||||
**用法**:
|
||||
```bash
|
||||
./start_flask_server.sh # 基础启动
|
||||
./start_flask_server.sh --with-ssh # 启用SSH隧道
|
||||
./start_flask_server.sh --port 8080 # 指定端口
|
||||
./start_flask_server.sh --debug # 调试模式
|
||||
```
|
||||
|
||||
### 3. Python 客户端 (flask_api_client.py)
|
||||
**文件**: `examples/flask_api_client.py` (299行)
|
||||
|
||||
**功能**:
|
||||
- ✅ DataFetcherClient 类封装
|
||||
- ✅ 健康检查
|
||||
- ✅ 资产类型检测
|
||||
- ✅ 单只/批量数据获取
|
||||
- ✅ 命令行调用示例
|
||||
- ✅ DataFrame 转换示例
|
||||
|
||||
**使用**:
|
||||
```python
|
||||
from examples.flask_api_client import DataFetcherClient
|
||||
|
||||
client = DataFetcherClient("http://localhost:5000")
|
||||
|
||||
# 获取单只标的
|
||||
data = client.get_ohlcv("000300.SH", "2024-01-01", "2024-03-31")
|
||||
|
||||
# 批量获取
|
||||
results = client.batch_ohlcv(
|
||||
["000300.SH", "NDX", "HSI"],
|
||||
"2024-01-01",
|
||||
"2024-03-31"
|
||||
)
|
||||
```
|
||||
|
||||
### 4. API 文档 (Flask_API接口说明.md)
|
||||
**文件**: `docs/Flask_API接口说明.md` (405行)
|
||||
|
||||
**内容**:
|
||||
- ✅ 快速开始指南
|
||||
- ✅ 完整的 API 端点文档
|
||||
- ✅ 请求/响应示例
|
||||
- ✅ 错误处理说明
|
||||
- ✅ Python 客户端示例
|
||||
- ✅ 环境配置指南
|
||||
|
||||
### 5. API 测试脚本 (test_flask_api.py)
|
||||
**文件**: `tests/test_flask_api.py` (141行)
|
||||
|
||||
**功能**:
|
||||
- ✅ 健康检查测试
|
||||
- ✅ 首页信息测试
|
||||
- ✅ 资产类型检测测试
|
||||
- ✅ K线数据获取测试
|
||||
- ✅ 批量获取测试
|
||||
- ✅ 支持的代码测试
|
||||
|
||||
## 🚀 快速开始
|
||||
|
||||
### 1. 启动服务
|
||||
|
||||
```bash
|
||||
# 进入项目目录
|
||||
cd /Users/aszer/Documents/vscode/etf
|
||||
|
||||
# 启动服务（仅A股）
|
||||
./start_flask_server.sh
|
||||
|
||||
# 或启动服务（支持港美股，需要SSH隧道）
|
||||
./start_flask_server.sh --with-ssh
|
||||
```
|
||||
|
||||
### 2. 测试 API
|
||||
|
||||
```bash
|
||||
# 健康检查
|
||||
curl http://localhost:5000/health
|
||||
|
||||
# 获取沪深300数据
|
||||
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"
|
||||
}'
|
||||
```
|
||||
|
||||
### 3. Python 调用
|
||||
|
||||
```python
|
||||
import requests
|
||||
|
||||
# 获取数据
|
||||
response = requests.get(
|
||||
'http://localhost:5000/api/v1/ohlcv',
|
||||
params={
|
||||
'code': '000300.SH',
|
||||
'start': '2024-01-01',
|
||||
'end': '2024-03-31'
|
||||
}
|
||||
)
|
||||
data = response.json()
|
||||
|
||||
print(f"获取到 {data['count']} 条数据")
|
||||
for item in data['data'][:3]:
|
||||
print(f"{item['date']}: 开盘 {item['open']}, 收盘 {item['close']}")
|
||||
```
|
||||
|
||||
## 📊 API 响应示例
|
||||
|
||||
### 单只标的响应
|
||||
|
||||
```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"]
|
||||
}
|
||||
```
|
||||
|
||||
### 批量获取响应
|
||||
|
||||
```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": {...}
|
||||
}
|
||||
},
|
||||
"success_count": 2,
|
||||
"failed_count": 0,
|
||||
"total": 2,
|
||||
"start": "2024-01-01",
|
||||
"end": "2024-03-31"
|
||||
}
|
||||
```
|
||||
|
||||
## 🔧 配置说明
|
||||
|
||||
### 环境变量
|
||||
|
||||
```bash
|
||||
# 必需
|
||||
export TUSHARE_TOKEN=your_token_here
|
||||
|
||||
# 可选（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_TOKEN=your_token_here
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
## 📁 文件结构
|
||||
|
||||
```
|
||||
etf/
|
||||
├── core/datasource/
|
||||
│ ├── flask_server.py # Flask API 服务 (541行)
|
||||
│ ├── universal_fetcher.py # 统一数据获取器 (441行)
|
||||
│ ├── hybrid_source.py # 混合数据源
|
||||
│ └── __init__.py # 模块导出
|
||||
├── examples/
|
||||
│ ├── flask_api_client.py # Python 客户端 (299行)
|
||||
│ └── universal_fetcher_examples.py
|
||||
├── tests/
|
||||
│ ├── test_flask_api.py # API 测试 (141行)
|
||||
│ ├── test_universal_fetcher.py
|
||||
│ └── test_ssh_tunnel.py
|
||||
├── docs/
|
||||
│ ├── Flask_API接口说明.md # API 文档 (405行)
|
||||
│ ├── 通用数据源说明.md
|
||||
│ └── ...
|
||||
├── start_flask_server.sh # 启动脚本 (128行)
|
||||
└── hk_ecs.pem # SSH 私钥
|
||||
```
|
||||
|
||||
## 🎯 支持的资产类型
|
||||
|
||||
| 类型 | 代码示例 | 数据源 | 需要SSH |
|
||||
|------|---------|--------|---------|
|
||||
| A股指数 | 000300.SH | Tushare | 否 |
|
||||
| A股ETF | 510300.SH | Tushare | 否 |
|
||||
| A股股票 | 600000.SH | Tushare | 否 |
|
||||
| 港股指数 | HSI | YFinance | 是 |
|
||||
| 美股指数 | NDX | YFinance | 是 |
|
||||
| 美股股票 | AAPL | YFinance | 是 |
|
||||
| 期货 | AU.SHF | Tushare | 否 |
|
||||
| 加密货币 | BTC | CCXT | 是 |
|
||||
|
||||
## 📝 注意事项
|
||||
|
||||
1. **Tushare Token**: 获取A股数据必需
|
||||
2. **SSH 隧道**: 获取港美股/加密货币需要
|
||||
3. **私钥权限**: 自动修复为 600
|
||||
4. **网络环境**: 中国大陆直接访问 YFinance 受限
|
||||
5. **日期格式**: 统一使用 YYYY-MM-DD
|
||||
|
||||
## 🔄 与现有代码的关系
|
||||
|
||||
```
|
||||
现有代码:
|
||||
UniversalDataFetcher
|
||||
└─ HybridDataSource
|
||||
├─ Tushare (A股)
|
||||
├─ YFinance (港美股) - 需要SSH
|
||||
└─ CCXT (加密货币) - 需要SSH
|
||||
|
||||
新增代码:
|
||||
Flask API Server
|
||||
└─ UniversalDataFetcher
|
||||
└─ ... (同上)
|
||||
|
||||
客户端:
|
||||
DataFetcherClient
|
||||
└─ HTTP requests
|
||||
└─ Flask API Server
|
||||
```
|
||||
|
||||
## ✅ 功能清单
|
||||
|
||||
### API 功能
|
||||
- [x] 健康检查
|
||||
- [x] 资产类型检测
|
||||
- [x] 单只标的K线获取
|
||||
- [x] 批量标的K线获取
|
||||
- [x] 支持的代码列表
|
||||
- [x] 统一的JSON响应
|
||||
- [x] 错误处理
|
||||
- [x] CORS支持
|
||||
|
||||
### 部署功能
|
||||
- [x] 环境检查
|
||||
- [x] 依赖安装
|
||||
- [x] SSH配置
|
||||
- [x] 命令行参数
|
||||
- [x] 彩色输出
|
||||
- [x] 帮助文档
|
||||
|
||||
### 客户端功能
|
||||
- [x] Python客户端类
|
||||
- [x] 健康检查
|
||||
- [x] 资产检测
|
||||
- [x] 数据获取
|
||||
- [x] 批量获取
|
||||
- [x] DataFrame转换
|
||||
|
||||
## 🚀 下一步建议
|
||||
|
||||
1. **添加认证**: API Key 或 JWT 认证
|
||||
2. **添加限流**: 防止滥用
|
||||
3. **添加缓存**: Redis 缓存常用数据
|
||||
4. **添加日志**: 请求日志和错误日志
|
||||
5. **Docker部署**: 容器化部署
|
||||
6. **监控告警**: 服务健康监控
|
||||
|
||||
## 📞 使用帮助
|
||||
|
||||
启动服务后访问:
|
||||
- API 文档: http://localhost:5000/
|
||||
- 健康检查: http://localhost:5000/health
|
||||
|
||||
查看详细文档:
|
||||
- [API 文档](./Flask_API接口说明.md)
|
||||
- [客户端示例](../examples/flask_api_client.py)
|
||||
|
||||
## 🎉 总结
|
||||
|
||||
Flask 数据服务已经完全实现，提供了：
|
||||
|
||||
✅ **RESTful API** - 统一的 HTTP 接口
|
||||
✅ **自动资产识别** - 智能路由到正确数据源
|
||||
✅ **SSH 隧道支持** - 自动管理代理连接
|
||||
✅ **批量获取** - 高效的多标的数据获取
|
||||
✅ **完整文档** - API 文档和客户端示例
|
||||
✅ **易于部署** - 一键启动脚本
|
||||
|
||||
现在可以通过 HTTP API 获取任何支持的资产数据了！
|
||||
Reference in New Issue
Block a user