China Holiday Calendar Sync

Use only official gov.cn holiday notices as the source of truth for China holiday and adjusted-workday schedules.

Keep the workflow conservative:

• Prefer configured notice_urls first.
• Use the China government policy search for discovery before any public-search fallback.
• Parse official notice正文 into structured holiday/workday rows.
• Apply frequency-controlled discovery — probe eagerness scales with how far the requested year is from the present.

Workflow

1. Load configured notice URLs.

   • Check notice_urls in local config for the requested year first.
   • If a confirmed URL exists and a refresh is not explicitly requested, use local holiday storage and skip steps 2–3.

2. Determine whether discovery is appropriate.

   • Compare the requested year to the current year using the frequency rules in the references.
   • If the year is too far in the future (≥ current year + 2), return no URL immediately — do not probe.
   • If discovery is allowed, check discovery_cache to see whether this year was already probed within the current calendar month. If it was, respect that cached result without re-fetching.

3. Discover the notice URL when needed.

   • Build search queries from the canonical title template, trying variants from exact to broad (see references).
   • Accept only https://www.gov.cn/zhengce/content/... candidates; validate each by fetching its page and confirming the title.
   • On success: write the confirmed URL to notice_urls and update discovery_cache.
   • On miss: write a negative entry to discovery_cache for the current month; return no URL to the caller.

4. Parse the official notice content.

   • Extract holiday ranges and adjusted workdays using the patterns in the references.
   • Emit normalized rows with date, is_holiday, is_workday, holiday_name, and source_url.

5. Persist two layers separately.

   • Stable source mapping in notice_urls.
   • Probe history in discovery_cache.

Rules

• Do not use third-party holiday calendars as authoritative data.
• Do not fabricate future-year schedules before an official notice exists.
• If a year has not been published yet, return no URL and record a negative check in discovery_cache for the current month.
• If a year is already present in local holiday storage, do not refetch the official notice unless the caller explicitly requests a refresh.
• Probe delay thresholds and cache TTL are parameters, not hard-coded constants. Defaults are documented in the references; callers may override them.

References

For source priority, URL validation, query variants, parsing regex patterns, frequency rules, and caching schemas, read references/official-notice-method.md.

Output Shape

Normalize notice parsing results into a shape close to:

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