AI_OJ/AGENTS.md

Repository Guidelines

This repository is a Maven multi-module Spring Boot microservices system for an Online Judge (AIOJ). Use the notes below as the contributor guide for structure, workflow, and expectations.

Tech Stack (Reference)

• Java 17
• Spring Boot 3.5.7
• Spring Cloud 2025.0.0
• Spring Cloud Alibaba 2025.0.0.0
• Maven build, Spring Java Format, JIB for Docker images

Project Structure & Module Organization

• Root pom.xml aggregates all modules.
• Shared libraries live in aioj-backend-common:
  • aioj-backend-common-bom (dependency management)
  • aioj-backend-common-core (core utilities + Spring extensions)
  • aioj-backend-common-security (JWT/Spring Security)
  • aioj-backend-common-feign (OpenFeign + Sentinel integration)
  • aioj-backend-common-log (AOP logging)
  • aioj-backend-common-mybatis (MyBatis extensions)
  • aioj-backend-common-starter (auto-config starter)
• Service modules live at the repo root:
  • aioj-backend-gateway, aioj-backend-auth, aioj-backend-user-service, aioj-backend-upms, aioj-backend-file-service, aioj-backend-judge-service, aioj-backend-question-service, aioj-backend-ai-service, aioj-backend-blog-service
• Supporting folders include docs, db, sentinel, logs, uploads, and generator.

Build, Test, and Development Commands

Use Maven from the repo root:

mvn clean compile                         # build all modules (no tests)
mvn clean install                         # build + run tests
mvn clean compile -pl aioj-backend-auth   # build a single module
mvn clean install -DskipTests             # build all modules, skip tests
mvn spring-boot:run -pl aioj-backend-gateway  # run a single service
mvn test -pl aioj-backend-user-service        # test a single service
mvn spring-javaformat:apply               # format code
mvn spring-javaformat:check               # verify formatting

Docker image build (JIB):

mvn package jib:build -pl <module-name>      # build & push
mvn package jib:buildTar -pl <module-name>   # build tar

Coding Style & Naming Conventions

• Follow existing formatting and run mvn spring-javaformat:apply before submitting changes.
• Indentation follows Java defaults (4 spaces; no tabs unless already present).
• Use standard Java naming: PascalCase for classes, camelCase for methods/fields, UPPER_SNAKE_CASE for constants.
• Controllers: <Resource>Controller; Services: <Resource>Service / <Resource>ServiceImpl; Mappers: <Resource>Mapper; DTOs: <Operation><Resource>DTO.
• Module names follow the aioj-backend-* pattern; keep new module names consistent.

Development Guidelines

• Service modules should depend on common modules, not on other service modules.
• Use Feign clients for inter-service communication.
• Keep classes focused and single-purpose; prefer Lombok to reduce boilerplate.
• Validate and sanitize user input; use @PreAuthorize for method security.
• Use custom exceptions + global handlers; return consistent DTO responses.
• Externalize configuration; use Nacos for centralized config management.
• Never commit sensitive credentials.

Architecture Notes

• Auth uses JWT via common-security.
• Gateway handles routing, auth checks, Sentinel-based flow control.
• Question service uses Chain of Responsibility for validation.
• Sentinel + Nacos provide dynamic flow control and rules.
• Redis used for cache/session; MyBatis for persistence.
• Blog service supports Markdown (Flexmark) + Redis caching.

Testing Guidelines

• Tests live under src/test/java in each module.
• Name tests clearly after the unit under test (e.g., UserServiceTest).
• Run mvn test for full coverage or mvn test -pl <module> for targeted runs.

Commit & Pull Request Guidelines

• Commit messages follow a conventional prefix pattern (e.g., feat: add rate limiting, refactor: simplify DTO mapping). Keep the subject imperative and concise.
• PRs should include: a short summary, affected services/modules, testing performed, and any config or port changes.
• If a change affects API behavior or configuration, update README.md or relevant docs.

Local Service Ports (Reference)

• Gateway 18085, Auth 18081, User 18082, UPMS 18083, File 18066. Update this list if you add or change service ports.