79 lines
9.4 KiB
Markdown
79 lines
9.4 KiB
Markdown
# WiseGrade（智评）交接说明
|
||
|
||
更新日期：2026-09-26。先阅读 [技术规格](docs/WISEGRADE_TECHNICAL_SPEC.md)、[对话页面与业务 Agent](docs/CHAT_AGENT.md) 和 [部署与使用指南](docs/DEPLOYMENT.md)；本文件记录当前实现、验证边界和接手后的优先事项。
|
||
|
||
## 当前状态
|
||
|
||
- 已实现《自动化专业综合实践》的教师端闭环：课程与规则版本、挂载目录扫描和导入、文档解析、课程及项目知识库、独立评分批次、逐项复核、Excel 成绩表和逐生 PDF 反馈。
|
||
- 当前源码新增默认“对话”页面、持久多轮会话、固定类型工具白名单、DeepSeek 原生工具调用、教师确认卡片、导入后自动索引任务和批次固定项目清单。旧页面继续可用。模型不能确认操作；会话、运行和待确认操作由迁移 `0003` 持久化。
|
||
- 前端为 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 导出 |
|
||
| `backend/wisegrade/services.py`、`indexing.py` | REST 与 Agent 共用导入、入库、建批、复核服务；持久后台索引任务 |
|
||
| `backend/wisegrade/agent_tools.py`、`actions.py`、`chat_api.py` | 类型化工具注册、确认边界、会话与 SSE 编排 |
|
||
| `frontend/src/App.tsx`、`frontend/src/api.ts` | 教师端页面及 API 调用 |
|
||
| `frontend/src/Chat.tsx` | 会话恢复、引用、进度和确认卡片 |
|
||
| `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 路径写法见 [部署指南](docs/DEPLOYMENT.md)。
|
||
|
||
```bash
|
||
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`：
|
||
|
||
```bash
|
||
cd backend
|
||
uv sync --extra ocr --group dev
|
||
uv run pytest -q
|
||
```
|
||
|
||
前端构建：`cd frontend && npm ci && npm run build`。宿主机缺少 LibreOffice 时，DOCX/PPTX 渲染测试会跳过；生产容器镜像已包含 LibreOffice。
|
||
|
||
## 已验证与尚未验证
|
||
|
||
- 部署镜像内完整后端测试：**19 通过、0 跳过**，包括 DOCX/PPTX 转换与页面图像测试。宿主机运行结果为 18 通过、1 跳过，因为宿主机未安装 LibreOffice；部署容器内为 25.2.3.2。另已用课程 DOCX 和验收 PPTX 实际验证页数、文字及页面图片。
|
||
- 2026-09-25：后端测试已改用独立 PostgreSQL + pgvector，并通过真实 DeepSeek 和本地 BGE-M3 模型测试。19 个其他测试通过；使用课程示例材料的完整流程单独重跑通过，22 个评分项全部完成，教师复核和导出检查通过。测试命令见 `docs/DEPLOYMENT.md`。
|
||
- 前端生产构建通过；Compose 的 PostgreSQL、Redis、API、worker、Web 当前均已启动，首页、深链接、`/api/health`、课程及仪表盘 API 返回正常。数据库版本为 `0002`；全新 SQLite 数据库迁移至 `0002` 也已验证。
|
||
- 2026-09-26 当前源码：宿主机独立 PostgreSQL 测试执行 `uv run pytest -q -m 'not integration'`，**24 通过、1 跳过、2 个真实集成测试未运行**；使用既有测试镜像加只读源码挂载执行 Compose 同组测试，**25 通过、2 个真实集成测试未运行**。单独构造旧版 `0002` 表结构，在临时 PostgreSQL 数据库升级 `0003` 通过；新数据库迁移也由测试覆盖。前端 `npm run build` 和新 Nginx 配置 `nginx -t` 通过。
|
||
- 2026-09-26 最小真实 DeepSeek `tool_calls` 兼容性探针通过，完整工具白名单也返回 `list_courses` 原生调用；该端点拒绝 `tool_choice="required"`，适配层已使用 `auto` 并校验返回的工具调用。未在该探针发送学生原件。
|
||
- 完整 Compose 测试首次运行 **25 通过、1 失败**：真实模型证据匹配导致示例流程首轮批次 `partial`。测试改为按既有重试规则继续未完成项后，单独重跑示例流程 **1 通过**（11 分 48 秒）；成功项和教师复核结果由生产评分代码保留。此次未重新运行一次完整的所有测试组合，不应把第一次完整命令写成全部通过。
|
||
- 测试 Compose 现增设独立 `test-redis`，与业务队列隔离。隔离前完整测试曾把 5 个测试索引作业送入业务 Redis；旧业务 worker 因缺少新模块执行失败，未写入业务数据库，测试作业已从业务 Redis 失败队列和作业键清理。
|
||
- 当前运行中的 Compose 业务镜像仍是上一版代码，数据库仍为 `0002`；本次源码尚未重建并部署到业务容器。上述 Compose 测试使用独立 `test-db`、独立 `test-redis` 和只读源码挂载。
|
||
- `docker compose --profile test run --build --rm test pytest -q -m 'not integration'` 曾启动镜像重建，但 Debian 软件源下载 LibreOffice 依赖在约 24 分钟后仍未完成，故中止；随后用已有测试镜像加最新源码只读挂载执行相同测试。尚未在浏览器中实际点击新对话主页、刷新恢复、确认卡片及深链接；目前这些路径由代码检查、后端 API 测试和前端 TypeScript／生产构建覆盖。重新部署业务容器及浏览器实机验收仍需完成。
|
||
- 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 机器上实测。
|
||
|
||
## 接手后优先完成
|
||
|
||
1. 使用独立提供、已脱敏的学生目录再次验收五类原始材料，尤其是学生原始 PPTX 和真实扫描仪 PDF；当前验收使用仓库示例报告与生成材料。
|
||
2. 在目标 Windows Docker Desktop 环境验证目录挂载、模型路径和完整启动。
|
||
3. 持续查看 worker 日志；若 Redis 空闲超时重复出现，再定位 Docker 后端休眠或网络原因。不要仅凭容器显示“已启动”判断评分任务可用。
|
||
|
||
当前代码位于 `main` 分支，阶段提交使用 Conventional Commits。交接前工作区应保持干净；`.env`、`models/`、`data/`、缓存和构建产物由 `.gitignore` 排除。
|