tdx2db: Instructions file for Claude Code

CLAUDE.md

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

项目概述

tdx2db：从本地通达信(TDX)行情软件读取 A 股数据，增量同步到数据库。是量化分析工作站的数据入口。

本文件面向贡献者（改 tdx2db 代码）。如果你是在消费数据库（查询 daily_data 等表做分析），请读 AGENTS.md——schema、典型查询、陷阱清单都在那里，配套 skill 见 .claude/skills/tdx2db-query/。

常用命令

# 安装依赖（开发模式，含 postgres/mysql 驱动）
pip install -e '.[all]'

# 一键增量同步（日线 + 5/15/30/60 分钟线）— 日常使用这一个命令即可
tdx2db sync

# 单独同步
tdx2db daily --db-only --auto-start --incremental
tdx2db minutes --db-only --auto-start --incremental

# 同步股票列表
tdx2db stock-list --db-only

# 数据库状态一览（只读，不需要 TDX_PATH；--json 机器可读）
tdx2db status

# 板块-个股关系同步（sync 已自动包含，也可单独跑）
tdx2db blocks --db-only

板块数据链（blocks.py，issue #39）：概念/指数/风格 ← T0002/hq_cache/infoharbor_block.dat（文本，板块名 8 字节截断需经 880 码还原全名）；行业 ← tdxhy.cfg X 码 × tdxzs3.cfg 类别 12（881 研究行业多级）；跨市场指数成分 ← spblock.dat；地区 ← base.dbf DY 字段 × tdxzs.cfg 类别 3。全量替换式快照（DELETE+INSERT），与行情表的增量语义不同。旧二进制 block_zs/gn/fg.dat 在新版通达信不存在，pytdx BlockReader 不适用。

python main.py <子命令> 与 tdx2db <子命令> 等价（main.py 是薄封装，保留老用户习惯）。包目录为 tdx2db/（v0.3.0 起从 src/ 改名，发布到 PyPI）。psycopg2-binary/pymysql 为可选依赖（extras: postgres/mysql/all），默认安装仅支持 SQLite。

测试：pytest tests/。CI 矩阵：ubuntu + windows × 3.9/3.11（+ ubuntu 3.10）——Windows 是用户主场景必须覆盖。tests/fixtures/ 存 .day/.lc5 二进制解析 fixture（合成字节，生成器 make_fixtures.py；断言值与生成参数一一对应）。数据正确性验证仍以运行 sync 后检查数据库为准。

发布 PyPI（维护者）

版本号需同步 bump 两处：pyproject.toml 与 tdx2db/__init__.py（教训：v0.3.0 曾漏改后者）。发布 token 为项目级，存本地 .env 的 PYPI_PROJECT_TOKEN（gitignored，勿打印其值）：

rm -rf dist && uv build
UV_PUBLISH_TOKEN=$(grep '^PYPI_PROJECT_TOKEN=' .env | cut -d= -f2-) uv publish

发布后必须在全新 venv pip install tdx2db==<版本> 验证（含从工作目录读 .env 的脚本入口场景，教训见 v0.3.1）。增量/幂等类改动的冒烟必须跑两轮（首轮全量 + 次轮增量）。

架构

四层管道，单向数据流：

CLI (cli.py)  → Reader (reader.py) → Processor (processor.py) → Storage (storage.py)
    ↓                ↓                      ↓                        ↓
 argparse        pytdx 读取本地       校验 + 重采样 + 均线      SQLAlchemy 批量写库
 命令分发 +      .day/.lc5 文件       (OHLCV 校验, resample,   支持增量 ON CONFLICT
 同步编排                              MA5~MA250)               表名白名单保护