⚙️ 本技能遵循公共运行环境契约（最高优先级，先于本文其余内容执行）： 详见 _shared/env-contract.md，执行前先读它。

quantdb-data-structure — QuantDB 数据结构与读取口径

写任何触碰 QuantDB 本地数据的代码/查询前必读。字段单位与口径陷阱另见 skills/quantdb-fields/SKILL.md（本技能管「数据在哪、怎么组织、怎么读」）。

一、路径映射（先定位数据）

⚠️ quantdb/ 是官方只读数据；quantcustom/ 是用户/挖掘产出（因子挖掘、因子工厂的落盘区，QM_QUANTCUSTOM_DATA_DIR）。两者结构同为 6 大类，但写入一律进 quantcustom，不要污染 quantdb。

数据目录解析优先级（quantdb_hub.py._resolve_data_dir）： 环境变量 QM_QUANTDB_DATA_DIR → /data/quantdb → /app/data/quantdb → D:/quant_data → 项目根 data/quantdb。

二、顶层数据集目录

辅助文件：releases/（数据包版本）、.sync_state / quantdb_sync.sqlite（增量同步状态）、.qlib_cache、_meta。

用户自定义数据集 quantcustom/6_ml_datasets/

挖掘产物统一落 data/quantcustom/6_ml_datasets/<数据集>/（结构与 quantdb 一致，按 dt=YYYYMMDD/ 分区）：

• 读取入口：QuantDBFactorReader(mode="CUSTOM")（QM_QUANTCUSTOM_DATA_DIR，默认 /data/quantcustom）。
• 只读展示：GET /api/v1/alpha-agent/factory-factors（读 l1_factors/MANIFEST.csv，只回显不回测）。
• 历史补全/落库路径：backend/services/api/routers/admin/alpha_factor_pipeline.py。

三、文件组织规律（决定查询写法）

1. 分区型：<数据集>/dt=YYYYMMDD/data.parquet。dt 是 Hive 分区列，整数（如 20260828），DuckDB 过滤 WHERE dt BETWEEN 20260101 AND 20260828 可走谓词下推，不要写字符串。
2. 单文件型：<数据集>/{symbol}.parquet（财务报表、分钟K）或整表单文件（instrument_detail.parquet），用 pd.read_parquet 直读。
3. 混合格式：6_ml_datasets/l1_factors/ 同时存在平铺 l1_factors_YYYYMMDD.parquet 与 dt=YYYYMMDD/ 分区——只读 dt=* 分区目录，避免混入平铺文件。
4. 北向资金特殊：2_base_sector/hsgt_north/ 日频在 daily_freq/*.parquet（无分区），季度快照用 quarter=YYYYQN Hive 分区（2024-08 起季度披露）。

四、代码格式口径（最高频踩坑点）

• 查 QuantDB parquet 前必须转换：后端用 backend/shared/stock_utils.py 的 StockCodeUtil.to_suffix(code)；前端 normalizeStockCode。
• 反面教训：把前缀式代码原样传进 parquet 查询会静默返回空、不报错，快路径还会悄悄跌入兜底数据源（复权口径随之失效）。写完新链路必须实测两种复权参数下首/末根数值真正分化，并核对响应的 source_used 字段。

五、读取入口与 DuckDB 视图清单

唯一推荐入口：backend/services/engine/data_platform/quantdb_hub.py（QuantDBDataHub）——懒加载、线程安全、自动做列名映射（time→trade_date、wind_code→symbol、volinstock/vol_in_stock→volume）。不要绕过它自己拼 parquet 路径，除非做数据巡检。

分区数据集挂载的 DuckDB 视图（hive_partitioning=1, union_by_name=true）：

临时探查可直接 DuckDB 查文件：

SELECT * FROM read_parquet('/data/quantdb/1_kline_data/daily_forward/dt=20260828/data.parquet')
WHERE symbol = '600519.SH';

六、服务器核查命令速查

# 目录与体量
ls /opt/quantmind/data/quantdb && du -sh /opt/quantmind/data/quantdb/*

# 容器内可见性
docker exec quantmind ls /data/quantdb

# 某交易日数据是否到位（以日K为例）
ls /opt/quantmind/data/quantdb/1_kline_data/daily_forward/dt=20260828/

数据更新后服务未感知时：docker compose restart quantmind celery-worker（数据走 bind mount，无需重建镜像）。增量同步需先在【个人中心】→【数据平台】绑定 QUANTDB_API_KEY 后 docker exec 触发。

七、写代码前的自查清单

• 用的是 QM_QUANTDB_DATA_DIR/默认目录解析，而不是写死路径？
• 分区过滤用的是整数 dt，范围合理（不跨年全表扫）？
• 查 parquet 的代码已转后缀式？查 PG 内部表保持前缀式？
• 查询结果为空时验证过不是「格式错配静默查空」，而是真的无数据？
• 涉及字段单位（成交量/成交额/市值/股息率）时已对照 quantdb-fields 技能？