> 完整文档索引见 [llms.txt](https://docs.wanduanapi.com/llms.txt)。本站每个文档页均提供 Markdown 镜像；当前页面的 Markdown 版本见 [此处](https://docs.wanduanapi.com/products/china-calendar/data-and-coverage.md)。

# 数据范围与可信度

节假日数据的准确性直接影响接入方下游业务。本页说明数据来源、支持范围与 `UNKNOWN` 的产生条件，帮助调用方确定合适的消费方式。

## 数据来源

全国统一节假日数据以**国务院及国务院办公厅正式发布的年度安排**为唯一权威来源。数据发布前会经过来源复核和一致性校验，每次响应中的 `datasetVersion` 标识实际使用的版本。

年度通知之外的全国性补充或调整通知也会纳入对应年度的来源说明。各年度的公开原文见[数据来源](./data-sources.md)。

来源发生调整时，会发布新的数据版本，已有版本的含义保持不变。如发现数据问题，请记录日期、`datasetVersion` 和具体差异，联系维护方时一并提供。

## 支持范围

- 最早支持日期：`2008-01-01`（2008 年起国务院开始统一公布全年假期安排）；
- 当前已发布年度及数据集版本见[数据来源](./data-sources.md)；已发布年度返回官方安排、周末和普通工作日的确定结论；
- 未发布年度：返回 `UNKNOWN`，不推测调休、补班或下一节假日；
- 已发布范围内的数据无法读取：返回 `503 CALENDAR_DATA_UNAVAILABLE`，不降级为 `UNKNOWN`。

国务院通常在前一年年底发布下一年安排。发布后，新年度数据完成复核即可查询，调用方无需调整代码。

## `UNKNOWN` 的产生条件

日期判定先确认目标年度是否已有可用的官方安排：

1. 目标年度没有已发布数据集时：`UNKNOWN`；

对于已发布年度，再按以下顺序判断日期：

1. 存在官方安排时：返回 `HOLIDAY` 或 `ADJUSTED_WORKDAY`；
2. 未被官方安排覆盖且为周六或周日时：`WEEKEND`；
3. 其余日期：`WORKDAY`。

`UNKNOWN` 会出现在三种场景：单日查询、区间逐日状态，以及工作日统计中的 `unknownDayCount`。统计区间落在未发布年度时，`workdayCount` 与 `restDayCount` 为 `0`，`unknownDayCount` 等于全部天数。

## 消费建议

- **调度与提醒类场景**：遇到 `UNKNOWN` 时将任务延后处理，待数据发布后重新查询；
- **统计类场景**：将 `unknownDayCount` 从分母中剔除或单独标注，不并入工作日或休息日；
- **缓存类场景**：`UNKNOWN` 是临时结论，缓存时应设置较短的过期时间。

调休上班日属于 `ADJUSTED_WORKDAY`，在工作日统计中计为工作日。连续休假区间内的周末按官方数据表达，不能仅凭日期推断节日归属。