# AGENTS.md - LXQ Spring Boot Development Guidelines

## Project Overview
Java 21, Spring Boot 3.5.9, Maven multi-module project with MyBatis-Plus, Redis, RocketMQ, OAuth2.

## Essential Commands
```bash
# Build & Run
mvn clean compile              # Compile
mvn clean package              # Package JAR
mvn spring-boot:run            # Run application
mvn clean install              # Install to local repo

# Testing
mvn test                       # Run all tests
mvn test -Dtest=ClassName      # Single test class
mvn test -Dtest=ClassName#methodName  # Single test method

# Code Quality
mvn spring-javaformat:apply    # Format code (MANDATORY before commits)
mvn validate                   # Check format during build

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

## Code Style
- **Formatter**: Spring Java Format plugin (v0.0.39) - REQUIRED before commits
- **Indentation**: 4 spaces, no tabs
- **Line endings**: LF (Unix)
- **Max line length**: 120 chars
- **No wildcard imports**
- **Line comments only** (no block comments)

## Naming Conventions
| Element | Convention | Examples |
|---------|------------|----------|
| Class/Interface | PascalCase | `SysUserController`, `UserDTO` |
| Method/Variable | camelCase | `getUserById`, `saveUser()` |
| Constant | UPPER_SNAKE_CASE | `DEFAULT_PAGE_SIZE`, `COMMON_STATUS` |
| Package | `com.kxs.{module}.biz.{layer}` | `com.kxs.admin.biz.controller` |

## Architecture Layers
```
com.kxs.{module}.biz.controller/   # REST endpoints
com.kxs.{module}.biz.service/       # Business logic
com.kxs.{module}.biz.mapper/        # Data access
com.kxs.{module}.biz.model/         # Entities
com.kxs.{module}.biz.domain.dto/    # Input DTOs
com.kxs.{module}.biz.domain.vo/     # Response VOs
```

## Layer Patterns
- **Controllers**: `@RestController`, `@AllArgsConstructor`, return `R<T>`
- **Services**: Extend `IService<Entity>`, use `@SysLog`
- **Mappers**: Extend `BaseMapper<Entity>`
- **DTOs**: `@Data`, `@Schema`, extend Entity when appropriate
- **VOs**: `@Data`, `@Schema` for API responses

## Database & ORM
```java
@TableName("table_name")
@TableId(type = IdType.AUTO)
public class Entity { }  // del_flag for logical deletion

// Query with type-safe wrapper
Wrappers.<Entity>query().lambda()
    .eq(Entity::getField, value)
    .orderByDesc(Entity::getCreateTime);
```
- **Dynamic Datasource**: `@DS("datasource_name")`
- **Joins**: Use MyBatis-Plus-Join library

## API Documentation (Knife4j/Swagger)
```java
@Tag(description = "module", name = "description")        // Class
@Operation(summary = "action", description = "details")   // Method
@ParameterObject                                        // Query params
@Schema(description = "...")                            // Fields
@SecurityRequirement(name = HttpHeaders.AUTHORIZATION)  // Secured APIs
```

## Security
```java
@PreAuthorize("@pms.hasPermission('module_action')")  // Permission check
@Inner  // Internal API (bypass OAuth2)
SecurityUtils.getUser()  // Current user info
```
- Permission format: `module_action` (e.g., `sys_user_add`)

## Error Handling
```java
return R.ok(data);                    // Success
return R.failed("error message");     // Error
return R.failed(ErrorEnum);           // Error with enum

@Slf4j  // Logger
@RestControllerAdvice  // Global exception handler
```

## Key Requirements
1. **ALWAYS** run `mvn spring-javaformat:apply` before commits
2. **ALWAYS** return `R<T>` from controllers
3. **ALWAYS** use `@PreAuthorize` for security
4. **ALWAYS** document APIs with Swagger annotations
5. **FOLLOW** Controller → Service → Mapper pattern
6. **USE** DTOs for input, VOs for output
7. **USE** `@SysLog` for business operations

## Configuration
- Main config: `kxs-admin/src/main/resources/application.yml`
- Profiles: `application-{dev|test|prod}.yml`
- Server: Port 8080, context path `/v1/admin`