QQuiz/docs/PLAN.md

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. 页面信息结构：标题、数据、动作优先，减少解释文字