kxs-boot/AGENTS.md

AGENTS.md - Development Guidelines for LXQ Spring Boot Application

Project Overview

Java Spring Boot enterprise application (v3.5.9, Java 21) with microservices architecture. Multi-module Maven project using MyBatis-Plus, Redis, RocketMQ, OAuth2, and Swagger for API documentation.

Development Environment Setup

# Start required services with Docker Compose
docker-compose up -d lxq-mysql lxq-redis

# Install Maven if not available (required for build commands)
# Download from: https://maven.apache.org/download.cgi

# IDE Configuration
# Install Spring Java Format IntelliJ plugin:
# https://repo1.maven.org/maven2/io/spring/javaformat/spring-javaformat-intellij-idea-plugin

Build & Package Commands

# Standard Maven commands (when Maven available)
mvn clean compile                    # Compile the project
mvn clean package                   # Package the application
mvn clean install                   # Install to local repository
mvn spring-boot:run                 # Run the application
mvn test                            # Run all tests
mvn spring-javaformat:apply        # Format code (MANDATORY before commits)

# Environment-specific builds
mvn clean package -Pdev            # Development build (default)
mvn clean package -Ptest           # Test environment build
mvn clean package -Pprod           # Production build

# Run single test (when tests exist)
mvn test -Dtest=ClassName#methodName
mvn test -Dtest=ClassName

# Code formatting validation (runs automatically during validate phase)
mvn validate                        # Check code format

Code Style & Formatting Guidelines

• MANDATORY: Spring Java Format plugin (v0.0.39) - must run before commits
• Package naming: com.lxq.* convention (e.g., com.lxq.admin.biz.controller)
• Import organization: Standard Java conventions, no wildcard imports
• Class naming: PascalCase (e.g., SysUserController, UserDTO)
• Method naming: camelCase (e.g., getUserById, saveUser)
• Constants: UPPER_SNAKE_CASE (e.g., COMMON_STATUS, DEFAULT_PAGE_SIZE)
• Variables: camelCase
• Lombok usage: @Data, @AllArgsConstructor, @Slf4j for boilerplate reduction
• Line endings: Use LF (Unix style)
• Indentation: 4 spaces (no tabs)
• Max line length: 120 characters

Architecture & Layer Patterns

com.lxq.admin.biz.controller/    # REST endpoints (@RestController)
com.lxq.system.biz.service/      # Business logic (extends IService<Entity>)
com.lxq.system.biz.mapper/       # MyBatis data access (extends BaseMapper<Entity>)
com.lxq.system.biz.model/        # Entity classes (@TableName)
com.lxq.system.biz.domain.dto/   # Data transfer objects (@Data, @Schema)
com.lxq.system.biz.domain.vo/    # View objects for API responses

Layer Structure: Controller → Service → Mapper → Domain

• Controllers: Use @RestController, @RequestMapping, @AllArgsConstructor
• Services: Extend IService<Entity> from MyBatis-Plus
• Mappers: Extend BaseMapper<Entity> from MyBatis-Plus
• DTOs: Separate from entities, extend entity when appropriate
• VOs: For API responses, use Lombok @Data

API Documentation Standards

• Framework: Swagger/OpenAPI 3 with Knife4j v4.3.0

• Required Annotations:

  @Tag(description = "module", name = "description")  // On class
  @Operation(summary = "action", description = "details")  // On methods
  @SecurityRequirement(name = HttpHeaders.AUTHORIZATION)  // For secured APIs
  

• Parameter Documentation: Use @ParameterObject for query parameters

• Response Documentation: Use @Schema(description = "...") on DTOs/VOs

• Swagger UI: Available at /doc.html when swagger.enabled=true

• Example: See SysUserController.java for complete annotation patterns

Database & ORM Guidelines

• ORM: MyBatis-Plus v3.5.15 with Spring Boot 3 integration

• Entity Conventions:

  @TableName("sys_user")  // Table mapping
  @TableId(type = IdType.AUTO)  // Auto ID generation
  // Logical deletion: del_flag (0=not deleted, 1=deleted)
  

• Mapper Patterns: Extend BaseMapper<Entity> from MyBatis-Plus

• Service Patterns: Extend IService<Entity> from MyBatis-Plus

• Dynamic Datasource: Use @DS("datasource_name") annotation

• Query Builder: Use Wrappers.<Entity>query().lambda() for type-safe queries

• Join Queries: Use MyBatis-Plus-Join for complex queries

• Logical Deletion: Automatically handled (del_flag: 0/1)

Security & Authorization

• Framework: Spring Authorization Server v1.1.2 with OAuth2

• Security Annotations:

  @PreAuthorize("@pms.hasPermission('permission_key')")  // Method security
  @Inner  // Internal APIs (bypass OAuth2)
  @EnableLoginResourceServer / @EnableAuthResourceServer  // Configuration
  

• Security Utilities: SecurityUtils.getUser() for current user info

• Permission Format: module_action (e.g., sys_user_add, sys_user_del)

• Token Handling: Automatic via resource server configuration

• Public Endpoints: Configure in security.oauth2.ignore.urls

Testing Guidelines

• Framework: Spring Boot Test (spring-boot-starter-test)
• Test Structure: Create src/test/java following main package structure
• Test Naming: *Test.java for test classes (e.g., SysUserServiceTest)
• Key Annotations: @SpringBootTest, @Test, @MockBean, @ExtendWith
• Single Test Execution: mvn test -Dtest=ClassName#methodName
• Integration Tests: Use @SpringBootTest with test configuration
• Service Testing: Mock dependencies with @MockBean
• Note: No test directories currently exist - create following package structure

Error Handling & Logging

• Response Wrapper: Always return R<T> from controllers

  return R.ok(data);           // Success response
  return R.failed("error");    // Error response
  return R.failed(errorEnum);  // Error with enum
  

• Logging: Use @SysLog("operation description") on service methods

• Exception Handling: Use global exception handler with @RestControllerAdvice

• Logging Framework: SLF4J with @Slf4j annotation

• Audit Trail: @SysLog automatically logs business operations

Configuration Management

• Main Config: application.yml in admin module
• Environment Files: application-{profile}.yml (dev/test/prod)
• Property Injection: Use @ConfigurationProperties
• Profile Activation: spring.profiles.active=@profiles.active@
• Database Config: Dynamic datasource with primary/main setup
• Swagger Config: Customizable via swagger.* properties
• Server Config: Port 8080, context path /v1/admin

Common Patterns & Examples

Controller Method Template

@SysLog("操作描述")
@PostMapping("/action")
@PreAuthorize("@pms.hasPermission('module_action')")
@Operation(summary = "操作", description = "详细描述")
public R<ResultVO> action(@Valid @RequestBody RequestDTO request) {
    return R.ok(service.action(request));
}

DTO Template

@Data
@Schema(description = "对象描述")
@EqualsAndHashCode(callSuper = true)
public class EntityDTO extends Entity {
    @Schema(description = "字段描述")
    private String field;
}

Query Template

Entity entity = service.getOne(Wrappers.<Entity>query()
    .lambda()
    .eq(Entity::getField, value)
    .orderByDesc(Entity::getCreateTime));

Key Requirements Summary

1. ALWAYS run mvn spring-javaformat:apply before commits
2. ALWAYS return R<T> from controller methods
3. ALWAYS use @PreAuthorize for security checks
4. ALWAYS document APIs with Swagger annotations
5. FOLLOW Controller → Service → Mapper pattern
6. USE DTOs for input, VOs for output
7. APPLY @SysLog for business operations
8. USE MyBatis-Plus Wrappers for type-safe queries