# QQuiz Execution Plan

更新时间：2026-04-17

## 目标

把当前项目推进到可以持续开发和稳定验收的状态，重点落实：

1. 默认 SQLite，兼容 MySQL
2. 前端界面简洁、可直接操作、少说明文字
3. 用户管理达到可上市产品的基础要求
4. push 后 GitHub 自动构建镜像
5. 逐步完成旧 Vite 前端到新 Next 前端的替换

## 已完成的代码级工作

- 默认 Docker 拓扑已切到 SQLite
- MySQL 兼容拓扑已拆到 `docker-compose.mysql.yml`
- 新前端容器已接入并替换 Docker 默认前端
- 管理员用户管理已经接入真实接口
- 管理员设置页已经接入真实配置接口
- 侧边栏选中态 bug 已修复
- 新前端色彩已收敛为更简洁的产品风格

## 当前代码扫描后的主要问题

### 后端

1. 数据库迁移体系仍然不完整
2. `LLMService` 仍存在启动期副作用
3. 文档解析任务仍依赖进程内后台任务
4. 题库导入并发与去重约束还没彻底补完
5. 管理模块还缺用户状态、审计、批量能力

### 前端

1. Exam detail / Question / Mistake / Quiz 仍是占位或半占位页面
2. 部分页面仍有旧迁移骨架内容，需要继续清理
3. 确认类交互还没统一替换为更正式的对话框方案
4. 视觉层还需要统一列表、表单、状态、分页组件

### 部署与文档

1. Compose 仍缺 dev/prod 分离
2. 文档体系仍需把运行方式统一到 SQLite 默认 + MySQL 兼容
3. CI 只有主干镜像构建，还缺 PR 验证与 smoke test

## 后续执行顺序

### 第一阶段：后端稳定性

1. Alembic 基线迁移
2. 去掉 `create_all` 正式职责
3. 去掉 LLM import side effect
4. 统一事务边界
5. 补用户状态字段与审计日志模型

### 第二阶段：前端业务页

1. 接通 `exams/[examId]`
2. 接通 `questions`
3. 接通 `mistakes`
4. 接通 `quiz/[examId]`
5. 接通 `mistake-quiz`

### 第三阶段：用户管理产品化

1. 用户状态管理
2. 审计日志
3. 批量操作
4. 更完整的密码与安全策略

### 第四阶段：工程化

1. Compose dev/prod 分离
2. PR workflow
3. SQLite/MySQL 双栈 smoke
4. 文档统一

## 前端视觉要求

1. 主色：深蓝，作为动作与选中态
2. 背景：浅灰蓝，不用大面积高饱和装饰
3. 卡片：白底、细边框、轻阴影
4. 状态色：成功绿、警告橙、错误红
5. 页面信息结构：标题、数据、动作优先，减少解释文字