python_market_data_service/QUICKSTART.md

# 统一行情数据服务 - 快速启动指南

本文档提供最快的启动方式，支持 **Go** 和 **Python** 双实现。

---

## 30秒快速启动（Python）

```bash
# 1. 进入Python项目目录
cd python_market_data_service

# 2. 创建并激活虚拟环境
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

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

# 4. 启动服务
python -m app.main
```

访问 http://localhost:8080/admin

---

## 30秒快速启动（Go）

```bash
# 1. 下载依赖
go mod download

# 2. 启动服务
go run ./cmd/server
```

访问 http://localhost:8080/admin

---

## 完整启动步骤

### 前置条件

| 组件 | 版本 | 安装命令 |
|------|------|----------|
| Go | 1.21+ | [下载安装](https://go.dev/dl/) |
| Python | 3.10+ | [下载安装](https://www.python.org/) |
| PostgreSQL | 15+ | `docker run -d -e POSTGRES_PASSWORD=postgres -p 5432:5432 postgres:15` |

### 方式一：Python实现（推荐开发）

#### 步骤1：环境准备
```bash
cd python_market_data_service

# 创建虚拟环境
python -m venv venv

# 激活虚拟环境
# Windows:
venv\Scripts\activate
# Linux/Mac:
source venv/bin/activate

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

#### 步骤2：配置环境变量
```bash
# 必需
export TUSHARE_TOKEN="your_tushare_token"  # 从 https://tushare.pro 获取
export DATABASE_URL="postgresql://postgres:postgres@localhost:5432/marketdata"

# 可选
export PORT=8080
export API_KEY=your-api-key
```

#### 步骤3：初始化数据库
```bash
# 方式1：自动创建表（推荐）
python -c "from app.repositories.database import init_db; init_db()"

# 方式2：使用SQL脚本
psql $DATABASE_URL -f ../memory/2026-03-07-database-schema.sql
```

#### 步骤4：启动服务
```bash
# 开发模式（热重载）
python -m app.main

# 或使用Uvicorn
uvicorn app.main:app --reload --port 8080

# 生产模式
uvicorn app.main:app --host 0.0.0.0 --port 8080 --workers 4
```

#### 步骤5：验证
```bash
# 健康检查
curl http://localhost:8080/v1/admin/health

# 访问管理后台
open http://localhost:8080/admin

# API文档（Python特有）
open http://localhost:8080/docs
```

---

### 方式二：Go实现（推荐生产）

#### 步骤1：环境准备
```bash
# 检查Go版本
go version  # 需 >= 1.21

# 设置国内镜像（推荐）
go env -w GOPROXY=https://goproxy.cn,direct

# 下载依赖
go mod download
```

#### 步骤2：配置环境变量
```bash
# 必需
export TUSHARE_TOKEN="your_tushare_token"
export DATABASE_URL="postgres://postgres:postgres@localhost:5432/marketdata?sslmode=disable"

# 可选
export PORT=8080
export GIN_MODE=debug
export CONFIG_PATH=./config.json
```

#### 步骤3：初始化数据库
```bash
# 创建数据库
createdb marketdata

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

#### 步骤4：启动服务
```bash
# 开发模式
go run ./cmd/server

# 或使用Makefile
make run

# 生产模式
make build
./bin/market-data-service
```

#### 步骤5：验证
```bash
# 健康检查
curl http://localhost:8080/v1/admin/health

# 访问管理后台
open http://localhost:8080/admin
```

---

## Docker启动（最简单）

### Python版本
```bash
cd python_market_data_service

# 构建并启动
docker-compose up -d

# 查看日志
docker-compose logs -f app
```

### Go版本
```bash
# 构建镜像
docker build -t market-data-service .

# 运行
docker run -d \
  -p 8080:8080 \
  -e TUSHARE_TOKEN=your_token \
  -e DATABASE_URL=postgres://... \
  market-data-service
```

---

## 数据同步

### 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
```

### 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 | Go |
|------|--------|----|
| 启动服务 | `python -m app.main` | `go run ./cmd/server` |
| 热重载 | `uvicorn app.main:app --reload` | `fresh` 或 `air` |
| 生产启动 | `uvicorn app.main:app --workers 4` | `./bin/market-data-service` |
| 后台运行 | `nohup python -m app.main &` | `nohup ./market-server &` |

### 数据库

```bash
# 连接数据库
psql postgresql://postgres:postgres@localhost:5432/marketdata

# 查看表
\dt stock.*
\dt futures.*

# 查看股票列表
SELECT * FROM stock.symbols LIMIT 10;
```

### 测试API

```bash
# 健康检查
curl http://localhost:8080/v1/admin/health

# 查询股票K线
curl "http://localhost:8080/v1/stock/klines/000001.SZ?start=20250301&end=20250307&freq=1d" \
  -H "X-API-Key: demo-api-key-2024"

# 热加载配置
curl -X POST http://localhost:8080/v1/admin/system/reload

# WebSocket测试
wscat -c ws://localhost:8080/v1/stream -H "X-API-Key: demo-api-key-2024"
> {"action":"subscribe","symbols":["000001.SZ"]}
```

---

## 故障排查

### 端口被占用
```bash
# 查找占用8080的进程
# Windows:
netstat -ano | findstr :8080
taskkill /PID <PID> /F

# Linux/Mac:
lsof -i :8080
kill -9 <PID>

# 或使用其他端口
# Python: uvicorn app.main:app --port 8081
# Go: PORT=8081 go run ./cmd/server
```

### 数据库连接失败
```bash
# 检查PostgreSQL是否运行
# Windows: 服务管理器查看 postgresql-x64-15
# Linux: sudo systemctl status postgresql

# Docker快速启动PostgreSQL
docker run -d --name postgres \
  -e POSTGRES_PASSWORD=postgres \
  -p 5432:5432 \
  postgres:15
```

### Python依赖问题
```bash
# 升级pip
pip install --upgrade pip

# 重新安装依赖
pip install -r requirements.txt --force-reinstall

# 使用国内镜像
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
```

### Go依赖问题
```bash
# 清理缓存
go clean -cache

# 重新下载
go mod download

# 整理依赖
go mod tidy
```

---

## 生产部署

### 使用Systemd（Linux）

**Python:**
```ini
# /etc/systemd/system/python-market-data.service
[Unit]
Description=Python Market Data Service
After=network.target

[Service]
Type=simple
User=marketdata
WorkingDirectory=/opt/python-market-data-service
Environment=PATH=/opt/python-market-data-service/venv/bin
ExecStart=/opt/python-market-data-service/venv/bin/uvicorn app.main:app --host 0.0.0.0 --port 8080
Restart=always

[Install]
WantedBy=multi-user.target
```

**Go:**
```ini
# /etc/systemd/system/market-data.service
[Unit]
Description=Market Data Service
After=network.target

[Service]
Type=simple
User=marketdata
WorkingDirectory=/opt/market-data-service
ExecStart=/opt/market-data-service/bin/market-data-service
Restart=always

[Install]
WantedBy=multi-user.target
```

启用服务：
```bash
sudo systemctl daemon-reload
sudo systemctl enable market-data.service
sudo systemctl start market-data.service
sudo systemctl status market-data.service
```

---

## 下一步

- [完整部署文档](DEPLOY.md) - 详细部署指南
- [开发指南](docs/development-guide.md) - 如何开发新功能
- [API文档](docs/admin-api-quick-reference.md) - API接口参考

---

**提示**: 开发环境推荐Python（启动快、热重载），生产环境推荐Go（性能高、资源省）。