# 平台总体设计（草案）

> 目标：面向初学者的 OI/CSP 学习知识库 + 日常练习 + 模拟竞赛系统，并提供在线 C++ 编写/编译/调试能力。前后端分离：Next.js + C++(Drogon) + SQLite。

## 1. 术语与核心对象

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

## 2. 技术架构

### 2.1 前端

- Next.js(App Router) + TypeScript + Tailwind
- 负责：题库/题面、编辑器页面、提交列表、错题本、排行、比赛大厅、知识库阅读

### 2.2 后端

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

### 2.3 在线编译/运行（安全边界）

- MVP：后端在临时目录中调用 `g++` 编译，并用子进程运行，使用 `ulimit`/超时 kill 做基础限制。
- 生产建议：判题/运行必须放在容器或隔离工具（如 nsjail/isolate）中；否则存在逃逸风险。

## 3. 数据库设计（SQLite）

### 3.1 表清单

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

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) 知识库文章与题目关联