197 lines
6.0 KiB
Markdown
197 lines
6.0 KiB
Markdown
# holiday-cn
|
||
|
||
[](https://github.com/NateScarlet/holiday-cn/actions)
|
||
[](https://github.com/NateScarlet/holiday-cn/releases/latest)
|
||
[](http://calver.org)
|
||
[](https://www.jsdelivr.com/package/gh/NateScarlet/holiday-cn)
|
||
|
||
|
||
中国大陆及香港节假日数据
|
||
|
||
- 中国大陆：自动每日抓取国务院公告
|
||
- 香港：来源于香港特别行政区政府 [1823.gov.hk](https://www.1823.gov.hk/common/ical/tc.json)，数据覆盖 2024 年起
|
||
|
||
- [x] 提供 JSON 格式节假日数据
|
||
- [x] CI 自动更新
|
||
- [x] 数据变化时自动发布新版本 ( `Watch` - `Release only` 以获取邮件提醒! )
|
||
- [x] [发布页面]提供 JSON 打包下载
|
||
|
||
数据格式（中国大陆、香港通用）:
|
||
|
||
[JSON Schema](./schema.json)
|
||
|
||
```TypeScript
|
||
interface Holidays {
|
||
/** 完整年份, 整数。*/
|
||
year: number;
|
||
/** 所用数据来源网址列表 */
|
||
papers: string[];
|
||
days: {
|
||
/** 节日名称 */
|
||
name: string;
|
||
/** 日期, ISO 8601 格式 */
|
||
date: string;
|
||
/** 是否为休息日 */
|
||
isOffDay: boolean;
|
||
}[]
|
||
}
|
||
```
|
||
|
||
## 注意事项
|
||
|
||
**中国大陆**
|
||
|
||
- 年份是按照国务院文件标题年份而不是日期年份，12 月份的日期可能会被下一年的文件影响，因此应检查两个文件。
|
||
|
||
- `与周末连休` 的周末不是法定节假日，数据里不会包含，见[《全国年节及纪念日放假办法》](https://www.gov.cn/zhengce/content/202411/content_6986380.htm) [#213](https://github.com/NateScarlet/holiday-cn/issues/213#issuecomment-1869546011) [#221](https://github.com/NateScarlet/holiday-cn/issues/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](https://github.com/hunshcn/gh-proxy) 或其他 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 工具 - 子模块](https://git-scm.com/book/zh/v2/Git-%E5%B7%A5%E5%85%B7-%E5%AD%90%E6%A8%A1%E5%9D%97)
|
||
|
||
## 数据生成
|
||
|
||
安装依赖：
|
||
|
||
```sh
|
||
pip install -r dev-requirements.txt
|
||
```
|
||
|
||
更新当年及次年数据（所有地区）：
|
||
|
||
```sh
|
||
python scripts/update.py
|
||
```
|
||
|
||
只更新指定地区：
|
||
|
||
```sh
|
||
python scripts/update.py --region cn # 仅中国大陆
|
||
python scripts/update.py --region hk # 仅香港
|
||
```
|
||
|
||
更新所有历史年份（仅中国大陆，香港数据源仅覆盖 2024 年起）：
|
||
|
||
```sh
|
||
python scripts/update.py --all --region cn
|
||
```
|
||
|
||
CI 每日自动执行 `python scripts/update.py --release`，数据有变化时自动提交并发布新版本。
|
||
|
||
## 导入到业务系统（teramesh-backend）
|
||
|
||
数据通过 Django management command 导入工作日历：
|
||
|
||
```sh
|
||
# 进入应用容器
|
||
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`，返回格式与现有地区一致：
|
||
|
||
```python
|
||
{
|
||
"year": 2025,
|
||
"papers": ["数据来源URL"],
|
||
"days": [
|
||
{"name": "假期名称", "date": "2025-01-01", "isOffDay": True}
|
||
]
|
||
}
|
||
```
|
||
|
||
注意：若该地区无调休补班制度，`isOffDay` 始终为 `True`。
|
||
|
||
**2. 在 `scripts/update.py` 的 `REGIONS` 中注册**
|
||
|
||
```python
|
||
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` 中注册**
|
||
|
||
```python
|
||
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` 即可导入，其余地区不受影响。
|
||
|
||
[发布页面]: https://github.com/NateScarlet/holiday-cn/releases
|