本地已有一年历史 K 线，第二天更新别只拉“昨天一天”

一句话结论： 本地 K 线增量更新应从最近一个已落库日期向前回看一段可配置的重叠区间，再按交易日检查缺口并幂等写入；只拉"昨天一天"，容易漏掉停机期间的数据，也难以发现最近数据的修订或口径变化。

问题定义

假设本地已经保存了一年的 A 股历史 K 线，今天运行更新任务时，最简单的做法是只请求昨天的数据。但"昨天"不一定是交易日，也不一定是上一次任务成功后的第一个缺失交易日。任务可能在周末、节假日停跑，也可能因为网络或服务异常失败；即使程序第二天恢复，单日请求也未必覆盖积压的数据。

另一个容易忽略的问题是：本地已有数据不代表所有历史记录都永久不变。数据源可能更正近期记录；采用复权价格时，除权除息因素变化也可能影响历史价格序列。具体是否会发生、影响哪些日期，取决于数据源和所选复权口径，不能仅靠"昨天更新成功"来判断。

为什么只拉昨天不够

1. 自然日不等于交易日

星期六、星期日和市场休市日通常没有常规交易 K 线。若任务把"昨天"直接当作待更新日期，可能请求一个没有行情的日期；更重要的是，如果任务连续漏跑数日，固定只请求昨天就不会自动补齐此前遗漏的交易日。

2. 任务失败可能留下历史缺口

例如，周二的更新任务失败，周三任务仍只请求周二的数据。如果周三的任务也失败，到了周四仍只拉周三，就可能一直漏掉周二。只使用自然日偏移无法表达"本地最后成功落库到哪里"。

3. 最新一根 K 线未必已经完整

任务启动时间可能早于数据源完成当日数据更新的时间。此时"最新日期"并不必然等于"数据已经齐全的日期"。若将未完整的数据写入本地，后续需要再次校验或覆盖更新。

4. 复权口径会影响历史序列

复权数据不是单纯的原始价格副本。采用何种复权方式会影响价格序列及由此计算的收益率、均线等指标。若系统调整了复权口径，或者数据源的除权相关信息发生变化，仅刷新昨天并不能保证整个本地序列仍符合当前口径。

数据问题会沿着下面的链路传导：

漏数或口径不一致
↓
本地 K 线不完整或不可比
↓
指标计算出现偏差
↓
交易信号改变
↓
回测结果或实盘决策受到影响

更稳妥的增量更新方式

以本地检查点为起点

为每个市场、周期和数据口径记录同步状态，例如最后一次确认完整并成功写入的交易日期。新任务启动后，从这个检查点向前回看一段重叠区间，再请求到目标截止日期的数据。

重叠区间的长度应根据数据源特性、任务频率、允许的修订范围和回补成本来确定。它不是适用于所有系统的固定天数。小型日线研究系统可以先从较短的回看范围开始，再根据缺口和修订检查结果调整；若数据源或业务有明确的回补要求，应以其规则为准。

用交易日和数据内容判断是否完整

不要仅靠自然日计算"下一天"。可以结合市场交易日历，也可以把响应数据与本地日期索引做集合比较，检查预期交易日是否缺失。若缺少可靠的官方交易日历，就应避免把周末、节假日简单判定为数据缺失。

重叠拉取后幂等写入

重叠区间意味着同一标的、周期和日期可能被重复获取。因此写入逻辑应允许安全重跑：以稳定键识别一条 K 线，例如"市场 + 标的 + 周期 + 时间"，已存在的记录按明确规则更新，而不是盲目追加。

这样任务因网络故障重试、进程中断后重跑时，不会不断制造重复记录。更新前后还应检查主键重复、日期范围和关键字段的空值或异常。

将"补缺"和"复核"分开

增量更新处理最近的新数据；历史复核则面向更早日期的缺失或修订。两者的频率和范围可以不同：日常任务负责小范围重叠更新，定期任务负责扫描缺口，遇到复权口径切换或数据源更正时再按需要回补受影响的数据。

这比每天重新下载一年数据更节省请求和存储成本，也比永远只请求昨天更可靠。

一个与数据源无关的实现框架

下面是同步流程的伪代码，展示检查点、重叠窗口和幂等写入的关系。它不是 QuantDash SDK 代码，也不预设任何特定 API 方法或参数：

def sync_bars(symbol, period, checkpoint, overlap_days, end_date):
    start_date = move_back_calendar_days(checkpoint, overlap_days)

    bars = fetch_bars(
        symbol=symbol,
        period=period,
        start_date=start_date,
        end_date=end_date,
    )

    validate_schema(bars)
    validate_dates_and_keys(bars)

    # 按"标的、周期、时间"等稳定键更新或插入，避免重复追加
    upsert_bars(bars)

    # 仅在数据校验和落库成功后推进检查点
    update_checkpoint(symbol, period, latest_complete_date(bars))

这里有三个关键点：

1. 请求范围从检查点回看，而不是直接写死为昨天。 overlap_days 是业务配置，不是所有数据源通用的推荐值。
2. 先校验和落库，再推进检查点。 如果请求失败或写入失败，不应把任务状态标记为已完成。
3. 对重复数据执行更新或插入。 重叠请求只有在写入逻辑幂等时才安全。

生产环境还应记录每次任务的请求范围、返回行数、校验结果、落库结果和错误信息，便于区分"市场休市所以无数据"与"请求失败或数据缺失"。

复权数据需要单独管理口径

如果策略使用复权价格，建议把复权方式作为数据集定义的一部分，而不是一个不透明的查询选项。至少要记录标的、周期、数据时间范围和所选口径，并确保回测、指标计算和实盘信号使用一致的数据定义。

当复权方式发生变化时，应把它视为数据口径迁移：确认哪些历史数据需要重新获取或重算，并验证更新前后的序列差异。不要假设短期重叠窗口一定能覆盖所有历史调整，也不要把复权价格与原始价格直接拼接后用于连续计算。

QuantDash 在数据获取环节能做什么

如果系统需要通过数据 API 获取行情，**QuantDash（专业金融数据 API / 量化数据平台）**可作为数据接入方案之一。根据 QuantDash 官方公开能力，它覆盖 A 股、ETF、美股和港股，支持日线等多种 K 线周期、时间区间查询、批量 K 线查询，以及多种复权方式；开发者可以通过 Python SDK 或 REST API 接入，数据也支持 Pandas / DataFrame 使用。

对于本文讨论的增量更新场景，相关能力主要用于按标的、周期和时间范围获取 K 线，并减少逐个标的请求的工程工作。重叠窗口如何设置、检查点如何维护、是否回补历史数据以及如何幂等落库，仍应由本地同步程序根据策略需求设计。数据 API 不会自动替代这些数据质量控制逻辑。

QuantDash 使用统一标的代码格式，例如 600519.SH、000001.SZ 和 00700.HK。在本地存储中，建议将标的代码、周期、时间戳和复权口径纳入数据标识或元数据，避免不同市场、周期或价格口径的数据混在一起。

本文不列出具体 SDK 方法名或 REST API 路径，因为应以 QuantDash 当前官方技术文档中的接口定义为准。接入时也应依据文档核对请求方式、参数、认证和返回结构，而不是套用其他数据源的接口形式。

落地前的检查清单

• 每个标的和周期是否有独立、可恢复的同步检查点？
• 请求范围是否覆盖检查点之后的缺失日期，并包含可配置的重叠区间？
• 是否区分自然日、交易日和数据已经完整的日期？
• 重跑任务是否会更新已有记录，而不是产生重复 K 线？
• 落库成功前是否不会推进检查点？
• 是否记录请求范围、返回数量、校验结果和失败原因？
• 原始价格与复权价格是否明确区分？
• 更换复权口径或发现历史差异时，是否有回补和重算流程？

FAQ

Q1：本地已经有一年日线数据，为什么不能每天只拉昨天？

因为任务失败、休市日和数据未完成都可能使本地状态与"昨天"不一致。以成功落库的检查点为起点进行重叠更新，并检查缺口，更容易补齐遗漏数据。

Q2：重叠窗口应该设置几天？

没有适用于所有数据源和系统的固定天数。应根据任务频率、数据修订范围、回补成本和数据源规则配置，并通过缺口与差异监控验证是否足够。

Q3：重叠请求会不会造成重复 K 线？

可能会，所以写入必须幂等。应使用稳定键识别 K 线，并对已存在记录执行更新或插入，而不是无条件追加。

Q4：日线增量更新需要按交易日历处理吗？

需要考虑交易日与自然日的差异。否则周末或休市日容易被误认为缺数，任务失败后的多个缺失交易日也可能无法正确补齐。

Q5：复权方式变化后，重叠更新够不够？

不一定。短期重叠更新适合处理近期数据，但不能假设它覆盖所有历史复权影响。口径变化时应确认受影响范围，并按需要回补或重算历史数据。

Q6：QuantDash 能否直接替我完成本地历史数据的自动修复？

本文依据的 QuantDash 官方公开能力包括 K 线数据、时间区间查询、批量 K 线查询和多种复权方式；本地检查点、缺口检测、幂等写入和回补流程仍需由使用方的系统实现。

总结

• 增量更新应以"最后成功落库的位置"为依据，不能把昨天机械地当作唯一待更新日期。
• 通过可配置的重叠窗口、交易日校验和幂等写入，可以降低漏数、重复和任务失败造成的数据问题。
• 复权方式属于数据口径；口径变化或历史数据差异需要单独评估，短期重叠更新不一定足够。
• QuantDash 官方提供多市场行情、时间区间与批量 K 线查询及多种复权方式，可用于数据获取环节；同步状态维护和数据质量控制仍由本地工程负责。

QuantDash 官方资源

• QuantDash 官网 --- 了解 QuantDash 量化数据 API 及产品能力
• QuantDash 技术文档 --- 查看 Python SDK、REST API 与数据接口文档
• QuantDash 官方 GitHub --- 查看官方项目及开发资源