feat(阶段1): 搬入 ojnext 为 apps/web，未改业务代码

2026-08-06 21:18:16 -06:00
parent 3c975e85ee
commit ae1fb329b5
258 changed files with 40490 additions and 91 deletions
--- a/apps/web/docs/API接口对比分析.md
+++ b/apps/web/docs/API接口对比分析.md
@@ -0,0 +1,548 @@
+# 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 说明
+- 最佳实践指南
+- 故障排除手册
+
--- a/apps/web/docs/FlowchartEditor.md
+++ b/apps/web/docs/FlowchartEditor.md
@@ -0,0 +1,311 @@
+# FlowchartEditor 流程图编辑器
+
+一个基于 Vue 3 + Vue Flow 构建的功能完整的流程图编辑器组件。
+
+## 功能特性
+
+### 🎯 核心功能
+- **拖拽创建节点** - 从工具栏拖拽节点到画布
+- **节点连接** - 支持节点间的连线操作
+- **节点编辑** - 双击节点进行文本编辑
+- **撤销重做** - 完整的历史记录管理
+- **自动保存** - 本地缓存，防止数据丢失
+- **键盘快捷键** - 支持常用快捷键操作
+
+### 🎨 节点类型
+- **开始节点** (start) - 流程开始
+- **输入节点** (input) - 数据输入
+- **处理节点** (default) - 数据处理
+- **判断节点** (decision) - 条件判断
+- **循环节点** (loop) - 循环处理
+- **输出节点** (output) - 数据输出
+- **结束节点** (end) - 流程结束
+
+### ⌨️ 快捷键
+- `Ctrl+Z` / `Cmd+Z` - 撤销
+- `Ctrl+Y` / `Cmd+Shift+Z` - 重做
+- `Delete` / `Backspace` - 删除选中节点
+
+## 组件结构
+
+```
+FlowchartEditor/
+├── index.vue              # 主组件
+├── CustomNode.vue         # 自定义节点组件
+├── Toolbar.vue            # 工具栏组件
+├── NodeHandles.vue        # 节点操作手柄
+├── NodeActions.vue        # 节点动作按钮
+├── useCache.ts            # 缓存管理
+├── useDnD.ts              # 拖拽处理
+├── useFlowOperations.ts   # 流程操作
+├── useHistory.ts          # 历史记录
+└── useNodeStyles.ts       # 节点样式
+```
+
+## 使用方法
+
+### 基本用法
+
+```vue
+<template>
+  <FlowchartEditor ref="flowchartRef" />
+</template>
+
+<script setup>
+import { ref } from 'vue'
+import FlowchartEditor from '@/shared/components/FlowchartEditor/index.vue'
+
+const flowchartRef = ref()
+
+// 获取流程图数据
+const getFlowchartData = () => {
+  return flowchartRef.value?.getFlowchartData()
+}
+</script>
+```
+
+### 获取流程图数据
+
+```javascript
+// 获取当前流程图数据
+const data = flowchartRef.value.getFlowchartData()
+console.log(data.nodes)  // 节点数组
+console.log(data.edges)  // 边数组
+```
+
+## 组件详解
+
+### 主组件 (index.vue)
+
+主组件负责整合所有功能模块，提供完整的流程图编辑体验。
+
+**主要功能**：
+- 整合 Vue Flow 核心功能
+- 管理节点和边的状态
+- 处理用户交互事件
+- 提供数据暴露接口
+
+**暴露的方法**：
+- `getFlowchartData()` - 获取当前流程图数据
+
+### 自定义节点 (CustomNode.vue)
+
+基于 Vue Flow 的自定义节点组件，支持多种节点类型。
+
+**节点类型配置**：
+- 每种节点类型都有独特的样式和图标
+- 支持自定义标签文本
+- 提供删除和编辑功能
+
+### 工具栏 (Toolbar.vue)
+
+提供节点创建和操作的工具集合。
+
+**功能**：
+- 节点类型选择
+- 撤销/重做操作
+- 清空画布
+- 保存状态显示
+
+### 缓存管理 (useCache.ts)
+
+提供本地存储功能，防止数据丢失。
+
+**功能**：
+- 自动保存到 localStorage
+- 页面刷新后恢复数据
+- 保存状态提示
+- 清空缓存功能
+
+### 拖拽处理 (useDnD.ts)
+
+处理节点拖拽创建的逻辑。
+
+**功能**：
+- 拖拽开始处理
+- 拖拽悬停效果
+- 拖拽放置处理
+- 节点位置计算
+
+### 流程操作 (useFlowOperations.ts)
+
+处理流程图的增删改操作。
+
+**功能**：
+- 节点连接处理
+- 边删除处理
+- 节点删除处理
+- 节点更新处理
+- 清空画布
+
+### 历史记录 (useHistory.ts)
+
+提供撤销重做功能。
+
+**功能**：
+- 状态快照保存
+- 撤销操作
+- 重做操作
+- 历史记录管理
+
+### 节点样式 (useNodeStyles.ts)
+
+定义各种节点类型的样式配置。
+
+**功能**：
+- 节点类型配置
+- 样式定义
+- 图标配置
+- 颜色主题
+
+## 样式定制
+
+### 节点样式
+
+可以通过修改 `useNodeStyles.ts` 来自定义节点样式：
+
+```typescript
+export function getNodeTypeConfig(type: string) {
+  const configs = {
+    start: {
+      label: '开始',
+      icon: 'play-circle',
+      color: '#10b981',
+      // 自定义样式
+    },
+    // 其他节点类型...
+  }
+  
+  return configs[type] || configs.default
+}
+```
+
+### 边样式
+
+边的样式在主组件中定义：
+
+```vue
+:default-edge-options="{
+  type: 'step',
+  style: { 
+    stroke: '#6366f1', 
+    strokeWidth: 2.5, 
+    cursor: 'pointer',
+    filter: 'drop-shadow(0 2px 4px rgba(0,0,0,0.1))'
+  },
+  markerEnd: {
+    type: MarkerType.ArrowClosed,
+    color: '#6366f1',
+    width: 16,
+    height: 16,
+  },
+}"
+```
+
+## 数据格式
+
+### 节点数据格式
+
+```typescript
+interface Node {
+  id: string
+  type: string
+  position: { x: number, y: number }
+  data: {
+    customLabel: string
+    [key: string]: any
+  }
+}
+```
+
+### 边数据格式
+
+```typescript
+interface Edge {
+  id: string
+  source: string
+  target: string
+  sourceHandle?: string
+  targetHandle?: string
+  type?: string
+}
+```
+
+## 最佳实践
+
+### 1. 性能优化
+- 大量节点时考虑虚拟化
+- 合理使用缓存机制
+- 避免频繁的状态更新
+
+### 2. 用户体验
+- 提供清晰的操作反馈
+- 支持键盘快捷键
+- 保持操作的直观性
+
+### 3. 数据管理
+- 定期保存到服务器
+- 提供数据导入导出功能
+- 支持版本控制机制
+
+## 扩展开发
+
+### 添加新节点类型
+
+1. 在 `useNodeStyles.ts` 中添加新类型配置
+2. 在 `Toolbar.vue` 中添加新节点按钮
+3. 在 `CustomNode.vue` 中添加新节点渲染逻辑
+
+### 添加新功能
+
+1. 创建新的 composable 函数
+2. 在主组件中集成新功能
+3. 更新工具栏和用户界面
+
+## 故障排除
+
+### 常见问题
+
+1. **节点无法拖拽**
+   - 检查拖拽事件处理
+   - 确认节点类型配置正确
+
+2. **撤销重做不工作**
+   - 检查历史记录状态
+   - 确认状态保存时机
+
+3. **数据丢失**
+   - 检查缓存配置
+   - 确认 localStorage 可用
+
+### 调试技巧
+
+1. 使用 Vue DevTools 查看组件状态
+2. 检查浏览器控制台错误
+3. 验证数据格式正确性
+
+## 更新日志
+
+### v1.0.0 (2024-01-15)
+- ✨ 初始版本发布
+- 🎯 基础流程图编辑功能
+- 🔧 拖拽创建节点
+- 🔗 节点连接功能
+- ↩️ 撤销重做支持
+- 💾 本地缓存功能
+
+### v1.1.0 (2024-01-20)
+- 🎨 新增多种节点类型
+- ⌨️ 键盘快捷键支持
+- 🖱️ 优化拖拽体验
+- 📱 响应式布局改进
+
+### v1.2.0 (2024-01-25)
+- 🔧 模块化重构
+- 📦 组合式函数优化
+- 🎯 性能提升
+- 🐛 修复已知问题
+
+## 许可证
+
+MIT License
--- a/apps/web/docs/superpowers/plans/2026-06-14-submit-formatting-button-state.md
+++ b/apps/web/docs/superpowers/plans/2026-06-14-submit-formatting-button-state.md
@@ -0,0 +1,259 @@
+# Submit Formatting Button State Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Show `格式化中` on the submit button during automatic formatting, then show `正在提交` continuously while the submission request is pending.
+
+**Architecture:** Extract the button presentation rules into a small pure TypeScript function so the state priority can be tested without adding a frontend test framework. Keep formatter and submission-request flags local to `SubmitCode.vue`, with `finally` blocks ensuring both flags clear on every outcome.
+
+**Tech Stack:** Vue 3 Composition API, TypeScript, Node.js built-in test runner, Rsbuild
+
+---
+
+### Task 1: Define and test submit button presentation rules
+
+**Files:**
+- Create: `tests/submitButtonState.test.ts`
+- Create: `src/oj/problem/components/submitButtonState.ts`
+
+- [ ] **Step 1: Write the failing test**
+
+Create `tests/submitButtonState.test.ts`:
+
+```ts
+import assert from "node:assert/strict"
+import test from "node:test"
+import { getSubmitButtonState } from "../src/oj/problem/components/submitButtonState.ts"
+
+const idleInput = {
+  isAuthed: true,
+  hasCode: true,
+  isFormatting: false,
+  isSubmitting: false,
+  isJudging: false,
+  isCooldown: false,
+}
+
+test("shows a disabled loading state while formatting", () => {
+  assert.deepEqual(
+    getSubmitButtonState({ ...idleInput, isFormatting: true }),
+    {
+      disabled: true,
+      label: "格式化中",
+      icon: "eos-icons:loading",
+    },
+  )
+})
+
+test("shows submitting immediately after formatting", () => {
+  assert.deepEqual(
+    getSubmitButtonState({ ...idleInput, isSubmitting: true }),
+    {
+      disabled: true,
+      label: "正在提交",
+      icon: "eos-icons:loading",
+    },
+  )
+})
+
+test("preserves existing login, judging, cooldown, and idle states", () => {
+  assert.deepEqual(
+    getSubmitButtonState({ ...idleInput, isAuthed: false }),
+    {
+      disabled: true,
+      label: "请先登录",
+      icon: "ph:play-fill",
+    },
+  )
+  assert.deepEqual(getSubmitButtonState({ ...idleInput, isJudging: true }), {
+    disabled: true,
+    label: "正在评分",
+    icon: "eos-icons:loading",
+  })
+  assert.deepEqual(getSubmitButtonState({ ...idleInput, isCooldown: true }), {
+    disabled: true,
+    label: "正在冷却",
+    icon: "ph:lightbulb-fill",
+  })
+  assert.deepEqual(getSubmitButtonState(idleInput), {
+    disabled: false,
+    label: "提交代码",
+    icon: "ph:play-fill",
+  })
+})
+```
+
+- [ ] **Step 2: Run the test to verify it fails**
+
+Run:
+
+```bash
+node --test tests/submitButtonState.test.ts
+```
+
+Expected: FAIL with `ERR_MODULE_NOT_FOUND` for `submitButtonState.ts`.
+
+- [ ] **Step 3: Implement the pure state function**
+
+Create `src/oj/problem/components/submitButtonState.ts`:
+
+```ts
+export interface SubmitButtonStateInput {
+  isAuthed: boolean
+  hasCode: boolean
+  isFormatting: boolean
+  isSubmitting: boolean
+  isJudging: boolean
+  isCooldown: boolean
+}
+
+export interface SubmitButtonState {
+  disabled: boolean
+  label: string
+  icon: string
+}
+
+export function getSubmitButtonState({
+  isAuthed,
+  hasCode,
+  isFormatting,
+  isSubmitting,
+  isJudging,
+  isCooldown,
+}: SubmitButtonStateInput): SubmitButtonState {
+  const disabled =
+    !isAuthed ||
+    !hasCode ||
+    isFormatting ||
+    isSubmitting ||
+    isJudging ||
+    isCooldown
+
+  let label = "提交代码"
+  if (!isAuthed) {
+    label = "请先登录"
+  } else if (isFormatting) {
+    label = "格式化中"
+  } else if (isSubmitting) {
+    label = "正在提交"
+  } else if (isJudging) {
+    label = "正在评分"
+  } else if (isCooldown) {
+    label = "正在冷却"
+  }
+
+  const icon =
+    isFormatting || isSubmitting || isJudging
+      ? "eos-icons:loading"
+      : isCooldown
+        ? "ph:lightbulb-fill"
+        : "ph:play-fill"
+
+  return { disabled, label, icon }
+}
+```
+
+- [ ] **Step 4: Run the test to verify it passes**
+
+Run:
+
+```bash
+node --test tests/submitButtonState.test.ts
+```
+
+Expected: 3 tests pass.
+
+### Task 2: Connect formatting and submission request lifecycle to the button
+
+**Files:**
+- Modify: `src/oj/problem/components/SubmitCode.vue`
+
+- [ ] **Step 1: Add local request states and computed presentation**
+
+Import `getSubmitButtonState`, add `isFormatting` and `isSubmittingRequest` refs, and replace the three existing button computed properties with:
+
+```ts
+const buttonState = computed(() =>
+  getSubmitButtonState({
+    isAuthed: userStore.isAuthed,
+    hasCode: codeStore.code.value.trim() !== "",
+    isFormatting: isFormatting.value,
+    isSubmitting: isSubmittingRequest.value || submitting.value,
+    isJudging: judging.value || pending.value,
+    isCooldown: isCooldown.value,
+  }),
+)
+```
+
+Use `buttonState.disabled`, `buttonState.icon`, and `buttonState.label` in the template.
+
+- [ ] **Step 2: Guard and track the formatting request**
+
+At the start of `submit`, return when `buttonState.value.disabled` is true. Around `formatCode`, set `isFormatting.value = true` before the request and clear it in `finally`:
+
+```ts
+isFormatting.value = true
+try {
+  const res = await formatCode({
+    code: codeStore.code.value,
+    language: formatLang,
+  })
+  codeStore.setCode(res.data.code)
+} catch (e: any) {
+  if (e?.error === "format-error") {
+    message.warning(`代码格式化失败：${e.data}，请检查代码后重试`)
+    return
+  }
+} finally {
+  isFormatting.value = false
+}
+```
+
+- [ ] **Step 3: Track the submission API request**
+
+Set `isSubmittingRequest.value = true` immediately before `submitCode`, keep the existing success flow inside the `try`, and clear the request state in `finally`:
+
+```ts
+isSubmittingRequest.value = true
+try {
+  const res = await submitCode(data)
+  console.log(`[Submit] 代码已提交: ID=${res.data.submission_id}`)
+
+  startCooldown()
+  startMonitoring(res.data.submission_id)
+  showResult.value = true
+} finally {
+  isSubmittingRequest.value = false
+}
+```
+
+- [ ] **Step 4: Run focused tests**
+
+Run:
+
+```bash
+node --test tests/submitButtonState.test.ts
+```
+
+Expected: 3 tests pass.
+
+- [ ] **Step 5: Run the production build**
+
+Run:
+
+```bash
+npm run build
+```
+
+Expected: Rsbuild exits with status 0.
+
+- [ ] **Step 6: Check the final diff**
+
+Run:
+
+```bash
+git diff --check
+git diff -- src/oj/problem/components/SubmitCode.vue src/oj/problem/components/submitButtonState.ts tests/submitButtonState.test.ts
+```
+
+Expected: no whitespace errors; diff is limited to the button state feature and its test.
--- a/apps/web/docs/superpowers/plans/2026-07-26-demo-student-view.md
+++ b/apps/web/docs/superpowers/plans/2026-07-26-demo-student-view.md
@@ -0,0 +1,296 @@
+# 学生视角（演示模式）Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** 超级管理员在右上角下拉菜单点一下，整站界面变成普通学生看到的样子，再点一下恢复。
+
+**Architecture:** 纯前端伪装。全站 40 多处权限判断读的都是 `shared/store/user.ts` 里的 6 个角色 getter，没有一处直接读 `user.admin_type`。在 store 里加一个 `demoMode` 开关，给每个 getter 加 `!demoMode.value &&` 前缀，全站自动跟随。路由守卫（`src/main.ts`）、权限工具（`src/utils/permissions.ts`）、各页面 `v-if` 零改动。
+
+**Tech Stack:** Vue 3 `<script setup>` + TypeScript，Pinia setup store，Naive UI（`n-dropdown` / `DropdownOption`），Vite。
+
+**Spec:** `docs/superpowers/specs/2026-07-26-demo-student-view-design.md`
+
+## Global Constraints
+
+- **不写测试。** 项目根 CLAUDE.md 明确规定 "Do not write new tests"，且 ojnext 无测试框架。本计划的验证步骤全部是 `npm run build` 冒烟 + 浏览器手工核对。
+- **不改后端。** 演示模式是界面伪装，登录态仍是超管，接口权限不变。
+- 仅超级管理员可见此开关。教师管理员、学生管理员不提供。
+- 自动导入已配置：`ref` / `computed` / `useRouter` / `useRoute` / Naive UI 组件与类型（`DropdownOption`）均**不需要手写 import**。
+- 存储 key 常量统一放 `src/utils/constants.ts` 的 `STORAGE_KEY`，读写走 `src/utils/storage.ts` 默认导出（内部做 JSON 序列化）。
+- 提交前跑 `npm fmt`（Prettier）。
+- 中文注释、中文 UI 文案，与现有代码一致。
+
+---
+
+## File Structure
+
+| 文件 | 职责 | 本次改动 |
+|---|---|---|
+| `src/utils/constants.ts` | 全局常量 | `STORAGE_KEY` 增加一个键 |
+| `src/shared/store/user.ts` | 用户身份与角色判断的唯一来源 | 新增 `demoMode` 状态与伪装逻辑（改动主体） |
+| `src/shared/components/Header.vue` | 顶栏与用户下拉菜单 | 新增菜单项与切换处理函数 |
+
+不新建文件。`demoMode` 放进已有的 `user` store 而不是单开一个 store —— 它伪装的就是这个 store 的输出，分开会让两个 store 循环依赖。
+
+---
+
+### Task 1: store 层伪装开关
+
+**Files:**
+- Modify: `src/utils/constants.ts:147-153`
+- Modify: `src/shared/store/user.ts`
+
+**Interfaces:**
+- Consumes: 无（第一个任务）
+- Produces: `useUserStore()` 新增三个成员，供 Task 2 使用：
+  - `demoMode: boolean` — 当前是否处于演示模式（store 解包后为布尔值）
+  - `canToggleDemoMode: boolean` — 是否显示切换入口（真实超管身份，不受伪装影响）
+  - `toggleDemoMode(): void` — 翻转开关并写入 localStorage
+
+- [ ] **Step 1: 在 `STORAGE_KEY` 增加常量**
+
+打开 `src/utils/constants.ts`，把 `STORAGE_KEY` 改成：
+
+```ts
+export const STORAGE_KEY = {
+  AUTHED: "authed",
+  LANGUAGE: "problemLanguage",
+  LEARN_CURRENT_STEP: "learnStep",
+  ADMIN_PROBLEM: "adminProblem",
+  ADMIN_PROBLEM_TAGS: "adminProblemTags",
+  DEMO_MODE: "demoMode",
+}
+```
+
+- [ ] **Step 2: 在 user store 加入 `demoMode` 与真实身份 getter**
+
+打开 `src/shared/store/user.ts`。在 `const isAuthed = ...` 那一行之后、`const isAdminRole = ...` 之前，插入：
+
+```ts
+  // 演示模式：超管临时把界面伪装成普通学生，方便上课投屏
+  const demoMode = ref<boolean>(storage.get(STORAGE_KEY.DEMO_MODE) ?? false)
+
+  // 不受伪装影响的真实身份，只用于判断能否切换演示模式。
+  // 若这里用被伪装后的 isSuperAdmin，一进入演示模式入口就消失了，退不出来。
+  const realIsSuperAdmin = computed(
+    () => user.value?.admin_type === USER_TYPE.SUPER_ADMIN,
+  )
+```
+
+`storage` 和 `STORAGE_KEY` 文件顶部已经 import 过，不需要新增 import。
+
+- [ ] **Step 3: 给 6 个角色 getter 加上伪装前缀**
+
+把 `src/shared/store/user.ts` 中原有的 6 个 getter（`isAdminRole`、`isStudentAdmin`、`isTeacherAdmin`、`isTeacherOrAbove`、`isSuperAdmin`、`hasProblemPermission`）整段替换为：
+
+```ts
+  const isAdminRole = computed(
+    () =>
+      !demoMode.value &&
+      (user.value?.admin_type === USER_TYPE.STUDENT_ADMIN ||
+        user.value?.admin_type === USER_TYPE.TEACHER_ADMIN ||
+        user.value?.admin_type === USER_TYPE.SUPER_ADMIN),
+  )
+  const isStudentAdmin = computed(
+    () => !demoMode.value && user.value?.admin_type === USER_TYPE.STUDENT_ADMIN,
+  )
+  const isTeacherAdmin = computed(
+    () => !demoMode.value && user.value?.admin_type === USER_TYPE.TEACHER_ADMIN,
+  )
+  const isTeacherOrAbove = computed(
+    () =>
+      !demoMode.value &&
+      (user.value?.admin_type === USER_TYPE.TEACHER_ADMIN ||
+        user.value?.admin_type === USER_TYPE.SUPER_ADMIN),
+  )
+  const isSuperAdmin = computed(() => !demoMode.value && realIsSuperAdmin.value)
+  const hasProblemPermission = computed(
+    () =>
+      !demoMode.value &&
+      user.value?.problem_permission !== PROBLEM_PERMISSION.NONE,
+  )
+```
+
+注意：`isAdminRole` 和 `isTeacherOrAbove` 原本是多个 `||` 连成的表达式，加前缀时**必须给原表达式套一层括号**，否则 `&&` 的优先级会让第一个 `||` 分支逃过伪装。
+
+- [ ] **Step 4: 加入切换能力与切换函数**
+
+紧接在 `hasProblemPermission` 之后插入：
+
+```ts
+  const canToggleDemoMode = computed(() => realIsSuperAdmin.value)
+
+  function toggleDemoMode() {
+    demoMode.value = !demoMode.value
+    storage.set(STORAGE_KEY.DEMO_MODE, demoMode.value)
+  }
+```
+
+- [ ] **Step 5: 退出登录时重置内存中的开关**
+
+`storage.clear()` 会清掉 localStorage 里的标记，但内存中的 ref 还留着，同一次会话里换账号登录会带过去。把 `clearProfile` 改成：
+
+```ts
+  function clearProfile() {
+    profile.value = null
+    demoMode.value = false
+    storage.clear()
+  }
+```
+
+- [ ] **Step 6: 导出新成员**
+
+在 store 末尾的 `return { ... }` 里加入三项（放在 `hasProblemPermission` 之后）：
+
+```ts
+    demoMode,
+    canToggleDemoMode,
+    toggleDemoMode,
+```
+
+- [ ] **Step 7: 格式化并冒烟构建**
+
+```bash
+cd ojnext
+npm fmt
+npm run build
+```
+
+Expected: 构建成功，无报错。
+
+- [ ] **Step 8: 手工验证伪装生效（此时还没有 UI 入口，用 localStorage 模拟）**
+
+启动 `npm start`，用超管账号登录，然后在浏览器 DevTools Console 执行：
+
+```js
+localStorage.setItem("demoMode", "true")
+location.reload()
+```
+
+逐项核对：
+- 顶栏「后台」菜单项消失
+- 地址栏直接输入 `/admin` → 被弹回首页
+- 题目详情页不再出现管理员专属按钮
+
+再执行 `localStorage.setItem("demoMode", "false"); location.reload()`，确认上述内容全部恢复。
+
+- [ ] **Step 9: 提交**
+
+```bash
+cd ojnext
+git add src/utils/constants.ts src/shared/store/user.ts
+git commit -m "feat(user): store 层加入演示模式伪装开关
+
+超管开启后所有角色 getter 降级为普通学生，全站权限判断自动跟随。
+realIsSuperAdmin 保留真实身份，用于判断能否切换。"
+```
+
+---
+
+### Task 2: 下拉菜单切换入口
+
+**Files:**
+- Modify: `src/shared/components/Header.vue:109-113`（新增函数）、`:178-227`（`options` 改为 computed 并增加菜单项）
+
+**Interfaces:**
+- Consumes: Task 1 提供的 `userStore.demoMode`、`userStore.canToggleDemoMode`、`userStore.toggleDemoMode()`
+- Produces: 无后续任务依赖
+
+- [ ] **Step 1: 把 `options` 从普通数组改为 computed**
+
+`src/shared/components/Header.vue` 第 178 行现在是：
+
+```ts
+const options: Array<DropdownOption | DropdownDividerOption> = [
+```
+
+改为：
+
+```ts
+const options = computed<Array<DropdownOption | DropdownDividerOption>>(() => [
+```
+
+并把第 227 行的结尾 `]` 改为 `])`。
+
+**这一步是必需的，不是风格偏好**：原来的 `options` 是普通数组，只在 setup 时求值一次。新菜单项的 `label`（「进入演示」/「退出演示」）和 `show` 都要跟随状态变化，留在普通数组里永远不会更新。同文件的 `menus`（第 119 行）本来就是 computed，改完两者一致。
+
+模板里 `:options="options"`（第 280 行）不用动，computed 在模板中自动解包。
+
+- [ ] **Step 2: 加入切换处理函数**
+
+在 `handleLogout`（第 109-113 行）之后插入：
+
+```ts
+function handleToggleDemoMode() {
+  const entering = !userStore.demoMode
+  userStore.toggleDemoMode()
+  // 进入演示模式时若正停在后台页面，当前界面已经失去权限，必须主动退出去
+  if (entering && route.path.startsWith("/admin")) {
+    router.push("/")
+  }
+}
+```
+
+`route` 和 `router` 在第 16-17 行已经拿到，`userStore` 在第 12 行已经拿到，无需新增。
+
+- [ ] **Step 3: 在下拉菜单中加入菜单项**
+
+在 `options` 数组里、`{ type: "divider" }`（第 220 行）**之前**插入：
+
+```ts
+  {
+    label: userStore.demoMode ? "退出演示" : "进入演示",
+    key: "demo-mode",
+    show: userStore.canToggleDemoMode,
+    icon: renderIcon("fluent-emoji:graduation-cap"),
+    props: { onClick: handleToggleDemoMode },
+  },
+```
+
+文案本身就是状态指示器：看到「退出演示」说明当前正处于演示模式。按设计不额外加横幅。
+
+- [ ] **Step 4: 格式化并冒烟构建**
+
+```bash
+cd ojnext
+npm fmt
+npm run build
+```
+
+Expected: 构建成功，无报错。
+
+- [ ] **Step 5: 手工验证完整流程**
+
+先清掉 Task 1 遗留的手工标记：DevTools Console 执行 `localStorage.removeItem("demoMode")`，刷新。
+
+用超管账号登录，逐项核对：
+
+1. 右上角用户名下拉菜单出现「进入演示」，图标正常显示（不是空白方块）
+2. 点击 →「后台」菜单项消失，下拉菜单文案变为「退出演示」
+3. 刷新页面 → 仍是学生界面，菜单仍显示「退出演示」
+4. 地址栏直接输入 `/admin` → 弹回首页
+5. 点「退出演示」→「后台」入口恢复，文案变回「进入演示」
+6. 进入 `/admin/problem/list`，打开下拉菜单点「进入演示」→ 自动跳回首页
+7. 退出登录后重新用超管登录 → 演示模式已重置为关闭状态
+8. 用教师管理员账号登录 → 下拉菜单中**没有**这一项
+
+- [ ] **Step 6: 提交**
+
+```bash
+cd ojnext
+git add src/shared/components/Header.vue
+git commit -m "feat(header): 用户下拉菜单加入学生视角开关
+
+仅超管可见。进入演示模式时若停在后台页面则跳回首页。
+options 改为 computed，否则菜单文案与显示条件不会随状态更新。"
+```
+
+---
+
+## 完成后
+
+两个任务都提交后，整个特性即完成。回读一遍 spec 的「连带影响」章节，确认这些变化在实机上都是预期的：
+
+- 提交列表的教师筛选与额外列消失，`showSubmissions` 改为跟随站点配置
+- 比赛失去超管免密码特权
+- 协同代码编辑（`shared/composables/sync.ts`）的超管特殊颜色与提示一并变为学生行为 —— **已确认不做豁免**
--- a/apps/web/docs/superpowers/specs/2026-06-14-submit-formatting-button-state-design.md
+++ b/apps/web/docs/superpowers/specs/2026-06-14-submit-formatting-button-state-design.md
@@ -0,0 +1,34 @@
+# Submit Formatting Button State
+
+## Goal
+
+Make the code submission button reflect the automatic formatting request that runs before submission.
+
+## Behavior
+
+- For Python3, C, and C++, the button displays `格式化中` while the formatting API request is pending.
+- During formatting, the button uses the existing loading icon and is disabled to prevent duplicate submissions.
+- After formatting succeeds, the existing submission flow continues and the button can display `正在提交`.
+- A formatting error stops submission and clears the formatting state before showing the existing warning.
+- A formatter server or network failure keeps the existing fallback behavior: clear the formatting state and submit the original code.
+- Languages without automatic formatting skip this state and submit directly.
+- Existing button labels and judging/cooldown behavior remain unchanged.
+
+## Implementation
+
+Add a component-local `isFormatting` ref in `SubmitCode.vue`.
+
+- Include it in `submitDisabled`.
+- Give it priority in `submitLabel`, using `格式化中`.
+- Include it in the loading-icon condition.
+- Set it immediately before `formatCode`.
+- Clear it in a `finally` block so every formatter outcome restores the button state.
+
+The state remains local because it is transient UI state owned only by the submission button.
+
+## Verification
+
+The frontend currently has no automated test suite. Verify with:
+
+- TypeScript production build.
+- Manual inspection of the state transitions for successful formatting, formatting errors, formatter infrastructure failures, and languages that do not format.
--- a/apps/web/docs/superpowers/specs/2026-07-05-sql-min-two-testcases-design.md
+++ b/apps/web/docs/superpowers/specs/2026-07-05-sql-min-two-testcases-design.md
@@ -0,0 +1,28 @@
+# SQL 题强制至少 2 个测试点 — 设计
+
+日期：2026-07-05
+
+## 背景
+
+题目页的 `sql_display` 用**测试点 1** 的数据生成期望结果展示（截断到 20 行）。如果 SQL 题只有 1 个测试点且结果 ≤20 行，页面展示的期望结果就是完整答案输出，学生可用 `SELECT ... UNION ALL ...`（query 模式）或硬编码 INSERT/UPDATE（modify 模式）对照抄写直接 AC。多测试点时数据不同，硬编码只能过测试点 1。
+
+## 决定
+
+SQL 题**强制至少 2 个数据不同的初始化脚本**，前后端双重拦截：
+
+- **前端** `ojnext/src/admin/problem/components/SQLTestcaseEditor.vue`：
+  - `canUpload` 要求非空脚本数 ≥ 2，不满足时上传按钮禁用；
+  - 上传按钮 tooltip 在脚本不足时显示原因（"SQL 题至少需要 2 个数据不同的测试点，防止硬编码期望结果"）。
+- **后端** `OnlineJudge/problem/views/admin.py` 的 `TestCaseZipProcessor.process_zip`：
+  - `sql=True` 且测试点数 < 2 时 `raise APIError(...)`，兜底直接调 API 的情况。
+
+## 影响范围
+
+- 只在**重新上传/保存测试点**时拦截，已有的单测试点老题目不受影响、不回溯校验。
+- 非 SQL 题（.in/.out 沙箱判题）不受影响。
+- "数据不同"不做内容级校验（两个脚本内容相同也能过），只保证数量下限，YAGNI。
+
+## 验证
+
+前端 `vue-tsc --noEmit`、Prettier 通过；后端 `ruff check` / `ruff format --check` 通过。
+人工验证：出题页只填 1 个脚本 → 上传按钮禁用且 tooltip 说明原因；填 2 个并预览通过 → 可上传。
--- a/apps/web/docs/superpowers/specs/2026-07-05-sql-schema-autocompletion-design.md
+++ b/apps/web/docs/superpowers/specs/2026-07-05-sql-schema-autocompletion-design.md
@@ -0,0 +1,50 @@
+# SQL 题目表名/字段名自动补全 — 设计
+
+日期：2026-07-05
+
+## 目标
+
+学生在 SQL 题目的代码编辑器里输入时，自动补全列表中除现有的 SQL 关键字/函数外，还出现**当前题目的表名和字段名**（带类型提示），减少抄写表名字段名的负担和拼写错误。
+
+## 背景
+
+- SQL 题目详情页已下发 `problem.sql_display`（`SQLDisplay` 类型），其中 `tables: SQLDisplayTable[]` 包含每张表的 `name`、`columns[{name, type}]`。数据在前端齐全，**无需后端改动**。
+- 编辑器补全入口是 `shared/extensions/autocompletion.ts` 的 `enhanceCompletion(language)`，`CodeEditor.vue` 和 `SyncCodeEditor.vue` 都用它，且都叠加了 `completeAnyWord`。
+- SQL 静态关键字补全表在 `shared/extensions/sql.ts`。
+- `shared` 直接 import `oj/store/problem` 已有先例（`FlowchartEditor/index.vue`）。
+
+## 方案（已选：方案 A）
+
+在 `enhanceCompletion` 中，当 `language === "SQL"` 时，从 `useProblemStore().problem?.sql_display?.tables` 动态生成补全项，追加到静态关键字列表后：
+
+- **表名**：`type: "class"`，`detail: "数据表"`，`info` 列出该表全部字段（如 `字段：id INTEGER, name TEXT, score REAL`），`boost` 高于所有关键字（如 110）。
+- **字段名**：`type: "property"`，`detail` 标注来源表和类型（如 `students 的字段 · TEXT`），`boost` 略低于表名、高于关键字（如 105）。
+- **同名字段每表一条**，靠 detail 区分来源表。
+- store 在补全回调内惰性读取（每次按键执行），题目切换后自动反映最新表结构。
+- 非 SQL 语言、无题目上下文（如 admin/tutorial/learn 页面）或 `sql_display` 为空时，不追加任何项，行为与现状一致。
+
+### 不做的事（YAGNI）
+
+- 不改后端；不改题目描述展示（`SQLDataTable` 已展示表结构）。
+- 管理端出题的 SQL 编辑器（`SQLTestcaseEditor`）不接入。
+- 不做基于 SQL 语法位置的智能上下文补全（如 FROM 后只补表名）。
+
+## 改动文件
+
+| 文件 | 改动 |
+|---|---|
+| `src/shared/extensions/autocompletion.ts` | SQL 分支追加由 `sql_display.tables` 生成的动态补全项 |
+
+（如生成逻辑较长，可拆一个小函数放同文件或 `sql.ts`，保持单一职责。）
+
+## 错误处理
+
+- `problem`、`sql_display`、`tables` 任一为空 → 返回纯静态列表（可选链兜底）。
+- Pinia store 在组件上下文外调用的风险：补全回调在编辑器运行期触发，此时 Pinia 已安装；与 FlowchartEditor 的既有用法一致。
+
+## 测试
+
+项目无测试套件（政策：不写新测试）。人工验证：
+1. 打开一道 SQL 题，编辑器中输入表名/字段名前缀，确认补全项出现且 detail/info 正确。
+2. 打开非 SQL 题，确认补全行为无变化。
+3. 协作编辑（SyncCodeEditor）场景同样生效。
--- a/apps/web/docs/superpowers/specs/2026-07-26-demo-student-view-design.md
+++ b/apps/web/docs/superpowers/specs/2026-07-26-demo-student-view-design.md
@@ -0,0 +1,102 @@
+# 学生视角（演示模式）设计
+
+日期：2026-07-26
+范围：仅前端（ojnext）
+
+## 背景
+
+超级管理员给学生上课演示时，界面上到处是管理员才可见的入口和按钮（后台菜单、题目编辑、提交列表的额外操作列等）。这些东西对学生是噪音，也容易误点。需要一个一键开关，把界面临时切换成普通学生看到的样子。
+
+## 目标
+
+- 超管点一下，全站界面变成普通学生的样子
+- 再点一下恢复
+- 刷新页面不丢状态
+- 改动集中，不散落到几十个页面
+
+## 非目标
+
+- 不改后端。演示模式是纯界面伪装，登录态仍然是超管，接口权限不变。目的是演示，不是权限隔离。
+- 不做审计日志、不做时长限制。
+- 教师管理员、学生管理员不提供此功能。
+
+## 机制
+
+全站所有权限判断都读 `shared/store/user.ts` 里的几个 getter，没有任何一处直接读 `user.admin_type`。因此在 store 层加一个开关，就能一次性覆盖全部调用点。
+
+```ts
+// shared/store/user.ts
+const demoMode = ref<boolean>(storage.get(STORAGE_KEY.DEMO_MODE) ?? false)
+
+// 不受伪装影响的真实身份，只用于决定是否显示切换入口
+const realIsSuperAdmin = computed(
+  () => user.value?.admin_type === USER_TYPE.SUPER_ADMIN,
+)
+
+const isSuperAdmin = computed(() => !demoMode.value && realIsSuperAdmin.value)
+const isAdminRole = computed(() => !demoMode.value && (/* 原逻辑 */))
+const isStudentAdmin = computed(() => !demoMode.value && (/* 原逻辑 */))
+const isTeacherAdmin = computed(() => !demoMode.value && (/* 原逻辑 */))
+const isTeacherOrAbove = computed(() => !demoMode.value && (/* 原逻辑 */))
+const hasProblemPermission = computed(() => !demoMode.value && (/* 原逻辑 */))
+
+const canToggleDemoMode = computed(() => realIsSuperAdmin.value)
+
+function toggleDemoMode() {
+  demoMode.value = !demoMode.value
+  storage.set(STORAGE_KEY.DEMO_MODE, demoMode.value)
+}
+```
+
+`realIsSuperAdmin` 是关键：如果切换入口的显示条件用被伪装后的 `isSuperAdmin`，一进入演示模式入口自己就消失了，退不出来。
+
+## 改动清单
+
+| 文件 | 改动 |
+|---|---|
+| `src/utils/constants.ts` | `STORAGE_KEY` 增加 `DEMO_MODE: "demoMode"` |
+| `src/shared/store/user.ts` | 新增 `demoMode`、`realIsSuperAdmin`、`canToggleDemoMode`、`toggleDemoMode`；6 个角色 getter 加 `!demoMode.value &&` 前缀；导出新成员 |
+| `src/shared/components/Header.vue` | 用户下拉菜单 `options` 增加一项「进入演示 / 退出演示」 |
+
+**不改**：`src/main.ts` 路由守卫、`src/utils/permissions.ts`、以及所有页面级的 `v-if` 判断。它们读的都是上述 getter，自动跟随。
+
+## 交互
+
+**入口**：右上角用户头像下拉菜单，与「我的主页」「我的提交」并列。
+
+- 显示条件：`userStore.canToggleDemoMode`
+- 文案随状态翻转：未开启显示「进入演示」，已开启显示「退出演示」
+- 该文案本身就是状态指示器，不额外加横幅或角标
+
+**点击行为**：
+
+1. 调用 `toggleDemoMode()`
+2. 如果是**进入**演示模式，且当前路由属于 `admins` 分支，执行 `router.push("/")`。否则页面会停在一个已失去权限的后台界面上。
+3. 退出演示模式不需要跳转，留在当前页即可。
+
+## 连带影响（均为预期行为）
+
+- **后台入口消失**（`Header.vue:165-175`）。手动输入 `/admin/*` 地址也会被 `main.ts` 守卫弹回首页，因为守卫读的是被伪装后的 getter。
+- **提交列表**（`submission/list.vue`）的教师专属筛选、额外列隐藏；`showSubmissions` 改为跟随站点配置 `submission_list_show_all`，而不是无条件为 true。
+- **题目编辑表单**（`problem/components/Form.vue`）的管理员字段隐藏。
+- **比赛访问**（`oj/store/contest.ts:49`）失去超管免密码特权，需按学生流程输密码。演示时更真实。
+- **协同代码编辑**（`shared/composables/sync.ts`）的超管特殊颜色与提示一并变为学生行为。**确认不做豁免**——演示场景不涉及协同编辑功能。
+
+## 持久化与清理
+
+- 存 `localStorage`，key 为 `demoMode`
+- store 初始化时从 storage 读取，刷新后保持
+- 退出登录时 `clearProfile()` 调用 `storage.clear()`，会一并清除，不会残留到下一个登录用户
+
+## 验证方式
+
+手工验证（本项目不写测试）：
+
+1. 超管登录 → 下拉菜单出现「进入演示」
+2. 点击 → 顶栏「后台」消失，菜单文案变为「退出演示」
+3. 停在 `/admin/problem/list` 时点击 → 跳回首页
+4. 地址栏直接输 `/admin` → 弹回首页
+5. 刷新页面 → 仍是学生界面
+6. 点「退出演示」→ 后台入口恢复
+7. 退出登录再登录 → 演示模式已重置为关闭
+8. 用教师管理员账号登录 → 菜单中无此项
--- a/apps/web/docs/图表.md
+++ b/apps/web/docs/图表.md
@@ -0,0 +1,216 @@
+# 图表组件说明
+
+基于 Chart.js 和 Vue-ChartJS 构建的数据可视化组件库，为 OJ Next 项目提供丰富的图表展示功能。
+
+## 技术栈
+
+- **Chart.js** - 强大的图表库，支持多种图表类型
+- **Vue-ChartJS** - Chart.js 的 Vue 3 封装
+- **Vue 3 Composition API** - 现代化的组件开发方式
+- **TypeScript** - 完整的类型支持
+
+## 现有图表组件
+
+### 1. DurationChart 混合图表
+**文件位置**: `src/oj/ai/components/DurationChart.vue`
+
+**功能描述**: 展示用户学习进度的时间趋势，结合柱状图和折线图。
+
+**数据来源**: `durationData` API 接口
+- 每周/每月的综合情况
+- 题目数、提交数、等级变化
+
+**图表类型**: 
+- 柱状图：完成题目数
+- 折线图：提交次数、等级变化
+
+**使用场景**: AI分析页面的主要图表
+
+### 2. Heatmap 热力图
+**文件位置**: `src/oj/ai/components/Heatmap.vue`
+
+**功能描述**: 展示用户的提交活跃度分布。
+
+**数据来源**: `heatmapData` API 接口
+- 按日期统计提交数
+- 可视化用户活跃度
+
+**图表类型**: 热力图矩阵
+
+**使用场景**: 展示学习习惯和时间规律
+
+### 3. Details 详细数据
+**文件位置**: `src/oj/ai/components/Details.vue`
+
+**功能描述**: 展示用户详细的学习数据。
+
+**数据来源**: `detailsData` API 接口
+- 用户等级、已解决题目列表
+- 标签统计、难度统计
+- 参赛次数等
+
+**展示方式**: 数据表格和统计卡片
+
+## 可扩展的图表类型
+
+### 1. 提交效率趋势图 (折线图)
+**数据来源**: `durationData` 中的 `submission_count / problem_count`
+**展示内容**: 每个时间段的提交效率（提交次数/完成题目数）
+**价值**: 反映刷题质量的提升，值越接近1说明一次AC率越高
+
+### 2. 排名分布图 (直方图/箱线图)
+**数据来源**: `solved` 数组中每道题的 `rank` 和 `ac_count`
+**展示内容**: 用户解题排名的分布情况（如：前10%、10-30%、30-50%等区间的题目数量）
+**价值**: 了解解题速度和竞争力
+
+### 3. 等级分布饼图/环形图
+**数据来源**: `solved` 数组中每道题的 `grade`
+**展示内容**: S/A/B/C 各等级题目的数量和占比
+**价值**: 直观看出题目质量分布
+
+### 4. 标签雷达图
+**数据来源**: `tags` 对象
+**展示内容**: 多维度展示各类标签的掌握程度（可以归一化处理）
+**价值**: 可视化知识点覆盖面
+
+### 5. 时间活跃度分析 (热力矩阵)
+**数据来源**: `solved` 数组中的 `ac_time`
+**展示内容**: 按星期几和时间段统计做题分布（如：工作日vs周末，早中晚时段）
+**价值**: 了解学习习惯和时间规律
+
+### 6. 难度-等级关联散点图
+**数据来源**: `solved` 数组中的难度信息和 `grade`
+**展示内容**: X轴为难度，Y轴为等级，每个点代表一道题
+**价值**: 分析在不同难度下的表现
+
+### 7. 做题加速度图
+**数据来源**: `durationData`
+**展示内容**: 每个时间段完成题目数的变化率
+**价值**: 看出学习动力的变化趋势
+
+### 8. 竞赛题目占比
+**数据来源**: `solved` 数组中的 `contest_id` 和 `contest_count`
+**展示内容**: 竞赛题 vs 常规题的数量对比
+**价值**: 了解竞赛参与情况
+
+### 9. 连续做题天数统计
+**数据来源**: `heatmapData`
+**展示内容**: 最长连续做题天数、当前连续天数等
+**价值**: 激励持续学习
+
+### 10. 月度对比雷达图
+**数据来源**: `durationData`
+**展示内容**: 多个维度（完成题目数、提交次数、等级、效率等）的月度对比
+**价值**: 全面评估进步情况
+
+## 组件开发指南
+
+### 创建新图表组件
+
+```vue
+<template>
+  <div class="chart-container">
+    <Line
+      :data="chartData"
+      :options="chartOptions"
+    />
+  </div>
+</template>
+
+<script setup lang="ts">
+import { Line } from 'vue-chartjs'
+import { computed } from 'vue'
+
+// 定义 props
+const props = defineProps<{
+  data: any[]
+}>()
+
+// 计算图表数据
+const chartData = computed(() => ({
+  labels: props.data.map(item => item.label),
+  datasets: [{
+    label: '数据',
+    data: props.data.map(item => item.value),
+    backgroundColor: 'rgba(54, 162, 235, 0.2)',
+    borderColor: 'rgba(54, 162, 235, 1)',
+    borderWidth: 1
+  }]
+}))
+
+// 图表配置
+const chartOptions = {
+  responsive: true,
+  maintainAspectRatio: false,
+  plugins: {
+    legend: {
+      display: true
+    }
+  }
+}
+</script>
+```
+
+### 图表样式定制
+
+```typescript
+// 主题配置
+const theme = {
+  colors: {
+    primary: '#6366f1',
+    secondary: '#8b5cf6',
+    success: '#10b981',
+    warning: '#f59e0b',
+    error: '#ef4444'
+  },
+  gradients: {
+    primary: 'linear-gradient(135deg, #667eea 0%, #764ba2 100%)',
+    success: 'linear-gradient(135deg, #11998e 0%, #38ef7d 100%)'
+  }
+}
+```
+
+## 性能优化
+
+### 1. 数据懒加载
+- 按需加载图表数据
+- 使用虚拟滚动处理大量数据
+
+### 2. 图表缓存
+- 缓存计算结果
+- 避免重复渲染
+
+### 3. 响应式设计
+- 自适应容器大小
+- 移动端优化
+
+## 最佳实践
+
+### 1. 数据预处理
+- 在组件外部处理数据
+- 使用 computed 属性缓存计算结果
+
+### 2. 错误处理
+- 添加数据验证
+- 提供降级方案
+
+### 3. 用户体验
+- 添加加载状态
+- 提供交互反馈
+
+## 更新日志
+
+### v1.0.0 (2024-01-15)
+- ✨ 初始版本发布
+- 📊 基础图表组件
+- 🎨 主题样式支持
+- 📱 响应式设计
+
+### v1.1.0 (2024-01-20)
+- 🔧 性能优化
+- 📈 新增混合图表
+- 🎯 交互体验改进
+
+## 许可证
+
+MIT License