本页总结 BagelQuant Data 的设计契约。
目标
将 bagelquant-data 构建为面向量化研究的高性能、可扩展、数据源无关的数据框架。
系统必须：
- 使用 Polars 作为主要 DataFrame 引擎
- 使用 Parquet 作为标准分析存储格式
- 使用 SQLite 保存可变元数据和运行状态
- 优先考虑增量更新效率和查询性能
- 支持多个外部数据源
- 将 Tushare 作为第一个数据源适配器
- 保持 point-in-time 正确性
- 提供清晰稳定的 Python API
- 提供完整文档和可执行示例
- 存储源数据，但不预计算供应商专用财务比率
- 提供用户可组合成指标的通用财务变换
- 对非引用研究数据返回单值长面板
非目标
项目不实现：
- 遗留迁移
- 向后兼容
- 旧布局兼容
- reset 命令
- 永久一资产一文件存储
- 永久一 API 调用一文件存储
eps_ttm()或roe_ttm()这类硬编码指标函数
核心原则
数据源专用代码属于 bagelquant_data.sources。
数据集行为属于声明式 spec 和注册表。
标准存储保持行式结构。
研究提取每次返回一个字段。
财务处理必须通用，并保持 point-in-time 安全。
运行元数据属于 SQLite，而不是成千上万个元数据 Parquet 文件。
路线图主题
当前实现已经建立新的公开 API、包结构、存储区域、标准写入、manifest、查询 API、财务原语和 Tushare 数据源适配器。
未来可以深化：
- 优化初始构建
- 微批分区合并
- 资产级 content hash 状态
- 并发分区锁
- manifest 重建操作
- 压缩和修复工作流
- 更丰富的数据集校验器
- 更多数据源适配器