From fb98a84ea5455429e86e9043c003b5d827db7498 Mon Sep 17 00:00:00 2001
From: Nvex <alonair@NvexMacBook-Pro.local>
Date: Thu, 23 Oct 2025 09:16:56 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E7=A7=BB=E9=99=A4=E5=91=BD=E4=BB=A4?=
 =?UTF-8?q?=E8=A1=8C=E6=A8=A1=E5=BC=8F=EF=BC=8C=E4=B8=93=E6=B3=A8=E4=BA=8E?=
 =?UTF-8?q?Web=E7=95=8C=E9=9D=A2?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 移除README.md中所有命令行模式相关内容
- 更新项目架构描述，专注于Web API服务
- 简化快速开始指南，只保留Web界面步骤
- 优化项目结构说明
- 提升文档的专注性和用户体验
---
 README.md             | 261 +++++++++++++++++++++++++++++----------
 toolbox-app/README.md | 278 +++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 471 insertions(+), 68 deletions(-)

diff --git a/README.md b/README.md
index a042d45..7ff0f24 100644
--- a/README.md
+++ b/README.md
@@ -2,29 +2,107 @@
 
 ## 🚀 功能概述
 
-本工具旨在帮助管理员通过 API 自动批量退选学生的课程。
+本工具提供用户友好的 Web 界面来帮助管理员批量退选学生的课程，支持文件上传、数据预览和可视化操作，让批量退课更加直观便捷。
 
-系统会从项目根目录下的 `退课列表.xlsx` 文件中读取学生 ID 和待退选的课程班 ID 列表，然后执行以下操作：
+## 🏗️ 项目架构
 
-1.  **获取学生课程**：通过 `GET` 请求获取每个学生当前已选的课程班列表。
-2.  **匹配与退课**：在学生的已选课程中匹配需要退选的课程班 ID，并通过 `DELETE` 请求发起退课操作。
-3.  **结果反馈**：在终端清晰地输出每一位学生的处理结果，并在操作结束后提供总结报告。
+```
+deleclass_副本2/
+├── src/                    # 后端 API 服务
+│   └── main.py            # Flask API 服务器
+├── toolbox-app/           # 前端 Web 应用
+│   ├── src/               # Vue.js 源代码
+│   ├── public/            # 静态资源
+│   └── package.json       # 前端依赖配置
+├── requirements.txt       # Python 依赖
+├── generate_template.py   # Excel 模板生成工具
+├── .env.example          # 环境变量模板
+└── README.md             # 项目文档
+```
+
+## 🛠️ 技术栈
+
+### 后端
+- **Python 3.x** - 主要编程语言
+- **Flask** - Web 框架，提供 API 服务
+- **openpyxl** - Excel 文件处理
+- **requests** - HTTP 请求库
+- **python-dotenv** - 环境变量管理
+
+### 前端
+- **Vue.js 3** - 现代化前端框架
+- **Vite** - 快速构建工具
+- **Element Plus** - UI 组件库
+- **Axios** - HTTP 客户端
+
+## 🎯 核心功能
+
+系统会处理 Excel 文件中的学生 ID 和课程班 ID 列表，执行以下操作：
+
+1.  **获取学生课程**：通过 `GET` 请求获取每个学生当前已选的课程班列表
+2.  **匹配与退课**：在学生的已选课程中匹配需要退选的课程班 ID，并通过 `DELETE` 请求发起退课操作
+3.  **结果反馈**：提供详细的处理结果和统计报告
 
 > **🛡️ 安全第一**：为了防止误操作，本工具采用 **先预览，后确认** 的安全执行模式。
 
 ---
 
-## 🛠️ 快速上手指南
+## 🚀 快速开始
 
-### 第 1 步：环境配置 (`.env` 文件)
+### 1. 启动后端服务
 
-在首次使用前，请在项目根目录下创建一个名为 `.env` 的文件，并将以下内容复制进去。
+```bash
+# 安装 Python 依赖
+pip3 install -r requirements.txt
+
+# 配置环境变量（创建 .env 文件）
+cp .env.example .env
+# 编辑 .env 文件，填入您的 API 配置
+
+# 启动 Flask 后端服务
+python3 src/main.py
+```
+
+### 2. 启动前端应用
+
+```bash
+# 进入前端目录
+cd toolbox-app
+
+# 安装 Node.js 依赖
+npm install
+
+# 启动开发服务器
+npm run dev
+```
+
+### 3. 使用 Web 界面
+
+1. 打开浏览器访问 `http://localhost:5173`
+2. 上传包含学生 ID 和课程班 ID 的 Excel 文件
+3. 预览退课数据，确认无误后执行批量退课
+4. 查看详细的操作结果和统计信息
+
+## 📋 数据格式要求
+
+Excel 文件应包含以下列：
+
+| 学生ID | 课程班ID |
+| --- | --- |
+| 3831629 | 1820221, 1820210 |
+| 3831630 | 1820456 |
+
+-   **学生ID**: 学生的唯一标识符
+-   **课程班ID**: 需要退选的一个或多个课程班 ID，多个 ID 之间用英文逗号 `,` 分隔
+
+## ⚙️ 环境配置
+
+创建 `.env` 文件并配置以下参数：
 
 ```dotenv
 # --- API 配置 ---
 BASE_URL=https://api.seiue.com
 
-
 # --- 身份认证 ---
 # ⚠️ 请将 <你的Token> 替换为有效的 Bearer Token
 AUTHORIZATION="Bearer <你的Token>"
@@ -34,78 +112,131 @@ X_REFLECTION_ID="969269"
 SEMESTER_ID=61626
 ```
 
-> **⚠️ 注意：**
-> -   **必须** 将 `AUTHORIZATION` 配置项中的 `<你的Token>` 替换为您自己的有效令牌。
-> -   `.env` 文件包含了敏感信息，请 **绝对不要** 将其提交到任何公共代码仓库。
+> **⚠️ 重要提醒：**
+> - 必须将 `AUTHORIZATION` 中的 `<你的Token>` 替换为您的有效令牌
+> - `.env` 文件包含敏感信息，请勿提交到公共代码仓库
 
-### 第 2 步：准备数据 (`退课列表.xlsx`)
+---
 
-请确保项目根目录下存在 `退课列表.xlsx` 文件，并遵循以下格式：
+## 🔧 开发指南
 
-| 学生ID | 课程班ID |
-| --- | --- |
-| 3831629 | 1820221, 1820210 |
-| 3831630 | 1820456 |
+### 本地开发环境搭建
 
--   **学生ID**: 学生的唯一标识符。
--   **课程班ID**: 需要退选的一个或多个课程班 ID，多个 ID 之间请用 **英文逗号** `,` 分隔。
+1. **克隆项目**
+   ```bash
+   git clone https://git.vcck.cn/nvex/toolbox.git
+   cd toolbox
+   ```
 
-### 第 3 步：安装依赖
+2. **后端开发**
+   ```bash
+   # 安装 Python 依赖
+   pip3 install -r requirements.txt
+   
+   # 配置环境变量
+   cp .env.example .env
+   # 编辑 .env 文件
+   
+   # 启动后端服务（开发模式）
+   python3 src/main.py
+   ```
 
-在项目根目录下打开终端，运行以下命令：
+3. **前端开发**
+   ```bash
+   cd toolbox-app
+   
+   # 安装依赖
+   npm install
+   
+   # 启动开发服务器
+   npm run dev
+   
+   # 构建生产版本
+   npm run build
+   ```
 
-> 👉 **执行安装命令**
-> ```bash
-> pip3 install -r requirements.txt
-> ```
-
-这将安装运行本工具所需的所有库 (`requests`, `openpyxl`, `python-dotenv`)。
-
-### 第 4 步：执行脚本
-
-一切准备就绪后，在项目根目录下运行主程序：
-
-> 👉 **执行主程序**
-> ```bash
-> python3 src/main.py
-> ```
-
-#### 4.1) 预览变更
-
-脚本启动后，将 **自动进入预览模式**。它会分析数据并显示即将发生的操作，但 **不会执行任何实际的退课**。
+### 项目结构说明
 
 ```
---- 预览模式: 以下操作将不会实际执行 ---
----
-➡️ [预览] 学生 3831629 将退课: 体育自主选修, 音乐
-ℹ️ 学生 3831630 无匹配课程班可退。
----
+├── src/main.py              # Flask API 服务器
+├── toolbox-app/
+│   ├── src/
+│   │   ├── components/      # Vue 组件
+│   │   ├── views/          # 页面视图
+│   │   ├── router/         # 路由配置
+│   │   └── store/          # 状态管理
+│   ├── public/             # 静态资源
+│   └── vite.config.js      # Vite 配置
+├── requirements.txt         # Python 依赖
+├── generate_template.py     # Excel 模板生成工具
+└── .env.example            # 环境变量模板
 ```
 
-#### 4.2) 确认执行
+## 📦 部署指南
 
-预览信息显示完毕后，程序会暂停并等待您的最终确认。
+### 生产环境部署
 
-> 👉 **输入 `drop` 确认执行**
-> ```
-> 请检查以上预览信息。
-> 👉 如果确认要执行退课操作，请输入 'drop' 并按 Enter。输入其他任何内容将取消操作: drop
-> ```
+1. **后端部署**
+   ```bash
+   # 使用 gunicorn 部署 Flask 应用
+   pip install gunicorn
+   gunicorn -w 4 -b 0.0.0.0:5000 src.main:app
+   ```
 
--   **确认执行**：精确输入 `drop` 并按回车键，脚本将开始执行实际的退课操作。
--   **取消操作**：输入任何其他内容（或直接按回车），程序将立即安全退出。
+2. **前端部署**
+   ```bash
+   cd toolbox-app
+   npm run build
+   # 将 dist/ 目录部署到 Web 服务器
+   ```
 
-#### 4.3) 查看结果
+3. **使用 Docker（可选）**
+   ```dockerfile
+   # 示例 Dockerfile
+   FROM python:3.9-slim
+   WORKDIR /app
+   COPY requirements.txt .
+   RUN pip install -r requirements.txt
+   COPY . .
+   EXPOSE 5000
+   CMD ["python", "src/main.py"]
+   ```
 
-确认执行后，脚本会处理每个学生，并实时打印结果。全部操作完成后，会显示最终的统计报告。
+## 🤝 贡献指南
+
+1. Fork 本项目
+2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
+3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
+4. 推送到分支 (`git push origin feature/AmazingFeature`)
+5. 开启 Pull Request
+
+## 📄 许可证
+
+本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。
+
+## 🆘 常见问题
+
+### Q: 如何生成 Excel 模板？
+A: 运行 `python3 generate_template.py` 生成标准格式的 Excel 模板文件。
+
+### Q: API 认证失败怎么办？
+A: 请检查 `.env` 文件中的 `AUTHORIZATION` 配置，确保 Token 有效且格式正确。
+
+### Q: 前端无法连接后端？
+A: 确保后端服务已启动（默认端口 5000），检查前端配置中的 API 基础 URL。
+
+### Q: Excel 文件格式错误？
+A: 确保 Excel 文件包含 "学生ID" 和 "课程班ID" 列，且数据格式符合要求。
 
-```
---- 开始执行批量退课 ---
 ---
-✅ 学生 3831629 已退课: 体育自主选修, 音乐
-ℹ️ 学生 3831630 无匹配课程班，跳过。
 
---- 批量退课结果 ---
-✅ 成功: 1
-❌ 失败: 0
-```
\ No newline at end of file
+## 📞 技术支持
+
+如有问题或建议，请通过以下方式联系：
+
+- 📧 提交 Issue: [项目 Issues](https://git.vcck.cn/nvex/toolbox/issues)
+- 💬 项目讨论: [项目讨论区](https://git.vcck.cn/nvex/toolbox/discussions)
+
+---
+
+*最后更新: 2024年12月*
\ No newline at end of file
diff --git a/toolbox-app/README.md b/toolbox-app/README.md
index 1511959..52f3445 100644
--- a/toolbox-app/README.md
+++ b/toolbox-app/README.md
@@ -1,5 +1,277 @@
-# Vue 3 + Vite
+# 批量退课工具 - Web 前端应用
 
-This template should help get you started developing with Vue 3 in Vite. The template uses Vue 3 `<script setup>` SFCs, check out the [script setup docs](https://v3.vuejs.org/api/sfc-script-setup.html#sfc-script-setup) to learn more.
+## 🌐 项目概述
 
-Learn more about IDE Support for Vue in the [Vue Docs Scaling up Guide](https://vuejs.org/guide/scaling-up/tooling.html#ide-support).
+这是批量退课工具的 Web 前端应用，基于 Vue.js 3 + Vite 构建，提供用户友好的图形界面来执行批量退课操作。
+
+## ✨ 主要功能
+
+- 📁 **文件上传**: 支持拖拽上传 Excel 文件
+- 👀 **数据预览**: 上传后即时预览退课数据
+- 🔍 **数据验证**: 自动检查数据格式和完整性
+- ⚡ **批量操作**: 一键执行批量退课
+- 📊 **结果展示**: 详细的操作结果和统计信息
+- 🎨 **响应式设计**: 适配各种屏幕尺寸
+
+## 🛠️ 技术栈
+
+- **Vue.js 3** - 渐进式 JavaScript 框架
+- **Vite** - 下一代前端构建工具
+- **Element Plus** - Vue 3 UI 组件库
+- **Axios** - HTTP 客户端
+- **Vue Router** - 官方路由管理器
+- **Pinia** - Vue 状态管理库
+
+## 🚀 快速开始
+
+### 环境要求
+
+- Node.js >= 16.0.0
+- npm >= 8.0.0
+
+### 安装依赖
+
+```bash
+npm install
+```
+
+### 开发模式
+
+```bash
+npm run dev
+```
+
+应用将在 `http://localhost:5173` 启动
+
+### 生产构建
+
+```bash
+npm run build
+```
+
+构建文件将输出到 `dist/` 目录
+
+### 预览生产构建
+
+```bash
+npm run preview
+```
+
+## 📁 项目结构
+
+```
+toolbox-app/
+├── public/                 # 静态资源
+│   ├── vite.svg           # 应用图标
+│   └── *.xlsx             # 示例 Excel 文件
+├── src/
+│   ├── components/        # Vue 组件
+│   │   ├── CourseWithdrawal.vue    # 主要的退课组件
+│   │   └── ...
+│   ├── views/             # 页面视图
+│   ├── router/            # 路由配置
+│   │   └── index.js
+│   ├── store/             # 状态管理
+│   │   └── index.js
+│   ├── assets/            # 资源文件
+│   ├── style.css          # 全局样式
+│   ├── App.vue            # 根组件
+│   └── main.js            # 应用入口
+├── index.html             # HTML 模板
+├── vite.config.js         # Vite 配置
+├── package.json           # 项目配置
+└── README.md              # 项目文档
+```
+
+## 🔧 配置说明
+
+### API 配置
+
+前端应用通过 Axios 与后端 Flask API 通信。API 基础 URL 配置在组件中：
+
+```javascript
+// 默认后端地址
+const API_BASE_URL = 'http://localhost:5000'
+```
+
+如需修改后端地址，请在相关组件中更新此配置。
+
+### 构建配置
+
+Vite 配置文件 `vite.config.js`：
+
+```javascript
+import { defineConfig } from 'vite'
+import vue from '@vitejs/plugin-vue'
+
+export default defineConfig({
+  plugins: [vue()],
+  server: {
+    port: 5173,
+    host: true
+  }
+})
+```
+
+## 📋 使用指南
+
+### 1. 准备 Excel 文件
+
+确保 Excel 文件包含以下列：
+
+| 学生ID | 课程班ID |
+|--------|----------|
+| 3831629 | 1820221, 1820210 |
+| 3831630 | 1820456 |
+
+### 2. 上传文件
+
+- 点击上传区域选择文件，或直接拖拽文件到上传区域
+- 支持 `.xlsx` 和 `.xls` 格式
+- 文件大小限制：10MB
+
+### 3. 预览数据
+
+- 上传成功后，系统会自动解析并显示数据预览
+- 检查学生 ID 和课程班 ID 是否正确
+- 确认数据无误后点击"执行退课"
+
+### 4. 执行退课
+
+- 点击"执行退课"按钮开始批量操作
+- 系统会显示实时进度和结果
+- 操作完成后查看详细的统计报告
+
+### 5. 查看结果
+
+- 成功退课的记录会显示为绿色
+- 失败的记录会显示为红色，并包含错误信息
+- 跳过的记录会显示为灰色
+
+## 🎨 界面特性
+
+### 响应式设计
+- 支持桌面端、平板和移动端
+- 自适应布局，优化各种屏幕尺寸的使用体验
+
+### 用户体验
+- 直观的文件上传界面
+- 实时的操作反馈
+- 清晰的结果展示
+- 友好的错误提示
+
+### 视觉设计
+- 现代化的 UI 设计
+- 一致的色彩方案
+- 清晰的信息层次
+- 流畅的交互动画
+
+## 🔍 开发指南
+
+### 组件开发
+
+主要组件 `CourseWithdrawal.vue` 包含：
+
+- 文件上传功能
+- 数据预览表格
+- 批量退课执行
+- 结果展示
+
+### 状态管理
+
+使用 Pinia 管理应用状态：
+
+```javascript
+// store/index.js
+import { defineStore } from 'pinia'
+
+export const useAppStore = defineStore('app', {
+  state: () => ({
+    // 应用状态
+  }),
+  actions: {
+    // 状态操作
+  }
+})
+```
+
+### API 集成
+
+使用 Axios 进行 HTTP 请求：
+
+```javascript
+import axios from 'axios'
+
+const api = axios.create({
+  baseURL: 'http://localhost:5000',
+  timeout: 30000
+})
+```
+
+## 🚀 部署
+
+### 静态部署
+
+构建后将 `dist/` 目录部署到任何静态文件服务器：
+
+```bash
+npm run build
+# 将 dist/ 目录上传到服务器
+```
+
+### Nginx 配置示例
+
+```nginx
+server {
+    listen 80;
+    server_name your-domain.com;
+    root /path/to/dist;
+    index index.html;
+
+    location / {
+        try_files $uri $uri/ /index.html;
+    }
+}
+```
+
+### Docker 部署
+
+```dockerfile
+FROM nginx:alpine
+COPY dist/ /usr/share/nginx/html/
+EXPOSE 80
+CMD ["nginx", "-g", "daemon off;"]
+```
+
+## 🐛 故障排除
+
+### 常见问题
+
+**Q: 无法连接到后端服务？**
+A: 检查后端服务是否启动，确认 API 地址配置正确。
+
+**Q: 文件上传失败？**
+A: 检查文件格式是否为 Excel，文件大小是否超过限制。
+
+**Q: 数据预览为空？**
+A: 确认 Excel 文件包含"学生ID"和"课程班ID"列。
+
+**Q: 退课操作失败？**
+A: 检查后端 API 配置和网络连接，查看浏览器控制台错误信息。
+
+### 调试模式
+
+开启 Vue DevTools 进行调试：
+
+```bash
+# 开发模式自动启用 DevTools
+npm run dev
+```
+
+## 📄 许可证
+
+本项目采用 MIT 许可证。
+
+---
+
+*最后更新: 2024年12月*