# API接口对比分析

## 更新日志

### 最近更新（2025-01-15）
- ✨ **FlowchartEditor 流程图编辑器**：新增完整的流程图编辑功能
  - 基于 Vue Flow 构建的流程图编辑器组件
  - 支持7种节点类型：开始、输入、处理、判断、循环、输出、结束
  - 完整的拖拽创建、节点连接、编辑功能
  - 撤销重做、自动保存、键盘快捷键支持
  - 模块化设计，包含9个独立的功能模块
- 🎨 **前端组件优化**：完善了组件文档和项目结构说明
  - 更新了 README.md 中的技术栈和项目结构
  - 创建了详细的 FlowchartEditor 使用文档
  - 优化了开发指南和构建流程说明
- 🔧 **构建工具升级**：从 Vite 迁移到 Rsbuild
  - 使用 Rsbuild 作为新的构建工具
  - 支持多环境构建（test、staging、production）
  - 优化了构建性能和开发体验

### 历史更新（2025-10）
- ✨ **AI分析功能增强**：完善了AI智能分析模块的文档说明
  - 详细说明了4个AI相关接口的功能和参数
  - 新增等级系统说明（S/A/B/C），包含特殊规则
  - 补充了时间范围选择功能
  - 说明了流式响应的实现方式
  - 前端组件从 `WeeklyChart.vue` 升级为 `DurationChart.vue`（混合图表）
- 🔧 **数据缓存优化**：后端AI接口增加了缓存机制，提升性能
- 🐛 **修正等级系统说明**：更正了等级阈值（A级：前35%，B级：前75%），并补充了小规模参与惩罚规则

---

## 一、前端已使用的API接口

### 1. 用户认证相关（shared/api.ts）
- `POST /api/login` - 用户登录
- `POST /api/register` - 用户注册
- `GET /api/logout` - 用户登出
- `GET /api/profile` - 获取用户资料
- `GET /api/captcha` - 获取验证码

### 2. OJ普通用户API（oj/api.ts）
#### 2.1 网站配置
- `GET /api/website` - 获取网站配置
- `GET /api/hitokoto` - 获取一言

#### 2.2 题目相关
- `GET /api/problem` - 获取题目列表
- `GET /api/problem` - 获取单个题目
- `GET /api/problem/tags` - 获取题目标签列表
- `GET /api/problem/author` - 获取题目作者列表
- `GET /api/problem/beat_count` - 获取题目击败率
- `GET /api/pickone` - 随机获取题目
- `GET /api/contest/problem` - 获取竞赛题目

#### 2.3 提交相关
- `GET /api/submission` - 获取单个提交
- `POST /api/submission` - 提交代码
- `GET /api/submissions` - 获取提交列表
- `GET /api/submissions/today_count` - 获取今日提交数
- `GET /api/contest_submissions` - 获取竞赛提交列表

#### 2.4 排名相关
- `GET /api/user_rank` - 获取用户排名
- `GET /api/user_activity_rank` - 获取活跃度排名
- `GET /api/user_problem_rank` - 获取题目排名
- `GET /api/contest_rank` - 获取竞赛排名

#### 2.5 竞赛相关
- `GET /api/contests` - 获取竞赛列表
- `GET /api/contest` - 获取单个竞赛
- `GET /api/contest/access` - 获取竞赛访问权限
- `POST /api/contest/password` - 验证竞赛密码

#### 2.6 公告相关
- `GET /api/announcement` - 获取公告列表/单个公告

#### 2.7 消息相关
- `POST /api/message` - 创建消息
- `GET /api/message` - 获取消息列表

#### 2.8 评论相关
- `POST /api/comment` - 创建评论
- `GET /api/comment` - 获取评论
- `GET /api/comment/statistics` - 获取评论统计

#### 2.9 用户相关
- `POST /api/upload_avatar` - 上传头像
- `PUT /api/profile` - 更新用户资料
- `GET /api/profile/fresh_display_id` - 刷新用户题目显示ID
- `GET /api/metrics` - 获取用户统计数据

#### 2.10 教程相关
- `GET /api/tutorial` - 获取单个教程
- `GET /api/tutorials` - 获取教程列表

#### 2.11 AI分析相关
- `GET /api/ai/detail` - 获取用户详细数据
  - **参数**: start, end（时间范围）
  - **返回**: 用户等级(S/A/B/C)、已解决题目列表、标签统计、难度统计、参赛次数等
  - **特点**: 包含班级排名对比，计算每道题的解题排名和等级
- `GET /api/ai/duration` - 获取时段数据
  - **参数**: end（结束时间）, duration（时间单位，如 "months:6", "weeks:1"）
  - **返回**: 每周/每月的综合情况（题目数、提交数、等级）
  - **用途**: 用于绘制时间趋势图，展示学习进度变化
- `GET /api/ai/heatmap` - 获取热力图数据
  - **返回**: 用户的提交热力图数据（按日期统计提交数）
  - **用途**: 可视化用户活跃度分布
- `POST /api/ai/analysis` - AI智能分析生成
  - **请求体**: details（详细数据）, duration（时段数据）
  - **响应方式**: 流式响应（Server-Sent Events）
  - **AI提供商**: DeepSeek
  - **功能**: 根据用户学习数据生成个性化学习建议和鼓励
  - **实现**: 使用fetch直接调用，在 `oj/store/ai.ts` 中处理流式输出

### 3. 管理员API（admin/api.ts）
#### 3.1 仪表板
- `GET /api/admin/dashboard_info` - 获取仪表板信息
- `GET /api/admin/random_user` - 随机获取用户

#### 3.2 题目管理
- `GET /api/admin/problem` - 获取题目列表/单个题目
- `POST /api/admin/problem` - 创建题目
- `PUT /api/admin/problem` - 编辑题目
- `PUT /api/admin/problem/visible` - 切换题目可见性
- `DELETE /api/admin/problem` - 删除题目
- `GET /api/admin/contest/problem` - 获取竞赛题目
- `POST /api/admin/contest/problem` - 创建竞赛题目
- `PUT /api/admin/contest/problem` - 编辑竞赛题目
- `DELETE /api/admin/contest/problem` - 删除竞赛题目
- `POST /api/admin/contest/add_problem_from_public` - 从公开题库添加题目到竞赛

#### 3.3 用户管理
- `GET /api/admin/user` - 获取用户列表
- `POST /api/admin/user` - 导入用户
- `PUT /api/admin/user` - 编辑用户
- `DELETE /api/admin/user` - 删除用户
- `POST /api/admin/reset_password` - 重置用户密码

#### 3.4 竞赛管理
- `GET /api/admin/contest` - 获取竞赛列表/单个竞赛
- `POST /api/admin/contest` - 创建竞赛
- `PUT /api/admin/contest` - 编辑竞赛
- `GET /api/admin/contest/acm_helper` - 获取ACM比赛辅助检查列表
- `PUT /api/admin/contest/acm_helper` - 更新ACM比赛辅助检查状态

#### 3.5 测试用例管理
- `POST /api/admin/test_case` - 上传测试用例
- `GET /api/admin/prune_test_case` - 列出无效测试用例
- `DELETE /api/admin/prune_test_case` - 清理无效测试用例

#### 3.6 题目管理扩展
- `POST /api/admin/contest_problem/make_public` - 将竞赛题目转为公开题目

#### 3.7 判题服务器管理
- `GET /api/admin/judge_server` - 获取判题服务器列表
- `DELETE /api/admin/judge_server` - 删除判题服务器

#### 3.8 公告管理
- `GET /api/admin/announcement` - 获取公告列表/单个公告
- `POST /api/admin/announcement` - 创建公告
- `PUT /api/admin/announcement` - 编辑公告
- `DELETE /api/admin/announcement` - 删除公告

#### 3.9 评论管理
- `GET /api/admin/comment` - 获取评论列表
- `DELETE /api/admin/comment` - 删除评论

#### 3.10 网站配置
- `GET /api/admin/website` - 获取网站配置
- `POST /api/admin/website` - 更新网站配置

#### 3.11 文件上传
- `POST /api/admin/upload_image` - 上传图片（富文本编辑器、Markdown编辑器使用）

#### 3.12 提交管理
- `GET /api/admin/submission/rejudge` - 重新判题
- `GET /api/admin/submission/statistics` - 获取提交统计

#### 3.13 教程管理
- `GET /api/admin/tutorial` - 获取教程列表/单个教程
- `POST /api/admin/tutorial` - 创建教程
- `PUT /api/admin/tutorial` - 更新教程
- `DELETE /api/admin/tutorial` - 删除教程
- `PUT /api/admin/tutorial/visibility` - 设置教程可见性

---

## 二、后端提供但前端未使用的API接口

### 1. 用户认证相关（account）
- `POST /api/change_password` - 修改密码
- `POST /api/change_email` - 修改邮箱
- `POST /api/apply_reset_password` - 申请重置密码
- `POST /api/reset_password` - 重置密码
- `GET /api/check_username_or_email` - 检查用户名或邮箱是否存在
- `GET /api/tfa_required` - 检查是否需要双因素认证
- `POST /api/two_factor_auth` - 双因素认证
- `GET /api/sessions` - 会话管理
- `GET /api/open_api_appkey` - OpenAPI密钥管理
- `GET /api/sso` - 单点登录

### 2. 用户管理（admin）
- `GET /api/admin/generate_user` - 生成用户

### 3. 网站配置相关
- `GET /api/languages` - 获取支持的编程语言列表

### 4. 判题服务器内部接口（不需要前端实现）
- ❌ `POST /api/judge_server_heartbeat/` - 判题服务器心跳
  - **标记为不需要**
  - **原因**: 此接口由 JudgeServer Docker 容器调用，用于向后端报告服务器状态
  - **使用方**: 判题服务器（非前端）
  - **数据内容**: hostname, judger_version, CPU/内存使用率等
  - **认证方式**: 使用特殊的 judge_server_token，非用户认证

### 5. 管理员配置相关
- `GET /api/admin/smtp` - SMTP配置
- `POST /api/admin/smtp_test` - SMTP测试
- `GET /api/admin/versions` - 版本信息

### 6. 题目管理相关（admin）
- `POST /api/admin/export_problem` - 导出题目
- `POST /api/admin/import_problem` - 导入题目
- `POST /api/admin/import_fps` - 导入FPS格式题目

### 7. 竞赛相关（admin）
- `GET /api/contest/announcement` - 获取竞赛公告列表（OJ端）
- `GET /api/admin/contest/announcement` - 获取竞赛公告（管理端）
- `GET /api/admin/download_submissions` - 下载竞赛提交

### 8. 提交相关（不必要的接口）
- ❌ `GET /api/submission_exists` - 检查提交是否存在
  - **标记为不需要**
  - **原因**: 题目接口返回的 `my_status` 字段已完整包含此信息
  - **替代方案**: 直接判断 `my_status` 的值（0=已通过，非零=已尝试未通过，null=未尝试）
  - **优势**: 零额外请求，性能更优

### 9. 文件上传相关（admin）
- `POST /api/admin/upload_file` - 上传文件（任意格式）
  - **说明**: 前端已使用 `upload_image`（仅图片），`upload_file` 可上传任意文件
  - **当前状态**: 未使用（前端暂无上传非图片文件的需求）
  - **潜在场景**: 题目附件、教程资料、作业提交等

---

## 三、统计总结

### 前端已使用接口统计
- **OJ普通用户接口**: 38个（包括1个直接用fetch调用的流式接口）
- **管理员接口**: 35个
- **共享接口**: 5个
- **总计**: 78个API调用

### 后端未被使用接口统计
- **用户认证相关**: 10个
- **网站配置相关**: 2个（languages）
- **题目管理相关**: 3个
- **竞赛管理相关**: 3个
- **其他**: 1个
- **标记为不需要**: 2个
  - submission_exists（数据冗余）
  - judge_server_heartbeat（内部接口）
- **总计**: 21个API端点（其中2个不需要前端实现）

### 未使用接口占比
约 **21%** 的后端API接口前端尚未使用
- **需要考虑实现**: 19个接口
- **不必要实现**: 2个接口（submission_exists, judge_server_heartbeat）

**备注**: 本次更新新增了 ACM 比赛辅助检查功能（2个接口），用于赛后人工审核代码。

---

## 四、建议

### 1. 高优先级需要实现的功能
- **密码管理**: change_password, apply_reset_password, reset_password
- **邮箱管理**: change_email
- **用户名/邮箱检查**: check_username_or_email（注册时实时验证）
- **编程语言列表**: languages（显示支持的编程语言）
- **题目导入导出**: export_problem, import_problem（方便题库管理）

### 2. 中等优先级功能
- **双因素认证**: tfa_required, two_factor_auth（增强安全性）
- **会话管理**: sessions（多设备登录管理）
- **竞赛公告**: contest/announcement（OJ端，增强竞赛体验）

### 3. 低优先级功能
- **SSO单点登录**: sso（如需要集成其他系统）
- **OpenAPI**: open_api_appkey（如需要开放API）
- **SMTP配置**: smtp, smtp_test（管理员配置）
- **版本信息**: versions（显示系统版本）
- **FPS导入**: import_fps（特定格式题目导入）
- **文件上传**: upload_file（目前只有图片上传）

### 4. 可选功能
- **生成用户**: generate_user（批量生成测试用户）
- **下载提交**: download_submissions（下载竞赛所有提交）

---

## 五、接口使用率分析

| 模块 | 后端提供 | 前端使用 | 使用率 |
|------|---------|---------|--------|
| 用户认证 | 17 | 7 | 41% |
| 题目管理 | 14 | 11 | 79% |
| 提交管理 | 7 | 6 | 86% |
| 竞赛管理 | 12 | 9 | 75% |
| 公告管理 | 4 | 4 | 100% |
| 评论管理 | 4 | 4 | 100% |
| 消息管理 | 1 | 1 | 100% |
| 教程管理 | 4 | 4 | 100% |
| AI分析 | 4 | 4 | 100% ✅ |
| 配置管理 | 9 | 3 | 33% ⚠️（1个为内部接口） |

**总体使用率约为 79%**（已实现ACM比赛辅助检查功能，竞赛管理使用率提升至75%）

### 特殊说明

#### 1. AI智能分析功能 ✨

**功能概述**: 基于用户的学习数据，使用DeepSeek AI生成个性化的学习分析报告和建议。

**涉及接口**:
- `GET /api/ai/detail` - 获取详细学习数据
- `GET /api/ai/duration` - 获取时段趋势数据
- `GET /api/ai/heatmap` - 获取活跃度热力图
- `POST /api/ai/analysis` - 生成AI分析（流式响应）

**前端实现**:
- **页面**: `src/oj/ai/analysis.vue`
- **Store**: `src/oj/store/ai.ts`
- **组件**: 
  - `DurationChart.vue` - 混合图表（柱状图+折线图），展示题目数、提交数、等级变化
  - `Heatmap.vue` - 提交热力图
  - `Details.vue` - 详细数据展示
  - `AI.vue` - AI分析结果展示（Markdown格式）

**时间范围选择**:
支持多种时间范围：一节课(1小时)、两节课(2小时)、一天、一周、一个月、两个月、半年、一年

**等级系统**:
- **S级**: 排名前10%（卓越水平，约10%的人）
- **A级**: 排名前35%（优秀水平，约25%的人）
- **B级**: 排名前75%（良好水平，约40%的人）
- **C级**: 75%之后（及格水平，约25%的人）
- **特殊规则**: 参与人数少于10人时，S级降为A级，A级降为B级（避免因人少而评级虚高）

**流式接口实现**:
`POST /api/ai/analysis` 使用了**流式响应（Server-Sent Events）**，在 `oj/store/ai.ts` 中直接使用 `fetch` API调用，配合 `consumeJSONEventStream` 工具函数处理流式数据，实现AI内容的实时流式输出。

**数据缓存**:
为提升性能，后端对 `ai/detail` 和 `ai/duration` 接口的返回数据进行了缓存，相同参数的请求会直接返回缓存结果。

#### 2. ACM 比赛辅助检查功能 ✨

**功能说明**: 用于赛后人工审核 ACM 模式比赛的代码，检查是否存在抄袭、作弊等行为。

**涉及接口**:
- `GET /api/admin/contest/acm_helper` - 获取比赛中所有 AC 的提交记录
  - **返回数据**: 用户名、题目ID、AC时间、错误次数、检查状态等
- `PUT /api/admin/contest/acm_helper` - 更新提交的检查状态
  - **参数**: contest_id, rank_id, problem_id, checked

**使用场景**:
1. 管理员进入比赛详情页，点击"审核"按钮进入辅助检查页面
2. 系统展示所有 AC 提交的列表（按用户和题目分组）
3. 管理员可以：
   - 查看每个提交的代码详情
   - 标记已检查的提交
   - 批量标记所有提交为已检查
   - 按用户名、题目、检查状态筛选
4. 实时显示检查进度统计（总计/已检查/未检查）

**实现位置**:
- 页面: `src/admin/contest/helper.vue`
- 路由: `/admin/contest/:contestID/helper`
- API: `src/admin/api.ts` (getACMHelperList, updateACMHelperChecked)

#### 3. 前端不需要的接口 ❌

##### 3.1 数据冗余接口
**`GET /api/submission_exists`** - 此接口**无需实现**

**分析结论**：
- 后端题目接口（`GET /api/problem`）已返回 `my_status` 字段
- `my_status` 完整记录了用户的做题状态：
  - `0` (JudgeStatus.ACCEPTED) = 已通过 ✅
  - `-1` (JudgeStatus.WRONG_ANSWER) = 答案错误 ❌
  - `-2` (JudgeStatus.COMPILE_ERROR) = 编译错误 ❌
  - `1` (JudgeStatus.TIME_LIMIT_EXCEEDED) = 超时 ❌
  - 其他非零值 = 其他失败原因 ❌
  - `null/undefined` = 从未提交 ⭕

**前端实现**：
```typescript
// 仅需一个计算属性即可判断
const hasTriedButNotPassed = computed(() => {
  return problem.value?.my_status !== undefined &&
         problem.value?.my_status !== null &&
         problem.value?.my_status !== 0
})
```

**优势对比**：
| 方案 | API请求 | 代码复杂度 | 性能 |
|------|---------|-----------|------|
| ❌ 使用 submission_exists | +1 | 高（需异步+状态管理） | 慢（额外网络请求） |
| ✅ 使用 my_status | 0 | 低（3行计算属性） | 快（本地计算） |

**经验教训**：
- 实现新功能前应充分了解后端现有数据结构
- 避免创建冗余接口，优先利用现有数据
- 简单的解决方案往往是最好的

---

##### 3.2 内部系统接口
**`POST /api/judge_server_heartbeat/`** - 此接口**无需前端实现**

**接口说明**：
- **用途**: 判题服务器（JudgeServer）向后端报告健康状态
- **调用方**: JudgeServer Docker 容器（非前端）
- **调用频率**: 每隔几秒自动调用一次
- **认证方式**: 使用 `judge_server_token`（特殊令牌，非用户认证）

**报告的数据**：
```python
{
  "hostname": "judge-server-1",
  "judger_version": "2.0.4",
  "cpu_core": 4,
  "cpu": 45.2,           # CPU使用率
  "memory": 60.5,        # 内存使用率
  "service_url": "http://judger:8080"
}
```

**后端使用场景**：
- 监控判题服务器在线状态
- 显示服务器资源使用情况（仅在管理后台显示）
- 负载均衡分配判题任务

**前端已有接口**：
前端查看判题服务器状态使用的是：
- `GET /api/admin/judge_server` - 获取所有判题服务器列表及状态

**结论**：
此接口是系统内部通信接口，前端完全不需要调用。类似的内部接口还可能存在于分布式系统的其他服务间通信中。

---

## 六、新增功能模块

### FlowchartEditor 流程图编辑器 ✨

**功能概述**: 基于 Vue Flow 构建的完整流程图编辑器，支持拖拽创建、节点连接、编辑等核心功能。

**技术实现**:
- **核心库**: Vue Flow (@vue-flow/core)
- **组件架构**: 模块化设计，9个独立功能模块
- **状态管理**: 基于 Vue 3 Composition API
- **数据持久化**: localStorage 自动缓存
- **交互体验**: 拖拽、键盘快捷键、撤销重做

**组件结构**:
```
FlowchartEditor/
├── index.vue              # 主组件 - 整合所有功能
├── CustomNode.vue         # 自定义节点 - 7种节点类型
├── Toolbar.vue            # 工具栏 - 节点创建和操作
├── NodeHandles.vue        # 节点操作手柄 - 连接点管理
├── NodeActions.vue        # 节点动作 - 删除、编辑按钮
├── useCache.ts            # 缓存管理 - 自动保存/恢复
├── useDnD.ts              # 拖拽处理 - 节点创建逻辑
├── useFlowOperations.ts   # 流程操作 - 增删改查
├── useHistory.ts          # 历史记录 - 撤销重做
└── useNodeStyles.ts       # 节点样式 - 类型配置
```

**节点类型支持**:
- **开始节点** (start) - 流程开始，绿色主题
- **输入节点** (input) - 数据输入，蓝色主题
- **处理节点** (default) - 数据处理，紫色主题
- **判断节点** (decision) - 条件判断，橙色主题
- **循环节点** (loop) - 循环处理，青色主题
- **输出节点** (output) - 数据输出，粉色主题
- **结束节点** (end) - 流程结束，红色主题

**核心功能**:
1. **拖拽创建**: 从工具栏拖拽节点到画布
2. **节点连接**: 支持节点间的连线操作
3. **节点编辑**: 双击节点进行文本编辑
4. **撤销重做**: 完整的历史记录管理
5. **自动保存**: 本地缓存，防止数据丢失
6. **键盘快捷键**: Ctrl+Z/Ctrl+Y 撤销重做，Delete 删除
7. **批量操作**: 支持多选和批量删除

**数据格式**:
```typescript
// 节点数据
interface Node {
  id: string
  type: string
  position: { x: number, y: number }
  data: {
    customLabel: string
    [key: string]: any
  }
}

// 边数据
interface Edge {
  id: string
  source: string
  target: string
  sourceHandle?: string
  targetHandle?: string
  type?: string
}
```

**使用场景**:
- 算法流程图绘制
- 业务流程设计
- 教学演示工具
- 问题分析图表

**性能优化**:
- 基于 Vue Flow 的高性能渲染
- 模块化设计，按需加载
- 本地缓存减少重复计算
- 响应式状态管理

**扩展性**:
- 支持自定义节点类型
- 可扩展工具栏功能
- 支持主题定制
- 支持数据导入导出

**文档支持**:
- 详细的使用文档: `docs/FlowchartEditor.md`
- 完整的 API 说明
- 最佳实践指南
- 故障排除手册