Simon
6acf938caf
- 删除 11 个残留文件: continuation.md, init_plan.md, reasonix.toml, djapi/continuation.md, djapi/.serena/, djapi/.claude/, djapi/.mcp.json, .claude/skills/, docs/usage.html, docs/db_schema.md, docs/report_db_design.md - 7 个 CLAUDE-*.md 移入 docs/ 并重命名去 CLAUDE- 前缀 - 新增 4 个文档: architecture.md, development.md, api.md, deployment.md - 重写 usage.md, README.md - 修复所有过时引用和交叉链接
100 lines
3.7 KiB
Markdown
100 lines
3.7 KiB
Markdown
# 数据层 + 数据库
|
||
|
||
## DataManager (`finance/data/data_manager.py`)
|
||
|
||
双数据源：Tushare（优先）→ AkShare（fallback）。DB 缓存优先。
|
||
|
||
```python
|
||
from data.data_manager import DataManager
|
||
dm = DataManager()
|
||
dm.init_db() # 首次建表（幂等）
|
||
```
|
||
|
||
### 关键方法
|
||
|
||
```python
|
||
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/`)
|
||
|
||
### 连接
|
||
|
||
```python
|
||
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()` → 报告管理
|
||
|
||
### 配置
|
||
|
||
```bash
|
||
# 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 数据产出，节假日无新数据属于正常
|