8.5 KiB
8.5 KiB
公考助手（前后端分离 + Docker 一键运行）
本项目基于 readme.md 中的 PRD 实现了可运行的全栈版本：
- 前端：React + Vite + Nginx
- 后端：FastAPI + SQLAlchemy
- 数据库：PostgreSQL
目录结构
.
├── backend
│ ├── app
│ ├── Dockerfile
│ └── requirements.txt
├── frontend
│ ├── src
│ ├── Dockerfile
│ └── nginx.conf
└── docker-compose.yml
一键启动
确保本机已安装 Docker Desktop，然后在项目根目录执行：
docker compose up --build
或使用快速启动脚本：
./start.sh
启动后访问：
已实现功能（PRD 对齐版）
- 资源汇总：链接/文件导入、搜索、筛选、排序、编辑、删除、批量分类/删除、资源打开
- 错题整理：图片上传、分类与关键词检索、按频次排序、编辑、删除、导出 PDF/Word、训练检索
- 过程管理：模考分数新增/编辑/删除、近 7/30 天筛选、自定义时间筛选、折线图与统计
- AI 模块（千问）：错题智能解析、学习计划自动生成
- 数据持久化：PostgreSQL 卷持久化（
postgres_data）
AI 配置（千问）
- 复制配置模板：
cp .env.example .env
- 编辑
.env，填入你的QWEN_API_KEY - 重新启动服务：
./start.sh
千问接口采用 OpenAI 兼容模式，默认
QWEN_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1，模型qwen-plus。
常用命令
# 后台运行
docker compose up -d --build
# 停止并删除容器
docker compose down
# 停止并删除容器 + 数据卷
docker compose down -v
后续可扩展
- 鉴权登录（手机号注册登录）
- 文件上传（MinIO / OSS）与预览
- 错题导出 PDF/Word
- 分数筛选（近 7 天 / 近 30 天 / 自定义） 公考助手PRD 一、文档基础信息 产品名称：公考助手（网页版） 文档版本：V1.0.0 适用终端：PC 网页端（Chrome/Edge/Firefox 主流浏览器） 核心定位：一站式公考学习资源管理、错题归集、学习进度可视化工具 目标用户：公职类考试备考人群 二、版本修订记录 版本号 日期 修改内容 修改人 V1.0.0 2026-03-22 完整覆盖资源汇总、错题整理、过程管理三大模块 吴美晨 三、产品目标 统一管理备考多形态资源，解决资源分散、查找低效问题 标准化错题归集与复盘，支持导出训练，提升错题利用率 模考分数可视化追踪，直观呈现学习效果，辅助备考决策 四、全局规则 分类体系：固定五大分类 ——常识、数量关系、言语理解、判断推理、资料分析，支持用户自定义子标签 账号体系：网页端支持手机号注册 / 登录，数据云端同步，单用户独立存储空间 文件约束：单文件≤50MB，支持断点续传，上传失败自动重试 交互规范：所有操作实时反馈（成功 / 失败 / 加载中），删除操作二次确认 五、核心功能模块（详细需求） 模块 1：资源汇总 1.1 功能概述 支持多类型资源导入、分类标记、整合检索，实现备考资源统一管理。 1.2 资源导入类型 P0 1.2.1 链接类资源 支持导入：网站链接、云盘链接、公众号链接、小程序链接 录入方式：输入框粘贴链接 + 自定义标题 + 选择分类 + 添加标签，提交后生成资源卡片 展示字段：资源标题、链接地址、分类、标签、创建时间、操作栏（编辑 / 删除 / 打开） 1.2.2 文件类资源 支持格式：PDF、Word（doc/docx）、图片（JPG/PNG/Webp） 上传方式：点击上传 / 拖拽上传，支持批量上传 处理规则： 图片：生成缩略图，支持在线预览 文档：支持在线预览（PDF）、下载，Word 转网页预览 云端存储，不占用本地空间 1.3 分类与标记 P0 必选：五大核心分类（常识 / 数量 / 言语 / 判断 / 资料分析） 可选：自定义标签（如 “高频考点”“基础知识点”“刷题资料”） 筛选能力：按分类、标签、资源类型、创建时间筛选 排序能力：按创建时间、文件大小、名称排序 1.4 资源管理操作 P1 编辑：修改标题、分类、标签 删除：二次确认，删除后云端同步清除 检索：全局搜索资源标题 / 标签 / 链接关键词 批量操作：批量分类、批量删除、批量打标签 1.5 前端页面结构 P1 顶部：搜索框、批量操作按钮 左侧：分类导航栏、标签筛选栏 主体：资源卡片列表 / 列表视图切换 弹窗：资源导入弹窗、编辑弹窗 模块 2：错题整理 2.1 功能概述 支持拍照 / 上传错题、添加知识点备注、分类归集、导出打印，服务错题反复训练。 2.2 错题录入 拍照上传：网页端调用摄像头拍照，支持多题连拍 P1，可以不做 图片上传：本地相册 / 截图上传，支持裁剪、旋转 基础信息：错题图片 + 分类（必选，枚举值：常识、言语、数量、判断、资料、科学、其他）+ 知识点备注（可选）+ 难度标签（可选，枚举值：易、中、难） 备注规则：支持文本输入，最多 500 字，记录考点、错误原因、解题思路 2.3 错题分类与管理 分类：同五大核心分类，支持按分类查看错题集 排序：按录入时间、错误频次、知识点筛选 编辑：修改备注、更换分类、替换图片 删除：单题删除 / 批量删除，二次确认 2.4 错题导出 导出格式：PDF（带图片 + 备注）、Word（可编辑） 导出范围：按分类导出、按时间导出、全量导出 导出样式：标题 + 错题图片 + 知识点备注 + 留白答题区 功能约束：单次最多导出 200 题，导出后浏览器自动下载 2.5 错题训练模式 预览模式：按分类浏览错题，隐藏答案 / 备注 检索模式：按知识点关键词检索错题 模块 3：过程管理 3.1 功能概述 记录模考分数，自动生成折线图，可视化展示分数变化趋势。 3.2 模考分数录入 录入字段：考试名称（如 “2026 省考模考 1”）、考试时间、总分（0-200 分）、各模块分数（可选） 校验规则：总分≤200，非空校验，时间不可选未来日期 编辑 / 删除：支持修改分数、删除记录，数据实时更新图表 3.3 数据可视化 图表类型：折线图（X 轴：时间，Y 轴：分数） 展示信息：分数节点标注、趋势线、最高分 / 最低分 / 平均分标注 交互：鼠标悬浮显示单次考试详情（名称、分数、时间） 筛选：按时间范围（近 7 天 / 近 30 天 / 自定义区间）筛选数据 3.4 数据统计 统计项：最高分数、最低分数、平均分数、提升分数（末次 - 首次） 展示位置：图表下方，数据实时计算 六、非功能性需求 P2 6.1 性能需求 页面加载：首屏≤3s，功能切换≤1s 上传速度：10MB 文件≤10s（带宽正常） 并发：单用户操作无延迟，支持 1000 + 用户同时在线 6.2 兼容性需求 浏览器：Chrome≥90、Edge≥90、Firefox≥88、Safari≥14 分辨率：1920×1080、1366×768、2560×1440 自适应 6.3 存储与安全 存储：单用户资源 + 错题≤5GB，云端自动备份 安全：用户数据加密，上传内容合规检测，防止恶意文件 6.4 体验需求 无复杂操作，3 步内完成核心功能（上传 / 分类 / 导出） 错误提示清晰，引导用户修正操作 支持键盘快捷键（搜索 Ctrl+F、批量 Ctrl+A） 七、业务流程 7.1 资源上传流程 点击导入→选择类型（链接 / 文件）→填写信息→选择分类→提交→存储成功→列表展示 7.2 错题上传流程 点击添加错题→拍照 / 上传图片→裁剪编辑→填写备注→选择分类→保存→错题集展示 7.3 模考分数录入流程 点击添加记录→填写信息→提交→图表自动更新→统计数据刷新 八、验收标准 资源导入：支持所有指定类型，分类筛选准确，预览 / 下载正常 错题功能：拍照上传稳定，备注可编辑，导出 PDF/Word 无乱码、格式规范 过程管理：分数录入无误，折线图实时渲染，数据统计准确 兼容性：主流浏览器无样式错乱、功能异常 性能：大文件上传、批量操作无卡顿，响应时间符合要求 九、后续迭代规划（V2.0） 新增 AI 错题解析、自动归类 新增学习计划制定、打卡提醒 支持资源分享、错题协作 移动端 H5 适配 数据导出 Excel、多维度统计报表