# 编程学习世界

**Repository Path**: bingbingyihao/programming-learning

## Basic Information

- **Project Name**: 编程学习世界
- **Description**: No description available
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-03
- **Last Updated**: 2026-10-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 编程学习世界（Programming Learning World）

严谨的编程学习系统，外壳借鉴游戏激励模式：课程关卡、每日任务、成就、排行榜、背包道具、世界频道。

分**用户端**与**管理端**两套独立的「前端 + 后端」，共用同一个 MySQL 库与 Redis。

## 技术栈

| 层 | 用户端 | 管理端 |
| --- | --- | --- |
| 前端 | Vue 3 + Vue Router + Axios（Vue CLI 5） | 同左 |
| 后端 | Spring Boot 2.7 / Java 8 / MyBatis-Plus | 同左 |
| 存储 | MySQL 5.7+、Redis | 同左 |
| 其他 | JWT + Redis 会话、WebSocket（世界频道）、Hutool、Lombok | 同左 |

## 目录结构

```
code/User_SpringBoot    用户端后端（:8080）
code/Admin_SpringBoot   管理端后端（:10010）
code/user               用户端前端（开发 :8081 / 生产 :80）
code/admin              管理端前端（开发 :10000 / 生产 :10000）
config/                 后端配置源文件（user / admin / ssl）
db/test.sql             数据库结构与初始化数据（可重复执行）
bash/                   Linux 部署与运维脚本
scripts/                Windows 开发脚本（启动 / 格式化）
html/                   维护模式静态页
ssl/                    HTTPS 证书
```

## 端口约定

| 服务 | 端口                               |
| --- |----------------------------------|
| 用户端后端 API | 8080                             |
| 管理端后端 API | 10010                            |
| 用户端前端（开发） | 8081，`/api`、`/ws/world` 代理到 8080 |
| 管理端前端（开发） | 10000，`/api` 代理到 10010           |
| 生产入口 | Nginx :80 用户端、:10000 管理端         |

## 本地开发（Windows）

```powershell
# 前置：MySQL、Redis 已启动，且已导入 db/test.sql
.\scripts\start-dev.ps1              # 打开 4 个窗口：两个后端 + 两个前端
.\scripts\start-dev.ps1 -SkipInstall # 跳过首次 npm install
```

若被执行策略拦截：

```powershell
powershell -ExecutionPolicy Bypass -File scripts\start-dev.ps1
```

## 生产部署（Linux）

```bash
bash/install.sh                  # 安装 MySQL / JDK / Node / Redis / Maven / Nginx，以及 python3、g++（判题用）
cd config && ./init_config_sh.sh         # 写入口令，替换脚本占位符 xxx
cd config && ./init_config_properties.sh # 配置从 config/ 同步进两个 resources 目录
cd ../bash && ./start_backend.sh         # 启动两个后端（日志 backend_logs/）
./start_front.sh                         # 构建两个前端（产物 code/*/dist）
sudo ./sync_nginx.sh /usr/share/nginx/html
./stop.sh                                # 停止后端与 Nginx
```

> `config/` 是配置的唯一来源，改完必须执行 `init_config_properties.sh` 才会生效到 Spring Boot（`src/main/resources` 下的同名文件是副本）。

## 数据库

- 库名 `test`，脚本 `db/test.sql` 全部使用 `CREATE TABLE IF NOT EXISTS`，可重复执行、不丢数据。
- 覆盖用户与鉴权、学习内容、任务与成就、背包与道具、世界频道、排行榜，以及管理端的 `admin_user`、`sys_*_log`、`user_blacklist`、`sensitive_word`。
- 管理端首个超管账号由配置 `admin.init` 控制，默认开启并在启动时自动初始化。

## 安全与风控

- **鉴权**：JWT + Redis 会话双层校验，登出/停用/拉黑立即生效（用户端单端登录，新登录顶掉旧会话）；管理端可查在线并强制下线。
- **拦截器链**（用户端 `/api/**`，顺序固定且有依赖）：全局限流 → 鉴权 → 受限判定 → 场景限流。
- **限流**：令牌桶算法，避免固定窗口在边界瞬时放行 2 倍流量。
  - 场景限流：`@RateLimit` 注解声明 `scene`，阈值走 `rate-limit.rules` / `rule-windows`；
  - 全局兜底：按 IP + URI 拦截未打注解的接口，`global-excludes` 放行静态资源。
  - 客户端 IP 取值优先级 `X-Real-IP` → `X-Forwarded-For` 最后一项 → `remoteAddr`（顺序即安全设计，勿随意调整）。
- **账号 / IP 受限**：Redis Hash（原因、来源、开始时间、解除时间），TTL 即剩余时长；两端 Key 结构完全一致，管理端拉黑后用户端立即生效，受限页无需回源 DB 即可展示「为什么、还剩多久」。
- **敏感词**：命中即拦截；世界频道违规达阈值自动禁言并可选邮件通知。
- **维护模式**：`enable_maintenance.sh` / `disable_maintenance.sh` 一键切换全站 503 维护页。

## 在线编程（OJ）

在「做选择题」之外新增**编程题**：写代码 → 判题 → 结算 → 拿奖励，闭环与客观题一致。

- **题型**：`question.question_type = 'PROGRAMMING'`，复用课程 / 章节 / 关卡 / 星级 / 进度，不另建体系。
- **判题**：`com.boot.judge` 包。`JudgeSandbox` 落盘 → 编译 → 逐用例运行 → 比对 → 清理；
  支持 Java / Python 3 / C++（`LanguageSpec` 收口语言差异）。状态含 `AC / WA / TLE / MLE / RE / CE / SE`。
- **用例**：`programming_case` 表，只有 `is_sample=1` 的**公开示例**会下发给前端；
  隐藏用例的输入输出**绝不外发**（否则可硬编码骗过判题），失败时只回用例序号。
- **接口**（`/api/programming`）：`GET /questions/{id}`、`POST /questions/{id}/run`（只跑示例、不计分）、
  `POST /questions/{id}/submit`（全用例、落库计分）、`GET /questions/{id}/submits`、`POST /questions/{id}/ai-hint`。
- **AI 提示**：消耗「AI 提示卡」换取解题思路（1 张）或示例解答（2 张）。
  调用**成功后才扣卡**，超时 / 熔断 / 配额用尽一律不扣；结果按「题目 + 级别」缓存，并有 Redis 每日配额。
  提示词只含题干、语言、模板与公开示例，**绝不含隐藏用例**。
- **结算**：判题在事务外先完成并落库，`SettleService` 只读历史最高分**不重复执行代码**（避免长事务占连接）。
- **前端**：`MonacoEditor` 自托管打包（`monaco-editor` + `monaco-editor-webpack-plugin`），
  只打包 `java/python/cpp` 与必要 features，**不走 CDN**（生产 Nginx 可能无外网）；
  Monaco 懒加载 + 独立分包，且加载失败时降级为原生 textarea，保证「仍然能写、能提交」。
  页面 `views/ProgrammingPlay.vue`（左题面 / 右编辑器）、路由 `/programming/:questionId`，代码草稿本地缓存。
- **管理端**：`Content.vue` 支持题型选 `PROGRAMMING` 并维护测试用例。

> ⚠️ **安全边界（务必阅读）**：判题在**本机以子进程方式执行用户代码**，靠「超时 + 内存上限 +
> 输出上限 + 低权限运行用户」限制破坏面，**它不是一个真正的安全沙箱**——用户代码理论上仍可读写文件、
> 发起网络请求。请务必：①用独立低权限用户运行后端（勿用 root）；②只在内网 / 学习场景开放，
> 不要暴露给不可信的公网用户；③如需强隔离，把 `JudgeSandbox` 替换为容器 / nsjail / cgroup 实现
> （该类是本模块唯一与「代码怎么被执行」耦合的地方，替换它不影响上层业务）。

## 代码格式化

统一风格，提交前执行：

```powershell
.\scripts\format.ps1          # 格式化：Java(Spotless) + 前端(ESLint + Prettier)
.\scripts\format.ps1 check    # 只检查不修改
```

## 定时任务

- `bash/backup.sh` 每日备份数据库到 `/home/jack/backup`，由 `bash/init.sh` 注册到 crontab。
- 用户端后端启用 `@EnableScheduling`，每日任务生成等定时任务由 `task.generate-cron` 等配置控制。

## 说明

- `ssl/`、`config/*/application-dev.yml` 中含明文口令与证书，仅用于开发环境，生产请改走环境变量并替换密钥。