docs: 项目接管理解文档 — CodeSense 酷森思

[H1686hou]

文档型 PR：项目接管理解

本 PR 仅添加文档 docs/project-understanding.md，不修改任何业务逻辑、不做重构、不包含生产配置或密钥。

使用的 AI 工具

• 豆包（Doubao）：代码理解、架构梳理、文档撰写

查阅的核心文件

• README.md / README.en.md / DEPLOYMENT.md / AGENTS.md / CHANGELOG.md
• app.py（应用工厂、蓝图注册、中间件、会话、日志、启动初始化）
• config.py（三环境配置）
• models.py（全部 15+ 数据模型、init_db、索引维护）
• utils/sandbox_runner.py（C++ 代码执行沙箱）
• utils/async_tasks.py、utils/ability_scorer.py、utils/code_evaluator.py
• services/demo_database.py、services/llm_client.py、services/teacher_analytics.py
• routes/ 全部 8 个蓝图、services/ 全部 9 个服务、utils/ 核心引擎
• requirements.txt、.env.example、database_maintenance.py、run.py、wsgi.py

验证命令与结果

命令	结果
py -3.10 -m venv .venv	虚拟环境创建（Python 3.10.1）
pip install -r requirements.txt	全部依赖安装成功
winget install BrechtSanders.WinLibs.POSIX.UCRT	g++ 16.1.0 (MinGW-w64)
python database_maintenance.py	SQLite 数据库初始化
python run.py	服务运行在 http://127.0.0.1:5000
curl http://127.0.0.1:5000/login	HTTP 200
pytest tests/test_app.py tests/test_account_basics.py tests/test_sandbox_features.py	9 passed

未解决问题

1. 完整测试套件（40+ 文件）未全部运行，部分测试依赖真实 AI 服务和 Redis
2. 生产环境部署（Linux + Gunicorn + Nginx + MySQL + Redis）未实际验证
3. AI 功能因无 API 密钥未测试
4. 阶段三多 Agent 系统在无 AI 密钥时的降级行为未深入验证
5. .gitignore 中 docs/* 规则忽略了 docs 目录文件，本文件通过 git add -f 强制添加；建议维护者后续评估是否调整 gitignore 规则

文档内容概览

1. 项目定位、主要用户与核心问题
2. 目录结构与主要模块职责（routes/services/utils/models 分层说明）
3. 核心运行流程与调用链（代码提交评测、三阶段引导学习、演示数据库隔离、单点登录）
4. 安装运行与测试记录
5. 风险、疑问与待确认事项（安全/架构/技术债务/待确认共 18 项）
6. 整体架构理解（个人总结）

[XiaoCow666]

需要先修正核心提交流程描述：当前 routes/api.py::submit_code 是同步路径，会直接调用 evaluate_cpp_code 并在 HTTP 请求内更新 Submission；异步沙箱路径是 routes/assignments.py::submit_code -> tasks/submission_tasks.evaluate_submission_async。文档当前把 /api/submit 画成异步沙箱主链，会误导接管者。另，tests/test_sandbox_features.py 的 3 个测试实际覆盖演示数据播种、免密登录和生产环境禁止入口，并没有验证 g++ 集成；请删除或改写该结论。models.py 当前有 18 个模型类，“约 15 张表”应修正或明确统计口径。

[XiaoCow666]

这次先退回，不是任务失败。请让你的 AI 按下面步骤处理后重新提交新的 PR：

1. 打开 docs/project-understanding.md。
2. 把提交流程改成两条清楚的链路：
   • API 路径：routes/api.py::submit_code → evaluate_cpp_code，这是同步处理。
   • 网页作业路径：routes/assignments.py::submit_code → tasks/submission_tasks.evaluate_submission_async，这是异步处理。
3. 不要再把 /api/submit 写成“异步沙箱主链”。
4. 先执行：git fetch origin，再把 origin/main 合并到你的分支，解决 docs/project-understanding.md 的冲突；保留当前 main 上已有内容，同时保留你补充的、经过代码核对的内容。
5. 运行：python -m pytest tests/test_sandbox_features.py -q。
6. 测试通过后提交并推送，再重新创建 PR。

原 PR 已关闭，分支没有删除。当前任务仍需继续完成。

[XiaoCow666]

结论：通过。提供的 diff 仅新增 docs/project-understanding.md，未改动业务代码、依赖、生产配置或迁移脚本；未发现必须修改的功能、安全或数据风险。

已检查范围：文档的架构与调用链说明、§4 安装和测试记录、§5 风险清单及附录。本文明确记录了沙箱隔离不足和未验证范围。审查仅依据提供的文本，未执行命令，也无法独立确认底层实现或贡献者报告的“9 passed”。

后续建议（不阻塞，按优先级）：

1. §4.2 创建虚拟环境后缺少激活步骤，直接运行 pip、python 可能使用系统环境。建议改用 .\.venv\Scripts\python.exe -m pip install -r requirements.txt，并让后续运行、测试命令使用同一解释器，方便新手复现。
2. §3.4 的“所有读写都……完全隔离”和§6 的多 worker“会有重复执行”属于较强结论。建议补充对应函数或测试依据；未验证部分改为设计意图或待确认风险，避免接管者误判隔离保证与任务行为。
3. §4.4 将 tests/test_sandbox_features.py 描述为“验证 g++ 集成”，但未提供实际编译执行断言。建议注明具体测试函数及覆盖行为，将演示登录测试与编译执行验证区分清楚。

PR description 已包含变更范围、验证命令和限制，适合首次贡献。后续更新时保持这些信息，并在§4补充实际运行的完整测试命令、解释器路径和对应提交 SHA；无需为本次纯文档变更补跑生产部署或真实 AI 服务。