# 考试信息管理系统 - 快速上手指南

## 🚀 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. 查看源代码学习实现细节

---

## 💡 小贴士

- **开发模式**: 后端支持热重载，修改代码后自动重启
- **调试技巧**: 使用浏览器的开发者工具查看网络请求
- **数据清理**: 测试数据可随时在数据库中清空重来
- **备份习惯**: 定期备份数据库，防止数据丢失

---

## 🎉 恭喜！

您已经成功搭建并运行了考试信息管理系统！

现在您可以：
- ✅ 发布和管理考试
- ✅ 处理报名申请
- ✅ 录入和查询成绩
- ✅ 发布考试通知
- ✅ 管理用户信息

**开始您的考试管理之旅吧！** 🚀

---

**需要帮助？**
- 查看项目文档
- 检查日志输出
- 联系技术支持