OJ_server/AGENTS.md

AGENTS.md

Spring Boot 3.5 / Java 17 OJ backend template. Root project is serve (see settings.gradle.kts), Java package space.anyi.serve. Stack and API docs are in README.md; this file only covers non-obvious gotchas.

Commands

• Run: ./gradlew bootRun (serves on :8080)
• Test: ./gradlew test (JUnit Platform). No lint/format/typecheck or CI config exists.

Runtime prerequisites

• Startup requires env vars databaseHost, databaseUsername, databasePassword — missing any makes the app fail on first DB access. No local dev defaults are provided.
• DB is named oj, all tables live in the dev schema. Initialize via psql -U <user> -f sql/postgersql.sql (note the misspelled filename postgersql.sql).
• The contextLoads test spins up the full context and needs a live PostgreSQL; it fails without one.

Architecture & conventions

• Every controller returns the Response<T> wrapper (Response.ok / Response.error). Validation failures map to HTTP 400; other uncaught exceptions return HTTP 200 with an error body (see GlobalExceptionHandler).
• Auth is stateless JWT in Authorization: Bearer <token>. Roles are stored as plain user/coach/admin in the DB, but method-level auth requires the ROLE_ prefix — JwtAuthenticationFilter adds it, so write @PreAuthorize("hasRole('ROLE_admin')"). Only /auth/login, /auth/register, and swagger paths are public.
• No Lombok. Entities/DTOs use hand-written getters/setters; controllers use @Resource injection, services use constructor injection.
• Status/enum values are defined as public static final constants in the entity class they belong to (e.g. User.ROLE_ADMIN, Contest.STATUS_RUNNING, Submission.STATUS_AC, Problem.DIFFICULTY_EASY). Use those constants instead of hardcoded string/number literals everywhere in Java code. Exception: SpEL annotation strings (@PreAuthorize("hasRole('ROLE_admin')")), the "ROLE_" + role authority-prefix concatenation, Swagger @Schema/@Parameter description text, and MyBatis XML (which cannot reference Java constants, e.g. status = 'AC' in SubmissionMapper.xml) keep literals — when adding a literal to a mapper XML, mirror the matching entity constant and keep the value in sync.
• MyBatis-Plus has a global logic-delete field (deleteFlag), so deletes are logical. Entities target schema-qualified tables via @TableName("dev.user"). Mapper XML lives in src/main/resources/mapper/.
• JWT secret is a hardcoded base64 key in JwtTokenProvider, 24h expiry, using the jjwt 0.12 API (verifyWith/parseSignedClaims).
• Swagger UI: /swagger-ui/index.html.

本地代码沙箱（space.anyi.codesandbox）

• 沙箱在独立包 space.anyi.codesandbox（与 space.anyi.serve 平级，不在 serve 包内）。实现未接入 Spring Bean，直接 new JVMNativeCodeSandBox() 调用；CodeSandBox 是接口，控制器/服务依赖抽象。
• CodeContext.maxMemory 单位为 KB（与 Submission.memoryUsedKb 一致），拼接为 -Xmx<kb>k 传给子 JVM；maxTime 单位为毫秒。不要传字节值（会把 256MB 变成 256GB）。
• 输出判定不是严格 equals：按行归一化，忽略行尾空白（空格/\t/\r）与末尾空行（outputMatches）。
• 并发上限 MAX_CONCURRENT（默认 10），超限 tryAcquire(5s) 失败返回 SE「系统繁忙」。超时/异常路径由 destroyForcibly() 杀子进程，临时目录 code/<uuid> 在 finally 中删除，不得在早退路径遗漏。
• 运行时 javac/java 取 JAVA_HOME（回退 java.home），需指向含 javac/java 的 JDK；环境为 JDK 17 时测试可运行（Gradle toolchain 为 17）。
• JVMNativeCodeSandBoxTest 需真实 JDK/JVM 子进程，不依赖数据库。

Coding style

• Controller methods take concrete DTOs for request bodies/params (e.g. UserDto, LoginDto) and return concrete VOs for responses (e.g. UserVo), never raw User entities or generic maps.
• OpenAPI annotations are mandatory on APIs and models: @Tag/@Operation on controllers and methods, and @Schema on both request DTOs and response VOs (class-level and per-field). Follow the existing DTO/VO examples.
• Depend on abstractions, not implementations: controllers inject the service interface (UserService), implementations live in service/impl/ (UserServiceImpl). Don't let controllers reference impl classes directly.

Workflow

• Active branch is oj. Commit messages use the # feat: ... / # sql: ... prefix style from git log.
• Commit after every completed feature point (each feature is a separate version-control checkpoint).