# ai-smart-question-system

**Repository Path**: zhangsonggui/ai-smart-question-system

## Basic Information

- **Project Name**: ai-smart-question-system
- **Description**: AI 驱动的智能题库系统，支持文档自动生题、智能组卷、多端刷题。提供管理后台（Vue 3）和微信小程序双端访问。
- **Primary Language**: Python
- **License**: MulanPSL-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-15
- **Last Updated**: 2026-06-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AI 智能题库系统

AI 驱动的智能题库系统，支持文档自动生题、智能组卷、多端刷题。提供管理后台（Vue 3）和微信小程序双端访问。

## 架构

```
┌─────────────────────────────────────────────────┐
│                  微信小程序                       │
│          (question-wx / 刷题端)                   │
└──────────────────┬──────────────────────────────┘
                   │ HTTP / WebSocket
┌──────────────────┴──────────────────────────────┐
│             管理后台 (question-vue)                │
│           Vue 3 + Naive UI + Vite                │
└──────────────────┬──────────────────────────────┘
                   │ /api  /ws  /uploads
┌──────────────────┴──────────────────────────────┐
│          后端 API (question-bank)                  │
│     FastAPI + SQLAlchemy + AI Engine             │
│     Uvicorn / Python 3.12                        │
└──────────┬───────────────────────┬───────────────┘
           │                       │
     ┌─────┴──────┐         ┌──────┴──────┐
     │   SQLite    │         │   MySQL 8   │
     │  (开发模式)  │         │  (生产模式)   │
     └────────────┘         └─────────────┘
```

## 技术栈

| 组件 | 技术 |
|------|------|
| 后端框架 | FastAPI 0.136+ / Uvicorn |
| 数据库 ORM | SQLAlchemy 2.0 (async) |
| 数据库 | SQLite (dev) / MySQL 8 (prod) |
| AI 集成 | OpenAI SDK / DeepSeek / Qwen |
| 认证 | JWT (python-jose + passlib/bcrypt) |
| 管理前端 | Vue 3 + Vite + Naive UI |
| 小程序端 | 微信原生 + weui-miniprogram |
| 部署 | Docker Compose + Nginx 反向代理 |

## 目录结构

```
ai-smart-question-system/
├── question-bank/              # 后端 API 服务
│   ├── src/
│   │   ├── main.py             # 应用入口 (FastAPI app)
│   │   └── app/
│   │       ├── api/            # 路由层 (16 个路由模块)
│   │       ├── core/           # 配置 / 数据库 / 安全
│   │       ├── engine/         # AI 生成引擎 / 评分
│   │       ├── models/         # SQLAlchemy 数据模型
│   │       ├── schemas/        # Pydantic 请求/响应模型
│   │       └── services/       # 业务逻辑层
│   ├── Dockerfile              # 生产构建（联网 uv sync）
│   ├── Dockerfile.local        # 离线构建（本地 .venv）
│   ├── nginx.conf              # 标准模式（服务名解析）
│   └── nginx.pod.conf          # Pod 共享网络模式（localhost）
│
├── question-vue/               # 管理后台 (Vue 3)
│   ├── src/
│   │   ├── views/              # 页面组件
│   │   ├── router/             # 路由配置
│   │   ├── stores/             # Pinia 状态管理
│   │   └── service/            # Axios API 封装
│   └── vite.config.js
│
├── question-wx/                # 微信小程序 (刷题端)
│
├── build.sh                    # 构建打包脚本
└── cleanup.sh                  # 容器清理脚本（部署环境用）
```

## 快速开始

### 后端

```bash
cd question-bank

# 安装依赖（需要先安装 uv: pip install uv）
uv sync

# 启动开发服务器（SQLite，自动创建数据库和初始数据）
uv run uvicorn main:app --reload --host 0.0.0.0 --port 8000
```

访问 http://localhost:8000/docs 查看 API 文档。默认管理员账号：`admin` / `admin123`。

### 管理后台

```bash
cd question-vue
npm install
npm run dev
```

访问 http://localhost:3000，自动代理 `/api` 到后端 8000 端口。

### 微信小程序

```bash
cd question-wx
npm install
```

用微信开发者工具打开 `question-wx/` 目录：
1. 菜单栏 → 工具 → 构建 npm
2. 构建完成后，手动删除 `miniprogram_npm/weui-miniprogram/miniprogram_dist/`（避免主包超 1.5MB）
3. 编译运行

> 手机预览需修改 `config.js` 中的 `baseUrl` 为电脑局域网 IP。

## 环境变量

后端通过 `conf/.env` 文件配置（首次启动自动生成模板）：

| 变量 | 说明 | 默认值 |
|------|------|--------|
| `RUN_MODE` | dev / prod | dev |
| `DATABASE_URL` | 数据库连接 | `sqlite+aiosqlite:///./question_gen.db` |
| `AI_API_KEY` | AI 模型 API Key | - |
| `AI_BASE_URL` | AI 接口地址 | `https://api.deepseek.com` |
| `AI_MODEL` | 模型名称 | `deepseek-v4-flash` |
| `AI_TEMPERATURE` | 生成温度 | 0.7 |
| `AI_MAX_TOKENS` | 最大 token 数 | 16384 |
| `TASK_WORKER_COUNT` | AI 任务并发数 | 2 |
| `MAX_UPLOAD_SIZE_MB` | 上传限制 | 50 |

生产环境连接 MySQL：

```ini
RUN_MODE=prod
DATABASE_URL=mysql+aiomysql://root:password@127.0.0.1:3306/question?charset=utf8mb4
```

## 构建与部署

构建过程将前端编译、后端源码、Docker 镜像、配置文件统一打包为一个 `.tar.gz` 发布包，支持在线和离线部署。

### 构建发布包

```bash
# 默认：联网构建镜像（uv sync）
bash build.sh

# 使用本地虚拟环境加速构建（跳过网络下载）
bash build.sh --local-venv

# 仅打包文件，跳过镜像构建
bash build.sh --skip-image
```

构建产物输出到 `release/` 目录：

```
release/
└── ai_question_system.tar.gz     # 完整发布包（~2-5GB，含镜像）
```

### 发布包结构

解压后的目录结构：

```
ai_question_system/
├── code/src/                # 后端源码（挂载到容器 /app/src）
├── conf/
│   ├── .env                 # 生产环境配置（需修改 AI_API_KEY 等）
│   └── expert/              # AI 专家提示词
├── frontend/                # Vue 构建产物（直接 nginx 根目录）
│   ├── index.html
│   ├── assets/
│   └── vendor/
├── logs/                    # 运行时日志（自动创建）
├── uploads/                 # 上传文件（自动创建）
├── mysql-data/              # MySQL 数据持久化（保留跨构建）
├── images/                  # ★ 导出的容器镜像（离线安装用）
│   ├── backend.tar.gz       #   后端镜像
│   ├── mysql.tar.gz         #   MySQL 镜像
│   └── nginx.tar.gz         #   Nginx 镜像
│
├── docker-compose.yml       # 标准模式（Docker / Podman DNS 正常）
├── docker-compose.pod.yml   # Pod 覆盖模式（Podman DNS 异常时）
├── nginx.conf               # 标准 Nginx 配置（服务名解析）
├── nginx.pod.conf           # Pod 模式 Nginx 配置（localhost）
│
├── Dockerfile               # 镜像构建文件（可本地重建）
├── Dockerfile.local
├── pyproject.toml
├── uv.lock
│
├── start.sh                 # ★ 一键启动脚本（自动检测）
└── cleanup.sh               # 清理脚本
```

### 在线部署

```bash
# 1. 将发布包上传到目标服务器，解压
tar -xzf ai_question_system.tar.gz
cd ai_question_system

# 2. 编辑配置
vi conf/.env                  # 必须修改 AI_API_KEY 和 JWT_SECRET

# 3. 一键启动（自动检测 Docker/Podman）
bash start.sh

# 4. 查看状态
docker ps                     # 或 podman ps
docker logs ai-question-backend -f
```

### 离线部署

目标服务器没有互联网访问时：

```bash
# 1. 在有网络的构建机上运行 build.sh（自动导出镜像到 images/）
# 2. 将 tar.gz 传到目标服务器

tar -xzf ai_question_system.tar.gz
cd ai_question_system

vi conf/.env                  # 修改 AI_API_KEY 和 JWT_SECRET

# 3. start.sh 会自动加载 images/ 中的离线镜像
bash start.sh
```

也可手动加载：

```bash
for img in images/*.tar.gz; do
  docker load -i "$img"       # 或 podman load -i "$img"
done
```

### Podman DNS 问题说明

某些 Podman 版本（如 WSL 环境）的 CNI dnsname 插件与 firewall 插件不兼容，导致容器间无法通过服务名解析。为此提供两种部署模式：

**模式一：标准模式**（Docker 或 Podman DNS 正常）

```bash
podman-compose up -d
```

**模式二：Pod 共享网络模式**（Podman DNS 异常时使用）

容器在同一个 Pod 内共享网络命名空间，通过 `localhost` 通信。

```bash
podman-compose -f docker-compose.yml -f docker-compose.pod.yml up -d
```

`start.sh` 会**自动检测** DNS 可用性并选择模式，通常无需手动指定。

## 主要功能

| 功能 | 管理后台 | 小程序 |
|------|---------|--------|
| 题库树管理 | CRUD + 拖拽调整 | 选择切换 |
| 题目编辑 | 单选/多选/判断/简答 | 答题/背题/刷题模式 |
| AI 自动生题 | 文档生题 / 题库拆题 | - |
| 智能组卷 | 按题型/难度/知识点组卷 | 试卷答题 |
| 知识点管理 | 树形管理 | 树形浏览 + 练习 |
| 文件管理 | 上传/预览 (PDF/Word/文本) | 文档预览 |
| 批改评分 | AI 简答评分 | 自动批改 |
| 学习统计 | - | 正确率 / 连续天数 / 错题本 |
| 权限管理 | 多角色 / 按钮级权限 | - |
| 用户管理 | 激活/禁用/重置密码 | 登录/注册/微信登录 |

## AI 生题模式

系统支持三种 AI 生题模式：

1. **整篇模式** — 整篇文档输入 AI，一次性生成全部题目。适合篇幅较短的内容。
2. **逐页模式** — 按页分割文档，逐页生题，支持跨页知识点合并。适合长篇教材。
3. **提取模式** — 从已有试卷中按结构化格式提取题目。适合导入现成试卷。

生题任务通过 WebSocket 实时推送进度，管理后台可监控、重试、中断。