feat(auth): 新增登录日志模块并记录登录失败
- 新增 SystemLoginLog 实体、Mapper、Service 及 XML 配置 - UserController 登录接口补充异常捕获与失败日志记录 - 删除旧压缩日志，新增最新日志文件 - 补充 AGENTS.md 使用说明文档
This commit is contained in:
195
AGENTS.md
Normal file
195
AGENTS.md
Normal file
@@ -0,0 +1,195 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user