tkcrawl-client/AGENTS.md

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

# 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

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

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

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