init

2026-03-20 21:41:00 +08:00
commit 3d1d4cf506
53 changed files with 7105 additions and 0 deletions
--- a/QUICKSTART.md
+++ b/QUICKSTART.md
@@ -0,0 +1,343 @@
+# 考试信息管理系统 - 快速上手指南
+
+## 🚀 5 分钟快速开始
+
+### 前置条件
+
+请确保您的计算机已安装：
+- ✅ Go 1.21+ 
+- ✅ MySQL 8.0+
+- ✅ Node.js 18+
+
+### 第一步：克隆项目（如果还未获取）
+
+```bash
+# 如果已经下载好，跳过此步
+# 项目位置：E:\Exam_registration
+```
+
+---
+
+### 第二步：初始化数据库（2 分钟）
+
+#### 方法一：使用 SQL 脚本（推荐）
+
+1. 打开命令行，登录 MySQL：
+```bash
+mysql -u root -p
+```
+
+2. 执行 SQL 脚本：
+```sql
+source E:\Exam_registration\database.sql;
+```
+
+3. 验证数据库创建成功：
+```sql
+SHOW DATABASES;
+USE exam_registration;
+SHOW TABLES;
+```
+
+应该看到 5 张表：`user`, `exam`, `exam_registration`, `exam_notice`, `exam_score`
+
+#### 方法二：手动创建
+
+如果自动脚本失败，可以手动执行 `database.sql` 文件中的 SQL 语句。
+
+---
+
+### 第三步：配置后端（1 分钟）
+
+1. 打开配置文件：`config/config.yaml`
+
+2. 修改数据库密码：
+```yaml
+database:
+  host: localhost
+  port: 3306
+  user: root
+  password: YOUR_PASSWORD  # ⚠️ 改为你的 MySQL 密码
+  dbname: exam_registration
+```
+
+3. 保存文件
+
+---
+
+### 第四步：启动后端服务（1 分钟）
+
+```bash
+# 进入项目目录
+cd E:\Exam_registration
+
+# 下载依赖（首次需要）
+go mod tidy
+
+# 启动服务
+go run cmd/main.go
+```
+
+看到以下输出表示成功：
+```
+Server started on port 8080
+```
+
+**测试后端**: 打开浏览器访问 http://localhost:8080，能看到页面说明后端正常。
+
+---
+
+### 第五步：启动前端（2 分钟）
+
+打开新的命令行窗口：
+
+```bash
+# 进入前端目录
+cd E:\Exam_registration\frontend
+
+# 安装依赖（首次需要，约 1-2 分钟）
+npm install
+
+# 启动开发服务器
+npm run dev
+```
+
+看到以下输出表示成功：
+```
+  VITE v5.0.8  ready in 1234 ms
+
+  ➜  Local:   http://localhost:3000/
+  ➜  Network: use --host to expose
+```
+
+**测试前端**: 打开浏览器访问 http://localhost:3000
+
+---
+
+### 第六步：登录系统
+
+使用默认管理员账号登录：
+
+- **用户名**: `admin`
+- **密码**: `admin123`
+
+登录后可以看到系统首页！
+
+---
+
+## 🎯 快速功能演示
+
+### 1️⃣ 发布考试（管理员）
+
+1. 点击导航栏「考试管理」
+2. 点击「发布考试」按钮
+3. 填写考试信息：
+   - 考试名称：2024 年春季英语等级考试
+   - 考试代码：ENG-2024-001
+   - 考试时间：选择未来某个时间
+   - 其他信息按需填写
+4. 点击确定
+
+✅ 考试发布成功！
+
+---
+
+### 2️⃣ 报名考试（普通用户）
+
+1. 注册新账号或退出管理员账号
+2. 浏览考试列表
+3. 点击感兴趣的考试查看详情
+4. 点击「立即报名」
+5. 等待管理员审核
+
+✅ 报名成功！
+
+---
+
+### 3️⃣ 审核报名（管理员）
+
+1. 使用 admin 账号登录
+2. 点击「报名管理」→「报名列表」
+3. 找到待审核的报名记录
+4. 点击「通过」或「拒绝」
+5. 填写审核意见
+
+✅ 审核完成！系统自动生成准考证号
+
+---
+
+### 4️⃣ 录入成绩（管理员）
+
+1. 点击「成绩管理」→「成绩录入」
+2. 选择对应的考试
+3. 点击「批量录入」
+4. 输入 JSON 格式的成绩数据：
+```json
+[
+  {"user_id": 2, "score": 85},
+  {"user_id": 3, "score": 92}
+]
+```
+5. 点击确定
+
+✅ 成绩录入成功！
+
+---
+
+### 5️⃣ 查询成绩（用户）
+
+1. 用户登录自己的账号
+2. 点击「成绩查询」
+3. 查看自己的分数和排名
+
+✅ 成绩查询成功！
+
+---
+
+## 🔧 常见问题排查
+
+### ❌ 问题 1：后端启动失败
+
+**错误**: `无法连接数据库`
+
+**解决方案**:
+1. 检查 MySQL 服务是否运行
+2. 确认 `config/config.yaml` 中的密码正确
+3. 确认数据库 `exam_registration` 已创建
+
+```bash
+# 检查 MySQL 服务状态（Windows）
+net start | findstr MySQL
+
+# 启动 MySQL 服务
+net start MySQL80
+```
+
+---
+
+### ❌ 问题 2：前端启动失败
+
+**错误**: `npm: command not found`
+
+**解决方案**:
+1. 确认已安装 Node.js
+2. 将 Node.js 添加到系统 PATH
+3. 重新打开命令行
+
+```bash
+# 检查 Node.js 版本
+node --version
+npm --version
+```
+
+---
+
+### ❌ 问题 3：跨域错误
+
+**错误**:`Access-Control-Allow-Origin`
+
+**解决方案**:
+1. 确认后端已启动 CORS 中间件（代码中已包含）
+2. 确认前端请求的 baseURL 是 `/api`
+3. 检查 `vite.config.js` 中的代理配置
+
+---
+
+### ❌ 问题 4：登录失败
+
+**错误**: `用户名或密码错误`
+
+**解决方案**:
+1. 确认用户名是 `admin`
+2. 确认密码是 `admin123`
+3. 如果忘记密码，可以在数据库中重置：
+
+```sql
+-- 重置 admin 密码为 admin123
+UPDATE user 
+SET password = '$2a$10$N9qo8uLOickgx2ZMRZoMyeIjZAgcfl7p92ldGxad68LJZdL17lhWy' 
+WHERE username = 'admin';
+```
+
+---
+
+## 📱 移动端访问
+
+系统支持响应式布局，可在手机上访问：
+
+1. 确保手机和电脑在同一局域网
+2. 启动前端时添加 `--host` 参数：
+```bash
+npm run dev -- --host
+```
+3. 使用手机浏览器访问：`http://你的电脑 IP:3000`
+
+---
+
+## 🎓 进阶使用
+
+### 添加更多管理员
+
+```sql
+INSERT INTO user (username, password, email, role, status) 
+VALUES ('newadmin', '$2a$10$N9qo8uLOickgx2ZMRZoMyeIjZAgcfl7p92ldGxad68LJZdL17lhWy', 'admin2@example.com', 'admin', 1);
+```
+
+### 批量导入考生
+
+编写脚本或使用 Excel 转 CSV 后批量插入数据库。
+
+### 自定义配置
+
+编辑 `config/config.yaml`:
+
+```yaml
+server:
+  port: 8080  # 修改端口
+  
+jwt:
+  expire: 86400  # Token 有效期（秒）
+  
+database:
+  max_idle_conns: 20  # 连接池大小
+```
+
+---
+
+## 📚 下一步学习
+
+1. 阅读 `API_DOCUMENTATION.md` 了解完整接口文档
+2. 阅读 `PROJECT_SUMMARY.md` 了解所有功能
+3. 阅读 `DEPLOYMENT.md` 学习生产环境部署
+4. 查看源代码学习实现细节
+
+---
+
+## 💡 小贴士
+
+- **开发模式**: 后端支持热重载，修改代码后自动重启
+- **调试技巧**: 使用浏览器的开发者工具查看网络请求
+- **数据清理**: 测试数据可随时在数据库中清空重来
+- **备份习惯**: 定期备份数据库，防止数据丢失
+
+---
+
+## 🎉 恭喜！
+
+您已经成功搭建并运行了考试信息管理系统！
+
+现在您可以：
+- ✅ 发布和管理考试
+- ✅ 处理报名申请
+- ✅ 录入和查询成绩
+- ✅ 发布考试通知
+- ✅ 管理用户信息
+
+**开始您的考试管理之旅吧！** 🚀
+
+---
+
+**需要帮助？**
+- 查看项目文档
+- 检查日志输出
+- 联系技术支持