collector/README_NEW.md

# QMT数据采集器

这是一个用于采集QMT交易客户端状态数据并存储到PostgreSQL数据库的服务。

## 功能特性

- ✅ 使用 `github.com/robfig/cron/v3` 定时任务调度
- ✅ 每5秒(可配置)从HTTP接口采集数据
- ✅ 计算数据SHA256哈希值,检测数据变化
- ✅ 仅在数据变化时使用 `GORM` ORM存储到数据库,避免重复数据
- ✅ 自动数据库表结构迁移
- ✅ 完整的日志记录
- ✅ 优雅退出支持
- ✅ 环境变量配置

## 数据结构

采集的数据包括:
- **资产信息**: 账户资金、市值、盈亏等
- **订单信息**: 所有委托订单详情
- **持仓信息**: 当前持仓股票及盈亏
- **行情数据**: 实时tick行情数据

## 数据库表结构

系统会自动创建以下数据表:

1. `assets_snapshots` - 资产快照表
2. `orders` - 订单表
3. `positions` - 持仓表
4. `tick_data` - 行情数据表
5. `collection_logs` - 采集日志表

详细的表结构请查看 [scripts/schema.sql](scripts/schema.sql)

## 快速开始

### 1. 安装依赖

```bash
go mod download
```

### 2. 配置环境变量

复制 `.env.example` 为 `.env` 并修改配置:

```bash
cp .env.example .env
```

编辑 `.env` 文件:

```env
# 采集地址
COLLECTOR_URL=http://localhost:5000/status

# 数据库连接字符串 (修改为你的实际配置)
DATABASE_URL=postgres://user:password@localhost:5432/qmt_db?sslmode=disable

# 采集间隔(秒)
COLLECTION_INTERVAL=5
```

**注意**: 使用GORM后,程序会自动创建和迁移数据库表结构,无需手动执行SQL脚本。

### 3. 运行程序

```bash
go run cmd/main.go
```

或者设置环境变量后运行:

```bash
export COLLECTOR_URL=http://localhost:5000/status
export DATABASE_URL=postgres://user:password@localhost:5432/qmt_db?sslmode=disable
export COLLECTION_INTERVAL=5
go run cmd/main.go
```

### 4. 编译程序

```bash
go build -o collector cmd/main.go
```

## 配置说明

| 环境变量 | 说明 | 默认值 |
|---------|------|--------|
| COLLECTOR_URL | 数据采集地址 | http://localhost:5000/status |
| DATABASE_URL | PostgreSQL连接字符串 | postgres://user:password@localhost:5432/qmt_db?sslmode=disable |
| COLLECTION_INTERVAL | 采集间隔(秒) | 5 |

## 项目结构

```
collector/
├── cmd/
│   └── main.go           # 主程序入口
├── collector/
│   └── collector.go      # 数据采集器(HTTP请求、Hash计算)
├── models/
│   └── models.go         # 数据模型定义
├── storage/
│   └── storage.go        # 数据库存储模块
├── scripts/
│   ├── schema.sql        # 数据库表结构SQL
│   ├── build.sh          # 构建脚本
│   ├── deploy.sh         # 部署脚本
│   └── update.sh         # 更新脚本
├── exmple/
│   └── status.json       # 数据样本
├── go.mod                # Go模块文件
└── README.md             # 说明文档
```

## 技术栈

- **定时任务**: [github.com/robfig/cron/v3](https://github.com/robfig/cron/v3) - 强大的cron表达式调度器
- **ORM框架**: [GORM](https://gorm.io/) - Go语言优秀的ORM库
- **数据库驱动**: gorm.io/driver/postgres - PostgreSQL驱动
- **数据库**: PostgreSQL 9.6+

## 工作原理

1. **定时调度**: 使用cron调度器,根据配置的间隔定时执行采集任务
2. **数据采集**: 向配置的URL发起HTTP GET请求获取JSON数据
3. **Hash计算**: 对获取的数据计算SHA256哈希值
4. **变化检测**: 对比当前哈希与上次哈希,判断数据是否变化
5. **数据存储**: 如果数据有变化,使用GORM事务将数据保存到PostgreSQL数据库
6. **自动迁移**: 启动时自动检查并创建/更新数据库表结构
7. **日志记录**: 每次采集都记录日志,包括hash值和是否变化

## 错误处理

- HTTP请求失败会记录错误日志并继续下一次采集
- 数据库连接失败会导致程序退出
- 数据存储失败会记录错误但不会中断程序

## 注意事项

1. 确保PostgreSQL数据库已正确配置并可访问
2. **使用GORM后无需手动执行SQL脚本**,程序启动时会自动创建和迁移表结构
3. 建议在生产环境使用更安全的数据库连接方式
4. 可以根据需要调整采集间隔,但不建议设置过小
5. GORM会自动管理索引和表结构变更

## 开发

### 添加新功能

1. 在 `models/models.go` 中添加数据模型
2. 在 `storage/storage.go` 中实现数据库操作
3. 在 `collector/collector.go` 中扩展采集逻辑
4. 在 `cmd/main.go` 中集成新功能

### 测试

可以使用 `exmple/status.json` 中的样本数据进行测试。

## 许可证

MIT License