932 lines
20 KiB
Markdown
932 lines
20 KiB
Markdown
# WiseGrade（智评）技术方案与开发规格
|
||
|
||
> 2026-09-26 增量实现：默认“对话”页面、应用内固定工具 Agent、持久会话、待确认操作、自动索引任务和批次固定项目清单。具体状态机、API 与恢复流程见 [对话页面与业务 Agent](CHAT_AGENT.md)。旧版正文的阶段计划按原始系统设计编写，新增业务边界以该增量文档及当前代码为准。
|
||
|
||
## 1. 项目概述
|
||
|
||
### 1.1 基本信息
|
||
|
||
- 英文名：**WiseGrade**
|
||
- 中文名：**智评**
|
||
- 当前服务课程：**自动化专业综合实践**
|
||
- 使用对象：教师
|
||
- 部署形态：个人电脑本地部署
|
||
- 当前开发环境：Linux
|
||
- 目标运行环境：Linux、Windows（Docker Desktop）
|
||
- 主要大模型：`deepseek-flash`
|
||
- 主要能力：课程材料管理、学生材料批量导入、RAG 辅助评分、教师复核、成绩和反馈导出
|
||
|
||
### 1.2 项目目标
|
||
|
||
构建一个前后端分离的自动评分系统，对自动化专业综合实践课程中的以下材料进行内容评分：
|
||
|
||
1. 阶段报告 1
|
||
2. 阶段报告 2
|
||
3. 阶段报告 3
|
||
4. 最终报告
|
||
5. 汇报 PPT，或 PPT 导出的 PDF
|
||
|
||
系统输出可复核的逐项评分、原文证据、页码或幻灯片编号、缺失内容、评语和改进建议。
|
||
|
||
### 1.3 非目标
|
||
|
||
第一版不实现：
|
||
|
||
- 学生账号和在线提交
|
||
- 现场口头答辩、答辩视频和语音评分
|
||
- 学生个人贡献度自动识别
|
||
- 代码仓库自动审查
|
||
- AI 生成内容检测
|
||
- 自动控制实验硬件的远程接入
|
||
|
||
课程评分表中的“汇报答辩 40 分”保留原名称，但本系统只依据 PPT 内容或 PPT PDF 内容评分，不评价现场口头答辩。
|
||
|
||
## 2. 已确定的业务规则
|
||
|
||
### 2.1 教师使用流程
|
||
|
||
系统只供教师使用，采用单机单管理员模式。教师不需要创建学生账号。
|
||
|
||
教师流程：
|
||
|
||
```text
|
||
选择课程和学期
|
||
-> 选择评分规则版本
|
||
-> 选择挂载数据目录中的学生总文件夹
|
||
-> 扫描学生子文件夹
|
||
-> 自动识别学生信息和五类材料
|
||
-> 教师确认导入结果
|
||
-> 批量解析和评分
|
||
-> 查看模型评分和证据
|
||
-> 修改分数和评语
|
||
-> 导出 Excel 成绩表和逐生 PDF 反馈
|
||
```
|
||
|
||
### 2.2 学生目录结构
|
||
|
||
宿主机数据目录示例：
|
||
|
||
```text
|
||
WiseGradeData/
|
||
└── 2026春季第1批/
|
||
├── 1023009006_李傲琦_基于ROS2系统的自瞄移动机器人/
|
||
│ ├── 阶段报告1.pdf
|
||
│ ├── 阶段报告2.pdf
|
||
│ ├── 阶段报告3.pdf
|
||
│ ├── 自动化专业综合实践报告.pdf
|
||
│ └── 汇报PPT.pptx
|
||
└── 其他学生/
|
||
```
|
||
|
||
学生目录命名格式：
|
||
|
||
```text
|
||
学号_姓名_选题题目
|
||
```
|
||
|
||
文件夹名称只用于初步识别。系统还要从文件首页、标题和正文中抽取姓名、学号、项目题目和选题方向，并在不一致时提醒教师确认。
|
||
|
||
### 2.3 支持文件
|
||
|
||
支持：
|
||
|
||
- PDF
|
||
- DOCX
|
||
- PPTX
|
||
- PPT 导出的 PDF
|
||
|
||
不支持旧版 `.doc` 作为学生输入。
|
||
|
||
PPT PDF 必须在导入确认阶段标记为“汇报材料”，以免与最终报告 PDF 混淆。
|
||
|
||
### 2.4 成绩结构
|
||
|
||
总评成绩：
|
||
|
||
```text
|
||
总评 = 阶段报告1 × 10%
|
||
+ 阶段报告2 × 10%
|
||
+ 阶段报告3 × 10%
|
||
+ 期末成绩 × 70%
|
||
```
|
||
|
||
期末评分保持课程评分表结构：
|
||
|
||
| 评分项 | 分值 |
|
||
|---|---:|
|
||
| 任务完成度 | 20 |
|
||
| 报告规范性 | 20 |
|
||
| 汇报答辩（系统仅按 PPT 内容评价） | 40 |
|
||
| 结果分析 | 20 |
|
||
|
||
### 2.5 评分批次
|
||
|
||
每次评分创建独立批次。批次之间不覆盖、不替代，也不设置唯一“正式批次”。每个批次均可查看、复核和导出。
|
||
|
||
批次必须保存：
|
||
|
||
- 课程版本
|
||
- 评分规则版本
|
||
- 课程目标版本
|
||
- `deepseek-flash` 模型配置快照
|
||
- 嵌入模型名称和版本
|
||
- 创建时间和结束时间
|
||
- 评分任务状态
|
||
|
||
## 3. 课程和评分依据
|
||
|
||
初始资料位于 `docs/`：
|
||
|
||
- `课程导学-自动化专业综合实践.pdf`
|
||
- `自动化专业综合实践三融合选题课程概述.pdf`
|
||
- `大作业评分表-自动化专业综合实践.docx`
|
||
- `阶段报告1模板.doc`
|
||
- `阶段报告2模板.doc`
|
||
- `阶段报告3模板.doc`
|
||
- `阶段报告1.pdf`
|
||
- `阶段报告2.pdf`
|
||
- `阶段报告3.pdf`
|
||
- `自动化专业综合实践报告.pdf`
|
||
|
||
### 3.1 课程目标和毕业要求指标点
|
||
|
||
系统初始知识库必须包含并建立关联：
|
||
|
||
- 课程目标 1：问题解决与研究能力
|
||
- 课程目标 2：知识运用与分析能力
|
||
- 课程目标 3：实验设计与操作能力
|
||
- 课程目标 4：数据处理与报告撰写能力
|
||
- 毕业要求指标点 2.3、2.4
|
||
- 毕业要求指标点 4.1、4.2、4.3、4.4
|
||
- 毕业要求指标点 11.1、11.2
|
||
|
||
### 3.2 阶段报告要求
|
||
|
||
#### 阶段报告 1：复杂自动化工程问题解决方案论证报告
|
||
|
||
重点内容：
|
||
|
||
- 文献调研和技术现状
|
||
- 复杂工程问题分析
|
||
- 主方案和至少一套替代方案
|
||
- 方案原理、适用场景和优劣对比
|
||
- 数理或工程依据下的可行性论证
|
||
- 进度计划、资源配置、成本构成和经济性分析
|
||
|
||
初始评分框架：
|
||
|
||
| 评分项 | 分值 |
|
||
|---|---:|
|
||
| 复杂工程问题和需求分析 | 25 |
|
||
| 文献调研和技术现状总结 | 20 |
|
||
| 主方案和替代方案设计 | 25 |
|
||
| 可行性、风险和合理性论证 | 15 |
|
||
| 工程管理、进度和成本分析 | 10 |
|
||
| 报告完整性和规范性 | 5 |
|
||
| 合计 | 100 |
|
||
|
||
#### 阶段报告 2：实验系统设计与硬件搭建方案
|
||
|
||
重点内容：
|
||
|
||
- 硬件选型清单、参数和依据
|
||
- 系统架构图、硬件连接或接口关系
|
||
- 分步骤实验计划、测试方法和预期指标
|
||
- 安全风险、防护措施和操作规范
|
||
|
||
初始评分框架：
|
||
|
||
| 评分项 | 分值 |
|
||
|---|---:|
|
||
| 系统架构和实现思路 | 20 |
|
||
| 硬件选型及选型依据 | 20 |
|
||
| 系统框图、连接关系和接口设计 | 20 |
|
||
| 实验方案、测试方法和预期指标 | 20 |
|
||
| 安全风险和防护措施 | 10 |
|
||
| 阶段进展及下一阶段计划 | 10 |
|
||
| 合计 | 100 |
|
||
|
||
#### 阶段报告 3：软件设计与系统调试报告
|
||
|
||
重点内容：
|
||
|
||
- 软件逻辑、流程图或状态图
|
||
- 核心代码片段和实现说明
|
||
- 调试过程、故障现象、原因和解决方法
|
||
- 实验数据整理和初步分析
|
||
- 系统功能、性能指标和存在问题
|
||
|
||
初始评分框架：
|
||
|
||
| 评分项 | 分值 |
|
||
|---|---:|
|
||
| 软件逻辑和系统实现 | 20 |
|
||
| 核心代码和功能说明 | 20 |
|
||
| 调试过程、问题分析和解决方法 | 20 |
|
||
| 实验数据和初步分析 | 20 |
|
||
| 功能和性能指标验证 | 15 |
|
||
| 下一阶段计划及报告规范性 | 5 |
|
||
| 合计 | 100 |
|
||
|
||
阶段评分框架必须作为可编辑的初始规则导入，不能写死在业务代码中。
|
||
|
||
## 4. 总体架构
|
||
|
||
```text
|
||
React 前端
|
||
|
|
||
FastAPI 后端
|
||
|-- 课程、版本和规则管理
|
||
|-- 挂载目录扫描和导入
|
||
|-- 文档解析和事实抽取
|
||
|-- RAG 检索
|
||
|-- 评分编排和批次管理
|
||
|-- 教师复核
|
||
|-- Excel/PDF 导出
|
||
|
|
||
PostgreSQL + pgvector
|
||
Redis + RQ
|
||
本地文件存储
|
||
本地 BGE-M3 嵌入模型
|
||
DeepSeek API（deepseek-flash）
|
||
```
|
||
|
||
采用模块化单体后端，不在第一版拆分成大量微服务。模块边界清晰，后续可以拆分。
|
||
|
||
### 4.1 推荐技术栈
|
||
|
||
- 前端：React、TypeScript、Vite、Ant Design
|
||
- 后端：Python、FastAPI、SQLAlchemy、Pydantic
|
||
- 数据库：PostgreSQL、pgvector
|
||
- 后台任务：Redis、RQ
|
||
- PDF 解析：PyMuPDF
|
||
- DOCX 解析：python-docx
|
||
- PPTX 解析：python-pptx
|
||
- 页面转换：LibreOffice headless
|
||
- OCR：PaddleOCR，扫描 PDF 时作为回退
|
||
- 本地嵌入：`BAAI/bge-m3`
|
||
- 模型调用：OpenAI 兼容客户端，统一模型名 `deepseek-flash`
|
||
- Excel：openpyxl 或 pandas
|
||
- PDF 反馈：HTML/CSS + WeasyPrint 或 Playwright
|
||
- 部署：Docker Compose
|
||
|
||
## 5. 宿主机目录挂载方案
|
||
|
||
原始学生材料不通过浏览器上传。前端只选择后端可见的挂载目录下的大文件夹，后端扫描和读取文件。
|
||
|
||
### 5.1 Docker 挂载
|
||
|
||
```yaml
|
||
volumes:
|
||
- ${WISEGRADE_DATA_DIR}:/data/inbox:ro
|
||
- ./data/processed:/data/processed
|
||
- ./data/exports:/data/exports
|
||
- ./models:/models:ro
|
||
```
|
||
|
||
Linux 示例：
|
||
|
||
```env
|
||
WISEGRADE_DATA_DIR=/home/teacher/WiseGradeData
|
||
```
|
||
|
||
Windows 示例：
|
||
|
||
```env
|
||
WISEGRADE_DATA_DIR=D:/WiseGradeData
|
||
```
|
||
|
||
Windows 使用 Docker Desktop 时，教师需要允许 Docker Desktop 访问对应磁盘。
|
||
|
||
### 5.2 路径安全
|
||
|
||
- 后端只允许访问 `/data/inbox`
|
||
- 前端只提交挂载目录内的相对路径
|
||
- 禁止提交绝对路径
|
||
- 后端必须执行路径规范化和越界检查
|
||
- 原始输入目录只读挂载
|
||
- 解析结果、任务状态和导出文件写入独立目录
|
||
|
||
### 5.3 文件变更检测
|
||
|
||
导入时保存：
|
||
|
||
- 相对路径
|
||
- 文件大小
|
||
- 修改时间
|
||
- SHA-256
|
||
- MIME 类型
|
||
- 解析状态
|
||
|
||
若文件哈希未变化，不重复解析和向量化。源文件变化时提示重新导入。
|
||
|
||
## 6. 文档解析和结构化
|
||
|
||
### 6.1 统一文档对象
|
||
|
||
每个文档解析为：
|
||
|
||
```json
|
||
{
|
||
"document_type": "stage1",
|
||
"source_path": "...",
|
||
"pages": [
|
||
{
|
||
"page_number": 1,
|
||
"text": "...",
|
||
"tables": [],
|
||
"images": [],
|
||
"rendered_image_path": "..."
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
必须保留页码、章节名、表格和图片关联。
|
||
|
||
### 6.2 文件识别
|
||
|
||
支持通过以下信号识别材料类型：
|
||
|
||
- 文件名关键词
|
||
- 文件扩展名
|
||
- 文档标题
|
||
- 首页文本
|
||
- 章节标题
|
||
- PPT 页数和标题
|
||
|
||
识别结果包括：
|
||
|
||
```text
|
||
确定
|
||
不确定
|
||
缺失
|
||
重复
|
||
无法解析
|
||
```
|
||
|
||
不确定的文件进入教师确认界面。
|
||
|
||
### 6.3 PPT/PDF 视觉处理
|
||
|
||
- 提取 PPT 原生文字、表格和备注
|
||
- 将每一页渲染为图片
|
||
- PDF 每页保存页面图像
|
||
- 评分相关页面连同文字一起发送给 `deepseek-flash`
|
||
- 图片证据必须关联页码或幻灯片编号
|
||
|
||
## 7. RAG 方案
|
||
|
||
### 7.1 知识库分层
|
||
|
||
#### 公共课程知识库
|
||
|
||
- 课程导学
|
||
- 课程目标
|
||
- 毕业要求指标点
|
||
- 评分表
|
||
- 三个阶段模板
|
||
- 各选题方向要求
|
||
- 优秀报告
|
||
- 课程版本资料
|
||
|
||
#### 学生项目知识库
|
||
|
||
每个学生独立命名空间：
|
||
|
||
```text
|
||
course_2026/project_1023009006/
|
||
stage1/
|
||
stage2/
|
||
stage3/
|
||
final_report/
|
||
presentation/
|
||
```
|
||
|
||
禁止评分时检索其他学生的材料。
|
||
|
||
### 7.2 文本切分
|
||
|
||
- 按标题和章节进行结构感知切分
|
||
- 普通文本块约 400～800 个中文字符
|
||
- 重叠约 80～120 个中文字符
|
||
- 表格单独保存
|
||
- 图片及图片说明单独保存
|
||
- 每块必须保留页码、章节、文档类型和评分指标关联
|
||
|
||
### 7.3 检索
|
||
|
||
采用混合检索：
|
||
|
||
```text
|
||
PostgreSQL 全文检索
|
||
+ pgvector 向量检索
|
||
+ 课程版本过滤
|
||
+ 学生项目过滤
|
||
+ 报告类型过滤
|
||
+ 阶段过滤
|
||
```
|
||
|
||
默认每个评分项取 8～12 个候选证据块，去重后送入模型。
|
||
|
||
### 7.4 嵌入模型
|
||
|
||
默认：
|
||
|
||
```text
|
||
BAAI/bge-m3
|
||
```
|
||
|
||
低配置电脑可配置：
|
||
|
||
```text
|
||
BAAI/bge-small-zh-v1.5
|
||
```
|
||
|
||
模型通过独立离线包提供，不在应用镜像中强制在线下载。配置中保存模型名称、版本和本地路径。
|
||
|
||
## 8. DeepSeek 接入
|
||
|
||
### 8.1 统一模型
|
||
|
||
只使用一个模型配置：
|
||
|
||
```yaml
|
||
provider: deepseek
|
||
base_url: https://api.deepseek.com
|
||
model: deepseek-flash
|
||
```
|
||
|
||
同一个模型负责：
|
||
|
||
- 文本理解
|
||
- 图像理解
|
||
- 事实抽取
|
||
- 评分
|
||
- 评语生成
|
||
- PPT 分析
|
||
- 跨文档一致性检查
|
||
|
||
### 8.2 密钥管理
|
||
|
||
教师可以在设置页面配置：
|
||
|
||
- API Key
|
||
- Base URL
|
||
- 模型名
|
||
- 并发数
|
||
- 超时时间
|
||
- 重试次数
|
||
|
||
安全要求：
|
||
|
||
- 前端不直接调用 DeepSeek
|
||
- API Key 只发送给后端
|
||
- 数据库保存加密后的密钥
|
||
- 日志禁止输出 API Key
|
||
- 支持环境变量初始化
|
||
|
||
### 8.3 发送数据范围
|
||
|
||
原始文件保存在本地。模型请求只发送当前评分项所需的：
|
||
|
||
- 文本证据块
|
||
- 表格内容
|
||
- 必要的页面图片
|
||
- 课程评分标准
|
||
- 已抽取的项目事实
|
||
|
||
不把全部报告无条件重复发送给每一个评分项。
|
||
|
||
## 9. 评分引擎
|
||
|
||
评分采用多阶段流程：
|
||
|
||
```text
|
||
文件导入
|
||
-> 文档解析
|
||
-> 项目事实抽取
|
||
-> 规则检查
|
||
-> 指标级 RAG 检索
|
||
-> 指标级评分
|
||
-> 跨文档一致性检查
|
||
-> 分数汇总
|
||
-> 教师复核
|
||
```
|
||
|
||
### 9.1 事实抽取
|
||
|
||
抽取：
|
||
|
||
- 学号、姓名、项目名称
|
||
- 选题方向
|
||
- 功能目标
|
||
- 性能指标
|
||
- 硬件型号
|
||
- 软件技术
|
||
- 实验方案
|
||
- 实验数据
|
||
- 进度计划
|
||
- 成本信息
|
||
- 结论和改进方向
|
||
|
||
### 9.2 评分输出
|
||
|
||
每个评分项必须返回结构化 JSON：
|
||
|
||
```json
|
||
{
|
||
"criterion_id": "stage1.solution_design",
|
||
"score": 17,
|
||
"max_score": 20,
|
||
"reason": "...",
|
||
"evidence": [
|
||
{
|
||
"document": "阶段报告1",
|
||
"page": 12,
|
||
"quote": "..."
|
||
}
|
||
],
|
||
"missing_evidence": ["..."],
|
||
"suggestion": "...",
|
||
"confidence": 0.84
|
||
}
|
||
```
|
||
|
||
模型不得对没有证据的内容自行假设。结构化输出必须经过 Pydantic 校验；失败时自动重试或进入人工处理。
|
||
|
||
### 9.3 跨文档一致性
|
||
|
||
至少检查：
|
||
|
||
- 阶段 1 计划是否在阶段 2、3 中落实
|
||
- 各报告中的项目名称、硬件型号和技术路线是否一致
|
||
- 实验数据是否前后一致
|
||
- 最终报告和 PPT 是否描述同一成果
|
||
- 指标是否存在明显夸大或矛盾
|
||
|
||
## 10. 规则配置和版本管理
|
||
|
||
规则不能写死在 Prompt 或 Python 代码中。
|
||
|
||
### 10.1 评分指标结构
|
||
|
||
```yaml
|
||
criterion_id: stage1.solution_feasibility
|
||
name: 方案合理性与可行性
|
||
max_score: 15
|
||
description: 评价方案是否具有工程依据、可实施性和风险分析
|
||
linked_outcomes: [2.3, 2.4, 4.1]
|
||
required_evidence:
|
||
- 主方案
|
||
- 替代方案
|
||
- 方案比较
|
||
- 风险分析
|
||
score_levels:
|
||
- min: 12
|
||
max: 15
|
||
description: 论证充分，方案比较清晰，风险分析具体
|
||
- min: 6
|
||
max: 11
|
||
description: 基本完成论证，但证据或分析不充分
|
||
- min: 0
|
||
max: 5
|
||
description: 缺少核心论证
|
||
```
|
||
|
||
### 10.2 版本要求
|
||
|
||
课程、课程目标、毕业要求、模板、评分规则和 Prompt 都需要版本号。评分批次保存完整版本快照。
|
||
|
||
教师修改规则后创建新版本，不覆盖历史版本。
|
||
|
||
## 11. 核心数据表
|
||
|
||
建议至少包含：
|
||
|
||
```text
|
||
courses
|
||
course_versions
|
||
course_objectives
|
||
graduation_indicators
|
||
topic_directions
|
||
rubric_versions
|
||
rubric_criteria
|
||
rubric_score_levels
|
||
knowledge_documents
|
||
knowledge_chunks
|
||
students
|
||
projects
|
||
submissions
|
||
submission_files
|
||
scoring_batches
|
||
criterion_scores
|
||
score_evidences
|
||
teacher_revisions
|
||
export_tasks
|
||
app_settings
|
||
audit_logs
|
||
```
|
||
|
||
### 11.1 评分批次
|
||
|
||
```text
|
||
scoring_batches
|
||
id
|
||
course_version_id
|
||
rubric_version_id
|
||
model_name
|
||
model_config_snapshot
|
||
embedding_model_name
|
||
embedding_model_version
|
||
status
|
||
created_at
|
||
finished_at
|
||
```
|
||
|
||
### 11.2 评分项结果
|
||
|
||
```text
|
||
criterion_scores
|
||
id
|
||
batch_id
|
||
project_id
|
||
criterion_id
|
||
model_score
|
||
teacher_score
|
||
final_score
|
||
model_comment
|
||
teacher_comment
|
||
confidence
|
||
status
|
||
```
|
||
|
||
```text
|
||
final_score = teacher_score（存在时）或 model_score
|
||
```
|
||
|
||
模型原始结果不得被教师修改覆盖。
|
||
|
||
## 12. 前端页面
|
||
|
||
第一版页面建议：
|
||
|
||
1. 仪表盘
|
||
2. 课程管理
|
||
3. 课程版本和评分规则管理
|
||
4. 课程资料/知识库管理
|
||
5. 数据目录扫描与导入确认
|
||
6. 学生项目列表
|
||
7. 评分批次列表
|
||
8. 批量评分进度
|
||
9. 学生评分详情
|
||
10. 证据和页码查看
|
||
11. 教师复核
|
||
12. Excel/PDF 导出
|
||
13. 模型和系统设置
|
||
|
||
## 13. 后端 API 初稿
|
||
|
||
### 课程和规则
|
||
|
||
```text
|
||
GET /api/courses
|
||
POST /api/courses
|
||
GET /api/courses/{id}/versions
|
||
POST /api/courses/{id}/versions
|
||
GET /api/rubrics/{version_id}
|
||
PUT /api/rubrics/{version_id}
|
||
POST /api/rubrics/{version_id}/publish
|
||
```
|
||
|
||
### 文件扫描和项目导入
|
||
|
||
```text
|
||
GET /api/storage/directories
|
||
GET /api/storage/directories/{relative_path}/children
|
||
POST /api/import/scan
|
||
POST /api/import/confirm
|
||
GET /api/projects
|
||
GET /api/projects/{id}
|
||
```
|
||
|
||
### 评分
|
||
|
||
```text
|
||
POST /api/scoring-batches
|
||
GET /api/scoring-batches
|
||
GET /api/scoring-batches/{id}/progress
|
||
POST /api/scoring-batches/{id}/start
|
||
GET /api/scoring-batches/{id}/scores
|
||
GET /api/projects/{id}/scores?batch_id={batch_id}
|
||
PUT /api/criterion-scores/{id}/review
|
||
```
|
||
|
||
### 导出
|
||
|
||
```text
|
||
POST /api/exports/excel
|
||
POST /api/exports/project-pdf
|
||
GET /api/exports/{id}
|
||
```
|
||
|
||
## 14. 缺失和异常处理
|
||
|
||
材料状态：
|
||
|
||
```text
|
||
已提交
|
||
缺失
|
||
重复
|
||
无法解析
|
||
内容不完整
|
||
待人工确认
|
||
```
|
||
|
||
处理原则：
|
||
|
||
- 缺失阶段报告：该阶段进入待人工处理，不默认静默给零分
|
||
- 缺失 PPT：汇报材料项显示无法评分
|
||
- 缺少章节：按照对应评分项判断并扣分
|
||
- 文件损坏：进入人工确认列表
|
||
- DeepSeek 调用失败：自动有限重试，仍失败则标记评分项失败
|
||
- 评分批次允许部分完成，但导出时必须显示未完成项目
|
||
|
||
## 15. 模型离线分发
|
||
|
||
`bge-m3` 不依赖启动时在线下载。推荐单独提供模型包：
|
||
|
||
```text
|
||
WiseGrade-release/
|
||
├── docker-images.tar
|
||
├── models-bge-m3.tar.zst
|
||
├── docker-compose.yml
|
||
├── .env.example
|
||
└── README.md
|
||
```
|
||
|
||
也支持将模型目录放在：
|
||
|
||
```text
|
||
./models/bge-m3/
|
||
```
|
||
|
||
容器只读挂载：
|
||
|
||
```yaml
|
||
volumes:
|
||
- ./models:/models:ro
|
||
```
|
||
|
||
在线下载脚本是可选工具，不得成为系统正常启动的前置条件。
|
||
|
||
## 16. 测试要求
|
||
|
||
### 16.1 单元测试
|
||
|
||
- 目录扫描
|
||
- 学号/姓名/题目解析
|
||
- 文件类型识别
|
||
- 路径越界防护
|
||
- 文件哈希检测
|
||
- 规则权重计算
|
||
- 缺失材料处理
|
||
- 分数汇总
|
||
- 评分 JSON 校验
|
||
- 版本绑定
|
||
|
||
### 16.2 集成测试
|
||
|
||
- 从示例材料导入到项目生成
|
||
- PDF/DOCX/PPTX 解析
|
||
- PPT PDF 识别
|
||
- 知识库入库和检索
|
||
- 模型 API mock 调用
|
||
- 评分批次创建、运行和查询
|
||
- 教师修改分数
|
||
- Excel 导出
|
||
- PDF 反馈导出
|
||
|
||
### 16.3 验收测试
|
||
|
||
至少使用当前 `docs/` 中的示例材料完成一次完整流程：
|
||
|
||
```text
|
||
扫描目录
|
||
-> 导入学生项目
|
||
-> 解析五类材料
|
||
-> 创建评分批次
|
||
-> mock 或真实调用 deepseek-flash
|
||
-> 查看逐项证据
|
||
-> 修改分数
|
||
-> 导出 Excel
|
||
-> 导出学生 PDF 反馈
|
||
```
|
||
|
||
不应在测试中提交真实 API Key。使用环境变量或 mock 服务。
|
||
|
||
## 17. Git 开发要求
|
||
|
||
开发前初始化 Git：
|
||
|
||
```bash
|
||
git init
|
||
```
|
||
|
||
必须创建合理的 `.gitignore`，至少忽略：
|
||
|
||
```text
|
||
.env
|
||
data/processed/
|
||
data/exports/
|
||
models/
|
||
__pycache__/
|
||
.pytest_cache/
|
||
node_modules/
|
||
dist/
|
||
*.pyc
|
||
```
|
||
|
||
开发和测试过程中按阶段提交，推荐提交节点：
|
||
|
||
```text
|
||
chore: initialize project structure
|
||
feat: add backend foundation
|
||
feat: add course and rubric versioning
|
||
feat: add mounted directory scanning
|
||
feat: add document parsing pipeline
|
||
feat: add knowledge base and hybrid retrieval
|
||
feat: add deepseek-flash adapter
|
||
feat: add scoring batch orchestration
|
||
feat: add teacher review workflow
|
||
feat: add excel and pdf exports
|
||
test: add integration coverage
|
||
docs: add deployment and usage guides
|
||
```
|
||
|
||
每个提交应保持可理解、可回退、尽量可运行。禁止把 API Key、真实学生隐私数据和模型权重提交到 Git。
|
||
|
||
## 18. 开发优先级
|
||
|
||
### P0：可运行骨架
|
||
|
||
- Git、README、Docker Compose
|
||
- 前端和后端健康检查
|
||
- 数据库迁移
|
||
- 单管理员设置
|
||
|
||
### P1：课程和导入
|
||
|
||
- 课程版本和规则配置
|
||
- 挂载目录扫描
|
||
- 学生目录识别
|
||
- 文件识别和导入确认
|
||
|
||
### P2：解析和知识库
|
||
|
||
- PDF/DOCX/PPTX 解析
|
||
- 页面渲染
|
||
- OCR 回退
|
||
- BGE-M3 嵌入
|
||
- pgvector 混合检索
|
||
|
||
### P3：评分
|
||
|
||
- 事实抽取
|
||
- 指标级 RAG 评分
|
||
- 跨文档一致性检查
|
||
- 批次状态和失败重试
|
||
|
||
### P4：复核和导出
|
||
|
||
- 教师修改分数和评语
|
||
- Excel 成绩表
|
||
- 逐生 PDF 反馈
|
||
- 审计日志
|
||
|
||
### P5：验收和部署
|
||
|
||
- 示例材料完整验收
|
||
- Linux 部署文档
|
||
- Windows Docker Desktop 部署文档
|
||
- 离线模型包说明
|
||
|
||
## 19. 完成标准
|
||
|
||
当以下条件全部满足时，第一版系统完成：
|
||
|
||
- Linux 上可以通过 Docker Compose 启动
|
||
- Windows Docker Desktop 有明确部署步骤
|
||
- 教师可以选择挂载目录下的大文件夹
|
||
- 系统可以识别每个学生目录
|
||
- 支持五类材料和 PPT PDF
|
||
- 规则、课程目标和课程版本可编辑
|
||
- 可创建独立评分批次
|
||
- 使用本地嵌入模型完成检索
|
||
- 使用 `deepseek-flash` 完成文本和图像评分
|
||
- 每项评分显示证据和页码/幻灯片编号
|
||
- 教师可以修改分数和评语
|
||
- 每个批次都可以导出 Excel 和逐生 PDF
|
||
- 示例材料可以完成端到端测试
|
||
- Git 历史包含清晰的阶段提交
|