# exam

**Repository Path**: exam-prep/exam

## Basic Information

- **Project Name**: exam
- **Description**: 管理软考相关仓库开发
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-29
- **Last Updated**: 2026-06-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 通用考试训练平台

这是一个通用考试题库 / 刷题 / 模拟真考 / 后台题库管理系统的本地开发工作区，支持软考、自考、会计考试等考试项目，包含三个独立项目：

```text
ruankao-exam-prep-api      Go + Gin + GORM + PostgreSQL + Redis
ruankao-exam-prep-web      Vue3 + TypeScript + Vite 用户练习与模拟真考端
ruankao-exam-prep-admin    Vue3 + TypeScript + Vite 后台管理端
```

## 项目结构

```text
.
├── docker-compose.yml
├── docs/
│   └── development-plan.md
├── ruankao-exam-prep-api/
├── ruankao-exam-prep-web/
└── ruankao-exam-prep-admin/
```

## 环境要求

- Go 1.26+
- Node.js 25+
- pnpm
- Docker / Docker Compose
- PostgreSQL CLI `psql`，用于执行 migration 和 seed

## 快速启动

推荐先使用根目录 Makefile：

```bash
make setup
```

这会安装 Web/Admin 依赖，启动 PostgreSQL 和 Redis，并执行数据库 migration、默认管理员 seed 和示例题库 seed。

查看所有快捷命令：

```bash
make help
```

也可以按下面步骤手动启动。

### 1. 启动基础设施

在当前根目录执行：

```bash
docker compose up -d postgres redis
```

确认服务健康：

```bash
docker compose ps
```

默认端口：

- PostgreSQL: `localhost:5432`
- Redis: `localhost:6379`

### 2. 初始化数据库

```bash
cd ruankao-exam-prep-api

psql "postgres://ruankao:ruankao123@localhost:5432/ruankao_exam_prep?sslmode=disable" -f migrations/001_create_auth_tables.up.sql
psql "postgres://ruankao:ruankao123@localhost:5432/ruankao_exam_prep?sslmode=disable" -f migrations/002_create_question_bank_tables.up.sql
psql "postgres://ruankao:ruankao123@localhost:5432/ruankao_exam_prep?sslmode=disable" -f scripts/seed_admin.sql
psql "postgres://ruankao:ruankao123@localhost:5432/ruankao_exam_prep?sslmode=disable" -f scripts/seed_question_bank.sql
```

默认管理员账号：

- 用户名：`admin`
- 密码：`admin123`

### 3. 启动 API

```bash
cd ruankao-exam-prep-api
go run ./cmd/server
```

API 默认地址：

- Health Check: `http://localhost:8080/healthz`
- 用户端接口：`http://localhost:8080/api/v1`
- 后台接口：`http://localhost:8080/admin-api/v1`

### 4. 启动用户端 Web

```bash
cd ruankao-exam-prep-web
pnpm install
pnpm run dev
```

Vite 会输出本地访问地址，默认通常是：

```text
http://localhost:5173
```

用户端开发环境 API 地址配置在：

```text
ruankao-exam-prep-web/.env.development
```

### 5. 启动后台 Admin

```bash
cd ruankao-exam-prep-admin
pnpm install
pnpm run dev
```

如果用户端已经占用 `5173`，Vite 会自动使用下一个可用端口，例如：

```text
http://localhost:5174
```

后台开发环境 API 地址配置在：

```text
ruankao-exam-prep-admin/.env.development
```

## Docker 启动 API

也可以从根目录构建并启动 API 容器：

```bash
docker compose up -d postgres redis api
```

注意：当前 `api` 容器不会自动执行 migration 和 seed。首次启动前仍建议先执行“初始化数据库”步骤，或者后续补充专门的 migration 工具链。

## 常用命令

### 根目录快捷命令

```bash
make help
make setup
make infra-up
make db-init
make db-reset-platform
make api-dev
make web-dev
make admin-dev
make verify
```

常用开发方式是开三个终端分别运行：

```bash
make api-dev
make web-dev
make admin-dev
```

### API

```bash
cd ruankao-exam-prep-api

go test ./...
go run ./cmd/server
go build -o bin/server ./cmd/server
go mod tidy
```

也可以使用 Makefile：

```bash
make test
make dev
make build
make tidy
```

### 用户端 Web

```bash
cd ruankao-exam-prep-web

pnpm run dev
pnpm test
pnpm run build
pnpm run preview
```

### 后台 Admin

```bash
cd ruankao-exam-prep-admin

pnpm run dev
pnpm run build
pnpm run preview
```

## 接口验证示例

### Health Check

```bash
curl http://localhost:8080/healthz
```

### 用户注册

```bash
curl -X POST http://localhost:8080/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"username":"demo","password":"secret123","nickname":"Demo"}'
```

### 用户登录

```bash
curl -X POST http://localhost:8080/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"demo","password":"secret123"}'
```

### 管理员登录

```bash
curl -X POST http://localhost:8080/admin-api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin123"}'
```

## 当前开发进度

已完成登录链路、通用题库和严格模拟真考主链路：

- 用户注册
- 用户登录
- 用户 profile
- 管理员登录
- 管理员 profile
- JWT 认证中间件
- 考试项目、科目、大纲节点、题目、选项表结构
- 支持软考、自考、会计考试等考试项目
- 后台考试目录维护
- 后台选择题、填空题、简答题维护
- 后台严格模拟真考规则配置
- 用户端题库练习
- 提交答案并返回得分、正确答案与解析
- 简答题 AI 辅助评分并直接计入成绩
- 严格模拟真考开始、交卷、成绩结果
- 错题本
- 收藏题

后续阶段见：

```text
docs/development-plan.md
```

## 常见问题

### 端口被占用

如果 `5432`、`6379` 或 `8080` 被占用，可以先查看占用进程，或修改 `docker-compose.yml` 和 API 配置中的端口。

### migration 重复执行

当前建表 SQL 使用了 `IF NOT EXISTS`，重复执行不会重复建表。默认管理员 seed 和题库 seed 使用 `ON CONFLICT DO NOTHING` 或存在性判断，重复执行不会重复创建管理员、考试项目、科目和示例题。

### 从旧软考模型切换到通用考试平台

如果本地数据库已经执行过旧的软考题库 migration，请运行：

```bash
make db-reset-platform
```

该命令会重建考试平台领域表，并写入软考、自考、会计考试的示例项目和模拟真考规则。

### Admin 构建警告

后台 `pnpm run build` 目前可能出现 Rolldown 对依赖 `#__PURE__` 注释的 warning，以及 Element Plus 带来的 chunk 体积提示。当前不影响构建结果，后续做路由懒加载和依赖按需引入时再优化。