fix(market-data): 完善 Tushare 全量同步配置

This commit is contained in:
yuxuanhui
2026-08-06 22:45:18 +08:00
parent afdc5ca909
commit 039a81fe57
6 changed files with 119 additions and 7 deletions
+24
View File
@@ -13,6 +13,7 @@
- 应用用例:`SyncMarketData.execute(command: SyncMarketDataCommand | None = None) -> SyncBatchSummary`。
- CLI:`market-data-sync [--initialize | --retry-batch-id <id>] [--trade-date YYYY-MM-DD]`。
- 数据源端口:`fetch_stocks()`、`fetch_open_dates(start, end)`、`fetch_bars(ts_code, window)`、`fetch_daily_basic(trade_date)`。
- `TushareAdapter.from_token` 必须保存 `ts.pro_api(token)` 返回的 client,并通过 `ts.pro_bar(api=client, ...)` 调用 qfq 行情;不得依赖 Tushare 模块级全局 token。
- 数据库事实表:`market_stock`、`market_daily_bar(ts_code, trade_date)`、`market_daily_basic(ts_code, trade_date)`;同步审计表:`market_sync_batch`、`market_sync_item`。
### 3. Contracts
@@ -29,6 +30,7 @@
- 当前生产 PostgreSQL 在 `1panel-network` 上的稳定别名为 `postgresql`,服务端 SSL 为关闭状态,生产连接串使用 `sslmode=disable`;数据库用户必须具备 `public` schema 的 `CREATE` 权限以执行 Alembic 迁移。
- 股票 qfq 快照路径为 `bars/<ts_code>.csv`;每日指标路径为 `daily-basic/<YYYY>/<YYYYMMDD>.csv`;当前股票主数据为 `stock-basic/current.csv`。
- `market_daily_bar` 的唯一键是 `(ts_code, trade_date)`,`source_adj` 必须是 `qfq`;所有价格、金额和比率使用有限 `NUMERIC`/`Decimal`。
- Tushare 返回的空字符串、`None`、浮点或字符串 `NaN` 映射为数据库 `NULL`;正负无穷和其他非有限数值必须拒绝,不能写入事实表。
- `SyncBatchSummary` 至少返回 `batch_id`、目标交易日、窗口、状态、目标数、有效数、覆盖率、策略资格、插入数、更新数、未变化数和失败列表。
- 退出码:`0` 表示覆盖率达标的成功批次;`2` 表示部分成功或覆盖率不足;`1` 表示失败或没有可用成功结果。
- 单股票流程必须保持“临时 CSV → 指纹比较 → PostgreSQL 事务 → `os.replace` 发布”顺序;数据库异常不得替换正式 CSV。
@@ -43,6 +45,8 @@
| 重叠区间指纹相同 | 只批量插入旧上界之后的新交易日 |
| 重叠行字段变化、缺失或快照开始边界异常变化 | 当前股票执行六年窗口集合式 upsert/删除 |
| `daily_basic` 没有目标股票行 | 当前指标日期 item 失败,不发布空正式快照 |
| `pro_bar` 未绑定 `pro_api(token)` client | 当前股票 item 失败;适配器必须把 client 作为 `api` 参数传入模块级 `ts.pro_bar` |
| `daily_basic` 可空数值为 `NaN` | 该字段规范化为 `NULL`;正负无穷仍作为校验错误处理 |
| PostgreSQL/COPY/迁移异常 | 转换为安全的 repository error;成功对象不回滚,失败对象保留旧发布版本 |
| 同一环境已有同步锁 | 返回 `failed` 和退出码 `1`,不执行第二个批次 |
| `valid / target < coverage_threshold` | 不触发选股,批次显式标记 `strategy_eligible=false` |
@@ -51,6 +55,7 @@
- Good:相同六年 qfq 返回重复执行,指纹相同,数据库无无意义 update,正式 CSV 可原子替换,覆盖率为 `1`。
- Base:新增一个开市日且历史重叠不变,只 COPY 新日期;批次成功后清理窗口起点之前的数据库行和日期文件。
- Good:`daily_basic` 的缺失估值以 `NULL` 保存,使用 token client 的 `pro_bar` 能够完成真实 qfq 请求。
- Bad:一只股票历史 qfq 行变化或数据库事务失败,只修复/失败该股票;其他股票成功结果保留,失败对象正式 CSV 不被替换。
### 6. Tests Required
@@ -58,6 +63,7 @@
- 领域单元测试:六年窗口边界、输入顺序稳定性、历史值变化、重叠缺行、窗口提前、ST/北交所过滤;断言 `SnapshotChange` 和股票代码集合。
- CSV 单元测试:固定表头、临时文件、原子发布、异常/丢弃后旧正式文件仍可读;断言正式文件内容和临时文件清理。
- 同步编排测试:`success`、覆盖率、幂等重跑、空指标失败、部分失败和失败 item 重试;断言 batch/item 状态与退出码。
- Tushare 适配器回归测试:断言 `pro_bar` 收到由 `pro_api(token)` 创建的 `api` client;领域测试断言 `NaN -> None` 且无穷值被拒绝。
- PostgreSQL 集成测试:设置 `ZHIXING_TEST_DATABASE_URL` 后运行 Alembic upgrade,断言五张业务/审计表、唯一键和迁移头;批量 upsert 测试断言 insert/update/unchanged 计数和事务回滚。
- 质量门禁:`uv lock --check`、后端 Ruff/Pyright/pytest、前端/root `./dev.sh check` 与 `./dev.sh test`、四种 Compose config。
@@ -79,4 +85,22 @@ market_daily_bar[(ts_code, trade_date)] = bar
market_daily_basic[(ts_code, trade_date)] = daily_basic
```
#### Tushare client 与可空数值
错误:
```python
# 这会绕过 pro_api(token) 返回的 client,依赖未配置的模块级全局 token。
ts.pro_bar(ts_code=ts_code, adj="qfq")
```
正确:
```python
client = ts.pro_api(token)
ts.pro_bar(api=client, ts_code=ts_code, adj="qfq")
```
`NaN` 是供应商对缺失指标的常见表示,应在领域规范化阶段转为 `None`;`inf` 和 `-inf` 不属于缺失值,必须报校验错误。
> **Warning**:CSV 发布不是数据库事务的一部分。只有数据库事务成功后才能执行原子 `os.replace`;发布失败必须记录为 item 失败并依靠幂等重试恢复。