feat: rebuild CSP practice workflow, UX and automation

2026-02-13 15:49:05 +08:00
--- a/docs/平台总体设计.md
+++ b/docs/平台总体设计.md
@@ -1,174 +1,63 @@
-# 平台总体设计（草案）
+# 平台总体设计

-> 目标：面向初学者的 OI/CSP 学习知识库 + 日常练习 + 模拟竞赛系统，并提供在线 C++ 编写/编译/调试能力。前后端分离：Next.js + C++(Drogon) + SQLite。
+> 目标：围绕 CSP/OI 学习闭环构建一体化系统：知识学习 -> 日常练习 -> 错题复盘 -> 模拟竞赛 -> 排名反馈。

-## 1. 术语与核心对象
+## 1. 产品模块

- **用户(User)**：注册/登录；拥有积分、等级、学习进度。
- **题目(Problem)**：题面、标签、难度、来源（如 CSP/NOIP/自建）。
- **提交(Submission)**：用户对题目的一次代码提交（含编译/运行结果、耗时、内存、得分）。
- **练习(Practice)**：非比赛场景的做题记录（可以直接通过 submissions 体现）。
- **错题本(WrongBook)**：用户在练习/比赛中未通过的题目集合 + 错因备注。
- **比赛(Contest)**：模拟 CSP/NOIP 的比赛；包含题目列表、开始/结束、计分规则。
- **排名(Leaderboard)**：全站积分排行、比赛排行。
- **知识库(KnowledgeBase)**：学习文章/笔记/专题目录；可关联题目。
+1. 用户与鉴权
+2. 题库与在线提交
+3. 提交记录与结果追踪
+4. 错题本与复盘
+5. 模拟竞赛与排行
+6. 学习知识库
+7. 在线 C++ 编写/编译/运行

 ## 2. 技术架构

-### 2.1 前端
+### 前端（Next.js）
+- App Router + TypeScript
+- 页面模块：`/problems`、`/submissions`、`/wrong-book`、`/contests`、`/kb`、`/run`、`/me`、`/leaderboard`
+- 通过 `/admin139` 反代后端 API，避免跨域复杂度

- Next.js(App Router) + TypeScript + Tailwind
- 负责：题库/题面、编辑器页面、提交列表、错题本、排行、比赛大厅、知识库阅读
+### 后端（Drogon C++）
+- Controller：HTTP 路由与请求校验
+- Service：业务逻辑（题库/提交/错题本/竞赛/知识库）
+- Domain：实体与 JSON 序列化
+- DB：SQLite + 启动迁移 + 演示数据种子

-### 2.2 后端
+### 数据层（SQLite）
+- 单文件数据库，便于快速部署
+- 覆盖用户、题库、提交、错题本、竞赛、知识库完整模型

- Drogon (HTTP + JSON)
- SQLite（单文件数据库，便于部署）
- 模块分层（建议）：
-  - `controller/`：HTTP 路由
-  - `service/`：业务逻辑
-  - `repo/`：DB 访问（SQL + 映射）
-  - `domain/`：实体与枚举
-  - `judge/`：编译与判题执行器（后续）
+## 3. 核心业务流

-### 2.3 在线编译/运行（安全边界）
+### 3.1 练习流
+1) 用户登录
+2) 浏览题目并提交
+3) 后端调用 `g++` 编译并运行样例
+4) 结果写入 `submissions`
+5) 若未通过，写入/更新 `wrong_book`
+6) 若首次 AC，提升 `users.rating`

- MVP：后端在临时目录中调用 `g++` 编译，并用子进程运行，使用 `ulimit`/超时 kill 做基础限制。
- 生产建议：判题/运行必须放在容器或隔离工具（如 nsjail/isolate）中；否则存在逃逸风险。
+### 3.2 竞赛流
+1) 用户报名比赛
+2) 在比赛时间内提交比赛题目
+3) 按 AC 数与罚时生成排行榜

-## 3. 数据库设计（SQLite）
+### 3.3 学习流
+1) 浏览知识库文章
+2) 查看文章关联题目
+3) 进入题目页面进行练习

-### 3.1 表清单
+## 4. 安全与运行边界

-1) `users`
- `id` INTEGER PK
- `username` TEXT UNIQUE
- `password_hash` TEXT
- `created_at` INTEGER
- `rating` INTEGER DEFAULT 0  （综合积分）
+- 当前在线运行模块用于开发/教学环境。
+- 生产环境应将编译运行迁移到受限沙箱，避免宿主机风险。

-2) `problems`
- `id` INTEGER PK
- `slug` TEXT UNIQUE
- `title` TEXT
- `statement_md` TEXT
- `difficulty` INTEGER
- `source` TEXT
- `created_at` INTEGER
+## 5. 可扩展方向

-3) `problem_tags`
- `problem_id` INTEGER
- `tag` TEXT
- PK(`problem_id`,`tag`)
+- 增加多测试点判题与标准答案管理
+- 引入更细粒度比赛规则（罚时、封榜、重判）
+- 支持多语言判题
+- 增加学习路径与章节化知识图谱

-4) `submissions`
- `id` INTEGER PK
- `user_id` INTEGER
- `problem_id` INTEGER
- `language` TEXT  （先支持 cpp）
- `code` TEXT
- `status` TEXT   （Pending/Compiling/Running/AC/WA/TLE/MLE/RE/CE）
- `score` INTEGER
- `time_ms` INTEGER
- `memory_kb` INTEGER
- `created_at` INTEGER
-
-5) `wrong_book`
- `user_id` INTEGER
- `problem_id` INTEGER
- `last_submission_id` INTEGER
- `note` TEXT
- `updated_at` INTEGER
- PK(`user_id`,`problem_id`)
-
-6) `contests`
- `id` INTEGER PK
- `title` TEXT
- `starts_at` INTEGER
- `ends_at` INTEGER
- `rule_json` TEXT  （计分规则/罚时规则）
-
-7) `contest_problems`
- `contest_id` INTEGER
- `problem_id` INTEGER
- `idx` INTEGER
- PK(`contest_id`,`problem_id`)
-
-8) `contest_registrations`
- `contest_id` INTEGER
- `user_id` INTEGER
- `registered_at` INTEGER
- PK(`contest_id`,`user_id`)
-
-9) `kb_articles`
- `id` INTEGER PK
- `slug` TEXT UNIQUE
- `title` TEXT
- `content_md` TEXT
- `created_at` INTEGER
-
-10) `kb_article_links`
- `article_id` INTEGER
- `problem_id` INTEGER
- PK(`article_id`,`problem_id`)
-
-### 3.2 积分/排行
-
- 全站排行：按 `users.rating` 降序。
- rating 更新策略（MVP）：
-  - 练习 AC：+difficulty * 常数
-  - 比赛：按名次发放奖励分（rule_json 可配置）
-
-> 该策略后续可替换为 ELO/Codeforces 风格。
-
-## 4. HTTP API 设计（v1草案）
-
-统一前缀：`/api/v1`
-
-### 4.1 Auth
- `POST /auth/register` {username,password}
- `POST /auth/login` {username,password} -> {token}
- 鉴权：`Authorization: Bearer <token>`（MVP 可用 HMAC JWT）
-
-### 4.2 Problems
- `GET /problems?tag=&difficulty=&q=&page=`
- `GET /problems/:id`
-
-### 4.3 Submissions
- `POST /problems/:id/submit` {language,code}
- `GET /submissions?user_id=&problem_id=&page=`
- `GET /submissions/:id`
-
-### 4.4 WrongBook
- `GET /me/wrong-book`
- `PATCH /me/wrong-book/:problemId` {note}
- `DELETE /me/wrong-book/:problemId`
-
-### 4.5 Contests
- `GET /contests`
- `GET /contests/:id`
- `POST /contests/:id/register`
- `GET /contests/:id/leaderboard`
-
-### 4.6 Leaderboard
- `GET /leaderboard/global`
-
-### 4.7 Knowledge Base
- `GET /kb/articles`
- `GET /kb/articles/:slug`
-
-## 5. 测试策略（TDD）
-
- `repo` 层：用内存 SQLite（`:memory:`）+ 迁移脚本，做 CRUD 单测。
- `service` 层：对积分、错题本更新等写业务单测。
- `controller` 层：Drogon 自带测试/或以 HTTP 集成测试（启动测试服务器，发请求断言 JSON）。
-
-## 6. 下一步落地顺序（MVP）
-
-1) 用户注册/登录（token）
-2) 题库（只读）+ 提交记录入库
-3) 在线编译（仅编译 + 返回CE/OK），再扩展到运行
-4) 错题本（由 WA/未通过自动写入）
-5) 积分与全站排行
-6) 比赛（创建/报名/排行榜）
-7) 知识库文章与题目关联