WiseGrade（智评）交接说明

更新日期：2026-09-25。先阅读技术规格和部署与使用指南；本文件记录当前实现、验证边界和接手后的优先事项。

当前状态

已实现《自动化专业综合实践》的教师端闭环：课程与规则版本、挂载目录扫描和导入、文档解析、课程及项目知识库、独立评分批次、逐项复核、Excel 成绩表和逐生 PDF 反馈。
前端为 React/TypeScript/Vite/Ant Design；后端为 FastAPI/SQLAlchemy；PostgreSQL + pgvector 存储数据，Redis + RQ 执行评分任务，Nginx 提供前端并代理 /api。
本机 Compose 预览使用 127.0.0.1:18080，因为 8080 已被占用；仓库默认端口仍为 8080。本机 .env 已生成随机加密密钥并填入 DeepSeek API Key，但不在 Git 中。
已执行数据库迁移 0002，初始课程及其版本已写入 PostgreSQL。本机已从 docs/ 示例报告导入 1 个验收项目；汇报 PPTX 由示例报告内容生成，并非学生原始 PPT。
docs/阶段报告3.pdf 已纳入示例材料和端到端测试。
本机已下载 BGE-M3 到 models/bge-m3/，固定 Hugging Face 修订版 5617a9f61b028005a4858fdac845db406aefb181；模型目录不提交到 Git。
本机已下载 PP-OCRv5 mobile 检测与中文识别模型到 models/ocr/；下载与解压命令见部署指南。

代码入口与数据流

位置	作用
`compose.yaml`、`.env.example`	五个容器及环境变量；原件目录以只读方式挂载到 `/data/inbox`
`backend/wisegrade/main.py`、`api.py`	FastAPI 启动、初始化课程、教师端 API
`backend/wisegrade/models.py`、`migrations/`、`seed.py`	数据模型、Alembic 迁移、初始课程和规则
`backend/wisegrade/storage.py`、`parsing.py`	相对路径安全检查、目录识别、文件哈希、PDF/DOCX/PPTX 解析与页面资产
`backend/wisegrade/rag.py`、`llm.py`、`scoring.py`	本地嵌入与混合检索、DeepSeek 适配、批次评分
`backend/wisegrade/settings_store.py`、`exports.py`	API Key 加密保存、Excel/PDF 导出
`frontend/src/App.tsx`、`frontend/src/api.ts`	教师端页面及 API 调用
`backend/tests/`	路径、规则、版本、解析、模型输出、复核、导出及示例材料流程测试

教师选择 /data/inbox 下的相对目录后，后端扫描 学号_姓名_选题题目 子目录；教师确认材料类型后保存路径、大小、时间和 SHA-256。解析结果与页面图像进入 data/processed/，知识片段进入 PostgreSQL。评分时复制课程、规则和模型配置快照到独立批次，由 RQ worker 处理。模型原始评分、证据和教师修改记录分别保留；导出文件写入 data/exports/。原件不经过浏览器上传。

启动与检查

首次部署复制 .env.example 为 .env，设置学生目录 WISEGRADE_DATA_DIR、随机 WISEGRADE_SECRET_KEY、DeepSeek 地址及密钥，并把离线 BGE-M3 模型放在 models/bge-m3/。扫描版 PDF 另需 models/ocr/detection/ 和 models/ocr/recognition/。模型目录和 .env 均不提交到 Git。详情及 Windows 路径写法见部署指南。

docker compose up --build -d
docker compose ps -a
curl http://127.0.0.1:18080/api/health

上面的 curl 使用本机当前端口；其他环境应改为 .env 中的 WISEGRADE_WEB_PORT（默认 8080）。本机预览地址为 http://127.0.0.1:18080。api 启动时自动运行 Alembic 迁移。排障先看 docker compose logs api worker web。

Python 开发统一使用 uv：

cd backend
uv sync --extra ocr --group dev
uv run pytest -q

前端构建：cd frontend && npm ci && npm run build。宿主机缺少 LibreOffice 时，DOCX/PPTX 渲染测试会跳过；生产容器镜像已包含 LibreOffice。

已验证与尚未验证

最终后端测试：18 通过、1 跳过；跳过项是宿主机 LibreOffice 缺失。容器内 LibreOffice 25.2.3.2 已实际转换课程 DOCX 和验收 PPTX，页数、文字及页面图片均正常。
前端生产构建通过；Compose 的 PostgreSQL、Redis、API、worker、Web 当前均已启动，首页、深链接、/api/health、课程及仪表盘 API 返回正常。数据库版本为 0002；全新 SQLite 数据库迁移至 0002 也已验证。
RQ worker 曾在空闲期间因 Redis 连接超时退出，日志显示正常退出码 0；已在 compose.yaml 设置 restart: unless-stopped 并重新启动。接手后应观察是否反复超时。
使用 docs/ 的四份示例报告及生成的汇报 PPTX，经目录扫描、确认、课程资料入库、真实 BGE-M3/pgvector 检索和真实 DeepSeek API 完成批次 3：22/22 项成功。首轮有 1 项引文不匹配，重试后成功；保留了成功项。项目索引重建后有 316 段、平均 506 字，向量均为 1024 维；77 条评分证据均能匹配对应文档页的原文和页面图片。
对批次 3 完成教师复核和修改历史验证；Excel 成绩表及 11 页 PDF 反馈均可下载且可解析，文件位于 data/exports/。批次 2 保留为首次真实运行的对照记录（16 项成功、6 项证据不匹配）。
将 docs/阶段报告1.pdf 的一页栅格化为无文本层 PDF 后，离线 PaddleOCR 提取 496 字，识别到目录和章节标题。真实扫描仪产生的不同质量扫描件尚未实测。Windows Docker Desktop 尚未在 Windows 机器上实测。

接手后优先完成

使用独立提供、已脱敏的学生目录再次验收五类原始材料，尤其是学生原始 PPTX 和真实扫描仪 PDF；当前验收使用仓库示例报告与生成材料。
在目标 Windows Docker Desktop 环境验证目录挂载、模型路径和完整启动。
持续查看 worker 日志；若 Redis 空闲超时重复出现，再定位 Docker 后端休眠或网络原因。不要仅凭容器显示“已启动”判断评分任务可用。

当前代码位于 main 分支，阶段提交使用 Conventional Commits。交接前工作区应保持干净；.env、models/、data/、缓存和构建产物由 .gitignore 排除。

6.1 KiB Raw Blame History Unescape Escape