docs: add architecture analysis document (stage 1)

[Z11zhang]

Summary

This PR adds docs/architecture-analysis.md, completing Stage 1 project understanding and architecture analysis for CodeSense. Covers project positioning, module responsibilities (8 routes, 8 services, 15+ utils, agents/ subsystem), 3 core flows, run/test instructions, risks, and personal insights. All facts backed by code or runtime verification. No business code changes.

Verification Evidence (code-level)

• POST /api/submit is SYNCHRONOUS, AI-only scoring: routes/api.py:271 calls evaluate_cpp_code() at line 303 (heuristic + LLM, NO g++ compile, NO sandbox tests); response includes score and status=evaluated (lines 358-366). No sandbox_status fields.
• Web submission is ASYNCHRONOUS, AI + conditional sandbox: routes/assignments.py:483 calls evaluate_submission_async() at line 546; submission_tasks.py:123 AI eval -> line 157 if test_cases: run_test_cases (g++ compile + run) -> line 168 if total>0: score override -> line 193 status=evaluated (regardless of sandbox execution).
• sandbox_status values (sandbox_runner.py:178): passed/partial/failed/compile_error/no_cases/unavailable; None when assignment has no test cases
• status=evaluated means: evaluation flow finished (AI always executed); sandbox may or may not have run depending on test case config
• models.py has 18 db.Model classes (verified by grep)
• tests/ has 43 test_*.py files (verified by directory listing)
• Runtime: python run.py starts on Python 3.14.7 after dependency upgrade, /login returns 200

Python Compatibility

• ast.Str is deprecated in Python 3.12, removed in Python 3.14 (NOT removed in 3.12)
• Verified working: Python 3.10/3.11 + original deps; Python 3.14.7 + upgraded deps (Flask 2.3.3/Werkzeug 2.3.7/Flask-Session 0.8.0), startup only
• Not verified: Python 3.12/3.13 (ast.Str still exists but deprecated, may work with deprecation warnings)
• Python 3.14 install: pip install -r requirements.txt, then pip install Flask==2.3.3 Werkzeug==2.3.7 Flask-Session==0.8.0 (overrides venv packages only, does NOT modify requirements.txt)

Changes (v8)

• Fixed web entry status=evaluated description: no longer claims AI+sandbox both completed; clarified it means evaluation flow finished, sandbox execution depends on test case config
• Added detailed sandbox_status field meanings: None (no test cases), passed/partial/failed, compile_error, unavailable
• Added scoring rules for each branch: no test cases (AI score), has test cases (pass rate override), compile error (capped), sandbox exception (keeps AI score)
• Updated flow diagram: sandbox step marked as conditional (if test_cases), status=evaluated marked as regardless of sandbox
• Noted code inconsistency: submission_tasks.py:175 checks status==error but sandbox_runner returns compile_error

Previous changes

• v7: Clarified scoring semantics between API (AI-only) and web (AI+sandbox) entry points, fixed architecture diagram
• v6: Fixed async eval order inconsistency, clarified pip upgrade does not modify requirements.txt
• v5: Fixed ast.Str removal timeline (deprecated 3.12, removed 3.14), marked 3.12/3.13 as not verified
• v4: Fixed Python 3.14 install steps, marked RQ as unimplemented, unified /api/submit sync description
• v3: Fixed core factual error - /api/submit is synchronous, distinguished API sync vs web async entry points
• v2: Fixed model count (18 db.Model), test count (43 test_*.py)

[XiaoCow666]

需要先修正核心提交流程：当前 routes/api.py::submit_code 是同步路径，会直接调用 evaluate_cpp_code 并在 HTTP 请求内更新 Submission；异步沙箱路径是 routes/assignments.py::submit_code -> tasks/submission_tasks.evaluate_submission_async。文档当前把 /api/submit 画成异步沙箱主链，会误导接管者。另，models.py 当前有 18 个模型类而文档写 16 张表，tests 当前按 test_*.py 统计为 43 个而文档写 50+，请修正或明确统计口径。GitHub 上当前 PR description 显示为大量问号/乱码，请重新用 UTF-8 补充 PR 说明（AI 工具、阅读范围、验证命令/结果、未验证事项和风险）。

[XiaoCow666]

复审（当前 head: 1601355）：仍需修改，暂不通过。

当前 PR body 的交付说明已经比上一版完整，但文档仍有一个会影响接管的核心事实错误：它把 /api/submit 描述为异步提交主链。当前 main 的 routes/api.py::submit_code() 在默认 thread 配置下会在请求内直接调用 evaluate_cpp_code()；只有 SUBMISSION_EVALUATION_QUEUE_BACKEND=RQ 时才进入排队分支。异步网页提交入口是 routes/assignments.py::submit_code()，不是无条件的 /api/submit。

请修正流程图、文字和验证结论，明确默认配置与 RQ 配置的差异，并重新核对相关行号/函数名。修正后再申请复审。

[XiaoCow666]

• P2｜§4.1 本地运行：安装步骤无法复现文档声称的验证环境。 文档声明 Python 3.14 需要 Flask 2.3.3、Werkzeug 2.3.7、Flask-Session 0.8.0，但唯一安装命令是 pip install -r requirements.txt；§5.1 又明确该文件固定的是 2.2.3、2.2.3、0.4.0，并称直接运行会报错。影响：使用 Python 3.14 的读者按步骤操作，会安装文档已指出不兼容的依赖，无法复现启动结果。建议：在启动步骤中补充实际验证使用的依赖覆盖命令和安装顺序，明确其属于临时兼容方案；或将步骤限定到已验证可直接使用现有 requirements 的 Python 版本，并把 3.14 验证单独说明。

审查仅依据提供的元数据和 diff，未执行命令或核验仓库源码。

[XiaoCow666]

1. [P2] 提交 API 的执行模式与 PR 验证结论相反（docs/architecture-analysis.md §3.1）

   • 问题：正文明确称 /api/submit 同步评测、响应包含最终得分且无需轮询；PR 的 Verification 和 Changes 却称该接口异步返回 submission_id。提供的 diff 不含路由实现，无法判断哪一方正确。
   • 影响：这是核心接口契约，会直接影响前端结果处理、超时设置和架构理解。
   • 建议：针对同一源码版本核实调用链及响应结构，统一正文与 PR 描述，并提供对应版本的代码定位或请求/响应证据。

2. [P2] 启动步骤无法复现文档声称的 Python 3.14 验证环境（docs/architecture-analysis.md §4.1、§5.1 第 3 项）

   • 问题：文档称 Python 3.14 必须升级三个依赖才能启动，同时说明 requirements.txt 固定的是旧版本；启动步骤却只有 pip install -r requirements.txt，遗漏实际验证时的升级操作。
   • 影响：按文档在所述环境安装会得到文档自己指出无法运行的依赖组合，无法复现启动成功的结论。
   • 建议：补全验证环境所用的安装命令、准确版本及操作顺序，或将默认启动步骤限定到已验证可使用原始依赖的 Python 版本。

以上仅依据提供的元数据和 diff，未调用工具或执行验证。

[XiaoCow666]

仅依据提供的 diff 审查，未执行代码或验证仓库内容。

1. [P2] RQ 配置说明与“未实现”结论矛盾（docs/architecture-analysis.md，3.1“默认配置与队列后端差异”）

   • 问题：表格给出 SUBMISSION_EVALUATION_QUEUE_BACKEND=RQ 配置，并描述独立 worker、持久化与重试能力，但末行明确表示代码没有实际 RQ 分支。
   • 影响：读者可能误认为设置该变量即可启用外部队列，并据此错误判断重启后的任务可靠性。
   • 建议：将 RQ 列明确标为“未来方案，当前不可启用”，删除可直接启用的配置说明；持久化与重试应写成需要另行实现和配置的能力。

2. [P2] 安装步骤无法复现文档宣称的 Python 3.14 验证环境（docs/architecture-analysis.md，4.1 与 5.1 第 3 项）

   • 问题：文档称 Python 3.14 必须升级三个依赖，同时说明 requirements.txt 固定了旧版本；启动步骤却只有 pip install -r requirements.txt，随后宣称完成这些步骤即可成功启动。
   • 影响：使用 Python 3.14 的读者按步骤操作仍会安装文档所称存在兼容性问题的版本，无法复现运行结果。
   • 建议：补充实际验证使用的完整安装命令、依赖覆盖步骤和准确的解释器版本，或将快速开始限定为原始依赖已验证支持的 Python 版本，并单列 Python 3.14 的验证流程。

[XiaoCow666]

发现 1 项需修正的问题：

• P2｜docs/architecture-analysis.md §4.1、§5.1「Python 版本兼容性」：错误地将 ast.Str 的移除时间写为 Python 3.12。 ast.Str 在 Python 3.12 中被弃用，在 Python 3.14 中才被移除。因此，文中以该原因断言所有 Python 3.12+ 环境都会出现 AttributeError，并建议统一升级依赖或仅声明支持 3.10/3.11，依据不成立。
  • 影响：使用 Python 3.12/3.13 的读者可能被误导，进行不必要的依赖覆盖安装；项目支持范围也会被错误收窄。
  • 修复建议：将该移除原因限定为 Python 3.14；将 Python 3.12/3.13 标为未验证，除非补充对应验证证据。同步修改环境要求、兼容性说明、风险和升级建议，区分“已验证可运行”与“项目正式支持”。

本次仅审查提供的元数据和 diff，未调用工具或执行代码；无法独立确认源码行号、模块数量及运行验证声明。

[XiaoCow666]

仅依据提供的元数据和 diff 审查，未调用工具或执行验证。发现两处非阻断性文档问题：

1. [P3] 异步评测执行顺序前后矛盾（docs/architecture-analysis.md §2.7、§3.1）

   • 问题：§2.7 描述为“编译→运行测试→AI 评估”，§3.1 则为先调用 evaluate_cpp_code()，再调用 run_test_cases()。
   • 影响：读者无法确定实际执行顺序，可能误判评测延迟来源及分数覆盖关系。
   • 建议：按实际调用顺序统一描述；若 §3.1 准确，将 §2.7 改为“AI 基础评估→沙箱测试→按测试结果覆盖分数→更新统计”。

2. [P3] pip 升级对依赖文件的影响表述不准确（§4.1 Python 3.14 兼容流程，第 3 步）

   • 问题：注释称覆盖安装“会修改 requirements.txt 锁定的版本”，容易被理解为命令会修改文件；该命令只改变当前环境中的已安装版本。
   • 影响：读者可能误以为兼容版本已保存，后续按 requirements.txt 重建环境时仍安装原版本。
   • 建议：改为“覆盖当前虚拟环境中的三个依赖版本，不修改 requirements.txt；重建环境需重复此步骤”。

[XiaoCow666]

仅依据所给 diff 审查，未执行代码或核验仓库；未发现可据此确认的阻断问题。

• [P2] §1.1、§3.1：明确两个提交入口的评分语义差异。 问题：项目定位将“受限编译运行”描述为统一流程，但 §3.1 的 API 路径仅列出启发式与 LLM 评分，网页路径才列出沙箱测试及分数覆盖。目前只强调同步／异步差异，未明确 API 的 status="evaluated" 是否代表经过编译和测试。影响：接入方可能把 API 评分误认为测试用例通过情况，并预期两个入口产生相同成绩。建议：根据源码核实后，在两个入口旁明确列出是否编译运行、评分依据，以及 evaluated 的含义；同步收窄 §1.1 的统一流程描述。

• [P3] §2.1：分层图与后文调用关系不一致。 问题：图中串联 utils → tasks → models，但 §3.1 明确描述 API 路由直接创建模型并同步调用评测，网页路由直接启动任务。影响：读者容易误以为所有数据库访问或评测都经过异步任务层。建议：将模型标为路由／服务／任务共享的数据访问层，并将异步任务画成可选执行分支。

[XiaoCow666]

仅依据提供的 diff 审查，未执行工具或核验仓库源码。

• P2｜§3.1 网页入口的完成状态描述过于绝对
  问题：文档将 status="evaluated" 解释为“AI 评估 + 沙箱测试均已完成”，但同节也描述了无测试用例、编译错误等分支。评测流程结束不能直接说明测试用例已经执行。
  影响：接入方可能仅凭 evaluated 就向学生展示“已完成编译和测试”，误解最终分数的依据。
  建议：改为“评测流程已结束，具体编译和测试执行情况以 sandbox_status 等字段为准”，并补充无用例、编译失败时的字段含义及评分规则。核对这两个分支的返回数据即可验证描述是否准确。

[XiaoCow666]

仅依据提供的 diff 审查，未执行工具或验证仓库代码。

1. [P2] 编译失败的评分规则存在自相矛盾（docs/architecture-analysis.md，§3.1 网页入口“评分依据”）
   • 问题：文档断言 sandbox_status="compile_error" 时“分数受限”，但同一句又说明限分分支判断的是 status=="error"，实际返回值为 "compile_error"。按文档给出的条件，无法得出编译失败会触发最高 1 分限制的结论；最终得分还取决于此前 total > 0 分支是否覆盖 AI 分数。
   • 影响：读者会误以为系统已实现编译失败限分，进而错误理解成绩计算及异常处理行为。
   • 修复建议：删除“编译错误时分数受限”的确定性描述，明确返回值不匹配导致该限分分支无法匹配 compile_error。依据编译失败返回的 passed、total 和条件分支顺序补充实际得分规则；若尚未核实，标为待确认。此 PR 可仅修正文档，无需同时修改业务代码。