数据管理服务:落盘优先、任务化、增量

class LocalParquetData:
    def __init__(self, path):
        self._df = pd.read_parquet(path)          # 只读落盘文件
        self.fetched_at = self._df["fetched_at"].iloc[0]

数据适配器：LocalParquetData（51 个标的，fetched_at=2026-07-31 14:38:54）

一、三层分离:抓取 / 存储 / 读取

分析脚本只碰第三层。 这条分离让整个系统获得两个性质:

1. 可复现——同一份落盘文件,跑一百次结果一样
2. 可排障——出问题时不用担心"是不是数据源今天不一样了"

p7.5 那个 linter 的 QL009 规则扫出 41 处联网调用,全部在 build_*.py 里——这正是它们该在的地方。

二、落盘格式:为什么是 JSON Lines

交易流水用 JsonlStore,而不是数据库:

实测落盘:

fills=98   rejects=108   equity=622

注意 rejects 是独立的一份流水。 大多数系统只记成交——而 p4.1 已经证明,被拒才是最容易被静默吞掉的信息。

🔧 动手做:查一查你的分析脚本,是不是自己在联网取数(4 分钟)

qsys 的数据适配器 LocalParquetData 只读本地 parquet,分析脚本永远拿不到"联网取数"的能力。

回去看你自己的量化代码:算指标、跑回测的那个脚本,是不是里面直接 ak.stock_zh_a_hist(...) 联网拉数据?

想明白:分析脚本一旦自己联网,就把两件该分开的事搅在了一起——而且不可复现(p5.9 那次事故:同一条请求两次返回不同,ERC 期末倍数在 3.38~3.95 之间漂)。正确架构是取数和分析彻底分离:取数服务负责联网+落盘+血缘,分析层只读本地落盘文件。你的分析代码里不该出现任何网络调用。

三、任务化:每一次数据操作都是一条记录

数据服务对外只暴露"任务",不暴露"函数":

每条任务都要记下:谁触发的、用了什么参数、产出了什么、耗时多久。

没有这四样,三个月后你无法回答"这个 parquet 是怎么来的"——而那正是 p1.5「血缘」要解决的问题。

四、增量任务:最容易写错的一环

五、数据校验:落盘之后立刻做

build_universe.py 里那段检查,是这一层的模板:

51 个标的，199,150 行，2010-01-04~2026-07-29
(其中含 p1.3 的停牌占位行,需剔除)
turn 缺失率 0.00%，pbMRQ 缺失率 0.22%
ST 标记行 4,938 行（0.52%）

四类必查:行数与区间 · 缺失率 · 极值合理性 · 主键唯一性。

而 p1.1 那条教训必须写进代码,而不是写在文档里:

# ⚠️ query_hs300_stocks() 的返回不稳定：同一天连续调用，
# 一次返回 300 只，下一次只返回 6 只，且不报错。
# 所以：①校验数量 ②重试 ③一旦拿到就缓存。

"能取到 ≠ 取对了"——这条在系统里的形态,就是一段带数量校验的重试。

📌 免责:本课为技术教学,数据仅用于教学演示,不构成投资建议。