Development

开发指南

技术栈

层	技术
后端	Node.js >= 24、Express、Socket.io、JWT、helmet、multer、bcryptjs、node:sqlite
沙箱	C++（sandbox/sandbox_runner.cpp → sandbox_runner.exe，Job Object/受限令牌/Low IL）
前端	原生 HTML/JS + Tailwind（CDN）、marked.js + DOMPurify、KaTeX、opentype.js 验证码
测试	Node 内置 node --test、ESLint
文档	docs/api/openapi.yaml（OpenAPI 3.0）+ APIuse.md

项目结构（关键目录）

NoldOJ/
├── start.bat / stop.bat / st.bat / sp.bat   # 启停脚本（st/sp 含 Cloudflare Tunnel）
├── config/                  # 外部配置（.gitignore 忽略；示例在 example-config/）
├── docs/                    # GitHub Pages：index.html、support.html、api/
├── frontend/
│   ├── css/  js/            # 全局样式与公共 JS（API 封装、Markdown 渲染、导航栏）
│   └── pages/               # 42 个 HTML 页面（全中文）
├── backend/
│   ├── config/config.js     # 核心配置（端口/JWT/沙箱/限流）
│   ├── database/            # schema、initDB() 自动迁移
│   ├── data/                # 运行时数据：SQLite 库 + 题目测试数据 problems/（上传文件在仓库根 data/uploads/）
│   ├── middleware/          # 认证、限流、管理员操作日志（adminLogger）
│   ├── routes/              # API 路由（22 文件 / 163 端点）
│   ├── services/            # 评测引擎、IDE 评测、AI 审查、验证码、查重
│   ├── sandbox/             # 执行器 executor.js、计分脚本 scorer.js、C++ 运行器 sandbox_runner.cpp、build.bat
│   ├── test/                # 13 个测试文件（npm test 单测 104 项 + 黑盒 test:server 24 项）
│   └── src/server.js        # 服务器入口
└── scripts/                 # 工具脚本（migrate-sqlite.js、seed-test.js 等）

开发流程

1. 改代码：编辑前先读周边代码与既有约定（路由文件拆分方式、services/ 放业务、sandbox/ 放执行与评分）。
2. 静态检查：cd backend && npm run lint（必须零错误）。
3. 测试：npm test（104 项必须全绿）；涉及服务层的改动再起服务跑 npm run test:server（黑盒 24 项）。
4. 文档同步：改了 API 需同步 docs/api/APIuse.md 与 openapi.yaml；改了配置/用法需同步 README 与 docs/support.html。
5. 提交：中文提交信息、单行摘要；只提交相关文件（config/、log/、data/ 已被忽略）。

代码约定

• ESLint：eslint:recommended；空 catch 允许（no-empty 配置为 allowEmptyCatch）、未用变量以 _ 前缀豁免。
• 编辑器/工具链：仓库内含 BOM 的 Markdown/HTML（README.md、docs/*.html、server.js 等）不要用会丢 BOM 的工具批量改写。
• 安全：新增端点必须过 auth/requireRole 中间件；SQL 全部参数化；编译/运行命令不走 shell。
• 测试：需要数据库的测试用 _testdb.js 隔离库，绝不读写生产库。

常见开发任务

任务	位置/做法
新增 API 端点	backend/routes/*.js 注册路由，前缀 /api/v1，同步 APIuse.md + openapi.yaml
新增页面	frontend/pages/*.html + 导航栏（frontend/js/ 公共组件）
修改数据库结构	backend/database/db.js 的 initDB() 迁移段（幂等 ALTER/CREATE）
新增语言	无需改代码：超管在「语言」管理页配置编译/运行命令
调试判题	看 log/<时间戳>/ 日志；检查 sandbox_runner.exe 是否编译
发版	更新 README 与 docs/support.html 的更新日志、backend/package.json 版本号

相关文档

• API 文档 · 测试与 CI · 数据库