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 已生成随机加密密钥，但不在 Git 中。
已执行数据库迁移 0001，初始课程及其版本已写入 PostgreSQL。当前未导入学生项目。
docs/阶段报告3.pdf 已纳入示例材料和端到端测试。

代码入口与数据流

位置	作用
`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。

已验证与尚未验证

最终后端测试：15 通过、1 跳过；跳过项是宿主机 LibreOffice 缺失。容器内另行验证了 DOCX/PPTX 渲染。
前端生产构建通过；Compose 的 PostgreSQL、Redis、API、worker、Web 当前均已启动，首页、深链接、/api/health、课程及仪表盘 API 返回正常。数据库版本为 0001。
RQ worker 曾在空闲期间因 Redis 连接超时退出，日志显示正常退出码 0；已在 compose.yaml 设置 restart: unless-stopped 并重新启动。接手后应观察是否反复超时。
当前未提供真实 BGE-M3/OCR 权重和 DeepSeek API Key。测试对外部模型使用 mock；尚未验证真实模型请求、真实嵌入检索与扫描 PDF OCR。模型缺失时系统可启动和导入，但知识库入库或评分会给出错误。
Windows Docker Desktop 的步骤已写入部署指南，尚未在 Windows 机器上实测。

接手后优先完成

放入离线 BGE-M3 模型，配置 DeepSeek 密钥和可处理图像的 deepseek-flash 兼容端点；有扫描版 PDF 时再放入离线 OCR 模型。重启服务并确认模型设置页。
用一套脱敏的学生目录执行真实流程：扫描和确认、课程知识库入库、创建并运行评分批次、核对每项证据与页码、教师修改、导出 Excel 和 PDF。尤其检查真实模型 JSON、页面图像和批次失败重试。
在目标 Windows Docker Desktop 环境验证目录挂载、模型路径和完整启动。
持续查看 worker 日志；若 Redis 超时重复出现，再定位 Docker/WSL 休眠或网络原因。不要仅凭容器显示“已启动”判断评分任务可用。

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

5.3 KiB Raw Blame History Unescape Escape