⚙️ 本技能遵循公共运行环境契约（最高优先级，先于本文其余内容执行）： 详见 _shared/env-contract.md，执行前先读它。
quantdb-data-structure — QuantDB 数据结构与读取口径
写任何触碰 QuantDB 本地数据的代码/查询前必读。字段单位与口径陷阱另见
skills/quantdb-fields/SKILL.md（本技能管「数据在哪、怎么组织、怎么读」）。
一、路径映射（先定位数据）
| 位置 | 路径 |
|---|---|
| 生产服务器宿主机 | /opt/quantmind/data/quantdb |
容器内（./data:/data bind mount） | /data/quantdb |
| 本地仓库 | <项目根>/data/quantdb |
| 用户自定义数据集（产出区） | /data/quantcustom（宿主机 /opt/quantmind/data/quantcustom） |
⚠️
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。
二、顶层数据集目录
| 目录 | 内容 | 组织方式 |
|---|---|---|
1_kline_data/ | 日K（daily_forward/backward/unadjusted 三种复权）、index_daily、min1_kline、min5_kline、tick | 日K/指数=分区；分钟线=单文件 |
2_base_sector/ | instrument_detail、sector_concept、trading_calendar、index_weights、margin_trading、hsgt_north | 混合 |
3_financial_data/ | balance/income/cashflow/股本/分红因子等财务报表 | 单文件为主 |
4_bond_etf/ | 债券 / ETF | 单文件 |
5_technical_derived/ | valuation（估值）、technical_indicators、market_sentiment | 分区 |
6_ml_datasets/ | features_daily、l1_factors、l2_factors、l1_l2_factors、alpha_library（Alpha101+GTJA191+Alpha158 三库因子） | 分区 |
辅助文件：releases/（数据包版本）、.sync_state / quantdb_sync.sqlite（增量同步状态）、.qlib_cache、_meta。
用户自定义数据集 quantcustom/6_ml_datasets/
挖掘产物统一落 data/quantcustom/6_ml_datasets/<数据集>/（结构与 quantdb 一致，按 dt=YYYYMMDD/ 分区）：
| 数据集 | 来源 | 附加文件 |
|---|---|---|
l1_factors | ① RD-Agent 因子 export ② 因子工厂（backend/scripts/factor_factory.py） | MANIFEST.csv（factor_name/expression/ic/icir/coverage/kept）、PROPOSALS.json |
- 读取入口：
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。
三、文件组织规律（决定查询写法）
- 分区型：
<数据集>/dt=YYYYMMDD/data.parquet。dt是 Hive 分区列，整数（如20260828），DuckDB 过滤WHERE dt BETWEEN 20260101 AND 20260828可走谓词下推，不要写字符串。 - 单文件型：
<数据集>/{symbol}.parquet（财务报表、分钟K）或整表单文件（instrument_detail.parquet），用pd.read_parquet直读。 - 混合格式：
6_ml_datasets/l1_factors/同时存在平铺l1_factors_YYYYMMDD.parquet与dt=YYYYMMDD/分区——只读dt=*分区目录，避免混入平铺文件。 - 北向资金特殊：
2_base_sector/hsgt_north/日频在daily_freq/*.parquet（无分区），季度快照用quarter=YYYYQNHive 分区（2024-08 起季度披露）。
四、代码格式口径（最高频踩坑点）
| 存储位置 | 格式 | 示例 |
|---|---|---|
QuantDB parquet 的 symbol/wind_code | 后缀式 | 600519.SH、000001.SZ |
PG 表 stock_daily_latest 等内部表 | 前缀式 | SH600519、SZ000001 |
- 查 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）：
| 视图 | 数据 |
|---|---|
qdb_daily_forward / qdb_daily_backward / qdb_daily_unadjusted | 前复权 / 后复权 / 不复权日K |
qdb_index_daily | 指数日K |
qdb_valuation | 估值 |
qdb_technical_indicators | 技术指标 |
qdb_market_sentiment | 市场情绪 |
qdb_features_daily | 每日特征 |
qdb_margin_trading | 融资融券 |
qdb_l2_factors / qdb_l1_l2_factors | L2 / L1+L2 因子 |
qdb_l1_factors | L1 因子（仅当存在 dt=* 分区时挂载） |
qdb_alpha_library | 三库因子 429 列（训练直读） |
qdb_hsgt_north_daily / qdb_hsgt_north | 北向资金日频 / 季度 |
临时探查可直接 DuckDB 查文件：
sqlSELECT * FROM read_parquet('/data/quantdb/1_kline_data/daily_forward/dt=20260828/data.parquet') WHERE symbol = '600519.SH';
六、服务器核查命令速查
bash# 目录与体量 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技能？
