amazing-data-service/README.md

# AmazingData 金融数据服务平台

基于银河证券星耀数智量化平台SDK构建的金融数据服务系统，提供历史数据缓存、实时数据订阅、批量数据管理等功能。

## 功能特性

- ✅ **完整SDK接口封装** - 封装AmazingData所有接口
- ✅ **智能数据缓存** - 优先本地缓存，缺失自动从SDK补全
- ✅ **实时数据订阅** - WebSocket实时推送股票/期货行情
- ✅ **缺失数据检测** - 自动检测并提示缺失数据
- ✅ **批量缓存管理** - 一键检测、一键缓存
- ✅ **可视化K线图** - ECharts展示历史K线数据
- ✅ **完整测试中心** - 所有接口一键测试
- ✅ **配置管理** - SDK账号配置可视化维护

## 技术栈

| 层级 | 技术 |
|------|------|
| 后端 | Python 3.10+, FastAPI, SQLAlchemy 2.0 |
| 数据库 | PostgreSQL 15+ |
| 缓存 | Redis 7+ |
| 前端 | Vue3, TypeScript, Element Plus |
| 图表 | ECharts 5+ |
| 部署 | Docker, Docker Compose |

## 快速开始

### 1. 克隆项目

```bash
git clone <repository-url>
cd amazing-data-service
```

### 2. 安装AmazingData SDK

```bash
# 从银河证券获取 SDK wheel 文件
pip install AmazingData-1.0.24-py3-none-any.whl
```

### 3. 使用Docker启动

```bash
docker-compose up -d
```

服务将启动在：
- 前端: http://localhost
- 后端API: http://localhost:8000
- API文档: http://localhost:8000/docs

### 4. 初始化数据库

```bash
# 数据库会自动执行 init.sql 初始化脚本
# 默认管理员账号: admin / admin123
```

### 5. 配置SDK连接

1. 登录系统（admin / admin123）
2. 进入"配置管理"页面
3. 添加AmazingData SDK连接信息
4. 点击"测试连接"验证

## 项目结构

```
amazing-data-service/
├── backend/           # FastAPI后端
├── frontend/          # Vue3前端
├── database/          # 数据库脚本
├── docker/            # Docker配置
├── docs/              # 文档
└── README.md
```

## API接口文档

启动服务后访问：http://localhost:8000/docs

### 主要接口分类

- `/api/v1/auth/*` - 认证接口
- `/api/v1/configs/*` - 配置管理
- `/api/v1/stock/*` - 股票数据
- `/api/v1/future/*` - 期货数据
- `/api/v1/realtime/*` - 实时数据
- `/api/v1/finance/*` - 财务数据
- `/api/v1/cache/*` - 缓存管理
- `/api/v1/test/*` - 测试中心

## 核心功能说明

### 1. 数据缓存策略

系统采用"本地优先"策略：
1. 查询请求首先检查本地数据库
2. 检查数据完整性（与交易日历对比）
3. 缺失数据自动从AmazingData SDK获取
4. 新数据写入数据库时自动去重

### 2. 缺失数据检测

检测逻辑：
- 按交易日查询数据条数
- 与最近交易日数据对比
- 偏差超过10%标记为缺失

### 3. 实时数据订阅

- WebSocket连接：`ws://localhost:8000/api/v1/realtime/stream`
- 支持股票、期货、指数快照订阅
- 数据自动保存7天后清理

### 4. 测试中心

提供所有接口的自动化测试：
- 单个接口测试（参数调试）
- 批量接口测试（回归测试）
- 测试历史记录

## 数据库表结构

### 核心表

| 表名 | 说明 |
|------|------|
| users | 系统用户 |
| sdk_configs | SDK配置 |
| stock_kline_daily | 股票日线数据 |
| stock_kline_min | 股票分钟数据 |
| future_kline_daily | 期货日线数据 |
| future_kline_min | 期货分钟数据 |
| realtime_snapshot | 实时快照数据 |
| cache_tasks | 缓存任务 |
| api_test_logs | API测试日志 |

完整表结构见：`database/init.sql`

## 开发指南

### 后端开发

```bash
cd backend
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload
```

### 前端开发

```bash
cd frontend
npm install
npm run dev
```

## 配置说明

### 环境变量

| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| DATABASE_URL | 数据库连接URL | postgresql://postgres:postgres@localhost:5432/amazing_data |
| REDIS_URL | Redis连接URL | redis://localhost:6379/0 |
| SECRET_KEY | JWT密钥 | your-secret-key |
| ACCESS_TOKEN_EXPIRE_HOURS | Token过期时间 | 24 |

## 常见问题

### Q: 如何添加新的SDK配置？
A: 登录系统后，进入"配置管理"页面，点击"添加配置"，填写AmazingData账号信息。

### Q: 如何批量缓存历史数据？
A: 进入"缓存管理"页面，选择时间区间，点击"检测缺失数据"，然后点击"一键缓存"。

### Q: 实时数据如何订阅？
A: 在数据查询页面，输入代码后勾选"实时订阅"，系统会自动建立WebSocket连接。

### Q: 数据去重是如何工作的？
A: 系统比较open/high/low/close/volume五个核心字段，如果差异小于0.0001则视为相同数据，跳过插入。

## 许可证

MIT License

## 联系支持

如有问题，请联系项目维护者或提交Issue。

---

**注意**：使用本系统需要AmazingData SDK授权，请联系银河证券开通权限。