# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## 项目概述

基于深度学习的 BTC 小时级涨跌预测系统，包含模型训练、FastAPI 后端、Vue 3 看板、Polymarket 自动交易。当前最佳模型 DLinear 准确率 53.10%。

## 环境与构建

```bash
# Python 环境（必须使用 Conda，禁止 venv/poetry）
conda activate crypto_pred_312

# 安装依赖（PyTorch 需根据平台单独安装，requirements.txt 不含 torch）
pip install -r requirements.txt

# 数据库：仅支持 MySQL，禁止 SQLite
# 配置：复制 .env.example 为 .env 并填写 MySQL 连接信息
```

## 常用命令

```bash
# 启动完整系统（API + 自动交易）
python start_system.py

# 单独启动 API 服务
python -m uvicorn api.main:app --host 0.0.0.0 --port 8000

# 单独启动自动交易
python auto_trade_polymarket.py

# 训练 DLinear 分类模型
python train_classification_full.py

# 测试模型（2026年数据）
python test_models_feb_2026.py

# 集成预测
python ensemble_predict.py

# 测试与检查
pytest
flake8 .
```

## 架构

```
数据流: Binance API → data/fetcher.py → data/preprocessor.py (技术指标) → data/dataset.py → 模型推理
交易流: 模型预测 → auto_trade_polymarket.py → Polymarket 下单 → MySQL 记录
服务流: FastAPI (api/main.py) → 前端看板 (api/static/) → http://localhost:8000
```

### 核心模块

- **`data/`** — 数据层：`fetcher.py`(Binance数据获取)、`preprocessor.py`(特征工程: RSI+MACD)、`dataset.py`(PyTorch数据集)、`database.py`(市场数据MySQL)、`trading_db.py`(交易历史MySQL)
- **`models/`** — 模型层：`dlinear/model.py`(主力模型，时序分解+线性层)、`nbeats/`、`base.py`(抽象基类)
- **`models/checkpoints/dlinear_classification_2026/`** — 训练产物：`best_model.pt`、`preprocessor.pkl`、`test_2026_results.json`
- **`training/`** — 训练层：`trainer.py`(训练循环，支持 MPS/CUDA/CPU)、`config.py`(超参数)、`evaluator.py`(评估)
- **`api/`** — 服务层：`main.py`(FastAPI入口)、`models.py`(DB操作+时区转换)、`prediction_service.py`(预测服务)、`polymarket_client.py`(交易客户端)
- **`start_system.py`** — 统一启动入口（同时启动 API 和自动交易）
- **`auto_trade_polymarket.py`** — 自动交易主程序（每小时执行预测+下单）

### DLinear 模型结构

输入 (168h × 9特征) → MovingAvg 时序分解 → 季节性/趋势分量各经线性层 → MLP 聚合 → logits 输出 (BCEWithLogitsLoss)

## 开发约束

- **数据库**：仅 MySQL（`pymysql`），禁止 SQLite。连接使用 `data/database.py` 的 `DatabaseManager` 或 `api/models.py` 的 `get_db_connection`
- **时区**：数据库存 UTC/ET，前端展示 CST（北京时间），转换用 `api.models.convert_to_cst()`
- **代码注释**：中文，解释"为什么"
- **命名**：变量/函数 `snake_case`，类 `PascalCase`
- **代理访问 Binance**：需在 `.env` 配置 `SOCKS5_PROXY` 和 `USE_PROXY=true`
- **日志**：交易日志在 `logs/polymarket_trading.log`（10MB 轮转）

## 禁止事项

- 禁止引入 SQLite 或恢复已删除的 SQLite 代码
- 禁止在未确认的情况下升级核心库版本（torch, pandas 等）
- 禁止删除看似无用但可能被外部脚本调用的代码