3b75170862
- K4周日1900班第12课《花朵随心画》课评（梁境城、钟嘉逸、王睿意补课） - AICODE03/CSP03各班级第12课课评及班级总结 - 更新多班级学生画像 - 课评生成技能优化
153 lines
4.5 KiB
Markdown
153 lines
4.5 KiB
Markdown
# OJ 数据 API 使用说明
|
||
|
||
> 本文档面向所有老师，介绍如何通过 Claude Code 快速获取学生的 OJ 做题数据（含源代码和错误详情）。
|
||
|
||
## 一句话总结
|
||
|
||
在 Claude Code 对话中输入 **"获取 CSP05-02 的OJ数据"**，系统自动调 API 拉取、分析、保存结果。
|
||
|
||
---
|
||
|
||
## 前提条件
|
||
|
||
1. 项目根目录有 `.env` 文件，包含 OJ 登录凭据：
|
||
|
||
```ini
|
||
OJ_BASE_URL=https://oj.qonnwolf.com
|
||
OJ_USERNAME=你的用户名
|
||
OJ_PASSWORD=你的密码
|
||
```
|
||
|
||
2. OJ 插件 `HydroOJ-Course-Keli365` 已部署（目前已在 oj.qonnwolf.com 上运行）
|
||
|
||
---
|
||
|
||
## 使用方式
|
||
|
||
### 方式1：直接对话（推荐）
|
||
|
||
在 Claude Code 中输入：
|
||
|
||
```
|
||
获取 CSP05-02 的OJ数据
|
||
```
|
||
|
||
系统自动完成：登录 OJ → 找到课程 → 找到课次 → 拉取全部学生数据 → 保存分析结果。
|
||
|
||
### 方式2：指定班级筛选
|
||
|
||
```
|
||
获取 CSP05-02 的OJ数据，只看 CSP05克力周六1600 班的
|
||
```
|
||
|
||
### 方式3：不指定课次，列出所有可选课次
|
||
|
||
```
|
||
获取 CSP05 的OJ数据
|
||
```
|
||
|
||
系统会先展示 CSP05 下所有课次列表，你选择要分析哪一个。
|
||
|
||
---
|
||
|
||
## 能获取到什么数据
|
||
|
||
对**每个学生**在**每道题**上，API 返回：
|
||
|
||
| 数据 | 说明 | 举例 |
|
||
|------|------|------|
|
||
| 完成状态 | AC=通过，WA=答案错误，RE=运行错误等 | AC |
|
||
| 分数 | 0-100 分 | 100 |
|
||
| 提交次数 | 该学生这道题总共提交了几次 | 3 |
|
||
| 源代码 | 学生提交的完整代码 | `#include <bits/stdc++.h>...` |
|
||
| 编译错误 | 代码编译失败时的错误信息 | `expected ';' after expression` |
|
||
| 测试点详情 | 每个测试点的通过/失败情况 | 测试点1: AC, 测试点2: WA |
|
||
| 提交历史 | 每次提交的变化轨迹 | 第1次WA→第2次WA→第3次AC |
|
||
|
||
### 作业包分类
|
||
|
||
数据按三个作业包分别统计：
|
||
|
||
| 作业包 | 含义 | 常见题量 |
|
||
|--------|------|----------|
|
||
| 课堂练习 | 课上完成的题 | 3-5 题 |
|
||
| 课后作业 | 课后做的题 | 2-3 题 |
|
||
| 拓展练习 | 选做的挑战题 | 5-7 题 |
|
||
|
||
---
|
||
|
||
## 数据保存在哪里
|
||
|
||
```
|
||
.claude/memory/oj/analysis/
|
||
├── CSP05-02_student_analysis.json ← 原始数据（API 返回的完整 JSON）
|
||
└── CSP05-02_analysis.md ← AI 分析报告（可选）
|
||
```
|
||
|
||
**重要**：数据保存后，后续生成课评时会自动读取，不需要重复获取。
|
||
|
||
---
|
||
|
||
## 手动调 API（给开发者参考）
|
||
|
||
如果不用 Claude Code，也可以直接用 Python 调 API：
|
||
|
||
```python
|
||
import httpx
|
||
from pathlib import Path
|
||
|
||
# 1. 读取凭据
|
||
env = {}
|
||
for line in Path('.env').read_text().split('\n'):
|
||
if '=' in line and not line.startswith('#'):
|
||
k, v = line.split('=', 1)
|
||
env[k] = v
|
||
|
||
# 2. 登录
|
||
client = httpx.Client(base_url=env['OJ_BASE_URL'], follow_redirects=True)
|
||
client.post('/login', json={"uname": env['OJ_USERNAME'], "password": env['OJ_PASSWORD']})
|
||
|
||
# 3. 获取课程列表
|
||
r = client.get('/course/api/list')
|
||
print(r.json())
|
||
|
||
# 4. 获取课程详情（替换 {cid} 为实际课程 ID）
|
||
r = client.get(f'/course/api/detail/{cid}')
|
||
print(r.json())
|
||
|
||
# 5. 获取章节分析（替换 {cid} 和 {csid}）
|
||
r = client.get(f'/course/api/analysis/{cid}/{csid}?withHistory=true')
|
||
print(r.json())
|
||
```
|
||
|
||
### 三个 API 端点
|
||
|
||
| 端点 | 用途 | 说明 |
|
||
|------|------|------|
|
||
| `GET /course/api/list` | 课程列表 | 返回所有课程的标题、ID、人数 |
|
||
| `GET /course/api/detail/{课程ID}` | 课程详情 | 返回所有课次的标题和 ID |
|
||
| `GET /course/api/analysis/{课程ID}/{课次ID}` | 学生分析 | 返回每个学生每道题的完整数据 |
|
||
|
||
### 可选参数
|
||
|
||
| 参数 | 默认值 | 说明 |
|
||
|------|--------|------|
|
||
| `withCode` | true | 设为 false 跳过源代码，只返回状态（速度快） |
|
||
| `withHistory` | false | 设为 true 获取全部提交历史（含每次提交的代码和错误） |
|
||
|
||
---
|
||
|
||
## 常见问题
|
||
|
||
**Q：课程代码怎么填？**
|
||
A：就是 OJ 上的课程编号，比如 CSP05-02、CSP06-05。跟大纲编号可能不一样，以 OJ 实际的为准。
|
||
|
||
**Q：提示"未找到课程"怎么办？**
|
||
A：可能是阶段名不匹配。试试只说"获取 OJ 数据"，系统会列出所有可用课程让你选。
|
||
|
||
**Q：数据太多，等很久怎么办？**
|
||
A：如果班级学生多（15人以上），获取源代码会比较慢。可以加 `withCode=false` 只获取状态，速度快很多。
|
||
|
||
**Q：数据多久更新一次？**
|
||
A：每次调用 API 都是实时获取最新数据。但课评生成时会优先使用已保存的 JSON，避免重复请求。需要刷新时重新获取即可。
|