中国节假日日历同步

仅以官方 gov.cn 网站发布的节假日通知作为中国法定节假日及调休工作日安排的唯一权威来源。

保持工作流保守稳健：

• 优先使用配置项中指定的 notice_urls。
• 在启用任何公共搜索引擎回退机制前，优先通过中国政府政策检索系统进行发现。
• 将官方通知正文解析为结构化的节假日/工作日数据行。
• 采用频率可控的发现策略——探测积极性随请求年份与当前年份的时间距离增大而逐步降低。

工作流

1. 加载已配置的通知 URL。

   • 首先检查本地配置中的 notice_urls 是否包含所请求年份的条目。
   • 若存在已确认的 URL，且未显式要求刷新，则直接使用本地节假日存储，跳过后续第 2–3 步。

2. 判断是否应执行发现流程。

   • 依据参考资料中定义的频率规则，将请求年份与当前年份进行比较。
   • 若请求年份过远（≥ 当前年份 + 2），则立即返回空 URL，不执行探测。
   • 若允许执行发现，则查询 discovery_cache，确认该年份是否已在当前日历月内被探测过；如已存在缓存结果，则直接复用，不再重新抓取。

3. 按需发现通知 URL。

   • 基于标准标题模板构建搜索查询，尝试从精确匹配到宽泛匹配的多种变体（详见参考资料）。
   • 仅接受形如 https://www.gov.cn/zhengce/content/... 的候选 URL；对每个候选 URL，需实际抓取页面并验证其标题是否符合预期。
   • 成功时：将确认后的 URL 写入 notice_urls，并更新 discovery_cache。
   • 失败时：在 discovery_cache 中为当前月份写入负向记录；向调用方返回空 URL。

4. 解析官方通知正文内容。

   • 依据参考资料中定义的文本模式，提取节假日区间与调休工作日信息。
   • 输出标准化的数据行，字段包括：date、is_holiday、is_workday、holiday_name 和 source_url。

5. 分别持久化两层数据。

   • 稳定的源映射关系保存于 notice_urls。
   • 探测历史记录保存于 discovery_cache。

规则

• 不得将第三方节假日日历视为权威数据源。
• 在官方通知正式发布前，不得自行编造未来年份的节假日或调休安排。
• 若某一年份尚未发布官方通知，则返回空 URL，并在 discovery_cache 中为当前月份记录一次负向检查结果。
• 若某一年份已存在于本地节假日存储中，则除非调用方显式请求刷新，否则不得重新抓取官方通知。
• 探测延迟阈值与缓存 TTL 均为可配置参数，而非硬编码常量。默认值见参考资料；调用方可覆盖这些参数。

参考资料

关于源优先级、URL 验证逻辑、搜索查询变体、解析正则表达式、频率控制规则以及缓存结构设计，请参阅 references/official-notice-method.md。

输出格式

将通知解析结果标准化为接近如下结构：

{
  "date": "2026-10-08",
  "is_holiday": false,
  "is_workday": true,
  "holiday_name": "国庆节调休上班",
  "source_url": "https://www.gov.cn/zhengce/content/202511/content_7047090.htm"
}