66 lines
5.3 KiB
Markdown
66 lines
5.3 KiB
Markdown
# WiseGrade（智评）交接说明
|
||
|
||
更新日期：2026-09-25。先阅读 [技术规格](docs/WISEGRADE_TECHNICAL_SPEC.md) 和 [部署与使用指南](docs/DEPLOYMENT.md)；本文件记录当前实现、验证边界和接手后的优先事项。
|
||
|
||
## 当前状态
|
||
|
||
- 已实现《自动化专业综合实践》的教师端闭环：课程与规则版本、挂载目录扫描和导入、文档解析、课程及项目知识库、独立评分批次、逐项复核、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 路径写法见 [部署指南](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。
|
||
|
||
## 已验证与尚未验证
|
||
|
||
- 最终后端测试：**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 机器上实测。
|
||
|
||
## 接手后优先完成
|
||
|
||
1. 放入离线 BGE-M3 模型，配置 DeepSeek 密钥和可处理图像的 `deepseek-flash` 兼容端点；有扫描版 PDF 时再放入离线 OCR 模型。重启服务并确认模型设置页。
|
||
2. 用一套脱敏的学生目录执行真实流程：扫描和确认、课程知识库入库、创建并运行评分批次、核对每项证据与页码、教师修改、导出 Excel 和 PDF。尤其检查真实模型 JSON、页面图像和批次失败重试。
|
||
3. 在目标 Windows Docker Desktop 环境验证目录挂载、模型路径和完整启动。
|
||
4. 持续查看 worker 日志；若 Redis 超时重复出现，再定位 Docker/WSL 休眠或网络原因。不要仅凭容器显示“已启动”判断评分任务可用。
|
||
|
||
当前代码位于 `main` 分支，阶段提交使用 Conventional Commits。交接前工作区应保持干净；`.env`、`models/`、`data/`、缓存和构建产物由 `.gitignore` 排除。
|