# 课表日历生成器 (Class Schedule ICS Generator)

这是一个用于将学校提供的 **行政历 (Excel)** 和 **课表 (Excel)** 自动转换为通用日历文件 (`.ics`) 的 Python 脚本。
生成的日历文件可以直接导入到你的手机（iOS/Android）、Mac 日历、Outlook 或 Google Calendar 中。

## 功能特点

- **通用解析**：自动适配每学期新的日期，只需保证行政历中“周次”列和“课表”的星期列格式不变即可。
- **智能避开节假日**：行政历中带有“清明”、“劳动”、“端午”等汉字描述的日期，脚本会自动识别为节假日，并在生成当日日历时**自动跳过**，以免引发混乱。
- **完整的课程信息**：每节课自动包含：*课程名称* (标题)、*教室* (地点)、*代课班级/老师* (备注描述)。

---

## 依赖与安装 (首次使用)

本脚本依赖 Python 环境以及处理 Excel 文件的类库（主要是 `pandas` 和 `openpyxl`）。

为了避免污染全局 Python 环境或受到 macOS 系统限制，推荐使用 **虚拟环境 (venv)**。

### 1. 创建并激活虚拟环境
首次使用时，需要在项目根目录执行以下命令：
```bash
# 1. 创建虚拟环境 (名为 venv)
python3 -m venv venv

# 2. 激活虚拟环境 (每次运行脚本前都需要执行这一步)
source venv/bin/activate
```

### 2. 安装必要依赖库
在虚拟环境激活的状态下，安装解析表格所需的依赖：
```bash
pip install pandas openpyxl xlrd
```

---

## 使用说明 (每半年更新课表时)

当你拿到新学期的《课表.xlsx》和《行政历.xls》时，将它们放入该目录下，然后执行如下步骤：

### 1. 激活虚拟环境 (如果已在新终端)
```bash
source venv/bin/activate
```

### 2. 运行生成脚本
```bash
# 默认生成方式：
python generate_ics.py 课表.xlsx 行政历.xls
```

**可选参数**：
- `-o` 或 `--output`：指定输出的文件名（默认输出为 `schedule.ics`）
- `-w` 或 `--weeks`：指定生成多少周的课表（默认生成前 18 周）

**例如**：
```bash
python generate_ics.py 课表.xlsx 行政历.xls -o my_schedule.ics -w 16
```

### 3. 导入日历
运行成功后，目录中会多出一个 `.ics` 文件（如 `schedule.ics`）。
- **Mac/Windows**：直接双击使用自带的日历软件打开并导入即可。
- **手机**：将文件通过微信 / 隔空投送 (AirDrop) 传输到手机，再选择使用“日历”打开导入。

---

## 表格数据要求 (格式规范)

如果你未来发现脚本运行报错，请检查新的 Excel 文件是否满足以下基础格式要求：
1. **行政历**：
   - 第一列必须为周次，包含大写中文数字 `"一"`，脚本依靠该行来定位第一周。
   - 这行里必须至少有一列具有“带年份的完整日期”或被 Excel 识别为日期格式的内容，以供推算开学第一天的时间。
   - 节假日放假只需在原本数字上加上中文名称（诸如“4清明”），脚本遇到汉字即认为是假期并自动调休跳过。
2. **课表**：
   - 首列应包含完整的时间片段，如 `第1-2节 8:30~10:00`（必须包含 `8:30~10:00`）。
   - 列标题需带有 `"星期一"` 至 `"星期五"` 等字样。
   - 单元格内换行规则：第一行为课程名，中间为人群/班级描述，最后一行为地点教室（脚本通过换行符 `\n` 进行拆分）。