开发与构建

服务端

bun install
bun run start

默认监听 http://127.0.0.1:3000/。

主要环境变量：

EXAM_API_TOKEN     接口鉴权 token，必填
EXAMS_DB_FILE      可选，数据库路径
FILES_DIRECTORY    可选，hash 文件根目录
PORT               可选，HTTP 端口

试卷与检查流程

1. POST /api/v1/exams { name }                 创建空试卷
2. GET  /api/v1/exams/{id}                     读取内容
3. PUT  /api/v1/exams/{id}                     提交完整 JSON
4. POST /api/v1/files                          上传答题卡图片
5. POST /api/v1/exams/check { examId, fileIds } 批量检查试卷

试卷 JSON 标准见 试卷 JSON 标准。

生成与仿真

bun run generate
bun run simulate
bun run scan:photo -- "照片路径.jpg"

注意：当前 generate / simulate 仍读取旧的 config/exam.json 的 fields 网格；新接口与 check 使用 questions 标准。

配置

运行时配置：

config/exam.json     旧生成管线使用的试卷布局
config/detect.json   扫描阈值和定位块参数

检测阈值属于管理员配置，不应写进试卷 JSON。

打包

bun run build
bun run build:linux

打包会把 src/libs 复制到 exe 同级的 libs，把 config 复制到同级 config。

测试

bun test

文档

文档项目位于 docs，使用 MkDocs Material + uv。

cd docs
uv sync
uv run mkdocs serve

Windows 下也可以直接运行 serve.cmd 热启动。

构建：

cd docs
bun run build

或直接运行 MkDocs：

cd docs
uv run mkdocs build -f mkdocs.yml

输出目录：docs/dist。