226 lines
9.6 KiB
Markdown
226 lines
9.6 KiB
Markdown
# 公考助手（前后端分离 + Docker 一键运行）
|
||
|
||
本项目基于 `readme.md` 中的 PRD 实现了可运行的全栈版本：
|
||
- 前端：React + Vite + Nginx
|
||
- 后端：FastAPI + SQLAlchemy
|
||
- 数据库：PostgreSQL
|
||
|
||
## 目录结构
|
||
|
||
```text
|
||
.
|
||
├── backend
|
||
│ ├── app
|
||
│ ├── Dockerfile
|
||
│ └── requirements.txt
|
||
├── frontend
|
||
│ ├── src
|
||
│ ├── Dockerfile
|
||
│ └── nginx.conf
|
||
└── docker-compose.yml
|
||
```
|
||
|
||
## 国内镜像加速（部署）
|
||
|
||
- **容器基础镜像（Docker Hub）**：`docker-compose.yml` 与各 `Dockerfile` 使用官方镜像名（如 `python:3.12-slim`）。在国内拉取前，请在 **阿里云控制台 → 容器镜像服务 ACR → 镜像工具 → 镜像加速器** 获取你的加速器地址，并在 Docker Desktop → Settings → Docker Engine 中配置 `registry-mirrors`，例如：
|
||
|
||
```json
|
||
{
|
||
"registry-mirrors": [
|
||
"https://<你的加速器ID>.mirror.aliyuncs.com"
|
||
]
|
||
}
|
||
```
|
||
|
||
保存并重启 Docker 后生效。
|
||
|
||
- **Python / npm / apk**：构建时已分别使用 **阿里云 PyPI**（`mirrors.aliyun.com/pypi`）、**npmmirror**（阿里云镜像站指定的 npm 同步源）、**阿里云 Alpine** 源（见各 `Dockerfile`）。
|
||
|
||
## 一键启动
|
||
|
||
确保本机已安装 Docker Desktop，然后在项目根目录执行：
|
||
|
||
```bash
|
||
docker compose up --build
|
||
```
|
||
|
||
或使用快速启动脚本：
|
||
|
||
```bash
|
||
./start.sh
|
||
```
|
||
|
||
启动后访问：
|
||
- 前端：http://localhost:5173
|
||
- 后端健康检查：http://localhost:8001/health
|
||
|
||
## 已实现功能（PRD 对齐版）
|
||
|
||
- 资源汇总：链接/文件导入、搜索、筛选、排序、编辑、删除、批量分类/删除、资源打开
|
||
- 错题整理：图片上传、分类与关键词检索、按频次排序、编辑、删除、导出 PDF/Word、训练检索
|
||
- 过程管理：模考分数新增/编辑/删除、近 7/30 天筛选、自定义时间筛选、折线图与统计
|
||
- AI 模块（千问）：错题智能解析、学习计划自动生成
|
||
- 数据持久化：PostgreSQL 卷持久化（`postgres_data`）
|
||
|
||
## AI 配置（千问）
|
||
|
||
`docker-compose.yml` 会从 **`.env.example`** 注入 `QWEN_*` 环境变量；若项目根目录存在 **`.env`**，其中同名变量会**覆盖** `.env.example`。
|
||
|
||
1. 任选其一：
|
||
- 直接编辑 `.env.example`，填入 `QWEN_API_KEY`；或
|
||
- `cp .env.example .env` 后只编辑 `.env`（推荐，避免把密钥提交进仓库）
|
||
2. 重新启动服务：
|
||
|
||
```bash
|
||
./start.sh
|
||
```
|
||
|
||
> 千问接口采用 OpenAI 兼容模式，默认 `QWEN_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1`，模型可在 `.env.example` / `.env` 中通过 `QWEN_MODEL` 配置。
|
||
|
||
## 常用命令
|
||
|
||
```bash
|
||
# 后台运行
|
||
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、多维度统计报表
|
||
|