# AGENTS.md

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

## Project Overview

This is a Spring Boot 2.7.2 application serving as a multi-tenant system with AI integration capabilities. The application focuses on host/streamer data management with AI chat functionality, built on a layered architecture pattern.

**Key Technologies:**
- Spring Boot 2.7.2 with Java 17
- MyBatis-Plus 3.5.2 for data access
- SA-Token 1.44.0 for authentication
- Redis for distributed caching and session management
- RabbitMQ for message-driven architecture
- Knife4j 4.4.0 for API documentation
- MySQL database

## Build and Run Commands

### Development
```bash
# Run the application (dev profile is default)
mvn spring-boot:run

# Build the project
mvn clean package

# Run tests
mvn test

# Skip tests during build
mvn clean package -DskipTests
```

### Database Setup
```bash
# Initialize database using the SQL script
mysql -u root -p < sql/create_table.sql
```

**Important:** Update database credentials in `src/main/resources/application.yml` before running.

### Access Points
- Application: http://localhost:8101/api
- API Documentation: http://localhost:8101/api/doc.html

## Architecture

### Layered Structure
The codebase follows a standard layered architecture:

**Controller Layer** (`controller/`) → **Service Layer** (`service/`) → **Mapper Layer** (`mapper/`) → **Database**

### Key Packages
- `annotation/` - Custom annotations like `@AuthCheck` for role-based access control
- `aop/` - Aspect-oriented programming for cross-cutting concerns (logging, auth)
- `config/` - Spring configuration classes for SA-Token, MyBatis-Plus, Redis, RabbitMQ, CORS
- `model/entity/` - Database entities mapped with MyBatis-Plus
- `model/dto/` - Data Transfer Objects for API requests
- `model/vo/` - View Objects for API responses
- `model/enums/` - Enumerations including `LoginSceneEnum` for multi-scenario authentication
- `exception/` - Custom exception handling with `GlobalExceptionHandler`
- `utils/` - Utility classes for common operations

### Authentication System (SA-Token)

The application uses SA-Token with **multiple login scenarios**:

1. **HOST** - Host/streamer login (`/user/doLogin`)
2. **BIG_BROTHER** - Admin tenant login (`/user/bigbrother-doLogin`)
3. **AI_CHAT** - AI chat login (`/user/aiChat-doLogin`)
4. **WEB_AI** - Web AI login (`/user/webAi-doLogin`)

Each scenario uses a different SA-Token login mode (defined in `LoginSceneEnum`) and has its own role validation logic in `SystemUsersService`.

**Token Configuration:**
- Token name: `vvtoken`
- Timeout: 172800 seconds (2 days)
- Non-concurrent login (new login kicks out old session)
- Token style: random-128

**Public Endpoints** (no authentication required):
- All Swagger/Knife4j documentation endpoints
- Login endpoints for all scenarios
- `/tenant/get-id-by-name`
- `/error`

See `SaTokenConfigure.java:35` for the complete list of excluded paths.

### Database Layer (MyBatis-Plus)

**Configuration Notes:**
- Camel case to underscore mapping is **disabled** (`map-underscore-to-camel-case: false`)
- Field names in entities must match database column names exactly
- Logical deletion is enabled globally via `isDelete` field
- Pagination is configured via `PaginationInnerInterceptor`

**Custom Mappers:**
- Complex queries use XML mappers in `src/main/resources/mapper/`
- Simple CRUD operations use MyBatis-Plus built-in methods

### Message Queue (RabbitMQ)

The application uses **HeadersExchange** pattern for message routing. Configuration is in `RabbitMQConfig.java`.

**Key Queues:**
- Multiple business-specific queues with persistent messages
- Manual acknowledgment mode
- JSON message serialization with Jackson

### Redis Integration

Redis is used for:
- Distributed session storage (Spring Session)
- SA-Token session management
- Custom caching needs

**Configuration:** See `RedisConfig.java` for JSON serialization setup with Jackson.

### Multi-Tenant Architecture

The system supports multi-tenancy with:
- `SystemTenant` entity for tenant management
- `SystemUsers` entity with tenant associations
- Tenant-specific authentication flows (BIG_BROTHER scenario)
- Tenant ID retrieval endpoint: `/tenant/get-id-by-name`

## Development Guidelines

### Adding New Endpoints

1. Create/update DTO in `model/dto/` for request validation
2. Create/update VO in `model/vo/` for response formatting
3. Add service method in appropriate service interface and implementation
4. Add controller endpoint with proper `@AuthCheck` annotation if authentication is required
5. If endpoint should be public, add path to `SaTokenConfigure.getExcludePaths()`

### Working with Authentication

**Role-based Access Control:**
```java
@AuthCheck(mustRole = UserRoleEnum.ADMIN)
public BaseResponse<String> adminOnlyEndpoint() {
    // Implementation
}
```

**Multi-scenario Login:**
- Use `LoginSceneEnum` to determine the login scenario
- Each scenario has its own SA-Token mode and role validation
- Logout endpoints are scenario-specific (e.g., `/user/aiChat-logout`)

### Database Entities

**Important:** When creating or modifying entities:
- Use `@TableName` to specify exact table name
- Use `@TableField` for fields that don't follow naming conventions
- Include `isDelete` field for logical deletion support
- Add `createTime` and `updateTime` with appropriate defaults

### Code Generation

The project includes FreeMarker-based code generation utilities in the `generate/` package for scaffolding new modules.

## Configuration Files

- `application.yml` - Main configuration with SA-Token, database, and server settings
- `application-dev.yml` - Development environment overrides
- `application-prod.yml` - Production environment overrides

**Active Profile:** Defaults to `dev` (see `application.yml:9`)

## Important Notes

- **Redis:** Currently disabled in `MainApplication.java`. To enable, remove `RedisAutoConfiguration` from the `exclude` list and uncomment session store-type in `application.yml:17`
- **MyBatis Logging:** Disabled by default in static block of `MainApplication.java:24-27`
- **Context Path:** All endpoints are prefixed with `/api` (see `application.yml:42`)
- **File Upload Limit:** 10MB (see `application.yml:37`)
- **CORS:** Configured to allow all origins in `SaTokenConfigure.corsHandle()`

## Testing

Tests are located in `src/test/java/`. The project uses Spring Boot Test framework.

Run specific test class:
```bash
mvn test -Dtest=ClassName
```

## Common Issues

1. **Authentication Errors:** Verify the correct login endpoint is being used for the scenario (HOST, BIG_BROTHER, AI_CHAT, WEB_AI)
2. **Database Connection:** Ensure MySQL is running and credentials in `application.yml` are correct
3. **Redis Connection:** If Redis features are needed, enable Redis in `MainApplication.java` and configure connection in `application.yml`
4. **Field Mapping Issues:** Remember that camel-to-underscore mapping is disabled; field names must match exactly