Chan/CLAUDE.md

CLAUDE.md

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

Project Overview

缠论 (Chan Theory) technical analysis system for Freqtrade. Implements Chan Zhong Shui Chan's theory for crypto/stock trading, including fractal (分型), stroke (笔), segment (线段), pivot/center (中枢), and buy/sell point (买卖点) detection.

Core Architecture

Chan Theory Engine (chan/ package)

引擎已分层解耦；根目录 Chan*.py / TF_DF.py 仅为兼容旧 import 的 shim。新代码优先：

from chan import ChanLun, TF_DF
from chan.indicators import IndicatorEngine, IndicatorStore
from chan.analysis.bsp_macd import confirm_bsp, bi_macd_area

层	路径	职责
core	chan/core/	纯结构：KLU→KLC→BI→SBI→SEG→ZS→BSP 几何；不依赖 talib/指标参数
indicators	chan/indicators/	IndicatorConfig / IndicatorEngine / IndicatorStore；MACD/EMA/BB/RSI 外置计算
analysis	chan/analysis/	结构+指标接合：ChanMACD、bsp_macd（ConfirmedBSP）、Zone/Classifier 等
pipeline	chan/pipeline/	TF_DF / ChanLun 编排：先指标再结构，可选 attach 兼容

流水线：

1. chan/core/ChanKLU.py — K 线单元（OHLCV + 结构链）；指标字段仅兼容挂载
2. chan/core/ChanKLC.py — 合并 K 线：包含处理、分型
3. chan/core/ChanBI.py — 笔
4. chan/core/ChanSBI.py — 特征笔
5. chan/core/ChanSEG.py — 线段
6. chan/core/ChanZS.py / ChanBIZS.py — 中枢
7. chan/core/ChanBSP.py — 几何买卖点
8. chan/analysis/bsp_macd.py — 买卖点 × MACD 背驰 → ConfirmedBSP
9. chan/pipeline/ChanLun.py / TF_DF.py — 多周期/单周期编排

Support modules

• chan/core/ChanEnum.py — 枚举
• chan/core/ChanCTime.py — 时间工具
• chan/analysis/ChanMACD*.py — MACD 状态/段分析（读 KLU 上兼容指标或 Store）
• chan/analysis/ChanZone.py / ChanHeng.py / ChanLun_Classifier.py 等 — 分析扩展
• chan/analysis/ChanPY.py — 外部 chan.py 桥接（与本包名冲突已隔离）

Services

• data_provider/ — FastAPI data service: fetches crypto data from Binance via CCXT, caches to CSV, serves REST API + WebSocket. Synthesizes derived timeframes (e.g. 5m/15m/4h from 1m/1h base). Port 9009.
• web/ — Flask web UI for interactive chart visualization with Chan theory overlays. Port 8123.（本重构分支不改 web）
• strategies/ — Freqtrade trading strategies using the Chan theory engine (53 strategies)
• config/ — Freqtrade JSON config files per pair/timeframe

Data Flow

Exchange (CCXT) → data_provider (CSV cache) → Freqtrade → Strategy
  → ChanLun / TF_DF
      → IndicatorEngine → IndicatorStore
      → KLU → KLC → BI → SBI → SEG → ZS → 几何 BSP
      → analysis.bsp_macd → ConfirmedBSP

Common Commands

Freqtrade Trading

# Live trade
freqtrade trade -c ./user_data/Chan/config/<config>.json --strategy <StrategyName> --strategy-path ./user_data/Chan/strategies

# Backtest
freqtrade backtesting -c ./user_data/Chan/config/<config>.json --strategy <StrategyName> --strategy-path ./user_data/Chan/strategies --timerange=20251008-

# Download data
freqtrade download-data -c ./user_data/Chan/config/<config>.json -t 1m 1h 1d --pairs BTC/USDT:USDT --timerange=20240101-

# Hyperopt
freqtrade hyperopt --hyperopt-loss SharpeHyperOptLossDaily --spaces roi --strategy <StrategyName> --strategy-path ./user_data/Chan/strategies -c ./user_data/Chan/config/<config>.json -e 200 --timerange=20250201-20250901

# Plot
freqtrade plot-dataframe --strategy <StrategyName> --datadir user_data/data/binance -c ./user_data/Chan/config/<config>.json --timerange=20250721-

Data Provider

# Docker
cd data_provider && docker compose up -d

# Direct
cd data_provider && python main.py

# With custom config
CONFIG_PATH=./config.json python main.py

Web UI

cd web && python app.py
# or via gunicorn:
gunicorn -w 4 -b 0.0.0.0:8123 app:app

# Deploy scripts:
cd web && ./deploy.sh          # standard
cd web && ./deploy_venv.sh     # Ubuntu 22.04+ (venv)

Docker (Freqtrade)

sudo docker compose run --rm chanlun_btc backtesting -c ./user_data/Chan/config/<config>.json --strategy <StrategyName> --strategy-path ./user_data/Chan/strategies --timerange=20250721-

Key Conventions

• All Chan theory classes are prefixed with Chan (e.g., ChanBI, ChanZS)
• Strategies import ChanLun and add sys.path.append(os.path.dirname(os.path.dirname(os.path.abspath(__file__)))) to import from parent
• MACD params: MACD(26, 52, 9) by default (slow period 52 instead of standard 26)
• Enums in ChanEnum.py use auto() values
• ChanKLC is a linked-list style data structure with .next/.pre pointers
• The TF_DF class is the primary data container per timeframe
• K-line direction uses Chan_KLINE_DIR (UP/DOWN/COMBINE/INCLUDED)
• All text comments/commits are in Chinese