# 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:

```bash
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):

```bash
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.