test: 教师 AI 建议接入真实入口集成测试，并补异步任务失败兜底

[linxi123-A]

背景

阶段十四（#70，已合并）修复了教师 AI 周报"低分标签 + 最近得分100 → 误报数据异常"的问题：新增纯函数utils/teacher_advice_prompt.py ，给 prompt 补低分标签口径说明、给学生数据补历史综合分。但 #70 的测试全部停在 纯函数单元层 ，没有证明这些内容真的随 真实 HTTP 入口 送达 LLM。

本 PR 把改进接入真实使用路径：通过真实入口做集成验证，并补上异步入口缺失的失败兜底。

真实入口（集成范围）

教师路径的真实链路：

1
2
3
4

GET /teacher/ai_suggestions 落地页（只读渲染） └─ GET/POST /api/teacher/stream_suggestions SSE 流式生成（首次生成唯一路径） POST /api/teacher/generate_suggestions 刷新按钮 → 后台线程异步生成 GET /api/teacher/suggestion_status/<class_id> 前端轮询状态

集成测试全部通过app.test_client() 驱动上述 HTTP 路由，临时 SQLite、无网络/Redis。

变更范围

仅 2 个文件，不涉及 DB 结构、权限、安全策略、部署配置：

1. 新增tests/test_teacher_advice_integration.py （5 个集成测试）
   • test_real_sse_entry_delivers_risk_tag_caliber_to_llm ：用捕获 messages 的 FakeLLM 走真实 SSE 路由，断言 system prompt 含低分口径说明（"历史综合分"/60），孙三型学生行同时含历史综合分 44、最近一次 100 和"低分标签来自历史综合分"标注，且request_kind="interactive" 。
   • test_real_sse_entry_completes_persists_and_page_still_renders ：SSE 协议 status→start→done 完整、记录持久化、落地页 200、状态接口正常。
   • test_sse_stream_error_falls_back_without_stuck_processing ：流式 LLM 抛错时规则引擎兜底，done 收尾，状态为 completed 而非卡在 processing。
   • test_sse_llm_unavailable_uses_rules_fallback ：LLM 不可用时同样规则兜底。
   • test_async_entry_unexpected_error_marks_failed ：异步工作线程发生保护范围外的意外错误时，状态从 pending 翻成 failed（修复前线程直接死亡、永久 pending）。
2. services/teacher_ai_advisor.py ：generate_class_suggestions_async 增加外层兜底 。generate_class_suggestions 自身已捕获业务异常并标记 failed；但工作线程内若发生其保护范围之外的错误（如应用上下文异常），异常会杀死线程，记录永久停在 pending、前端轮询无法收口。现统一捕获：正式账户把 pending/processing 翻成 failed（不回退已完成结果）；demo 账户走_mark_demo_suggestion_failed ；清理本身再失败仅记日志，不向外抛。

验证（实际执行结果）

环境：仓库内隔离 venv.tmp_pytest_env （未装系统盘），Windows + PowerShell。

• 新增集成测试：
  1
  2

pytest tests/test_teacher_advice_integration.py -q 5 passed

• 与既有 AI 建议测试联跑：
  1
  2

pytest tests/test_teacher_advice_integration.py tests/test_teacher_ai_suggestions.py -q 13 passed in 40.28s

• 全量回归：
  1
  2

pytest tests/ -q 871 passed in 991.27s (0:16:31)

可复现命令（任意检出本分支的环境）：

PowerShell

运行

1

python -m pytest tests/test_teacher_advice_integration.py -v

失败处理说明

失败场景 处理 用户可见结果 流式 LLM 中途异常（非 demo） 捕获并转规则引擎 规则报告 + done，状态 completed 流式 LLM 不可用 规则引擎兜底 规则报告 + done 异步线程意外错误（本 PR 新增） 捕获并标记 failed 轮询得到 failed，可重试，不再永久 pending demo 会话 AI 失败 标记 failed + error 事件 错误提示，可重新进入演示 失败状态清理本身再失败 仅记日志，不外抛 不产生二次异常

事实 / 推断边界

• 事实（代码与测试可核实） ：真实 SSE 路由构造的 messages 中 system 含口径说明、user 行含历史综合分与来源标注（由捕获 messages 的集成测试断言）；改动前异步线程无外层异常保护（临时将被调函数置为抛错时，状态实测停在 pending）。
• 推断 ：线上真实 LLM 在收到口径说明后不会再输出"数据异常"结论——LLM 输出有非确定性，集成测试只证明口径信息送达，不能逐字断言最终文案。

影响范围与后续风险

• 影响面 ：仅教师 AI 建议功能。SSE 同步路径零改动；唯一生产代码改动是异步入口新增 try/except，正常路径行为不变（只在原本会"线程静默死亡"时新增 failed 标记）。
• 未覆盖 / 后续风险 ：
  • 未在部署后重跑线上真实 AI 验证最终文案；
  • demo 会话过期（activate_demo_run 失败）时仍直接返回、不改状态，维持现状（前端会重新进入演示）；
  • 其他风险标签（"近期未活跃""未提交"）与分数的组合解读未处理，沿用 fix: 教师 AI 周报补充低分标签口径，避免误报数据异常 #70 的范围边界。

[XiaoCow666]

CodeSense 自动评审

当前无法完成可靠的代码审查：GitHub 返回 503，实际 diff 不可用。PR 描述中的测试结果可作为提交者声明，但不足以在未查看改动的情况下批准代码变更。

需要先处理的问题

• 无法审查新增集成测试及 services/teacher_ai_advisor.py 的实际实现，因此无法确认异步失败兜底是否会正确更新状态、是否引入回归，也无法核对测试断言覆盖的真实入口。

请按下面的步骤修改

• 位置：PR diff；现在：GitHub 返回 503，当前事件仅提供变更文件统计和 PR 描述，无法查看具体补丁；改成：提供可访问的完整 diff，或重新触发包含这两个文件补丁的审查事件；交给 AI：请重新加载并审查 tests/test_teacher_advice_integration.py 与 services/teacher_ai_advisor.py 的完整 diff，并在确认无阻塞问题后运行可用的相关检查。

已有验证信息

• PR 描述声称 pytest tests/test_teacher_advice_integration.py -q：5 passed。
• PR 描述声称 pytest tests/test_teacher_advice_integration.py tests/test_teacher_ai_suggestions.py -q：13 passed in 40.28s。
• PR 描述声称 pytest tests/ -q：871 passed in 991.27s；这些结果未在当前事件中独立执行或验证。

评审事件：a4379610-b94e-11f1-8775-52bc114e926d

[linxi123-A]

感谢审查。503 是 GitHub 的临时故障，与改动无关。完整 diff 可通过以下永久链接获取（无需登录即可查看原始补丁）：

• Patch：https://github.com/XiaoCow666/CodeSense/pull/74.patch
• Diff：https://github.com/XiaoCow666/CodeSense/pull/74.diff
  补丁只涉及 2 个文件、361 行（其中生产代码仅 teacher_ai_advisor.py 的generate_class_suggestions_async 一处，新增外层 try/except；其余为集成测试）。关键事实再确认：

1. 正常路径零行为变化 ：兜底只在工作线程抛出generate_class_suggestions 保护范围之外的异常时触发，且仅当状态为pending /processing 才翻成failed ，已完成的结果不会被回退。
2. 失败标记经集成测试实际验证 ：test_async_entry_unexpected_error_marks_failed 临时令被调函数抛RuntimeError ，断言线程结束后记录由pending →failed （修复前实测停在pending ，即 RED）。
3. 真实入口断言 ：test_real_sse_entry_delivers_risk_tag_caliber_to_llm 走真实 HTTP SSE 路由并捕获 LLM 入参，断言口径说明与历史综合分送达。
   本地实际执行（隔离 venv，可复现）：tests/test_teacher_advice_integration.py 5 passed；与test_teacher_ai_suggestions.py 联跑 13 passed；全量 871 passed。

请在 GitHub 恢复后重新触发审查事件，或直接基于.patch 链接审查这两个文件。

[XiaoCow666]

CodeSense 自动评审

未发现会导致安全风险、数据损坏、明显回归或无法运行的阻塞问题，异步任务异常兜底与真实入口集成测试均覆盖了 PR 目标。根据 PR 提供的检查证据，新增测试、相关回归测试及全量测试均通过。

已有验证信息

• PR 提供证据：pytest tests/test_teacher_advice_integration.py -q，5 passed。
• PR 提供证据：pytest tests/test_teacher_advice_integration.py tests/test_teacher_ai_suggestions.py -q，13 passed in 40.28s。
• PR 提供证据：pytest tests/ -q，871 passed in 991.27s。

评审事件：986641d0-b9ba-11f1-9fbf-c5bd02d35d32