作业批改系统回顾（基于AI生成）

本系统旨在利用AI技术自动化学生报告的批改流程，打通从文件上传、AI批改、成绩记录到结果下载的完整工作流。系统核心围绕 WordPress 平台、Cloudflare R2 对象存储和自定义的 Python Worker 脚本构建。

前端: WordPress 平台，提供用户界面（UI）和基本的业务逻辑。
后端:
- WordPress PHP: 处理前端请求，与数据库交互，并作为后台任务的调度器。
- Python Worker: 独立运行的后台脚本，负责实际的AI批改和文件处理。
数据库: WordPress 数据库（MySQL），用于存储学生名单、任务状态等信息。
文件存储: Cloudflare R2，提供高可靠、低成本的对象存储服务，用于存放原始报告和批改后的报告。
核心技术:
- Python: 后台 Worker 脚本语言。
- PHP: WordPress 插件和主题开发语言。
- Google Gemini API: 提供AI批改的核心能力。
- AWS SDK for PHP/Python: 用于与 Cloudflare R2 的交互。
- python-docx: 用于处理和编辑 Word 文档。
- openpyxl: 用于读写 Excel 文件以更新成绩。
- phpserialize: 用于在 PHP 和 Python 之间传递序列化的数据。

解耦: 采用前端（WordPress）和后端（Python Worker）分离的架构。前端只负责触发任务和查询状态，实际的重量级任务在独立的 Worker 中异步执行。这避免了因长时间运行任务导致前端请求超时。
状态管理: 使用 WordPress 数据库中的 _transient 机制来存储和管理批改任务的状态（pending -> processing -> completed）。这确保了任务状态的持久性，即使 Worker 意外中断，任务信息也不会丢失。
文件处理: 采用内存友好的流式处理。为了避免 memory_limit 错误，Python Worker 脚本不将整个文件加载到内存，而是使用 SaveAs 参数将 R2 文件流式传输到本地临时文件，再用 addFile 从临时文件流式传输到 ZIP 包。
安全性: 对所有前端输入（如学号）进行 sanitize_text_field() 清理，防止代码注入。R2 的访问凭证应妥善保存在服务器环境变量中，而不是硬编码。

错误处理: 尽管我们加入了 try...catch 和 finally 块，但对致命错误的捕获仍然有限。未来可以考虑使用更健壮的错误监控工具。
用户体验: 批改过程目前没有进度条。可以引入 WebSockets 或 AJAX 长轮询来实时更新前端进度。
通用性: 目前系统是为“报告”设计的。可以通过在前端添加配置选项，让用户自定义文档类型（如 quiz或 exp1），使 Worker 更加通用。
多任务处理: 当前 Worker 是单进程的。未来可以引入多线程或消息队列（如 RabbitMQ）来并行处理多个批改任务。
Gemini API: 目前的提示词是静态的。可以考虑让老师自定义批改提示词，以适应不同类型的作业。

服务器环境: 需确保服务器上已安装 PHP, Python 3, pip。
软件依赖:
- PHP: mysqli 扩展。
- Python: pip install pymysql boto3 phpserialize docx openpyxl google-generativeai.
部署:
- 将 Python Worker 脚本上传至服务器。
- 使用 nohup 或 tmux 命令在后台运行 Worker。

无法下载/上传文件:
- 症状: Python Worker 日志中出现 R2 ClientError 或 404 Not Found。
- 可能原因: R2 凭证错误、Bucket 名称错误、文件不存在。
- 诊断: 检查 aws_config 中的凭证和 Bucket 名称。检查 R2 控制台，确认文件是否存在。
memory_limit 错误:
- 症状: PHP 页面或 Worker 日志中出现 Allowed memory size exhausted...。
- 可能原因: 正在处理的文件过大，或者 php.ini 的 memory_limit 值太低。
- 诊断: 确认 wp-config.php 中的 WP_MEMORY_LIMIT 值是否足够大，或检查你的 PHP 代码是否还在使用 addFromString。
ZipArchive::close() 错误:
- 症状: 即使是小文件下载也出现该错误。
- 可能原因: 临时目录权限不足。
- 诊断:
  - 检查 sys_get_temp_dir() 返回的目录权限。
  - 运行 is_writable(sys_get_temp_dir()) 进行确认。
Gemini API 错误:
- 症状: Worker 日志中出现 Error grading document with Gemini API。
- 可能原因: API 密钥错误、网络连接问题、API 响应格式不正确。
- 诊断:
  - 检查 GEMINI_API_KEY 是否正确。
  - 确认服务器可以访问 Gemini API 的 endpoint。
  - 查看 Worker 日志中的原始响应文本，确认是否为预期的 JSON 格式。