myquant/CLAUDE-data.md

CLAUDE-data.md — 数据层 + 数据库

DataManager (finance/data/data_manager.py)

双数据源：Tushare（优先）→ AkShare（fallback）。DB 缓存优先。

from data.data_manager import DataManager
dm = DataManager()
dm.init_db()  # 首次建表（幂等）

关键方法

stocks = dm.get_stock_list()          # → 5524 只, DB 优先
daily  = dm.get_daily("000001.SZ")    # DB优先 → Tushare → AkShare
fina   = dm.get_financial("000001.SZ")  # 同花顺 + fallback
n      = dm.sync_daily("000001.SZ")   # 增量同步: latest>=today → 跳过

指数 vs 个股路由

_try_fetch() 自动检测 is_index_code()：

• 000001.SH / 399001.SZ → fetch_index_daily()（Tushare index_daily / AkShare index_zh_a_hist）
• 000001.SZ / 600519.SH → fetch_daily()（stock daily）

数据源 (finance/data/sources/)

• akshare_source.py — AkShareSource（个股+指数+财务）
• tushare_source.py — TushareSource（需 TUSHARE_TOKEN，available=False 自动跳过）

数据库 (finance/database/)

连接

from database.connection import get_engine, test_connection
# get_engine() 自动检测断连 → 运行 autossh.sh → 重建引擎

表结构（mac_ 前缀）

表	内容	主键
mac_stock_basic	A股列表, 5524只	ts_code
mac_stock_daily	日线 OHLCV	(ts_code, trade_date)
mac_stock_financial	财务指标	(ts_code, end_date)
mac_report	报告持久化	id

DAO (finance/database/dao.py)

• _DAILY_COLS / _FINA_COLS — 入库前字段筛选
• get_latest_trade_date(ts_code) → 增量判断
• save_report() / query_reports() → 报告管理

配置

# SSH 隧道
bash shared/script/autossh.sh
# host: 127.0.0.1:13306  user: myquant  database: myquant

缓存策略

• sync_daily: 已缓存且最新 → 0.04s 跳过
• 未缓存 → 提示 agent_cli.py warmup
• 每日增量只更新已缓存股票，未缓存统计跳过

⚠️ 已知 Bug 速查（避免重复踩坑）

B1: .env 加载路径

• 症状: Tushare available=False, QWEN_API_KEY 读不到
• 根因: load_dotenv() 不传路径，从 CWD 找 .env，而非 finance/
• 修复: config/settings.py 用 Path(__file__).parent.parent / ".env"
• 加固: tushare_source.py, qwen_client.py, news_source.py 顶部 import config.settings

B2: SSH 重连只生效一次

• 症状: 第一次断连能恢复，第二次断连无法恢复
• 根因: _ssh_auto_attempted 全局变量设 True 后永不重置
• 修复: 移除该变量。get_engine() 每次断连都触发 _reconnect_ssh() → dispose() → 重建

B3: 连接池半开连接

• 症状: _test_engine() 返回 True 但实际查询报 _read_bytes 超时
• 根因: 池中有活连接也有死连接，test 取到活的，查询取到死的
• 修复: pool_pre_ping=True + pool_recycle=600 + 断连时 _engine.dispose()

B4: save_daily 主键冲突

• 症状: IntegrityError: Duplicate entry '000001.SZ-20260603'
• 根因: Tushare 返回的数据含已存在的日期，append 模式遇主键冲突
• 修复: 写入前 DELETE FROM mac_stock_daily WHERE ts_code IN (...) AND trade_date IN (...)

B5: 数据不更新排查清单

• 检查 SSH 隧道: lsof -i :13306 | grep LISTEN
• 检查 Tushare: python -c "from data.sources.tushare_source import TushareSource; print(TushareSource().available)"
• 检查最新数据: from database.dao import get_latest_trade_date; print(get_latest_trade_date('000001.SZ'))
• 手动触发 sync: dm.sync_daily('000001.SZ')
• 预期行为: T+1 数据产出，节假日无新数据属于正常