# CLAUDE.md

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

## 项目概述

这是一个 A 股量化交易分析系统，涵盖数据采集、策略回测、实时监控、机器学习预测、AI 智能分析和 Dagster 工作流编排。

## 开发环境

### Python 环境
- **Conda 环境**:
  - `dagster`: Dagster 工作流编排专用环境
    ```bash
    conda activate dagster
    ```
  - `prefect`: Prefect 3.4.4 工作流编排专用环境
    ```bash
    conda activate prefect
    ```

### 服务器配置
- **POWER04** (家庭内网服务器):
  - 配置: 32C 128G
  - 网络: 家庭宽带内网，使用 SakuraFrp 进行内网穿透
  - 主要使用: `prefect` conda 环境

- **JDYUN02** (京东云服务器):
  - 配置: 4C 8G
  - 网络: 京东云
  - 主要使用: `dagster` conda 环境

### 配置文件
- **主配置文件**: `config.ini`（不在版本控制中，包含敏感信息）
  - Tushare API token (`tushare`)
  - PostgreSQL 数据库凭据 (`postgresql_local`, `postgresql_power04`, `postgresql_jdyun`)
  - 企业微信 webhook (`wecom`)
  - PushPlus token (`pushplus`)
  - WxPusher token (`wxpusher`)
  - 交易账户 (`trader`)

## 常用命令

### 数据下载
```bash
cd 01_data_download
python 01_a_stock_trade_cal.py          # 交易日历
python 01_dim_date.py                    # 日期维度
python 01_agg_l1_data_to_yearly_file.py  # Level1 数据聚合
python download_financial_statements.py  # 财务报表
python download_stk_factor_pro.py        # 因子数据
python download_ths_data.py              # 同花顺概念数据
python download_concept_features.py      # 概念特征
python download_cyq_chips.py             # 筹码分布
```

### 数据处理
```bash
cd 02_data_processing
python 02_recompress_parquet_zstd.py     # Zstandard 压缩优化
python 02_zip_2_parquet_by_day.py        # Zip 数据按日转 Parquet
python 02_sync_data_to_jdyun.py          # 同步数据到京东云
```

### Prefect 工作流
```bash
cd prefect
./start_prefect_worker_stock.sh          # 启动标准数据处理 worker (使用 stock conda 环境)
./start_prefect_worker_autogluon.sh      # 启动 AutoGluon ML worker (使用 autogluon conda 环境)
prefect deploy --all                      # 部署所有工作流
prefect deployment ls                     # 列出部署
```

### Dagster 工作流
```bash
# 本地环境启动 Dagster 服务
cd dagster_jobs
./start_dagster_webserver.sh             # 启动 Dagster Web UI (端口 3100, 用户 enlai)

# 京东云环境启动 Dagster 服务
cd dagster_jobs
./start_dagster_webserver_jd_yun.sh      # 启动 Dagster Web UI (端口 3000, 用户 root)

# 常用命令
dagster job list -f <file.py>            # 列出作业
dagster job execute -f <file.py> <job>   # 执行作业
dagster instance migrate                 # 初始化/更新数据库表
dagster dev -h 0.0.0.0 -p 3100 -w workspace.yaml  # 启动开发服务器（使用 workspace.yaml）

# 环境变量（本地环境）
export DAGSTER_HOME=/home/enlai/dagster_home
export DAGSTER_CONFIG_YAML=/home/enlai/dagster.yaml

# 环境变量（京东云环境）
export DAGSTER_HOME=/root/dagster_home
```

### 策略回测
```bash
cd 03_backtest
python 03_vectorbt_ha_st_optimize.py            # HA-ST 参数优化
python 03_vectorbt_ha_st_multi_freq_optimize.py # 多频率优化
python 03_vectorbt_ha_st_quantstats_report.py   # 量化统计报告
```

### 策略监控
```bash
cd 04_strategy
python 04_qmt_ha_st_indecator_cal.py   # 计算 HA-ST 指标
python 04_qmt_monitor_ha_st_30m.py     # 监控 30 分钟 HA-ST 信号
```

### 机器学习模型（涨停预测）
```bash
cd 07_ml_models/limit_up_models_20260215
python a_stock_limit_up_predict_01.py   # 步骤1: 标签和权重
python a_stock_limit_up_predict_02.py   # 步骤2: 特征工程
python a_stock_limit_up_predict_03.py   # 步骤3: 模型训练
python a_stock_limit_up_predict_04.py   # 步骤4: 结果处理
# 也可使用 Jupyter Notebook: a_stock_limit_up_predict_03.ipynb

# 特征重要性分析
cd 07_ml_models/feature_importance
python calculate_moneyflow_features.py           # 计算资金流向特征
python calculate_moneyflow_feature_importance.py # 计算特征重要性
```

## 架构设计

### 目录结构（编号系统）
```
01_data_download/        # 从多数据源采集数据
02_data_processing/      # 离线数据处理（tick转parquet、压缩、云同步）
03_backtest/             # 使用 VectorBT 进行策略回测
04_strategy/             # 实时策略监控
05_sql_ddl/              # PostgreSQL 数据库表结构定义
07_ml_models/            # 机器学习预测模型
08_ai_agent/             # AI 多维度智能分析
99_not_used/             # 已归档代码（含历史实验Notebook）
prefect/                 # Prefect 3.4.4 工作流编排
dagster_jobs/            # Dagster 1.12.14 作业定义
```

### 模块职责

**01_data_download/**: 数据采集管道
- `common.py`: 共享工具函数（数据库连接、交易日历、股票代码转换）
- 数据源: Tushare、Baostock、同花顺（THS）
- 存储: PostgreSQL 使用 COPY 命令高效批量导入

**02_data_processing/**: 离线数据处理
- Tick 数据转 Parquet 格式
- Zstandard 压缩优化
- 数据同步到京东云数据库
- **QMT Level1 Tick 数据特性**:
  - 数据频率: 3秒一次的快照数据
  - 集合竞价阶段:
    - `bid_vol_1` = `ask_vol_1`，是累积值
    - `bid_vol_2` 和 `ask_vol_2` 在集合竞价阶段互斥，代表未匹配量的单边

**03_backtest/**: 策略回测
- `common_bt.py`: 回测工具（日志、HA-ST 指标计算）
- 核心策略: Heikin Ashi + SuperTrend
- 优化目标: 总收益率、年化收益率、夏普比率、卡尔玛比率、胜率、盈利因子
- 使用 16 核并行优化

**04_strategy/**: 实时监控
- `common_qmt.py`: QMT 交易工具（通知、日志、数据库）
- 通知渠道: 企业微信、邮件、PushPlus、WxPusher
- 集成平台: 迅投 QMT 量化交易平台

**05_sql_ddl/**: 数据库表结构
- 关键表: `a_stock_basic`、`a_stock_*_kline_*`、`a_stock_financial_*`、`a_stock_*_concept`、`a_stock_limit_list`、`a_stock_daily_factor_pro`
- 在 `trade_date` 和 `ts_code` 上创建索引
- 包含 Baostock 相关表结构（指数K线、复权因子）

**07_ml_models/**: 涨停股票 ML 预测
- **目标**: 预测涨停股票在 5 个交易日内先达到 +10% 还是先跌破 -5%
- **标签逻辑**:
  - `label=1`: 先触及 +10% 阈值
  - `label=0`: 先触及 -5% 阈值或观察期内都未触及
  - `weight=50`: T1 日高开跳水超过 8%（降权）
  - `weight=1`: 正常情况
- **子模块**:
  - `feature_engineering/`: 自动化特征工程（Featuretools、tsfresh、Boruta）
  - `feature_importance/`: 特征重要性分析（约400+特征，包含技术指标、资金流等）
  - `limit_up_models_20260215/`: 最新模型版本（2026年2月）
- **特征类别**: K线形态、技术指标、资金流、概念热度、市场情绪、基本信息
- **特征重要性评估**: IC、ICIR、AUC、SHAP、Coverage，加权计算综合重要性得分

**08_ai_agent/**: AI 智能分析框架
- 六维分析框架:
  1. 技术面（趋势、动量、量价关系、关键价位）
  2. 基本面（财务质量、估值水平、成长能力）
  3. 行业与赛道（行业空间、竞争格局、产业链）
  4. 政策与宏观（产业政策、货币政策、宏观经济）
  5. 资金与情绪（资金流向、市场情绪、龙虎榜）
  6. 公司治理与事件（公司治理、重大事件、风险排查）


**dagster_jobs/**: Dagster 1.12.14 工作流编排
- **存储配置**: MySQL (`dagster` 数据库)
- **启动脚本**:
  - `start_dagster_webserver_jd_yun.sh`: 京东云环境 Web UI (端口 3000, DAGSTER_HOME=/root/dagster_home)
- **配置文件**: `workspace.yaml` - 使用 python_package 模式加载 dagster_jobs 包
- **核心概念**:
  - `@op`: 操作（最小可执行单元）
  - `@job`: 作业（多个操作的组合）
  - `@asset`: 资产（数据产品，有版本控制）
- **通用工具**: `common_dagster.py` - 数据库连接、配置加载、数据保存（支持 UPSERT）
- **主要作业**:
  - 基础数据: `a_stock_basic.py`, `a_stock_daily_basic.py`, `a_stock_daily_factor_pro.py`
  - K线数据: `a_stock_baostock_multi_freq_kline.py`, `a_stock_baostock_index_1d_kline.py`
  - 财务报表: `a_stock_financial_*_table.py`
  - 其他数据: `a_stock_moneyflow.py`, `a_stock_ths_*.py`, `a_stock_chips_distribution.py`, `a_stock_margin_detail.py`
  - 涨停预测: `a_stock_limit_up_predict_*.py`

### 数据流
```
数据源（Tushare/Baostock/同花顺）
    ↓
Dagster 工作流（定时触发）
    ↓
数据下载脚本（01_data_download/ 或 dagster_jobs/）
    ↓
PostgreSQL 数据库（05_sql_ddl/ 表结构）
    ↓
特征工程（07_ml_models/）
    ↓
ML 模型训练/预测（07_ml_models/ 或 dagster_jobs/）
    ↓
策略回测（03_backtest/）
    ↓
实时监控（04_strategy/）
    ↓
通知发送（企业微信/邮件/PushPlus/WxPusher）
```

## 代码规范

### 文件命名
- `common.py`: 模块通用工具
- `common_bt.py`: 回测工具
- `common_qmt.py`: QMT 交易工具
- `common_prefect.py`: Prefect 通用工具
- `common_dagster.py`: Dagster 通用工具
- `01_*.py`: 数据下载脚本
- `03_*.py`: 回测脚本
- `04_*.py`: 策略脚本
- `a_stock_*.py`: Prefect/Dagster 工作流脚本

### 代码风格
- **编码**: UTF-8
- **风格**: PEP 8
- **命名**: 变量用 snake_case，类用 CamelCase，常量用 UPPER_CASE
- **函数注释**: 使用三引号 `"""`，尽量用一行简洁描述函数功能
- **单行代码**: 能一行写完的不要换行，允许写很长的单行代码
- **SQL语句**: 允许换行
- **异常处理**: 尽量少用 try-except，仅在必要时使用
- **import 语句**: 写在代码头部，不要分散到各函数中
- **参数设置**: 所有入参变量统一写在代码头部，紧跟 import 语句之后
- **通用函数**: 放置在 common_xxx.py 中

示例:
```python
# ====== 参数设置区域 ======
START_DATE = '2023-01-01'
END_DATE = '2025-12-31'
UP_THRESHOLD = 0.1
KLINE_PROCESSES = 16
# ================================

"""下载交易日历数据"""
def download_trade_calendar(start_date: str, end_date: str) -> pd.DataFrame:
    return ts.pro_api(token).trade_cal(exchange='SSE', start_date=start_date, end_date=end_date)
```

### 性能模式
- **并行处理**: 默认 16 进程（16核CPU），使用 `multiprocessing.Pool` 或 `concurrent.futures`
- **向量化操作**: 优先使用 pandas/numpy 内置方法
- **数据库导入**: 使用 COPY 命令批量导入，不用 INSERT
- **批量处理**: 大文件使用 `chunksize`

### 数据库操作
- **UPSERT 模式**: 使用 `ON CONFLICT DO UPDATE/NOTHING`
- **连接池**: `pool_size=20, max_overflow=40, pool_pre_ping=True`
- **及时释放**: 使用后调用 `engine.dispose()`
- **索引**: 在 `trade_date` 和 `ts_code` 列上创建
- **多数据库支持**: `postgresql_local`（本地）、`postgresql_power04`（远程）、`postgresql_jdyun`（京东云）

### 日志记录
- **工具**: `loguru`
- **级别**: INFO
- **编码**: UTF-8（支持中文）
- **轮转**: 10MB，保留 30 天

## 重要注意事项

### 交易日历
- 支持格式: `YYYYMMDD`、`YYYY-MM-DD`
- 优先查询本地数据库，失败时回退到 Tushare API
- 时区: `Asia/Shanghai`

### 模型版本管理
- 按日期命名: `limit_up_models_YYYYMMDD`
- 当前最新版本: `limit_up_models_20260215`
- 旧版本移至 `99_not_used/`
- 保留实验记录（Jupyter Notebook）

### 通知系统
- **企业微信**: 使用 webhook 发送 Markdown 消息
- **邮件**: 使用 yagmail，支持抄送
- **PushPlus**: 推送到手机/桌面
- **WxPusher**: 微信推送服务
- **错误处理**: 通知失败不影响主流程

### Dagster 端口配置
- 本地环境（用户 enlai）: Web UI 端口 3100, `DAGSTER_HOME=/home/enlai/dagster_home`
- 京东云环境（用户 root）: Web UI 端口 3000, `DAGSTER_HOME=/root/dagster_home`


## 技术栈

**数据处理**: pandas、numpy、sqlalchemy、psycopg2
**数据源**: tushare、baostock、迅投QMT
**机器学习**: AutoGluon（首选）、PyCaret、TabPFN、scikit-learn
**特征工程**: Featuretools、tsfresh、Boruta
**回测框架**: VectorBT、quantstats
**工作流**: Dagster 1.12.14
**可视化**: matplotlib（支持中文字体）
**工具库**: loguru、tqdm、configparser
**压缩**: Zstandard (zstd)