toolbox/toolbox-app/README.md

批量退课工具 - Web 前端应用

🌐 项目概述

这是批量退课工具的 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

安装依赖

npm install

开发模式

npm run dev

应用将在 http://localhost:5173 启动

生产构建

npm run build

构建文件将输出到 dist/ 目录

预览生产构建

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 配置在组件中：

// 默认后端地址
const API_BASE_URL = 'http://localhost:5000'

如需修改后端地址，请在相关组件中更新此配置。

构建配置

Vite 配置文件 vite.config.js：

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 管理应用状态：

// store/index.js
import { defineStore } from 'pinia'

export const useAppStore = defineStore('app', {
  state: () => ({
    // 应用状态
  }),
  actions: {
    // 状态操作
  }
})

API 集成

使用 Axios 进行 HTTP 请求：

import axios from 'axios'

const api = axios.create({
  baseURL: 'http://localhost:5000',
  timeout: 30000
})

🚀 部署

静态部署

构建后将 dist/ 目录部署到任何静态文件服务器：

npm run build
# 将 dist/ 目录上传到服务器

Nginx 配置示例

server {
    listen 80;
    server_name your-domain.com;
    root /path/to/dist;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }
}

Docker 部署

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 进行调试：

# 开发模式自动启用 DevTools
npm run dev

📄 许可证

本项目采用 MIT 许可证。

---

最后更新: 2024年12月