Initial commit: 批量退课工具项目

README.md

@@ -0,0 +1,111 @@
+# 学生课程批量退选工具
+
+## 🚀 功能概述
+
+本工具旨在帮助管理员通过 API 自动批量退选学生的课程。
+
+系统会从项目根目录下的 `退课列表.xlsx` 文件中读取学生 ID 和待退选的课程班 ID 列表，然后执行以下操作：
+
+1.  **获取学生课程**：通过 `GET` 请求获取每个学生当前已选的课程班列表。
+2.  **匹配与退课**：在学生的已选课程中匹配需要退选的课程班 ID，并通过 `DELETE` 请求发起退课操作。
+3.  **结果反馈**：在终端清晰地输出每一位学生的处理结果，并在操作结束后提供总结报告。
+
+> **🛡️ 安全第一**：为了防止误操作，本工具采用 **先预览，后确认** 的安全执行模式。
+
+---
+
+## 🛠️ 快速上手指南
+
+### 第 1 步：环境配置 (`.env` 文件)
+
+在首次使用前，请在项目根目录下创建一个名为 `.env` 的文件，并将以下内容复制进去。
+
+```dotenv
+# --- API 配置 ---
+BASE_URL=https://api.seiue.com
+
+
+# --- 身份认证 ---
+# ⚠️ 请将 <你的Token> 替换为有效的 Bearer Token
+AUTHORIZATION="Bearer <你的Token>"
+X_ROLE="shadow"
+X_SCHOOL_ID="665"
+X_REFLECTION_ID="969269"
+SEMESTER_ID=61626
+```
+
+> **⚠️ 注意：**
+> -   **必须** 将 `AUTHORIZATION` 配置项中的 `<你的Token>` 替换为您自己的有效令牌。
+> -   `.env` 文件包含了敏感信息，请 **绝对不要** 将其提交到任何公共代码仓库。
+
+### 第 2 步：准备数据 (`退课列表.xlsx`)
+
+请确保项目根目录下存在 `退课列表.xlsx` 文件，并遵循以下格式：
+
+| 学生ID | 课程班ID |
+| --- | --- |
+| 3831629 | 1820221, 1820210 |
+| 3831630 | 1820456 |
+
+-   **学生ID**: 学生的唯一标识符。
+-   **课程班ID**: 需要退选的一个或多个课程班 ID，多个 ID 之间请用 **英文逗号** `,` 分隔。
+
+### 第 3 步：安装依赖
+
+在项目根目录下打开终端，运行以下命令：
+
+> 👉 **执行安装命令**
+> ```bash
+> pip3 install -r requirements.txt
+> ```
+
+这将安装运行本工具所需的所有库 (`requests`, `openpyxl`, `python-dotenv`)。
+
+### 第 4 步：执行脚本
+
+一切准备就绪后，在项目根目录下运行主程序：
+
+> 👉 **执行主程序**
+> ```bash
+> python3 src/main.py
+> ```
+
+#### 4.1) 预览变更
+
+脚本启动后，将 **自动进入预览模式**。它会分析数据并显示即将发生的操作，但 **不会执行任何实际的退课**。
+
+```
+--- 预览模式: 以下操作将不会实际执行 ---
+---
+➡️ [预览] 学生 3831629 将退课: 体育自主选修, 音乐
+ℹ️ 学生 3831630 无匹配课程班可退。
+---
+```
+
+#### 4.2) 确认执行
+
+预览信息显示完毕后，程序会暂停并等待您的最终确认。
+
+> 👉 **输入 `drop` 确认执行**
+> ```
+> 请检查以上预览信息。
+> 👉 如果确认要执行退课操作，请输入 'drop' 并按 Enter。输入其他任何内容将取消操作: drop
+> ```
+
+-   **确认执行**：精确输入 `drop` 并按回车键，脚本将开始执行实际的退课操作。
+-   **取消操作**：输入任何其他内容（或直接按回车），程序将立即安全退出。
+
+#### 4.3) 查看结果
+
+确认执行后，脚本会处理每个学生，并实时打印结果。全部操作完成后，会显示最终的统计报告。
+
+```
+--- 开始执行批量退课 ---
+---
+✅ 学生 3831629 已退课: 体育自主选修, 音乐
+ℹ️ 学生 3831630 无匹配课程班，跳过。
+
+--- 批量退课结果 ---
+✅ 成功: 1
+❌ 失败: 0
+```