commit f7a9091c863c8560aa2b2a6c30ea8c6e0a925845 Author: SkyLi Date: Fri Sep 25 00:44:32 2026 +0800 docs: define WiseGrade technical specification diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..4a2e277 --- /dev/null +++ b/.gitignore @@ -0,0 +1,26 @@ +.env +.env.* +!.env.example +__pycache__/ +*.py[cod] +.pytest_cache/ +.mypy_cache/ +.ruff_cache/ +.venv/ +venv/ +node_modules/ +dist/ +build/ +coverage/ +.coverage +data/processed/ +data/exports/ +data/runtime/ +models/ +*.log +*.sqlite3 +*.db +.idea/ +.vscode/ +Thumbs.db +.DS_Store diff --git a/README.md b/README.md new file mode 100644 index 0000000..b262f09 --- /dev/null +++ b/README.md @@ -0,0 +1,22 @@ +# WiseGrade（智评） + +WiseGrade 是面向《自动化专业综合实践》课程的教师端自动评分系统。 + +当前项目处于技术方案固化和系统开发准备阶段。完整技术规格见： + +- [技术方案与开发规格](docs/WISEGRADE_TECHNICAL_SPEC.md) +- [Codex Goal 模式开发提示词](docs/CODEX_GOAL_PROMPT.md) + +## 当前约束 + +- 仅供教师使用 +- 通过宿主机挂载目录读取学生材料 +- 支持 PDF、DOCX、PPTX 和 PPT 导出的 PDF +- 使用本地 BGE-M3 嵌入模型 +- 使用 `deepseek-flash` 进行文本和图像理解 +- 支持课程、评分规则和评分批次版本化 +- 支持 Excel 成绩表和逐生 PDF 反馈导出 + +## 资料 + +课程原始资料位于 `docs/` 目录。 diff --git a/docs/CODEX_GOAL_PROMPT.md b/docs/CODEX_GOAL_PROMPT.md new file mode 100644 index 0000000..705e625 --- /dev/null +++ b/docs/CODEX_GOAL_PROMPT.md @@ -0,0 +1,190 @@ +# WiseGrade（智评）Codex Goal 模式开发提示词 + +将以下内容复制给 Codex，并使用 goal 模式执行。 + +```text +你是本项目的主开发代理。请在当前工作目录完成 WiseGrade（智评）整套系统的搭建、开发、测试和部署文档。 + +## 最高优先级要求 + +1. 先完整阅读 `docs/WISEGRADE_TECHNICAL_SPEC.md`，它是本项目的技术规格和业务约束。 +2. 当前项目英文名为 WiseGrade，中文名为智评。 +3. 当前只实现“自动化专业综合实践”，但课程、课程版本、课程目标、毕业要求指标点、评分规则、选题方向和 Prompt 必须可配置、可版本化，未来可以扩展其他课程。 +4. 系统只供教师使用，采用单机单管理员模式，不实现学生账号。 +5. 学生材料通过宿主机目录挂载进入容器。不要把原始学生文件设计成浏览器上传流程。前端只选择挂载目录 `/data/inbox` 下的相对目录，后端扫描和读取实际文件。 +6. 学生目录格式为 `学号_姓名_选题题目`。系统需要自动解析并支持教师在导入确认时修正。 +7. 支持 PDF、DOCX、PPTX 和 PPT 导出的 PDF。不支持旧版 DOC 输入。 +8. 评分材料为阶段报告1、阶段报告2、阶段报告3、最终报告、汇报 PPT/PPT PDF。 +9. 课程成绩结构是：阶段报告1 10% + 阶段报告2 10% + 阶段报告3 10% + 期末成绩 70%。期末成绩包含任务完成度20分、报告规范性20分、汇报答辩40分、结果分析20分；其中本系统只按照 PPT 内容评价“汇报答辩”，不评价现场口头答辩。 +10. 统一使用一个外部模型 `deepseek-flash`，该模型负责文本理解、图像理解、PPT分析、事实抽取、评分和评语生成。不要设计成文本模型和视觉模型两个必需模型。 +11. 使用本地嵌入模型，默认 `BAAI/bge-m3`，支持配置轻量替代模型。模型以独立离线模型目录或模型包提供，不能要求系统启动时在线下载。 +12. 每次评分创建独立评分批次。批次之间不覆盖、不设置唯一正式批次。每个批次都可查看、复核和导出。 +13. 教师必须可以逐项修改分数和评语。模型原始分数、教师修改结果、证据和修改记录必须同时保留。 +14. 最终必须支持导出 Excel 成绩表和每个学生一份 PDF 反馈报告。 +15. 开发和测试过程中必须及时 Git commit。提交信息使用清晰的 Conventional Commits 风格。 + +## 推荐技术栈 + +- 前端：React + TypeScript + Vite + Ant Design +- 后端：FastAPI + SQLAlchemy + Pydantic +- 数据库：PostgreSQL + pgvector +- 后台任务：Redis + RQ +- 解析：PyMuPDF、python-docx、python-pptx、LibreOffice headless +- OCR：PaddleOCR 作为扫描 PDF 回退 +- 嵌入：BAAI/bge-m3 +- 大模型：OpenAI 兼容方式调用 deepseek-flash +- 导出：openpyxl/pandas，HTML/CSS + WeasyPrint 或 Playwright +- 部署：Docker Compose，兼容 Linux 和 Windows Docker Desktop + +## 工作方式 + +### 第一步：检查和初始化 + +- 检查当前目录、现有文件和 `docs/` 资料。 +- 阅读 `docs/WISEGRADE_TECHNICAL_SPEC.md`。 +- 如果没有 Git，执行 `git init`。 +- 创建合理的 `.gitignore`，不得忽略课程资料和源代码，但必须忽略 `.env`、模型目录、运行数据、缓存、构建产物和真实学生材料。 +- 创建 `README.md`，说明项目名称、启动方式、配置方法和开发状态。 +- 先提交：`chore: initialize WiseGrade project`。 + +### 第二步：设计并实现后端基础 + +- 创建 FastAPI 项目结构。 +- 创建配置模块、日志模块、异常处理、健康检查和数据库连接。 +- 使用 Alembic 或等价迁移工具。 +- 创建课程、课程版本、评分规则、指标点、项目、提交材料、评分批次、评分结果、证据、教师复核、导出任务和审计日志模型。 +- 保证所有评分结果关联课程版本、规则版本、模型配置快照和嵌入模型版本。 +- 编写单元测试。 +- 测试通过后提交：`feat: add backend foundation and database models`。 + +### 第三步：初始化课程资料和可编辑规则 + +- 从 `docs/` 现有材料建立“自动化专业综合实践”的初始课程版本。 +- 课程目标和毕业要求指标点至少包括 2.3、2.4、4.1、4.2、4.3、4.4、11.1、11.2。 +- 建立阶段报告1、2、3的初始评分规则，以及期末评分规则。 +- 评分规则必须有分值、评分等级、证据要求和关联课程目标字段。 +- 规则应可在 API 和前端中编辑、复制、发布新版本。 +- 不要把规则写死在 Prompt 或评分代码中。 +- 测试通过后提交：`feat: add course versioning and editable rubrics`。 + +### 第四步：实现挂载目录扫描和导入确认 + +- Docker 将宿主机目录挂载为 `/data/inbox:ro`。 +- 后端只允许访问 `/data/inbox`，必须防止路径越界。 +- 前端显示后端扫描出的目录树，教师选择某个大文件夹。 +- 后端扫描其中的学生子文件夹，解析 `学号_姓名_选题题目`。 +- 识别阶段报告1、2、3、最终报告和汇报PPT/PPT PDF。 +- 结合文件名、扩展名、首页文本、章节标题进行识别。 +- 对不确定、缺失、重复、无法解析的材料标记状态，交给教师确认。 +- 保存相对路径、文件大小、修改时间、SHA-256和解析状态。 +- 原始材料不复制到浏览器或应用上传临时目录。 +- 测试通过后提交：`feat: add mounted directory scanning and import confirmation`。 + +### 第五步：实现文档解析和页面资产 + +- PDF 使用 PyMuPDF 按页解析，保留页码、文本、图片和表格信息。 +- DOCX 使用 python-docx 解析标题、段落、表格和图片。 +- PPTX 使用 python-pptx 提取文字、表格和备注，并使用 LibreOffice 渲染幻灯片。 +- PPT PDF允许作为汇报材料，但需要教师确认材料类型。 +- 扫描 PDF 使用 OCR 回退。 +- 生成可追溯的结构化文档对象和页面图像。 +- 解析失败不得静默忽略，必须进入错误状态并显示原因。 +- 测试通过后提交：`feat: add document parsing and page rendering`。 + +### 第六步：实现知识库和 RAG + +- 建立公共课程知识库：课程导学、课程目标、毕业要求、评分表、阶段模板、选题方向要求和优秀报告。 +- 为每个学生项目建立独立命名空间，禁止跨学生检索。 +- 使用结构感知切分，保留文档类型、阶段、页码、章节、课程版本和项目编号元数据。 +- 使用本地 BGE-M3 生成嵌入，向量保存到 pgvector。 +- 同时使用 PostgreSQL 全文检索、向量检索和元数据过滤。 +- 首次启动不得强制在线下载模型；支持挂载 `./models` 或指定本地模型目录。 +- 测试通过后提交：`feat: add knowledge ingestion and hybrid retrieval`。 + +### 第七步：实现 DeepSeek 适配器和评分编排 + +- 使用 OpenAI 兼容客户端接入 DeepSeek。 +- 模型默认名为 `deepseek-flash`，Base URL、API Key、超时、并发数和重试次数可配置。 +- API Key 后端保存，前端不得直接调用 DeepSeek，日志不得输出密钥。 +- 通过结构化 JSON Schema/Pydantic 校验模型输出。 +- 实现项目事实抽取、规则检查、指标级评分、PPT 页面分析和跨文档一致性检查。 +- 每个评分项输出分数、理由、原文证据、页码或幻灯片编号、缺失证据、建议和置信度。 +- 每个评分项只发送相关 RAG 证据和必要页面图片，不重复发送完整报告。 +- 模型不能对没有证据的内容自行假设。 +- 实现批次级后台任务、进度、失败重试和部分完成状态。 +- 测试通过后提交：`feat: add deepseek-flash scoring pipeline`。 + +### 第八步：实现教师复核和导出 + +- 实现学生项目列表、评分批次列表、逐项评分详情和证据查看。 +- 教师可以修改每个评分项的分数和评语。 +- 保留模型原始值和教师修改记录。 +- 缺失材料和无法评分状态必须明显显示。 +- 导出 Excel：学生信息、各阶段分数、期末分项、期末成绩和总评。 +- 导出单学生 PDF 反馈：各项分数、证据、页码、缺失内容、建议、教师修改结果、规则版本和模型信息。 +- 每个评分批次都可以单独导出。 +- 测试通过后提交：`feat: add teacher review and score exports`。 + +### 第九步：完善前端 + +实现至少以下页面： + +- 仪表盘 +- 课程和课程版本 +- 评分规则编辑 +- 知识库资料 +- 挂载目录选择和扫描 +- 导入确认 +- 学生项目列表 +- 评分批次和进度 +- 学生评分详情 +- 教师复核 +- 导出任务 +- 模型设置 + +页面必须适合教师批量操作，重点显示异常、缺失和待复核项目。 + +测试通过后提交：`feat: add teacher-facing frontend`。 + +### 第十步：测试、部署和文档 + +- 使用 `docs/` 当前示例材料完成端到端测试。 +- 为路径安全、文件哈希、规则权重、材料识别、模型 JSON 输出、评分批次、教师复核和导出补充测试。 +- 不在测试中提交真实 API Key。 +- 提供 Linux 启动说明。 +- 提供 Windows Docker Desktop 启动说明。 +- 提供离线 BGE-M3 模型包安装说明。 +- 提供 `.env.example`，说明 DeepSeek 配置、挂载目录、数据库和模型目录。 +- 完成后提交：`test: add end to end coverage` 和 `docs: add deployment and usage guides`。 + +## 重要实现原则 + +- 先做可运行的最小闭环，再扩展功能。 +- 不要为了“微服务化”增加不必要复杂度，第一版采用模块化单体后端。 +- 不要把评分规则、课程目标或 Prompt 写死在代码中。 +- 不要把模型权重、API Key、真实学生材料提交到 Git。 +- 不要静默忽略解析失败、材料缺失或模型失败。 +- 所有自动评分都必须能回溯到证据。 +- 所有模型输出都必须经过结构化校验。 +- 对需要外部网络的模型调用提供清晰错误信息和重试机制。 +- 每完成一个可验证阶段就运行测试并及时提交 Git。 +- 除非遇到真正阻塞开发的业务矛盾，否则不要停下来请求用户确认，按规格和合理工程判断继续推进。 + +## 最终验收标准 + +完成后必须能够： + +1. 在 Linux 上通过 Docker Compose 启动 WiseGrade。 +2. 在 Windows Docker Desktop 上按文档启动。 +3. 选择挂载目录下的大文件夹并扫描学生子目录。 +4. 识别和解析阶段报告、最终报告和 PPT/PPT PDF。 +5. 编辑课程目标、毕业要求和评分规则并生成新版本。 +6. 使用本地 BGE-M3 完成混合检索。 +7. 使用 `deepseek-flash` 完成文本和页面图像评分。 +8. 为每个评分项显示证据和页码/幻灯片编号。 +9. 创建多个独立评分批次并分别保存。 +10. 教师可以修改分数和评语。 +11. 每个批次分别导出 Excel 和逐生 PDF。 +12. 使用当前 `docs/` 示例材料完成端到端测试。 +13. Git 历史包含清晰、及时、可回退的阶段提交。 +``` diff --git a/docs/WISEGRADE_TECHNICAL_SPEC.md b/docs/WISEGRADE_TECHNICAL_SPEC.md new file mode 100644 index 0000000..0c9ed4f --- /dev/null +++ b/docs/WISEGRADE_TECHNICAL_SPEC.md @@ -0,0 +1,930 @@ +# WiseGrade（智评）技术方案与开发规格 + +## 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 历史包含清晰的阶段提交 + diff --git a/docs/大作业评分表-自动化专业综合实践.docx b/docs/大作业评分表-自动化专业综合实践.docx new file mode 100644 index 0000000..918d7f7 Binary files /dev/null and b/docs/大作业评分表-自动化专业综合实践.docx differ diff --git a/docs/自动化专业综合实践三融合选题课程概述.pdf b/docs/自动化专业综合实践三融合选题课程概述.pdf new file mode 100644 index 0000000..db4ec0a Binary files /dev/null and b/docs/自动化专业综合实践三融合选题课程概述.pdf differ diff --git a/docs/自动化专业综合实践报告.pdf b/docs/自动化专业综合实践报告.pdf new file mode 100644 index 0000000..72bcaf8 Binary files /dev/null and b/docs/自动化专业综合实践报告.pdf differ diff --git a/docs/课程导学-自动化专业综合实践.pdf b/docs/课程导学-自动化专业综合实践.pdf new file mode 100644 index 0000000..7be1e73 Binary files /dev/null and b/docs/课程导学-自动化专业综合实践.pdf differ diff --git a/docs/阶段报告1.pdf b/docs/阶段报告1.pdf new file mode 100644 index 0000000..6bd5607 Binary files /dev/null and b/docs/阶段报告1.pdf differ diff --git a/docs/阶段报告1模板.doc b/docs/阶段报告1模板.doc new file mode 100644 index 0000000..5e34b4a Binary files /dev/null and b/docs/阶段报告1模板.doc differ diff --git a/docs/阶段报告2.pdf b/docs/阶段报告2.pdf new file mode 100644 index 0000000..464ae64 Binary files /dev/null and b/docs/阶段报告2.pdf differ diff --git a/docs/阶段报告2模板.doc b/docs/阶段报告2模板.doc new file mode 100644 index 0000000..8753b92 Binary files /dev/null and b/docs/阶段报告2模板.doc differ diff --git a/docs/阶段报告3模板.doc b/docs/阶段报告3模板.doc new file mode 100644 index 0000000..310e30a Binary files /dev/null and b/docs/阶段报告3模板.doc differ