xuyue/ojnext

Fork 0

Files

yuetsh 2c31acaba7

Deploy / deploy (push) Has been cancelled

Details

流程图的功能

2025-10-13 01:38:54 +08:00

21 KiB

Raw Blame History

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

使用场景:

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

实现位置:

页面: 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 = 从未提交 ⭕

前端实现：

// 仅需一个计算属性即可判断
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（特殊令牌，非用户认证）

报告的数据：

{
  "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) - 流程结束，红色主题

核心功能:

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

数据格式:

// 节点数据
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
}