trade/CLAUDE.md

CLAUDE.md

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

项目概述

基于 Docker + Python(tushare) 的中国期货行情分析系统,实现日线数据采集、三层加权打分模型与 Bark 推送通知。运行方式定位为脚本自动化(宿主机 cron/launchd 等定时调用 docker-compose run),不规划独立后端服务。详细业务说明见 使用说明.md。

常用命令

# 不传参 = 按当月 FG 主力自动选合约(轮换规则见 contracts.py:ROLLOVER_RULES)
docker-compose run --rm tushare

# 显式指定合约(注意交易所后缀:.ZCE/.SHF/.DCE,郑商所是 .ZCE 不是 .CZC)
docker-compose run --rm tushare python -m src.main RB2510.SHF

# 用品种代号自动选当月主力(目前只配置了 FG)
docker-compose run --rm tushare python -m src.main --symbol FG

# 修改 tushare/src/ 下任意 .py 后必须重建镜像
docker-compose build tushare

# 查最新打分
sqlite3 data/futures.db "SELECT ts_code, trade_date, composite, signal FROM scores ORDER BY trade_date DESC LIMIT 5;"

tushare/.env 必须存在且含 TUSHARE_TOKEN=xxx(已 gitignored)。可选 BARK_KEY 覆盖 notifier.py 默认 key。

关键架构

单进程串行流水线:src.main.main() 先按命令行参数(显式 ts_code 优先,否则 contracts.active_contract(symbol) 按当月主力自动选)定下合约,再调 run() 顺序执行 fetcher → storage(candles) → scorer → storage(scores) → notifier。无后台任务、无队列,每次 CLI 调用处理一个合约一日。

主力轮换规则(contracts.py):每个品种在 ROLLOVER_RULES 中维护 month -> (主力月, 年份偏移) 表。FG 当前规则:1-3/12 月→05、4-7 月→09、8-11 月→01,其中 8-11 月与 12 月跨年(year_offset=1)。新增品种(如 RB、I)只需在该 dict 里加一条,无需改 main 流程。

三层打分模型(scorer.py):综合 = 短期(7日,0.4) + 中期(15日,0.35) + 长期(30日,0.25)。score_daily() 要求 DataFrame ≥31 行,fetcher.fetch_contract 默认拉一个合约的全历史(实际 100+ 行),按 trade_date 升序排列后供打分使用。打分结果通过 dataclass ScoreResult + ScoreDetail 流转,storage.save_score 把 detail 序列化为 detail_json 文本列。

SQLite 作为唯一数据面:storage.py 的 candles 与 scores 两表都用 INSERT OR REPLACE(候选键 (ts_code, trade_date))实现幂等,可反复重跑同一天。PRAGMA journal_mode=WAL,提升并发读写。表结构在 init_db() 中维护,新增字段需同步该函数。

Docker 边界:docker-compose.yml 仅把 ./data 挂为 /app/data(数据持久化);tushare/src/ 是在 Dockerfile 的 COPY --chown=app:app src ./src 阶段拷进镜像的,没有源码挂载——改完 Python 代码不重建镜像就跑等于跑旧代码。这是重要陷阱。

Bark 推送:notifier.push_bark 用 requests.get 走路径形式(/{key}/{title}/{body}),所有片段以 quote(safe='') URL 编码,失败仅 print [WARN] 不抛错。容器内首发请求有时 DNS 慢导致 15s timeout,内置 1 次重试;主机直连通常 <1s。

配置/密钥规则

.gitignore 排除范围广(见文件):data/、*.db*、.env*、CTP 流文件(*.con/*.dat/ResultInfo.xml 等)、.claude/、所有日志。新增任何账户、token、行情流文件务必先确认匹配 ignore 规则。