From 526d99f1931b372e7dca19781c88dc98d186a11b Mon Sep 17 00:00:00 2001
From: "mingsheng.li" <mingsheng.li@gaiamesh.com>
Date: Mon, 27 Apr 2026 12:53:44 +0800
Subject: [PATCH] docs: add data generation, import, and extension guide to
 README

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 README.md | 96 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 96 insertions(+)

diff --git a/README.md b/README.md
index c02d9d4..aaebec0 100644
--- a/README.md
+++ b/README.md
@@ -97,4 +97,100 @@ interface Holidays {
 
 参见 [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