holiday-cn/README.md

holiday-cn

中国大陆及香港节假日数据

• 中国大陆：自动每日抓取国务院公告

• 香港：来源于香港特别行政区政府 1823.gov.hk，数据覆盖 2024 年起

• 提供 JSON 格式节假日数据

• CI 自动更新

• 数据变化时自动发布新版本 ( Watch - Release only 以获取邮件提醒! )

• 发布页面提供 JSON 打包下载

数据格式（中国大陆、香港通用）:

JSON Schema

interface Holidays {
  /** 完整年份, 整数。*/
  year: number;
  /** 所用数据来源网址列表 */
  papers: string[];
  days: {
    /** 节日名称 */
    name: string;
    /** 日期, ISO 8601 格式 */
    date: string;
    /** 是否为休息日 */
    isOffDay: boolean;
  }[]
}

注意事项

中国大陆

• 年份是按照国务院文件标题年份而不是日期年份，12 月份的日期可能会被下一年的文件影响，因此应检查两个文件。

• 与周末连休 的周末不是法定节假日，数据里不会包含，见《全国年节及纪念日放假办法》 #213 #221

香港

• 香港不设调休补班制度，数据中不会出现 isOffDay: false 的条目。
• 假期名称为繁体中文。
• 数据覆盖范围取决于港府发布进度，通常提前公布至次年。

通过互联网使用

提示：任何第三方服务都可能故障或停止服务，如果稳定性要求高请自己搭建静态文件服务。

中国大陆

https://raw.githubusercontent.com/NateScarlet/holiday-cn/master/{年份}.json

或使用 JSDelivr：

https://cdn.jsdelivr.net/gh/NateScarlet/holiday-cn@master/{年份}.json

https://fastly.jsdelivr.net/gh/NateScarlet/holiday-cn@master/{年份}.json

也可尝试使用 ghproxy 或其他 Github 加速：

https://{ghproxy服务}/https://raw.githubusercontent.com/NateScarlet/holiday-cn/master/{年份}.json

访问 github 不方便时可使用国内镜像仓库 2022-08-05: coding 现在要求登录才能下载开源仓库的文件。

https://natescarlet.coding.net/p/github/d/holiday-cn/git/raw/master/{年份}.json

香港

https://raw.githubusercontent.com/NateScarlet/holiday-cn/master/hk/{年份}.json

ICalendar 订阅

中国大陆

{年份}.ics 为对应年份的节假日

holiday-cn.ics 为 3 年前至次年的节假日

香港

hk/{年份}.ics 为对应年份的节假日

holiday-hk.ics 为 3 年前至次年的节假日

感谢 @retanoj 的 ics 格式转换实现

作为 git 子模块使用

参见 Git 工具 - 子模块

数据生成

安装依赖：

pip install -r dev-requirements.txt

更新当年及次年数据（所有地区）：

python scripts/update.py

只更新指定地区：

python scripts/update.py --region cn   # 仅中国大陆
python scripts/update.py --region hk   # 仅香港

更新所有历史年份（仅中国大陆，香港数据源仅覆盖 2024 年起）：

python scripts/update.py --all --region cn

CI 每日自动执行 python scripts/update.py --release，数据有变化时自动提交并发布新版本。

导入到业务系统（teramesh-backend）

数据通过 Django management command 导入工作日历：

# 进入应用容器
kubectl exec -it pod/teramesh-app-0 -- /bin/sh

# 导入所有地区（中国大陆 + 香港）
python manage.py populate_working_calendar

# 只导入指定地区
python manage.py populate_working_calendar --region CN
python manage.py populate_working_calendar --region HK

命令会导入当年及次年的假期数据。数据按 country 级别写入，部署在香港（country=HK）的站点自动使用香港假期，内地站点使用内地假期，无需额外配置。

扩展支持新地区

如需接入其他地区（如美国、日本等），按以下步骤操作：

1. 新增数据抓取模块

在 scripts/ 下新建 fetch_{地区代码}.py，实现 fetch_{地区代码}_holiday(year: int) -> dict，返回格式与现有地区一致：

{
    "year": 2025,
    "papers": ["数据来源URL"],
    "days": [
        {"name": "假期名称", "date": "2025-01-01", "isOffDay": True}
    ]
}

注意：若该地区无调休补班制度，isOffDay 始终为 True。

2. 在 scripts/update.py 的 REGIONS 中注册

REGIONS = {
    "cn": { ... },
    "hk": { ... },
    "us": {                              # 新增
        "fetch": fetch_us_holiday,
        "start_year": 2024,
        "subdir": "us",
        "main_ics_name": "holiday-us.ics",
        "cal_name": "美国联邦假期",
        "cal_desc": "美国联邦公共假期数据。",
    },
}

3. 在 teramesh-backend 的 HOLIDAY_SOURCES 中注册

HOLIDAY_SOURCES = {
    "CN": f"{GITEA_BASE}/{{year}}.json",
    "HK": f"{GITEA_BASE}/hk/{{year}}.json",
    "US": f"{GITEA_BASE}/us/{{year}}.json",  # 新增
}

之后运行 python manage.py populate_working_calendar --region US 即可导入，其余地区不受影响。