market-data-service/README.md

# 统一行情数据服务

提供股票和期货的标准化行情数据查询服务，支持多周期K线、复权计算、数据源热切换等功能。

**🎉 重大更新**: 现已支持 **Go** 和 **Python** 双实现，所有接口完全一致！

| 实现 | 推荐场景 | 目录 |
|------|----------|------|
| **Go** | 生产环境、高并发 | `market-data-service/` (本目录) |
| **Python** | 快速开发、原型验证 | `python_market_data_service/` |

---

## 特性

- **多周期K线支持**：1m/5m/15m/30m/60m/1d/1w/1month
- **股票复权支持**：前复权(qfq)/后复权(hfq)
- **数据源热切换**：支持Wind、Tushare等多个数据源动态切换
- **双轨设计**：股票和期货接口独立，数据存储隔离
- **WebSocket实时订阅**：支持实时行情推送
- **数据质量监控**：自动检测数据缺失并告警
- **交易日历**：支持查询股票和期货的交易日历
- **期货合约查询**：根据品种获取可交易合约列表
- **双语言实现**：Go高性能 + Python快速开发

---

## 技术栈

### Go实现
- **语言**: Go 1.21+
- **Web框架**: Gin
- **WebSocket**: Gorilla WebSocket
- **数据库**: PostgreSQL 15+ (原生SQL)
- **数据源**: Tushare

### Python实现
- **语言**: Python 3.10+
- **Web框架**: FastAPI
- **WebSocket**: FastAPI原生
- **数据库**: PostgreSQL 15+ (SQLAlchemy ORM)
- **数据源**: Tushare (原生支持)

---

## 项目结构

### Go实现

```
market-data-service/
├── api/                    # API接口定义
│   ├── types.go           # 请求/响应类型定义
│   ├── router.go          # HTTP路由注册
│   ├── admin_types.go     # 管理后台类型定义
│   └── admin_router.go    # 管理后台路由
├── internal/              # 内部实现
│   ├── handler/           # HTTP Handler实现
│   ├── service/           # 业务逻辑层
│   ├── repository/        # 数据访问层
│   ├── websocket/         # WebSocket服务
│   └── monitor/           # 数据质量监控
├── adapter/               # 数据源适配器框架
│   ├── adapter.go         # 适配器接口定义
│   └── tushare/           # Tushare适配器实现
├── pkg/                   # 公共包
├── cmd/                   # 程序入口
├── config.example.json    # 配置文件示例
├── go.mod
├── Makefile
└── README.md
```

### Python实现

```
python_market_data_service/
├── app/
│   ├── main.py            # FastAPI主应用
│   ├── api/               # API路由 (FastAPI)
│   ├── core/              # 核心模块 (配置、日志、错误)
│   ├── models/            # 数据模型 (Pydantic)
│   ├── repositories/      # 数据访问 (SQLAlchemy)
│   ├── services/          # 业务逻辑层
│   ├── adapters/          # 数据源适配器
│   ├── websocket/         # WebSocket服务
│   └── monitor/           # 数据质量监控
├── scripts/               # 数据同步工具
├── requirements.txt       # Python依赖
├── pyproject.toml        # 项目配置
├── config.json           # 配置文件 (与Go相同)
├── README.md             # Python项目说明
└── MIGRATION_GUIDE.md    # 迁移对照指南
```

---

## 快速开始

**最快方式**: 查看 [QUICKSTART.md](QUICKSTART.md) - 30秒启动指南

### 方式一：Go实现（推荐生产环境）

#### 1. 环境准备

- Go 1.21+
- PostgreSQL 15+
- Tushare Token (从 [Tushare官网](https://tushare.pro) 获取)

#### 2. 配置环境变量

```bash
export TUSHARE_TOKEN="your_tushare_token"
export DATABASE_URL="postgres://user:password@localhost:5432/marketdata?sslmode=disable"
export PORT="8080"
export GIN_MODE="debug"
```

#### 3. 初始化数据库

```bash
# 创建数据库
createdb marketdata

# 执行初始化脚本
psql $DATABASE_URL -f memory/2026-03-07-database-schema.sql
```

#### 4. 下载依赖并启动

```bash
make deps
make run
```

### 方式二：Python实现（推荐开发环境）

#### 1. 环境准备

- Python 3.10+
- PostgreSQL 15+
- Tushare Token

#### 2. 安装依赖

```bash
cd python_market_data_service

# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Linux/Mac
# 或
venv\Scripts\activate  # Windows

# 安装依赖
pip install -r requirements.txt
pip install tushare
```

#### 3. 配置环境变量

```bash
export TUSHARE_TOKEN="your_tushare_token"
export DATABASE_URL="postgresql://user:password@localhost:5432/marketdata"
export PORT="8080"
```

#### 4. 初始化数据库并启动

```bash
# 初始化数据库（SQLAlchemy自动创建表）
python -c "from app.repositories.database import init_db; init_db()"

# 启动服务
python -m app.main
# 或使用 uvicorn
uvicorn app.main:app --reload --port 8080
```

服务将启动在 `http://localhost:8080`

---

## API接口

> **注意**: Go和Python实现的API接口完全一致！

### 股票接口

| 接口 | 方法 | 说明 |
|------|------|------|
| `/v1/stock/klines/:symbol` | GET | 查询K线数据 |
| `/v1/stock/symbols` | GET | 查询标的列表 |
| `/v1/stock/klines/batch` | POST | 批量查询K线 |
| `/v1/stock/trading-dates` | GET | 获取交易日历 |

**查询K线示例**:
```bash
curl "http://localhost:8080/v1/stock/klines/000001.SZ?start=20250301&end=20250307&freq=1d&adjust=qfq" \
  -H "X-API-Key: your_api_key"
```

### 期货接口

| 接口 | 方法 | 说明 |
|------|------|------|
| `/v1/futures/klines/:symbol` | GET | 查询K线数据 |
| `/v1/futures/symbols` | GET | 查询标的列表 |
| `/v1/futures/klines/batch` | POST | 批量查询K线 |
| `/v1/futures/continuous/:underlying` | GET | 查询主力连续合约（预留） |
| `/v1/futures/trading-dates` | GET | 获取交易日历 |
| `/v1/futures/contracts` | GET | 获取品种合约列表 |

### 管理后台

服务启动后，访问 `http://localhost:8080/admin` 进入管理后台。

**Python特有**: 自动生成API文档
- Swagger UI: `http://localhost:8080/docs`
- ReDoc: `http://localhost:8080/redoc`

---

## 数据同步工具

### Go实现

```bash
# 同步股票列表
go run ./cmd/sync -type stocks

# 同步期货列表
go run ./cmd/sync -type futures

# 同步交易日历
go run ./cmd/sync -type calendar -start 20240101 -end 20241231

# 同步K线数据
go run ./cmd/sync -type klines -symbol 000001.SZ -start 20240301 -end 20240307 -freq 1d
```

### Python实现

```bash
# 同步股票列表
python scripts/sync_data.py --type stocks

# 同步期货列表
python scripts/sync_data.py --type futures

# 同步交易日历
python scripts/sync_data.py --type calendar --start 20240101 --end 20241231

# 同步K线数据
python scripts/sync_data.py --type klines --symbol 000001.SZ --start 20240301 --end 20240307 --freq 1d
```

---

## 部署

### Docker部署

**Go实现:**
```bash
docker build -t market-data-service:go .
docker run -p 8080:8080 market-data-service:go
```

**Python实现:**
```bash
cd python_market_data_service
docker build -t market-data-service:python .
docker run -p 8080:8080 market-data-service:python
```

详细部署文档请参考 [DEPLOY.md](./DEPLOY.md)

---

## 实现方式对比

| 特性 | Go | Python |
|------|----|--------|
| 性能 | ⭐⭐⭐ 高性能 | ⭐⭐ 良好 |
| 开发效率 | ⭐⭐ 中等 | ⭐⭐⭐ 高 |
| 数据源生态 | ⭐⭐ 需自行封装 | ⭐⭐⭐ Tushare原生支持 |
| 内存占用 | ⭐⭐⭐ 低 (~50MB) | ⭐⭐ 中等 (~100MB) |
| 启动速度 | ⭐⭐⭐ 快 (~100ms) | ⭐⭐ 中等 (~2s) |
| 类型安全 | ⭐⭐⭐ 编译期检查 | ⭐⭐ 运行时检查 (Pydantic) |
| 部署复杂度 | ⭐⭐⭐ 单二进制 | ⭐⭐ 依赖较多 |
| API文档 | ⭐⭐ 需手动维护 | ⭐⭐⭐ 自动生成 |

**推荐**:
- **生产环境**: Go实现
- **开发测试**: Python实现
- **数据源对接**: Python实现（生态更好）

---

## 文档

### 🚀 启动部署
- [QUICKSTART.md](./QUICKSTART.md) - **30秒快速启动指南**（推荐先看）
- [启动指南](./docs/startup-guide.md) - 完整的启动教程
- [部署文档](./DEPLOY.md) - 详细部署指南（含Docker和Systemd）

### 📚 开发文档
- [开发指南](./docs/development-guide.md) - 开发新功能指南
- [架构设计](./docs/architecture.md) - 系统架构文档
- [API速查表](./docs/admin-api-quick-reference.md) - API快速参考
- [Python迁移指南](./python_market_data_service/MIGRATION_GUIDE.md) - Go到Python迁移对照

### 📋 项目信息
- [项目进度](./PROGRESS.md) - 开发进度和计划

---

## 常见问题

### Q: 应该选择Go还是Python实现？

A: 
- 如果需要**生产环境高并发**，选择**Go**
- 如果需要**快速开发、原型验证**，选择**Python**
- 如果需要**频繁对接数据源**，选择**Python**（生态更好）

### Q: 两个实现的API是否兼容？

A: **完全兼容**。所有接口、请求参数、响应格式完全一致，客户端可无缝切换。

### Q: 数据库Schema是否相同？

A: **相同**。两个实现使用相同的数据库Schema，可共享数据。

### Q: 如何实现股票复权？

A: 查询时传入 `adjust=qfq` 或 `adjust=hfq` 参数，服务会自动应用复权系数。

### Q: 期货主力连续合约何时支持？

A: 主力连续合约功能在预留表结构中，将在后续版本实现。

---

## 贡献

欢迎提交Issue和PR！

- Go实现相关: 提交到本仓库
- Python实现相关: 提交到 `python_market_data_service/` 目录

---

## License

MIT