一个面向新人培训、岗位测评与知识复盘的全栈系统。它把“学习题库、场景练习、正式考试、AI 批改、错题复盘、团队管理”放进同一条闭环，既可独立运行，也可以通过可信代理 Header 接入已有企业平台。
本仓库是可公开运行的作品版。内置的 60 道题全部是为开源演示重新编写的合成内容，不包含任何企业手册、客户资料、生产题库或原仓库历史。
- 训练模式：逐题练习，提交后立即查看关键点、示例答案与纠正建议。
- 考试模式：支持 10 / 20 / 30 题，按分类和难度均衡抽题，整卷提交后统一批改。
- 双演示题库：通用能力、客户服务，各 30 道原创合成题。
- 两级批改方案：默认使用无需密钥的本地规则；配置兼容 OpenAI API 的模型后可启用 AI 语义批改。
- 学习闭环：错题列表、错题恢复、考试历史、个人最佳成绩与排行榜。
- 管理后台：查看用户快照、题目状态、考试明细，支持题目增删改与上下线。
- 音频能力：可保存语音回答、转写状态和音频元数据。
- 平台接入：支持员工、组长、管理员、超级管理员四种角色，以及请求标识透传和操作审计。
| 场景练习 | 管理后台 |
|---|---|
 |
 |
需要 Python 3.11+、Node.js 20.19+ 或 22+。
git clone https://github.com/k4ubx7/TrainAnswer.git
cd TrainAnswer
python -m pip install -r backend/requirements.txt
cd frontend
npm ci
cd ..
python start_dev.py启动脚本会自动完成三件事：创建隔离的 SQLite 数据库、导入公开演示题库、同时启动前后端。
- 前端：http://localhost:5190/tools-runtime/train-answer/
- 后端健康检查：http://localhost:8020/health
- API 文档：http://localhost:8020/docs
本地演示默认使用管理员身份，不需要账号、数据库服务或 AI 密钥。按 Ctrl+C 可同时结束前后端进程。
docker compose up --build然后打开 http://localhost:5190/tools-runtime/train-answer/。Docker 版本同样使用独立的演示数据库和合成题库。
flowchart LR
U["学员 / 管理员"] --> W["React 前端"]
W --> A["FastAPI API"]
A --> D[("SQLite / PostgreSQL")]
A --> G{"批改 Provider"}
G --> M["本地 Mock 规则"]
G --> L["兼容 OpenAI API 的模型"]
A --> S["音频存储"]
P["可选：企业平台代理"] -->|"身份与角色 Header"| A
- 题库与系统解耦：题目以结构化 JSON 导入，包含关键点、权重、常见错误和评分提示。
- 抽题可解释：考试按题库、分类和难度采样，避免连续抽到单一类型题目。
- 批改可替换：业务流程只依赖统一 Provider 接口，本地演示与真实 AI 使用相同输出协议。
- 结果可追溯：保存逐题回答、命中点、漏答点、纠正建议和批改运行记录。
- 身份边界清晰：开发模式提供本地身份；生产模式要求可信代理注入身份、角色和请求标识。
公开题库位于 backend/demo_questions.json，生成源位于 backend/scripts/generate_demo_questions.py。你可以检查每一道题是如何构造的，也可以重新生成：
python backend/scripts/generate_demo_questions.py
python backend/scripts/validate_question_bank.py backend/demo_questions.json当前分布：
| 题库 | 简单 | 中等 | 困难 | 合计 |
|---|---|---|---|---|
| 通用能力 | 10 | 10 | 10 | 30 |
| 客户服务 | 10 | 10 | 10 | 30 |
每道题满分 10 分，三个关键评分点的权重之和必须等于题目分值。验证脚本会检查题号唯一性、题库范围、答案完整性和权重一致性。
- 复制
demo_questions.json并替换为自己的题目内容。 - 保持字段结构，运行验证脚本。
- 设置独立的
DATABASE_URL，运行backend/scripts/import_questions.py导入。 - 真实资料不要提交到公共仓库；建议放在被
.gitignore排除的私有文件中。
默认 AI_PROVIDER=mock_local，只要回答非空就给出占位结果，适合界面演示和流程测试。
若要启用兼容 OpenAI API 的模型，在项目根目录创建 .env：
AI_PROVIDER=aliyun_qwen
AI_MODEL=your-model-name
AI_API_BASE_URL=https://your-provider.example.com/compatible-mode/v1
AI_API_KEY=your-key后端会要求模型返回结构化 JSON，并再次校验题目 ID、题目数量和分数范围，防止异常结果直接写入业务数据。
常用环境变量：
| 变量 | 默认值 | 用途 |
|---|---|---|
DATABASE_URL |
sqlite:///./demo.db（启动脚本） |
数据库连接 |
AI_PROVIDER |
mock_local |
批改 Provider |
AI_MODEL |
qwen3.6-plus |
模型名称 |
AI_API_BASE_URL |
阿里云兼容端点 | 模型服务地址 |
AI_API_KEY |
空 | 模型密钥 |
AUDIO_STORAGE_PATH |
backend/uploads |
音频目录 |
AUDIO_MAX_UPLOAD_BYTES |
26214400 |
单个音频上限 |
CORS_ALLOWED_ORIGINS |
空 | 生产环境允许的来源 |
完整示例见 .env.example。不要提交真实密钥或含个人信息的数据库。
# 后端
python -m pip install -r backend/requirements.txt pytest
python -m pytest backend/tests -q
# 前端
cd frontend
npm ci
npm test
npm run buildGitHub Actions 会运行题库验证、后端测试、前端测试与构建，并对 Docker 独立演示环境做启动冒烟测试。
TrainAnswer/
├─ backend/
│ ├─ app/ # FastAPI API、领域模型与服务
│ ├─ alembic/ # 数据库迁移
│ ├─ scripts/ # 题库生成、验证、导入和演示初始化
│ ├─ tests/ # 后端测试
│ └─ demo_questions.json # 公开合成题库
├─ frontend/
│ └─ src/ # React 页面、组件、API 客户端与测试
├─ docs/images/ # README 截图
├─ docker-compose.yml # 独立演示环境
└─ start_dev.py # 本地一键启动
这个仓库有意不包含：
- 企业真实题库、培训手册、客户资料和内部文档；
- 原私有仓库的 Git 历史、生成中间产物和审查报告；
- 本地数据库、上传音频、日志、密钥和个人身份信息。
如果你基于本项目部署自己的培训系统，请自行确认题库内容的著作权、个人信息保护要求和所使用模型服务的条款。
本项目建立在 FastAPI、SQLAlchemy、Alembic、React、TanStack Query、Vite 与 Lucide 等开源项目之上，感谢这些项目的维护者与贡献者。
第三方依赖继续适用其各自的许可证。
提交改进前请阅读 CONTRIBUTING.md。安全问题请按 SECURITY.md 私下报告，不要在 Issue 中提交密钥、真实题库或个人信息。
本项目采用 Apache License 2.0 开源。