路线图

路线图

AxData 的演进路线从本地版开始，逐步扩展到局域网共享，再到云端发布。每一阶段都应保持上一阶段可独立使用。

阶段 0：文档与契约

目标：把架构、分层、接口目录、调用边界和初始 schema 固化为实现依据。

交付：

• 架构设计文档。
• 数据分层文档。
• API 设计文档。
• 初始 schema 设计。
• 按需接口接入计划。
• 本地到云端的路线图。

完成标准：

• 贡献者可以按文档实现，不依赖口头同步。
• 初始核心表和按需接口的字段、参数、日期和代码格式达成一致。

阶段 1：接口契约与源端直取

目标：优先完善 AxData 接口手册、字段契约和源端直取链路，避免存储设计过早限制接口演进。

范围：

• 建立接口注册表：接口名、中文名、分类、参数、字段、示例、调用性质。
• 固定“接口即口径”的用户契约：交易所列表保留为当前主口径，新增源端接口都用独立接口名表达口径。
• 按项目接口需求接入源端直取：先写接口契约，再补适配器和解析。
• 提供 SDK client.call(interface, **params) 和 HTTP POST /v1/request/{interface}。
• 高频接口可按需补便捷方法，接口名和字段由实际业务口径决定。
• 前端“接口”页按三级目录展示字段、参数、示例请求和示例数据。
• 前端“调试”页可以立即请求源端并展示返回结果。

完成标准：

• 已注册接口在手册里能找到，且每个接口有 AxData 字段说明。
• 首批主链路接口能真实请求源端并返回 AxData 字段。
• 源端直取默认不写入 raw、staging、core 或 factor。
• 普通查询和源端直取在 SDK/API/前端上明确分开。
• 贡献者可以按接口逐个补字段解析，不需要重新讨论目录和命名。

阶段 2：本地存储版

目标：给已稳定的接口增加显式采集入库能力，形成可回放、可查询的数据底座。

范围：

• 建立本地 axdata-home 目录结构。
• 以 Parquet 保存 raw、staging、core。
• 使用 DuckDB 查询 core/factor Parquet。
• 实现 stock_basic_exchange、trade_cal、daily、adj_factor 等首批 core 表，并按需扩展新的接口口径。
• 提供 CLI 或 Python 函数完成初始化、增量采集、修复和重放。
• 增加 schema catalog、manifest 和数据质量报告。

完成标准：

• 可以采集并查询股票列表、交易日历、日行情和复权因子。
• Python SDK 不依赖本地 HTTP 服务即可读取本机数据目录。
• 删除 DuckDB 缓存后可以从 Parquet 重建查询视图。
• 每次采集都有 task/batch/run、manifest、行数、日期范围和质量检查结果。

阶段 3：本地研究版

目标：让研究者在 Notebook、脚本和回测中稳定使用 AxData。

范围：

• 完善 Python SDK 的表查询、字段选择、日期范围和本地 DataFrame 体验。
• 提供本地 HTTP API，作为 Web、curl、跨语言和远程调试通道。
• 增加常用因子样例，例如收益率、波动率、换手、量价动量。
• 增加批量导出能力，支持 JSON、CSV、Arrow、Parquet。
• 建立本地任务日志和失败重试。

完成标准：

• Notebook 中可以用统一 SDK 拉取行情、日历和因子。
• SDK 默认本地直读，传入 api_base 时才通过 HTTP API 读取远程服务；源端直取仍通过 call/request 显式触发。
• 因子结果可以追溯到 core 表版本和计算参数。

阶段 4：局域网共享版

目标：把个人本地数据底座升级为团队内网数据服务。

范围：

• API 服务绑定内网地址。
• 增加 AxData token 鉴权、作用域和访问日志。
• 数据目录可升级到共享盘、NAS 或内网对象存储。
• 采集任务服务化，支持定时更新和手动补数。
• 支持多用户只读查询和管理员写入。
• 建立基础限流，防止大查询拖垮服务。

完成标准：

• 团队成员无需第三方源 token 即可查询授权数据。
• 管理员可以查看采集任务、失败原因和数据质量报告。
• 服务重启不影响 Parquet 数据完整性。
• 内网客户端优先使用同一套 Python SDK，通过 api_base 指向内网 API；非 Python 客户端使用同一套 HTTP API 通道。

阶段 5：云端发布版

目标：将 AxData 作为可发布、可运维、可追溯的数据 API。

范围：

• Parquet 可升级到对象存储。
• 元数据可升级到托管数据库。
• 采集和重算任务可升级到队列与任务工作进程。
• API 前置网关，支持认证、配额、限流、访问记录和日志脱敏。
• 引入服务账号、用户账号和 token 轮换。
• 建立监控指标：延迟、错误率、查询量、任务成功率、数据新鲜度。

完成标准：

• 云端 API 与本地/局域网 API 保持兼容。
• Python SDK 继续作为推荐客户端，通过 api_base 接入云端 API。
• 可以按账号、token、表和接口统计用量。
• 源凭据不出服务端 secret manager。
• 数据修订和回滚有明确操作记录。

阶段 6：生态扩展

目标：在稳定底座上扩展资产、实时、回测和第三方兼容能力。

候选方向：

• 增加指数、基金、可转债、期货、财务报表。
• 增加更多分钟线、实时订阅和快照行情；实时默认只作为临时流，不进入历史表。
• 增加 Qlib 导出器，支持训练集生成。
• 增加可插拔数据接入扩展机制。
• 增加 Tushare/RQData 兼容调用入口。
• 增加 Web Dashboard，展示数据状态、质量、任务和 schema。

进入条件：

• 源端直取、采集入库、普通查询和实时录制的边界已经在实现中固定。
• 初始股票列表、交易日历、日行情和复权因子表稳定运行。
• 数据质量和 lineage 已经可查询。
• API 版本策略已经落地。
• 本地和局域网模式没有架构性差异。
• 接口目录和字段契约已经能支撑 Web 手册、SDK 和调试页。

风险与里程碑控制

• 上游接口不稳定：采集层保留可替换 adapter 和质量校验，用户表契约不跟随上游形态漂移。
• 查询链路误触源端：query 只读入库数据，request/call 才能请求源端，源端直取和实时订阅默认不写历史层。
• 复权口径差异：core 保存未复权价格和复权因子，复权视图可重算。
• 文件过多：按日期分区后定期 compaction，控制小文件数量。
• schema 演进失控：所有字段变更先改 schema 文档，再改实现。
• 过早云化：本地版未稳定前不引入分布式复杂度。