# 产品需求文档 (PRD)：综合编程与技能评测平台

## 1. 产品概述

### 1.1 产品背景与目标

传统的在线判题系统（OJ）大多局限于算法与数据结构评测，无法满足现代企业招聘与高校教学中对“全栈开发能力”（如数据库设计、前端还原与交互实现）的综合考评需求。

本产品旨在打造一个**多维度、沉浸式的编程与技能评测平台**，无缝集成算法 OJ、数据库 OJ、前端 AI 智能评测及标准客观题系统，为开发者、教师和招聘方提供一站式的技术能力评估解决方案。

### 1.2 目标用户与使用场景

- **普通用户/考生**：进行日常技能刷题、参加在线技术笔试或课程期末考试。
- **教研/招聘方（管理员）**：创建与管理题库、组卷发卷、查看多维度分析报告（代码质量、用时、AI 评语）。
- **核心场景**：企业技术校招/社招笔试、高校计算机专业程序设计与Web开发课程实验、技术社区公开打榜赛。

## 2. 用户角色与权限定义

| **角色**          | **核心权限范围**                                             | **备注**                 |
| ----------------- | ------------------------------------------------------------ | ------------------------ |
| **游客**          | 浏览公开题库、查看平台公告、注册/登录。                      | 无法提交代码。           |
| **考生/认证用户** | 提交代码与试卷、查看公开评测结果、查看个人数据面板。         | 仅对授权的私有考试可见。 |
| **出题人/教师**   | 题库 CRUD（增删改查）、配置测试用例、管理 AI 评分细则（Prompt）、组卷。 | 无法管理平台系统级配置。 |
| **系统管理员**    | 判题机节点管理、沙箱资源调度、全局权限分配、数据字典管理。   | 拥有系统最高权限。       |

## 3. 核心业务模块与功能需求

### 3.1 题型评测子系统（核心）

#### 3.1.1 算法 OJ 模块

- **需求描述**：支持多语言（C/C++、Java、Python、Go、Rust 等）的标准算法题评测。
- **功能点**：
  - **代码编辑器**：支持语法高亮、代码折叠、自动补全、Vim 模式切换、黑暗主题。
  - **输入输出流测试**：支持自定义测试用例的在线调试运行（Run Code）。
  - **资源限制配置**：支持对单题设置精确的时间限制（Time Limit, e.g., 1000ms）和空间限制（Memory Limit, e.g., 256MB）。
  - **评测状态机**：完整支持并展示 AC、WA、TLE、MLE、RE、CE 等标准判题状态。

#### 3.1.2 数据库 OJ 模块

- **需求描述**：支持 SQL 语句的在线编写与结果集正确性校验。
- **功能点**：
  - **环境隔离**：每次评测在独立内存数据库（如 DuckDB/SQLite）中初始化 Schema。
  - **多语言方言**：支持 MySQL 8.0 及 PostgreSQL 标准语法。
  - **判题逻辑**：
    - 结构比对：比对目标结果集与标准结果集的列名、列类型、行数。
    - 数据比对：比对具体数据值，支持对浮点数设置精度宽容度。
    - 排序校验：若题目要求 `ORDER BY`，需强制校验输出数据的物理顺序。

#### 3.1.3 前端代码 AI 评测模块

- **需求描述**：支持 HTML/CSS/JS 及前端框架（Vue/React）的综合评测，结合确定性测试与大模型智能评分。
- **功能点**：
  - **多文件工程视图**：支持类似 VS Code 的左侧目录树与右侧多 Tab 编辑器。
  - **实时预览（Live Preview）**：提供基于 WebContainer 或 iframe 的实时热更新预览窗口。
  - **混合评测管线**：
    - **阶段一（DOM 与断言）**：通过无头浏览器运行测试脚本，校验关键 DOM 节点是否存在、事件是否绑定、交互状态是否正确。
    - **阶段二（AI 视觉与代码审计）**：将网页截图与源代码提交至多模态大模型（如 GPT-4o），根据预设的评分维度（如 UI 还原度、CSS 命名规范、是否滥用 `!important`）输出 JSON 格式的得分与优化建议。

#### 3.1.4 客观题模块

- **需求描述**：标准化的题型支持，用于基础理论考察。
- **功能点**：
  - **题型支持**：单选题、多选题（支持漏选给一半分配置）、填空题。
  - **富文本题干**：全面支持 Markdown 渲染、代码块高亮及 LaTeX 数学公式。
  - **填空校验**：支持精确匹配、忽略大小写匹配、正则表达式匹配。

### 3.2 考试与防作弊模块

- **考试模式**：
  - **ACM 模式**：提交后立即显示评测结果与报错，按通过题目数量与总罚时排名。
  - **OI 模式**：考试期间仅保存代码，交卷后统一后台评测，按测试用例通过比例给部分分。
- **防作弊机制**：
  - 限制切屏次数，切屏超限自动交卷（需记录切屏时长）。
  - 禁用代码编辑区域的鼠标右键与 Ctrl+C / Ctrl+V。
  - **代码查重（后续迭代）**：基于 AST 抽象语法树的代码相似度对比，输出查重报告。

### 3.3 用户主页与开发者档案子系统（User Profile & Portfolio）

#### 3.3.1 个人名片与开发者形象
- **大尺寸直角头像**：128×128px 硬朗纯直角卡片风格头像，本人悬浮唤起更换蒙层；支持本地文件上传（最大 10MB 请求限额、5MB 文件大小），配置专用大文件友好提示与全局异常处理。
- **核心元数据**：展示用户名、系统 UID、邮箱、加入时间、GitHub 外链直达，以及引用式个性签名沉浸框。
- **三角色纯色标识**：遵循高对比纯色规范：管理员（紫色 `#7048e8`）、教师（绿色 `#2b8a3e`）、学生（黑色 `#1e1e1e`）。

#### 3.3.2 52-周打卡热力图（AC Heatmap）
- **打卡方块矩阵**：统计过去 365 天每日真实 AC 提交量，生成 52-周活跃方块日历矩阵，反映日常代码训练活跃度。
- **三大核心指标卡**：高反差展示「年度 AC 题数」、「当前连击天数（Current Streak）」与「历史最长连击（Max Streak）」。

#### 3.3.3 考试实战档案
- **战报卡片流**：实时沉淀并展示参与的机试与模拟赛成绩，公开呈现综合得分、全场名次、耗时及交卷时间，支持一键跳转战报快照回溯。

#### 3.3.4 全量提交记录整合
- **三合一题型切换**：整合编程题提交、数据库 SQL 提交、客观题作答三大分类标签，动态呈现各分类做题总数。
- **状态筛选与分页**：支持按 AC、WA、TLE、MLE、RE、CE、SE 等状态精确过滤，支持每页 10 条的标准分页。
- **代码快照弹窗**：支持在主页内直接调起代码/SQL/客观题明细弹窗，配备格式化展示与一键剪贴板复制。

#### 3.3.5 访客模式与公开档案（GitHub / LeetCode 范式）
- **全平台公开透明**：支持通过 `/profile/:id` 访问任意注册用户的个人主页，热力图、战报与提交历史全量公开，促进技术交流。
- **权限与视角隔离**：访客视角下自动隐藏编辑资料、修改密码及头像蒙层，展示「访客视角」标识，严防非授权篡改。

#### 3.3.6 题库大厅与顶栏交互工业化重构
- **题库卡片富信息**：单列卡片完整包含做题状态圈（已攻克/未解答）、题号（#1）、时空限制（1000ms/256MB，无emoji）、语言标签、纯色徽章（简单绿/中等橙/困难红；SELECT 黑/DML 钛灰），右侧快捷操作入口。
- **快捷筛选与随机刷题**：工具栏右侧增设做题状态过滤（全部/未解答/已通过）与「随机刷题」按钮；顶部配备攻克进度条。
- **顶栏跟随动效**：顶栏精简为核心学习模块，移入纯色角色标签至用户卡片内部，主导航配备鼠标悬浮灰色方块平滑滑动（Hover Slider）动效。

### 3.4 课堂练习与随堂互动子系统（Lesson Practice / 课练）

#### 3.4.1 6 位极速口令进房与免班级排课
- **极速上机口令**：教师一键生成 6 位大写字母与数字口令（如 `KE98A2`），学生无需预先分配班级或录入花名册，输入口令秒级加入房间，极大降低课上教学组织成本。
- **整套限时与随堂自适应**：支持配置随堂时间限制（如 30~45 分钟），学生在规定时间内自由把控各题答题节奏。

#### 3.4.2 客观题单页集中合卷（Unified Objective Sheet）
- **单页垂直合卷**：打破传统一题一页反复翻页的繁琐交互，将单场课练内所有客观题（单选/多选/填空）集中排布在同一个纵向试卷页面内。
- **直角硬朗选项与即时批量判分**：配备 32×32px 纯直角字母选项按钮，支持单选互斥与多选按字母自动排序；支持一键提交全卷客观题，由后端高性能引擎即时判分并回填各题对错状态与得分，答完即出分。

#### 3.4.3 算法与 SQL 题目继承主站标准评测流
- **经典评测体验对齐**：算法题与数据库题完全复用编程模块与数据库模块的核心做题逻辑，包含左侧 Markdown 题面/DDL 结构区、右侧 Monaco 编辑器代码工作台、模板重置、本地草稿防丢失（LocalStorage）、Ctrl+Enter 快捷提交以及异步状态机轮询机制。
- **做题进度与得分无缝同步**：学生在课练内完成算法或 SQL 提交后，评测结果自动计入个人在本次课练的当前总得分与 AC 题数。

#### 3.4.4 教师课堂投屏监控大屏（Projector Dashboard）
- **高对比暗黑大屏**：专为投影仪与阶梯教室黑板幕布设计的大字号高对比工业暗黑仪表盘（`#0f1115`），支持一键全屏投屏。
- **巨型口令方块与实时倒计时**：顶部中央醒目展示 6 位超大镂空发光口令方块，右侧展示高亮倒计时；支持教师课上一键快速加时（+5分钟）与提前截止收卷。
- **Bento 仪表盘与各题通过率横条**：实时呈现应到/实到人数、交卷人数、全班平均分、客观题平均正确率；多题横向柱状图实时动态展示各题通过率与薄弱点分布。
- **防社恐匿名脱敏榜单与实时提交气泡流（Ticker）**：支持一键开启排行榜学生姓名脱敏模式（如 `张***`），保护学生自尊心；大屏底部配备实时提交气泡流，动态滚动最新提交记录。

## 4. 判题引擎与非功能需求

### 4.1 安全性需求（Highest Priority）

- **运行沙箱**：所有算法代码必须在 Linux 强隔离沙箱（Cgroups v2 + Namespace + Seccomp）中运行。
- **网络隔离**：判题容器必须断开外部网络，禁止访问宿主机内网与公网，防止渗透与数据泄露。
- **系统调用限制**：严格通过白名单拦截危险系统调用（如 `execve`, `fork`）。

### 4.2 性能与并发需求

- **削峰填谷**：在集中笔试场景下，Web 后端必须将评测请求压入消息队列（如 Redis / RabbitMQ），避免并发洪峰冲垮数据库。
- **弹性扩容**：判题机（Judger）需设计为无状态节点，支持在笔试高峰期通过 Docker/K8s 动态增加 Worker 节点。
- **响应时效**：
  - 算法/数据库题评测：从用户点击提交到返回结果，P95 延迟需控制在 3 秒以内。
  - 前端 AI 评测：受大模型接口限制，允许进入“AI 评审中”状态，异步推送结果（不超过 30 秒）。

### 4.3 高可用与数据存储

- **高可用性**：系统 SLA 达到 99.9%，判题节点宕机需能自动重新将未完成的任务放回队列执行。
- **用例存储**：大型测试数据（单文件 > 5MB）需存储在对象存储（OSS/MinIO）中，判题节点拉取后进行本地缓存。

## 5. 项目分期实施规划（MVP 策略）

| **阶段**                | **目标与范围**                                               | **预计周期** |
| ----------------------- | ------------------------------------------------------------ | ------------ |
| **Phase 1: 核心链路**   | 跑通用户注册、算法题库 CRUD、纯算法沙箱评测（C++/Java/Python）、客观题模块。 | 4-6 周       |
| **Phase 2: 场景拓展**   | 引入 SQLite 内存评测引擎完成数据库 OJ；实现组卷、倒计时考试功能；引入消息队列。 | 3-4 周       |
| **Phase 3: 智能升级**   | 接入前端多文件编辑器，集成 Playwright 无头浏览器与 LLM 接口，完成前端 AI 评测。 | 4-5 周       |
| **Phase 4: 企业级商用** | 完善防作弊系统、数据大屏面板、高并发压力测试与判题集群动态扩容。 | 持续迭代     |