cal-sync

苹果日历订阅工具，自动计算公司加班日期并生成日历文件。

项目简介

这是一个 Python 工具，用于自动生成公司加班日历。根据公司规则（每月最后一周周六加班），自动计算全年加班日期，并考虑中国法定节假日和调休补班日的影响，遇到节假日自动顺延到下一周周六。

核心功能

• 动态计算加班日期：根据"每月最后一周周六"规则自动计算
• 节假日顺延：遇法定节假日自动顺延到下一周周六
• 调休补班处理：调休补班日也会触发顺延
• 自动更新数据：节假日数据来自 iCloud，每次运行自动更新

技术实现

• Python 3.10+：使用现代 Python 特性
• icalendar 库：生成标准 iCal 格式文件
• iCloud 节假日数据：从 Apple 官方日历获取中国节假日信息
• 缓存机制：本地缓存节假日数据，提高运行速度

快速开始

1. 环境准备

首次使用需要安装依赖：

cd project（4）
source .venv/bin/activate
pip install -e .

2. 生成日历

方式一：双击运行（推荐）

直接双击 生成日历.command 文件，会自动：

• 安装依赖（首次）
• 生成加班日历
• 打开输出文件夹

方式二：命令行运行

# 生成 2026 年加班日历
PYTHONPATH=src python -m cal_sync.cli generate -y 2026

# 查看 2026 年加班规则
PYTHONPATH=src python -m cal_sync.cli show -y 2026

3. 导入到苹果日历

Mac 用户：

• 双击 output/加班日历.ics 文件
• 日历应用会自动打开并提示导入

iPhone/iPad 用户：

• 方式 1：通过 AirDrop 发送 .ics 文件到 iPhone
• 方式 2：将文件上传到 iCloud 云盘，用"文件"app 打开
• 方式 3：邮件发送 .ics 文件，在手机上打开

配置说明

配置文件 config.yaml 示例：

calendar_name: 公司加班日历
output_file: output/加班日历.ics

workday_rules:
  "2026":
    - type: last_saturday_of_month  # 每月最后一周周六
      reason: 月底加班

规则类型

类型	说明	示例
last_saturday_of_month	每月最后一周周六	月底加班
fixed	固定日期	手动指定日期

项目结构

project（4）/
├── src/cal_sync/           # 源代码
│   ├── __init__.py
│   ├── calendar_generator.py  # 日历生成器
│   ├── cli.py              # 命令行接口
│   ├── config.py           # 配置管理
│   └── holidays.py         # 节假日判断
├── output/                 # 输出目录
│   └── 加班日历.ics        # 生成的日历文件
├── config.yaml             # 配置文件
├── 生成日历.command         # 双击运行脚本
├── pyproject.toml          # 项目配置
└── README.md               # 项目说明

节假日数据

程序使用 iCloud 中国节假日日历作为数据源：

• 数据来源：https://calendars.icloud.com/holidays/cn_zh.ics
• 更新方式：每次运行自动下载最新数据
• 缓存位置：~/.cache/cal-sync/holidays.ics
• 数据内容：包含法定节假日和调休补班日

节假日判断逻辑

• WORK-HOLIDAY：法定节假日（春节、国庆等假期）
• ALTERNATE-WORKDAY：调休补班日（周末补班）

2026 年加班日期示例

月份	加班日期	备注
1月	1月31日
2月	3月7日	2月28日调休补班顺延
3月	4月11日	4月4-6日清明假期顺延
4月	5月16日	5月2日调休 + 5月9日调休
5月	5月30日
6月	7月4日
7月	8月1日
8月	9月5日
9月	10月17日	10月3日国庆 + 10月10日调休
10月	10月31日
11月	12月5日
12月	1月2日(2027)

开发说明

依赖管理

使用 pip 管理依赖，主要依赖：

• icalendar>=6.0.0：iCal 文件生成
• pyyaml>=6.0：YAML 配置解析

代码规范

• 使用 ruff 进行代码检查和格式化
• 类型注解：所有公共函数必须有类型注解
• 代码风格：遵循 PEP 8 规范

运行测试

# 安装开发依赖
pip install -e .

# 运行代码检查
ruff check .

# 格式化代码
ruff format .

许可证

MIT License