From 0085c3a317be28494d3aba80b526e343d68d2403 Mon Sep 17 00:00:00 2001
From: seaHi <me@seahi.me>
Date: Sat, 28 Mar 2026 17:27:27 +0800
Subject: [PATCH] docs: add README.md documentation

---
 README.md | 79 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 79 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..feed276
--- /dev/null
+++ b/README.md
@@ -0,0 +1,79 @@
+# 课表日历生成器 (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` 进行拆分）。