# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Codebase Overview

This is a microservices architecture for an Online Judge (OJ) system, built on **Spring Boot 3.5.7** with **Spring Cloud 2025.0.0** and **Spring Cloud Alibaba 2025.0.0.0**. The project uses Maven as the build tool and follows a modular monorepo structure, with clearly separated core modules and service modules.

### Core Modules

The `aioj-backend-common` directory contains shared components and utilities used across all service modules:

1. **aioj-backend-common-bom**
   Bill of materials for centralized dependency management. This ensures consistent versions of all external libraries across all modules.

2. **aioj-backend-common-core**
   Core utilities and Spring framework extensions:
   - `BannerApplicationRunner`: Custom application banner display during startup
   - `SpringContextHolder`: Spring context accessor for non-Spring-managed classes
   - `JavaTimeModule`: Jackson module for Java 8+ time API support
   - Common constants and enumerations
   - Application-level configurations and auto-configuration classes

3. **aioj-backend-common-security**
   Security components for JWT authentication and Spring Security:
   - `JwtAuthenticationFilter`: JWT token validation filter
   - `JwtUtil`: JWT token generation and parsing utilities
   - `SecurityConfiguration`: Spring Security configuration with JWT support
   - `SecurityAutoConfiguration`: Auto-configuration for security features
   - JWT properties configuration with customizable secret and expiration

4. **aioj-backend-common-feign**
   Feign client configurations for seamless inter-service communication:
   - Auto-configuration for Feign clients with default settings
   - `@EnableAIOJFeignClients` annotation for enabling Feign clients with predefined base packages
   - Feign interceptors and error handling mechanisms
   - Integrated with Sentinel for circuit breaking

5. **aioj-backend-common-log**
   Aspect-oriented programming (AOP) based logging framework:
   - `SysLogAspect`: Aspect for logging system operations (controller methods, service calls)
   - `SysLogEvent` and `SysLogListener`: Event-driven logging mechanism
   - `SysLogUtils`: Utility class for creating and managing log entries
   - Configuration properties for logging behavior

6. **aioj-backend-common-mybatis**
   MyBatis ORM framework extensions:
   - Auto-fill functionality for `createTime` and `updateTime` fields
   - Pagination interceptor implementation
   - MyBatis configuration auto-configuration classes

7. **aioj-backend-common-starter**
   Auto-configuration starters for easily enabling common features in service modules.


### Service Modules

The service modules represent the individual microservices that make up the system:

1. **aioj-backend-auth**
   Authentication and authorization service:
   - JWT-based authentication with `JwtAuthenticationFilter`
   - Security configuration with Spring Security
   - User login, token generation, and validation
   - Permission verification and access control

2. **aioj-backend-gateway**
   API gateway for request routing and filtering:
   - Request routing to appropriate service modules based on path patterns
   - Authentication token validation before forwarding requests
   - Sentinel integration for rate limiting and circuit breaking
   - Load balancing and service discovery via Nacos

3. **aioj-backend-judge-service**
   Code judge service (under development):
   - Will handle code submission, compilation, and execution
   - Support for multiple programming languages
   - Test case validation and result return

4. **aioj-backend-user-service**
   User management service:
   - User registration, profile management, and information retrieval
   - User role and permission assignment
   - Integration with the auth service for authentication

5. **aioj-backend-question-service**
   Question bank service with advanced validation and flow control:
   - Programming problem management with CRUD operations
   - **Chain of Responsibility pattern** for request validation:
     - `QuestionTitleVerifyChain`, `QuestionContentVerifyChain`, etc. for create operations
     - `QuestionUpdateExistVerifyChain`, `QuestionUpdateTitleVerifyChain`, etc. for update operations
     - `QuestionExistVerifyChain`, `QuestionStatusVerifyChain`, `CodeVerifyChain`, `LanguageVerifyChain` for submission validation
   - **Sentinel flow control** with Nacos datasource for dynamic rule management
   - Redis integration for caching and session management
   - Support for problem difficulty levels, tags, and judge configuration
   - Integration with judge service for code submission

6. **aioj-backend-ai-service**
   AI-related functionality service (under development):
   - Will provide AI-assisted features like problem recommendation, code analysis, etc.

7. **aioj-backend-upms**
   User, permission, and menu management service (modular structure):
   - **aioj-backend-upms-api**: API definitions and DTOs for UPMS functionality
   - **aioj-backend-upms-biz**: Business logic implementation
   - Low-level user and permission management
   - Menu and resource access control
   - Integration with other services for authorization

8. **aioj-backend-file-service**
   File storage and management service:
   - Tencent Cloud COS integration for object storage
   - File upload, download, and management APIs
   - Support for various file types
   - Nacos service discovery integration

9. **aioj-backend-blog-service**
   Blog and content sharing service:
   - User article creation and publishing
   - **Markdown support** with Flexmark parser
   - **Redis caching** for improved performance
   - Spring Session for distributed session management
   - Technical experience sharing and discussion platform

## Commonly Used Commands

### Build
- **Build the entire project**: `mvn clean compile`
- **Build with tests**: `mvn clean install`
- **Build a single module**: `mvn clean compile -pl aioj-backend-auth`
- **Skip tests**: `mvn clean install -DskipTests`

### Code Formatting
- **Format code**: `mvn spring-javaformat:apply`
- **Check code format**: `mvn spring-javaformat:check`

### Testing
- **Run all tests**: `mvn test`
- **Run tests for a single module**: `mvn test -pl aioj-backend-user-service`

### Running Services
- **Run a service locally**: Use Spring Boot's `Application` class directly in IDE or use `mvn spring-boot:run -pl <module-name>`
- **Example**: `mvn spring-boot:run -pl aioj-backend-auth`

### Docker Image Build (using JIB)
- **Build and push Docker image**: `mvn package jib:build -pl <module-name>`
- **Build Docker image to tar file**: `mvn package jib:buildTar -pl <module-name>`
- **Example**: `mvn package jib:build -pl aioj-backend-gateway`

## Technology Stack

### Core Framework
- **Spring Boot**: 3.5.7
- **Spring Cloud**: 2025.0.0
- **Spring Cloud Alibaba**: 2025.0.0.0
- **Java Version**: 17

### Infrastructure Components
- **Service Discovery**: Alibaba Nacos
- **Flow Control**: Alibaba Sentinel
- **API Gateway**: Spring Cloud Gateway
- **Load Balancing**: Spring Cloud LoadBalancer

### Data & Persistence
- **ORM Framework**: MyBatis
- **Database**: MySQL
- **Cache**: Redis (Spring Data Redis)
- **Session**: Spring Session with Redis

### Security & Authentication
- **Security Framework**: Spring Security
- **Authentication**: JWT (JSON Web Tokens)
- **JWT Library**: JJWT (io.jsonwebtoken)

### Service Communication
- **HTTP Client**: OpenFeign
- **Circuit Breaker**: Sentinel

### Storage & Content
- **Object Storage**: Tencent Cloud COS
- **Markdown Parser**: Flexmark 0.64.8

### Documentation
- **API Documentation**: SpringDoc OpenAPI 3
- **API UI**: Knife4j

### Utilities
- **Java Utilities**: Hutool (hutool-core, hutool-extra, hutool-crypto)
- **Logging**: SLF4J with Logback (via Spring Boot)
- **JSON Processing**: Jackson (via Spring Boot)

### Build & Deploy
- **Build Tool**: Maven
- **Code Formatting**: Spring Java Format Maven Plugin 0.0.47
- **Docker Build**: JIB Maven Plugin 3.4.5
- **Git Info**: Git Commit ID Plugin 9.0.2
- **Version Management**: Flatten Maven Plugin 1.6.0

## Architecture Highlights

- **Authentication & Security**:
  - JWT-based authentication with `JwtAuthenticationFilter` in `common-security`
  - Centralized security configuration shared across services
  - Token generation, parsing, and validation utilities in `JwtUtil`

- **Flow Control & Rate Limiting**:
  - **Alibaba Sentinel** integration for flow control and circuit breaking
  - Dynamic rule management with Nacos datasource
  - Applied in question-service for submission rate limiting
  - Gateway-level traffic control and service protection

- **Request Validation**:
  - **Chain of Responsibility pattern** in question-service for complex validation logic
  - Modular and extensible validation chains for different operations
  - Context-based validation with clear separation of concerns

- **Logging**:
  - Aspect-oriented logging with `SysLogAspect` in `common-log`
  - Event-driven logging mechanism with `SysLogEvent` and `SysLogListener`

- **Database**:
  - MyBatis with auto-fill for create/update times in `common-mybatis`
  - Pagination support with interceptor implementation

- **Caching & Session**:
  - Redis integration for distributed caching
  - Spring Session for distributed session management
  - Applied in question-service and blog-service

- **Inter-service communication**:
  - Feign clients with auto-configuration from `common-feign`
  - Integrated with Sentinel for circuit breaking
  - Nacos service discovery for dynamic service routing

- **File Storage**:
  - Tencent Cloud COS integration in file-service
  - Support for object storage and CDN acceleration

- **Content Processing**:
  - Markdown parsing with Flexmark in blog-service
  - Rich text content support for technical articles

- **Banner**:
  - Custom application banner system in `common-core`

## Key Entry Points

- **Gateway Application**: `aioj-backend-gateway/src/main/java/cn/meowrain/aioj/backend/gateway/AIOJGatewayApplication.java`
- **Auth Application**: `aioj-backend-auth/src/main/java/cn/meowrain/aioj/backend/auth/AIOJAuthApplication.java`
- **User Service Application**: `aioj-backend-user-service/src/main/java/cn/meowrain/aioj/backend/userservice/UserServiceApplication.java`
- **Question Service Application**: `aioj-backend-question-service/src/main/java/cn/meowrain/aioj/backend/question/QuestionServiceApplication.java`
- **File Service Application**: `aioj-backend-file-service/src/main/java/cn/meowrain/aioj/backend/file/FileServiceApplication.java`
- **Blog Service Application**: `aioj-backend-blog-service/src/main/java/cn/meowrain/aioj/backend/blog/BlogServiceApplication.java`
- **UPMS Service Application**: `aioj-backend-upms/aioj-backend-upms-biz/src/main/java/cn/meowrain/aioj/backend/upms/UpmsApplication.java`

## Key Design Patterns

### Chain of Responsibility Pattern (Question Service)
Located in `aioj-backend-question-service/src/main/java/cn/meowrain/aioj/backend/question/dto/chains/`:

- **Create Question Validation**: `QuestionTitleVerifyChain`, `QuestionContentVerifyChain`, `QuestionDifficultyVerifyChain`, `QuestionTagsVerifyChain`, `QuestionJudgeConfigVerifyChain`
- **Update Question Validation**: `QuestionUpdateExistVerifyChain`, `QuestionUpdateTitleVerifyChain`, `QuestionUpdateContentVerifyChain`, etc.
- **Submit Question Validation**: `QuestionExistVerifyChain`, `QuestionStatusVerifyChain`, `LanguageVerifyChain`, `CodeVerifyChain`
- **Context Objects**: `QuestionCreateRequestParamVerifyContext`, `QuestionUpdateRequestParamVerifyContext`, `QuestionSubmitRequestParamVerifyContext`

### Security Filter Chain (Common Security)
Located in `aioj-backend-common/aioj-backend-common-security/`:

- `JwtAuthenticationFilter`: Pre-authentication filter for JWT token validation
- `SecurityConfiguration`: Spring Security filter chain configuration
- `SecurityAutoConfiguration`: Auto-configuration for security beans

## Development Guidelines

### Module Dependencies
- Service modules should depend on common modules, not other service modules
- Use Feign clients for inter-service communication
- Common modules should be lightweight and not depend on service-specific logic

### Code Style
- Follow Spring Java Format conventions
- Run `mvn spring-javaformat:apply` before committing code
- Use Lombok annotations to reduce boilerplate code
- Keep classes and methods focused and single-purpose

### Security Best Practices
- Use `@PreAuthorize` annotations for method-level security
- Never expose sensitive information in API responses
- Always validate and sanitize user input
- Use the chain of responsibility pattern for complex validation logic

### API Design
- Follow RESTful conventions
- Use appropriate HTTP methods (GET, POST, PUT, DELETE)
- Return consistent response structures using common DTOs
- Document APIs using SpringDoc annotations

### Error Handling
- Use custom exception classes for domain-specific errors
- Implement global exception handlers in controllers
- Return meaningful error messages to clients
- Log errors appropriately with context information

### Testing
- Write unit tests for service layer logic
- Use integration tests for controller endpoints
- Mock external dependencies in tests
- Aim for high code coverage on critical paths

### Configuration Management
- Use `application.yml` for service configuration
- Externalize environment-specific settings
- Use Nacos for centralized configuration management
- Never commit sensitive credentials to version control

### Flow Control with Sentinel
- Configure Sentinel rules in Nacos for dynamic updates
- Use `@SentinelResource` annotations for method-level flow control
- Define fallback methods for degraded service behavior
- Monitor Sentinel dashboard for real-time metrics
- Apply flow rules at both gateway and service levels

## Project Structure Best Practices

### Package Organization
```
cn.meowrain.aioj.backend.<service-name>
├── controller/       # REST API endpoints
├── service/          # Business logic
│   └── impl/        # Service implementations
├── mapper/          # MyBatis mappers
├── entity/          # Database entities
├── dto/             # Data transfer objects
│   └── chains/      # Validation chains (if applicable)
├── config/          # Spring configuration classes
├── common/          # Service-specific common utilities
│   ├── enums/       # Enumerations
│   └── constants/   # Constants
└── <ServiceName>Application.java  # Main application class
```

### Naming Conventions
- **Controllers**: `<Resource>Controller` (e.g., `QuestionController`)
- **Services**: `<Resource>Service` (interface) and `<Resource>ServiceImpl` (implementation)
- **Mappers**: `<Resource>Mapper` (e.g., `QuestionMapper`)
- **Entities**: Noun representing the domain object (e.g., `Question`, `User`)
- **DTOs**: `<Operation><Resource>DTO` (e.g., `CreateQuestionDTO`, `UpdateQuestionDTO`)
- **Validation Chains**: `<Resource><Property>VerifyChain` (e.g., `QuestionTitleVerifyChain`)

## Infrastructure Setup

### Required Services
Before running the microservices, ensure the following infrastructure components are running:

1. **Nacos Server** (Service Discovery & Configuration Center)
   - Default URL: http://localhost:8848/nacos
   - Required for service registration and configuration management

2. **Sentinel Dashboard** (Optional, for flow control monitoring)
   - Monitor real-time traffic and configure flow rules
   - Rules are persisted to Nacos

3. **MySQL Database**
   - Required for persistent data storage
   - Each service may have its own database schema

4. **Redis Server**
   - Required for caching and session management
   - Used by question-service and blog-service

5. **Tencent Cloud COS** (for file-service)
   - Configure credentials in application configuration
   - Required only if using file-service

### Service Startup Order (Recommended)
1. Start infrastructure services (MySQL, Redis, Nacos)
2. Start auth service (authentication required by other services)
3. Start gateway service (API entry point)
4. Start business services (user-service, question-service, etc.) in any order

### Configuration Files
Each service has `application.yml` with profiles:
- `application.yml`: Common configuration
- `application-dev.yml`: Development environment
- `application-test.yml`: Test environment
- `application-prod.yml`: Production environment

Activate profiles using: `spring.profiles.active=dev` or `-Dspring.profiles.active=dev`