# ExamForge

**Repository Path**: chazzorg/ExamForge

## Basic Information

- **Project Name**: ExamForge
- **Description**: 智能考试系统 - 题库管理、自动组卷、在线答题、智能评分一体化平台
- **Primary Language**: Unknown
- **License**: MPL-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-10
- **Last Updated**: 2026-03-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ExamForge 2.0

## 项目介绍

ExamForge 是一款功能强大的考试模拟与学习平台，从1.x的"单机考试工具"升级为2.0的"持续学习平台"。

### ✨ 2.0 新特性

- **双存储引擎**：支持文件存储和SQLite存储两种模式，可平滑切换
- **多AI Provider支持**：内置支持Claude CLI、Codex CLI、OpenAI API三类AI服务
- **高可用架构**：主备AI Provider自动降级，故障无缝切换
- **性能大幅提升**：SQLite模式下查询性能提升10~100倍，支持万级数据量
- **灰度升级能力**：dual模式双写，零停机迁移，随时可回滚
- **完善运维体系**：内置备份、恢复、优化、监控等运维工具

### 🎯 核心能力

- 📚 智能题库解析：支持标准Markdown题库自动解析
- 🎯 双模式考试：原题模式+AI智能模拟题模式
- 🔄 模拟题复用：支持重新生成和历史模拟题复用
- ✍️ 智能作答：一题一页、自动保存、标记复查、提交锁定
- 📊 智能阅卷：客观题自动判分+主观题AI评分，支持hybrid混合模式
- 📈 学习分析：完整的考试记录、作答统计、薄弱点分析
- 💾 多模式存储：文件/SQLite/dual三种存储模式自由切换
- 🤖 多AI支持：Claude/Codex/OpenAI三类AI服务可配置

## 使用方式

### 项目命名

项目名称：`ExamForge`

命名说明：

- `Exam` 表示考试与题库场景
- `Forge` 表示生成、锻造、构建，贴合模拟题生成、考试会话与阅卷流程
- 整体名称简洁，适合作为本地工具、Git 仓库名和后续产品名

### 1. 环境要求

- Go 1.25 或更高版本
- AI Provider（至少选择一种）：
  - Claude CLI（默认）
  - Codex CLI
  - OpenAI API（兼容所有OpenAI协议的服务）

### 2. 配置环境变量

ExamForge支持通过环境变量配置：

```bash
# 服务配置
APP_ADDR=:8080                    # 监听地址
APP_DEBUG=false                  # 调试模式

# 存储配置
STORAGE_MODE=file                # 存储模式：file/dual/sqlite
SQLITE_PATH=data/examforge.db    # SQLite数据库路径

# AI配置
AI_PROVIDER=claude_code_cli      # AI Provider：claude_code_cli/codex_cli/openai_api
AI_TIMEOUT_SEC=180               # AI调用超时时间
AI_LOG_DIR=logs/ai               # AI日志目录

# Claude CLI配置
CLAUDE_COMMAND=claude            # Claude CLI命令路径
CLAUDE_MODEL=claude-3-opus       # Claude模型名称

# Codex CLI配置
CODEX_COMMAND=codex              # Codex CLI命令路径
CODEX_MODEL=gpt-5.4              # Codex模型名称

# OpenAI API配置
OPENAI_BASE_URL=https://api.openai.com/v1  # API地址
OPENAI_API_KEY=sk-xxx                      # API密钥
OPENAI_MODEL=gpt-4o                        # 模型名称
```

### 3. 启动服务

#### 快速启动（默认文件模式+Claude）
```bash
go run ./cmd/server
```

#### SQLite模式启动
```bash
STORAGE_MODE=sqlite go run ./cmd/server
```

#### dual模式启动（双写）
```bash
STORAGE_MODE=dual go run ./cmd/server
```

#### 指定端口启动
```bash
APP_ADDR=:18080 go run ./cmd/server
```

默认访问地址：
```text
http://127.0.0.1:8080/
```

预期现象：
- 终端输出 `server listening on :8080` 或对应端口
- 浏览器打开首页后可以看到试卷列表

### 3. 基本使用流程

1. 打开首页
2. 输入考生姓名
3. 选择试卷
4. 点击“开始考试”
5. 在答题页逐题作答，答案会自动保存
6. 点击“提交考试”
7. 在结果页查看作答统计
8. 点击“尝试开始阅卷”获取阅卷结果

如果选择模拟题模式：

- 可以“重新生成一套新的模拟题”
- 也可以“使用已有模拟题”直接开始

### 4. 主要接口

- `GET /api/health`：服务健康检查
- `GET /api/papers`：获取试卷列表
- `GET /api/mock/sets?paperId=...`：获取指定试卷对应的可复用模拟题列表
- `POST /api/papers/parse`：手动解析试卷
- `POST /api/exam/start`：开始考试
- `GET /api/exam/:sessionId`：获取会话详情
- `GET /api/exam/:sessionId/question/:index`：获取指定题目
- `POST /api/exam/:sessionId/answer`：保存答案
- `POST /api/exam/:sessionId/submit`：提交试卷
- `POST /api/review/:sessionId`：开始阅卷
- `GET /api/review/:sessionId`：获取最新阅卷结果

## 存储模式

ExamForge 2.0支持三种存储模式，可自由切换：

| 模式 | 说明 | 适用场景 |
|------|------|----------|
| `file` | 纯文件存储，所有数据以JSON格式保存 | 小数据量、简单部署、需要直接编辑数据 |
| `dual` | 双写模式，同时写入文件和SQLite | 迁移过渡期、灰度升级、需要回滚保障 |
| `sqlite` | 纯SQLite存储，高性能 | 大数据量、追求性能、需要复杂查询 |

### 数据存储位置

#### 文件模式
所有数据均保存在本地文件系统中：
- `papers/`：原始Markdown题库
- `parsed/`：解析后的标准题目JSON
- `answer_keys/`：标准答案与采分点
- `sessions/`：考试会话记录
- `answers/`：答题记录
- `reviews/`：阅卷结果
- `generated/`：生成的模拟题
- `logs/`：AI调用日志

#### SQLite模式
所有数据保存在SQLite数据库文件中：
- 默认路径：`data/examforge.db`
- 可通过`SQLITE_PATH`环境变量自定义路径

### 题库与标准答案

- `papers/`
  可放置标准版题库文件
- `parsed/`
  题库解析后的标准题目 JSON
- `answer_keys/`
  标准答案、参考答案与采分点 JSON

### 考试过程数据

- `sessions/`
  考试会话文件
- `answers/`
  答题记录文件

### 阅卷结果与日志

- `reviews/`
  阅卷结果文件，每次阅卷一个批次文件
- `logs/claude/`
  Claude CLI 的 prompt 和 response 日志

### 模拟题数据

- `generated/`
  模拟题题集 JSON

### 代码与页面

- `web/`
  静态前端页面和资源
- `cmd/`
  服务启动入口
- `internal/`
  后端业务实现

## 文件命名规则

- 原题题集：`parsed/{paperId}.questions.json`
- 模拟题题集：`generated/{mockPaperId}.questions.json`
- 标准答案：`answer_keys/{paperId}.answer_key.json`
- 会话：`sessions/{sessionId}.json`
- 答案：`answers/{sessionId}.answers.json`
- 阅卷：`reviews/{sessionId}.{reviewBatchId}.review.json`

## 当前实现说明

- 当前支持 `original` 原题模式和 `mock` 模拟题模式
- 模拟题模式支持重新生成和复用已有题集
- 提交后答案不可修改
- 允许重复阅卷，每次会生成新的阅卷批次
- 客观题优先规则判分
- 主观题优先按标准答案和采分点结合 Claude CLI 评分
- 结果页会展示整份阅卷明细，而不只显示错题
- Claude CLI 不可用时，主观题会尽量回退到本地规则评分

## 迁移指南

从1.x版本升级到2.0版本非常简单：

### 方式1：直接切换（小数据量）
```bash
# 1. 备份数据
tar -czf data_backup.tar.gz data/

# 2. 执行全量迁移
go run cmd/migrate/main.go --validate

# 3. 切换到SQLite模式
STORAGE_MODE=sqlite go run ./cmd/server
```

### 方式2：灰度切换（大数据量，零停机）
```bash
# 1. 切换到dual模式双写
STORAGE_MODE=dual go run ./cmd/server

# 2. 运行至少一周，确认双写正常
./scripts/verify_data.sh

# 3. 执行全量迁移同步历史数据
go run cmd/migrate/main.go --validate

# 4. 切换到SQLite模式
STORAGE_MODE=sqlite go run ./cmd/server
```

### 一键迁移脚本
```bash
# 自动完成备份→预检查→迁移→校验全流程
./scripts/migrate.sh
```

## 运维工具

ExamForge 2.0提供了完善的运维脚本：

| 脚本 | 功能 | 用法 |
|------|------|------|
| `scripts/migrate.sh` | 全量数据迁移 | `./scripts/migrate.sh` |
| `scripts/verify_data.sh` | 数据一致性校验 | `./scripts/verify_data.sh` |
| `scripts/check_data.sh` | 数据完整性核对 | `./scripts/check_data.sh [--quick/--full/--diff]` |
| `scripts/switch_mode.sh` | 存储模式切换 | `./scripts/switch_mode.sh <file/dual/sqlite>` |
| `scripts/sqlite_backup.sh` | SQLite在线备份 | `./scripts/sqlite_backup.sh [备份目录]` |
| `scripts/sqlite_restore.sh` | SQLite恢复 | `./scripts/sqlite_restore.sh <备份文件路径>` |
| `scripts/sqlite_maintenance.sh` | SQLite运维 | `./scripts/sqlite_maintenance.sh <info/vacuum/analyze/clean>` |

## 常见问题

### 提交按钮点击无反应

先刷新页面确认已加载最新前端资源。如果按钮是灰色，通常表示当前会话已经不是 `doing` 状态；如果按钮可点但没有动作，建议先强制刷新浏览器缓存后再试。

### 模拟题列表为空

这通常表示当前试卷还没有生成过模拟题。直接选择“重新生成一套新的模拟题”即可；生成完成后，后续就可以在“使用已有模拟题”中复用。

### Claude CLI 无法阅卷

请先确认本机命令行可以正常执行：

执行位置：项目根目录或任意目录

```bash
claude --help
```

预期现象：

- 能正常输出帮助信息

如果命令不存在或未登录，主观题 AI 阅卷将无法正常使用；系统会尽量回退到本地规则评分。

### 如何放入题库

把标准版 Markdown 题库放到 [papers](/Users/zz/Documents/考试模拟/papers) 目录即可。首页会自动扫描并显示试卷列表；第一次开始考试时，如果该试卷还没有解析结果，后端会自动解析并生成 `parsed/*.questions.json`。