docs: describe chat operations and validation boundaries

docs/DEPLOYMENT.md

@@ -6,7 +6,7 @@ WiseGrade 是单机单管理员教师端。Web 服务仅绑定 `127.0.0.1`，默
 
 - Docker Engine + Compose v2（Linux），或 Windows Docker Desktop（WSL2 后端，运行 Linux 容器）。
 - 一个存放学生材料的宿主机目录；其下每个批次目录包含 `学号_姓名_选题题目` 子目录。
-- `deepseek-flash` 可访问的 OpenAI 兼容 API 地址和密钥；该端点必须支持文本与图片输入。
+- `deepseek-flash` 可访问的 OpenAI 兼容 API 地址和密钥；该端点必须支持文本、图片输入及原生 `tool_calls`。若只做评分而不使用对话，仍可沿用已有 JSON 调用。
 - 离线嵌入模型包。默认使用 BAAI/bge-m3。内存不足时可改用 BAAI/bge-small-zh-v1.5。
 
 仓库的 `docs/` 是课程资料，不是学生原件。旧版 `.doc` 只用于课程模板，经 LibreOffice 转换；学生输入只接受 PDF、DOCX、PPTX。
@@ -79,9 +79,12 @@ tar -xf models/ocr/PP-OCRv5_mobile_rec_infer.tar --strip-components=1 -C models/
 
 ## 教师操作
 
+打开系统默认进入“对话”。可新建并限定课程版本、批次和学生项目，使用自然语言查询规则、报告和进度。扫描目录可直接执行；导入、课程资料入库、建批、启动／重试、复核和导出须核对确认卡片并点击“确认执行”。有重复或识别异常的文件需先在卡片中修正选择。刷新后会话、引用和卡片保留。后台索引任务和评分进度可在对话页查看。详细规则见 [对话页面与业务 Agent](CHAT_AGENT.md)。
+
 1. 在“课程与规则”中查看初始课程版本和评分规则。已发布版本不能直接覆盖；复制草稿、编辑、保存并发布新版本。课程目标、指标点、选题方向、模板和三个 Prompt 都属于课程版本。
 2. 在“知识库资料”中选课程版本并入库课程资料。入库使用本地嵌入模型和 PostgreSQL `pgvector`。
 3. 在“目录扫描与导入”中浏览 `/data/inbox` 下的相对目录，选择学生总目录并扫描。修正学号、姓名、选题和材料类型；PPT 导出的 PDF 必须确认成“汇报PPT/PDF”。每类材料只选择一个文件。
+   确认导入后，材料自动进入后台解析、必要 OCR 和索引任务；评分前即可检索已完成索引的报告。失败任务可从索引任务列表重试。
 4. 在“评分批次”中选择已发布课程和规则版本，创建并启动批次。每次评分建立独立批次；重试不会覆盖其他批次。
 5. 在“评分与复核”中查看逐项模型原始分、原文证据、页码、页面图像和异常。教师可逐项填写分数、评语和修改说明；修改历史单独保留。
 6. 在“导出任务”中按批次导出 Excel，按学生导出 PDF 反馈。缺失或无法评分的项目显示待处理，不自动补零。
@@ -105,7 +108,9 @@ uv run uvicorn wisegrade.main:app --reload
 docker compose --profile test run --build --rm test
 ```
 
-测试使用独立的 PostgreSQL 16 + pgvector 容器，不连接业务数据库。每个数据库测试创建临时数据库，执行 Alembic 迁移后运行，结束时删除；`test-db` 的数据目录为 tmpfs，不会写入业务数据卷。测试会从 `.env` 读取真实 DeepSeek API Key，并加载 `models/bge-m3` 和 `models/ocr` 中的离线模型；完整流程测试会发起真实模型请求。在宿主机直接运行 `uv run pytest` 时，需先设置指向专用 `wisegrade_tests` 数据库的 `TEST_DATABASE_URL`（使用 `postgresql+psycopg` 驱动，账号需有创建数据库的权限），并提供可用的模型配置。
+先验证无需真实 API Key 的测试可运行：`docker compose --profile test run --build --rm test pytest -q -m 'not integration'`。宿主机运行同一测试时，须把 `TEST_DATABASE_URL` 指向独立 PostgreSQL 测试库，并将 `EMBEDDING_MODEL_PATH` 指向本机离线模型目录。完整集成测试会访问真实模型，应单独执行和记录。
+
+测试使用独立的 PostgreSQL 16 + pgvector 容器和 `test-redis`，不连接业务数据库或业务任务队列。每个数据库测试创建临时数据库，执行 Alembic 迁移后运行，结束时删除；`test-db` 的数据目录为 tmpfs，不会写入业务数据卷。测试会从 `.env` 读取真实 DeepSeek API Key，并加载 `models/bge-m3` 和 `models/ocr` 中的离线模型；完整流程测试会发起真实模型请求。在宿主机直接运行 `uv run pytest` 时，需先设置指向专用 `wisegrade_tests` 数据库的 `TEST_DATABASE_URL`（使用 `postgresql+psycopg` 驱动，账号需有创建数据库的权限），并提供可用的模型配置。
 
 本地开发需提供 PostgreSQL、Redis 和与容器路径一致的挂载目录；可用 Compose 启动 `db` 和 `redis`。Vite 前端：
 
@@ -121,5 +126,7 @@ npm run dev
 
 - `docker compose logs api worker` 查看迁移、解析和任务异常。日志不输出 API Key。
 - 模型请求失败后按配置有限重试，评分项显示失败原因；可修复配置后重试该批次。
+- 对话若提示端点或模型不支持 `tool_calls`，在“模型设置”中选择支持工具调用的 OpenAI 兼容端点和模型。探针不发送课程或学生资料；普通模型对话仍有调用次数和超时限制。
+- 导入后索引任务若显示失败，查看 `/api/index-tasks/{id}` 的错误并修复 Redis、离线 BGE-M3 或 OCR，再重试。批次若已入队或运行，重复点击启动会返回冲突。
 - 原件哈希变化后必须重新扫描并确认导入，否则解析会报“源文件已变化”。
 - 源文件和模型目录为只读挂载；解析产物在 `data/processed/`，导出在 `data/exports/`，均被 Git 忽略。