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

quantdb-fields — QuantDB 字段单位速查手册

用 QuantDB 数据做任何分析/回测/报告前必读。所有单位均为 2026-08 直接读本地 parquet 实测验证（不是照抄文档）。 单位搞错的后果：成交额差 1 万倍、股息率差 100 倍、换手率差 100 倍—— 分析结论全部作废。

一、通用规则（先记这个）

二、1_kline_data 日线（daily_forward / daily_backward / daily_unadjusted）

min1/min5：同单位（volume=股、amount=万元），但数据停滞在 2026-07-24，用前先查最新日期。

三、L2 原始逐笔与十档盘口（1_kline_data/l2_data + tick_data，2026-08 新增）

万得(Wind) L2 数据，backend/scripts/wind_l2_import.py 从逐日 7z 压缩包（20260511.7z）导入。 当前实测只有 1 个交易日 20260511（order 1950 + trade 1721 = 3671 文件，部分标的仅其一）， 用前先查日期覆盖：ls data/quantdb/1_kline_data/l2_data/ | grep -oE '[0-9]{8}' | sort -u。

文件命名：order_{code}_{date}.parquet / trade_{code}_{date}.parquet，code 为下划线格式 000001_SZ（对应后缀 000001.SZ）。time 单位统一为 UTC 毫秒（万得 hhmmssmmm 转 UTC， 北京 09:15:00 = 01:15:00 UTC），覆盖 09:15 集合竞价到 15:00 收盘。

逐笔委托 order_

逐笔成交 trade_

tick_data 十档盘口快照（18 列）

⚠️ 三个必踩的坑

1. 沪/深成交量双口径：逐笔成交 volume 求和，沪 SH = 日线 volume（实测 600714.SH 求和 34825501≈日线 34825500）； 深 SZ ≈ 1.8~2.1× 日线 volume（实测 002830 1.92×、300521 2.11×、000999 1.79×、000001 1.88×）。 → 逐笔求和不能当当日成交量，深市除 ~2 或直接与日线对账。
2. tick_data 单位混源：同一目录内单位不统一——wind_l2_import 导入的（如 20260511）volume=股、amount=万元； 更早 QuantDB tick 同步的（如 20260720）volume=手、amount=元。 实测：20260511 最后快照 volume 93186521≈日线 93186520 股、amount 104743.53≈104743.54 万； 20260720 volume 1567304 手×100=156730400 股、amount 1713460189 元=171346.02 万。 → 用前必须拿最后一条快照对账日线，或按 pvolume（0=旧/手·元，>0=wind/股·万元）区分。
3. 价格=未复权真实成交：有除权除息时与前复权日线差一个复权因子 （实测 002830.SZ 20260511 L2 末笔 24.08 vs 前复权 close 17.06）；算收益需先统一复权口径。

导入命令（手动增量，不吃 quantdb_daily_sync）

python backend/scripts/wind_l2_import.py --archive /path/to/20260511.7z                      # 全市场
python backend/scripts/wind_l2_import.py --archive ... --symbols 000001.SZ,600519.SH         # 指定标的
python backend/scripts/wind_l2_import.py --archive ... --force                               # 覆盖重导

文件名即日期（20260511.7z → 20260511），流式逐股解压导入、可断点续跑（已存在三件套自动跳过）。 容器内 7z 默认 /opt/p7zip-legacy/bin/7z，数据目录自动探测 /data/quantdb 或本地 data/quantdb。

四、1_kline_data/index_daily 指数日线（⚠️ 与个股相反）

反推：指数平均股价 = close×100/(close×volume/amount) = close×100/19808 ≈ 19.8 元/股，符合 A 股平均股价，故 volume 必为手。

五、5_technical_derived 技术衍生

valuation（估值）

technical_indicators（技术指标）

market_sentiment（市场情绪）

六、6_ml_datasets 因子

features_daily（技术+估值合并表，78 列，2026-09 起新增 30 列）

基础 46 个数值列单位与 technical_indicators / valuation 一致；新增 30 列全部以字符串存储，用前先转数值：

l1_factors（一级因子，decimal 为主）

l2_factors（二级因子，flow 金额注意）

读入归一：backend/shared/quantdb_flow_units.py 自动把万元→元（兼容旧分区），下游再 /1e8→亿、×1e-6→百万元。

flow 灌入口径（update_sdl_complete_pipeline.py）：假定源为元时 /1e6→百万元；新版万元源须先 ×1e4。

七、PG 表 stock_daily_latest（API 服务数据源）

八、research API 换算表（/research/features 等接口返回）

API 层 _UNIT_SCALES 把部分字段缩放后输出（L2 金额先归一为元）：

九、3_financial_data 财务数据

十、2_base_sector

十一、其他数据集

十二、已知数据缺口（2026-08 实测）

1. min1/min5 分钟线停更（最新 2026-07-24）
2. l2_factors 分区停更 —— 已恢复（2026-08-19 实测至 20260818）
3. hsgt_north 北向明细停更（2024-08，改季度披露所致）
4. instrument_detail HqDate 滞后（20260720）
5. dt=20260729~20260802 个股日线有同步缺口（非交易日+同步中断） 5b. valuation dt=20260813 只有 101 行（同步缺口，dividend_rate 全 NaN），features_daily 同日 5543 行正常
6. technical_indicators / features_daily 的 future_return_*（旧 return_*）是未来收益标签，勿当历史动量过滤
7. stock_daily_latest 的 turnover_rate/flow_net_amount/main_flow 常为 NULL
8. l2_data 原始逐笔仅 20260511 单日 —— 万得按日 7z 手动导入（wind_l2_import.py），非自动日更
9. tick_data 单位混源 —— wind=股/万元，旧同步=手/元，对账前勿直接用

十三、分析前检查清单

• 确认数据源是 parquet 还是 PG/API（单位体系不同）
• symbol 格式匹配数据源（parquet 后缀 / PG 前缀）
• 成交量：个股=股，指数=手
• 成交额：万元（API 输出已缩放为亿/百万）
• 波动率：technical_indicators 是 %，l1 是小数（差 100 倍）
• 股息率：valuation.dividend_rate 是 % 百分数值（0.148=0.148%），不是小数
• close 口径：technical_indicators 是后复权，valuation 是不复权
• 市值：parquet 是元，instrument_detail 是亿元/万股，API 是亿元
• 财务：financials 是元，instrument_detail J_* 是万元
• 用前查数据最新日期（分钟线、l2、hsgt 都可能已停更）
• L2 原始逐笔（l2_data）：先查日期覆盖（当前仅 20260511 单日），价格是未复权，逐笔求和沪≈日线量/深≈2×，别当成交量
• tick_data：先拿最后一条快照对账日线（wind=股/万元 vs 旧同步=手/元，单位混源）