update project-understanding_wjh.md

[Swan1127]

概述

CodeSense 阶段一交付：项目理解与架构分析（文档 PR）。本 PR 仅新增 project-understanding_wjh.md，无代码改动。

使用过的 AI 工具

Trae（接入 ds-v4-flash），用于代码理解问答、梳理调用链与辅助整理；所有结论经阅读源码复核。

实际阅读范围（仓库相对路径）

• 入口与配置：app.py（create_app 应用工厂）、config.py、models.py（18 个 ORM 数据模型 + 1 个 CodeSenseSession 会话存储类，共 19 个类）
• 路由层 8 个 Blueprint：routes/auth.py、routes/main.py、routes/assignments.py、routes/thinking.py、routes/classes.py、routes/users.py、routes/grades.py、routes/api.py
• 服务层：services/（llm_client、ai_evaluator、api_keys、course_grading、teacher_analytics、demo_database 等）
• 引擎/工具层：utils/（sandbox_runner、code_evaluator、llm_evaluator、thinking_ai、ability_scorer、async_tasks、sse、agents/ 等）
• 异步任务：tasks/submission_tasks.py、tasks/ability_analysis.py
• 前端与测试：templates/、static/ 关键页面/脚本，tests/ 各测试文件，并参考 git log 理解演进

验证命令及结果

环境：Windows + Python 3.11（.venv）+ g++ (MSYS2) 16.1.0，本地 SQLite。

命令	结果	说明
python -m pytest tests/test_sandbox_features.py -q	3 passed	沙箱（演示）登录与安全特性：演示数据装载/免密登录/生产禁用，不涉及 g++ 编译
python -m pytest tests/test_sandbox_output_limits.py -q	5 passed	有界进程输出/超时限制测试（mock 编译器、运行 Python 子进程），与 g++ 集成验证是两类
调用 utils/sandbox_runner.run_test_cases 编译运行 C++17 加法程序（3 用例，含公开/隐藏）	3/3 passed	真实 g++ 16.1.0 编译 → 运行 → 输出标准化比对，各用例 termination_reason 为空，单例 31–186ms
python run.py	启动成功	本地 SQLite 自动建表；无 Redis，会话降级文件系统

说明：tests/ 目录没有覆盖真实 g++ 编译链路的端到端用例（相关用例对 run_test_cases 做 mock），故前两项只证明沙箱演示/有界进程特性；编译运行链路由上表第 3 项真实验证支撑，两者已区分。

未验证事项与风险

• AI 辅助链路（能力分析、三阶段 Agent、提交 LLM 叠加评分等）需在 .env 配置智谱/OpenAI 密钥，本次未端到端验证；依赖真实 AI 密钥的部分 tests/ 用例未运行。
• 完整 Web「提交 → 后台任务 → SSE/轮询 → 落库」链路未做集成验证（真实编译验证仅到引擎层 sandbox_runner）。
• 本机未安装 Redis，仅验证文件系统会话降级路径。
• 文档为学习性记录，可能存在理解偏差；附录 A 已列出待确认疑问，请评审重点核查文档第三部分调用链与第四部分架构理解。