keyboard_admin/CLAUDE.md

# CLAUDE.md

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

## Project Overview

This is a Spring Boot 3.5.5 backend project using Java 17+ with a modular architecture. The project is based on the "芋道" (Yudao) framework and uses PostgreSQL as the primary database. It follows a multi-module Maven structure with clear separation between framework components, business modules, and the server container.

## Build & Run Commands

### Build the project
```bash
mvn clean install
```

### Run the application
```bash
# Run from yolo-server module
mvn spring-boot:run -pl yolo-server

# Or run the JAR after building
java -jar yolo-server/target/yolo-server.jar
```

### Run with specific profile
```bash
# Local environment (default)
mvn spring-boot:run -pl yolo-server -Dspring-boot.run.profiles=local

# Development environment
mvn spring-boot:run -pl yolo-server -Dspring-boot.run.profiles=dev
```

### Run tests
```bash
# Run all tests
mvn test

# Run tests for specific module
mvn test -pl yolo-module-system
```

### Package for deployment
```bash
mvn clean package -DskipTests
```

## Architecture

### Module Structure

The project uses a **modular monolith** architecture with the following key modules:

- **yolo-dependencies**: Centralized dependency management (BOM)
- **yolo-framework**: Technical framework components (reusable starters)
  - `yolo-common`: Core utilities, exceptions, enums, validation
  - `yolo-spring-boot-starter-web`: Web layer (Swagger, Jackson, XSS protection, API encryption)
  - `yolo-spring-boot-starter-security`: Spring Security integration
  - `yolo-spring-boot-starter-mybatis`: MyBatis Plus with multi-datasource support
  - `yolo-spring-boot-starter-redis`: Redis/Redisson integration
  - `yolo-spring-boot-starter-job`: Quartz job scheduling
  - `yolo-spring-boot-starter-mq`: Message queue support (RocketMQ, Kafka, RabbitMQ)
  - `yolo-spring-boot-starter-monitor`: Monitoring (Actuator, Spring Boot Admin)
  - `yolo-spring-boot-starter-websocket`: WebSocket support
  - `yolo-spring-boot-starter-excel`: Excel import/export
  - `yolo-spring-boot-starter-protection`: Rate limiting and circuit breaker
  - `yolo-spring-boot-starter-biz-*`: Business-specific components (tenant, data permission, IP)
- **yolo-module-system**: System management module (users, roles, permissions, dictionaries)
- **yolo-module-infra**: Infrastructure module (jobs, file storage, code generator, monitoring)
- **yolo-server**: Main application container (empty shell that aggregates modules)

### Layered Architecture

Each business module follows a standard three-layer architecture:

```
controller/     # REST API endpoints (admin-api, app-api)
  ├── admin/    # Admin backend APIs
  └── app/      # User-facing app APIs
service/        # Business logic layer
  └── impl/     # Service implementations
dal/            # Data Access Layer
  ├── dataobject/  # Entity classes (DO)
  ├── mysql/       # MyBatis mappers
  └── redis/       # Redis repositories
api/            # API interfaces and DTOs for module communication
convert/        # MapStruct converters (VO ↔ DO ↔ DTO)
enums/          # Module-specific enums
```

### Key Design Patterns

- **VO Pattern**: Request/Response VOs for API layer, separate from domain objects
- **DTO Pattern**: Data Transfer Objects for inter-module communication
- **DO Pattern**: Data Objects (entities) for persistence layer
- **Converter Pattern**: MapStruct for object mapping between layers
- **Multi-tenancy**: Built-in tenant isolation support
- **Data Permission**: Row-level data access control

## Database

### Primary Database
- **PostgreSQL** (configured in `application-local.yaml`)
- Connection: `jdbc:postgresql://localhost:5432/keyborad_db`
- Default credentials: root/123asd

### Database Scripts
SQL scripts are located in `sql/` directory with support for multiple databases:
- `sql/postgresql/` - PostgreSQL scripts
- `sql/mysql/` - MySQL scripts
- `sql/oracle/`, `sql/sqlserver/`, `sql/dm/`, `sql/kingbase/`, `sql/opengauss/` - Other DB support

### Database Conversion
Use `sql/tools/convertor.py` to convert MySQL scripts to other databases:
```bash
cd sql/tools
python3 convertor.py postgres > output.sql
```

### Quick Database Setup with Docker
```bash
cd sql/tools
docker compose up -d postgres
```

## Configuration

### Application Profiles
- `application.yaml` - Base configuration
- `application-local.yaml` - Local development (port 48080)
- `application-dev.yaml` - Development environment

### Key Configuration Properties
- `yolo.info.base-package`: Base package name (`com.yolo.keyboard`)
- `yolo.tenant.enable`: Multi-tenancy toggle (default: true)
- `yolo.api-encrypt.enable`: API encryption toggle (default: true)
- `yolo.websocket.enable`: WebSocket toggle (default: true)

### MyBatis Plus ID Strategy
The project uses "NONE" mode which auto-detects:
- AUTO for MySQL (auto-increment)
- INPUT for PostgreSQL/Oracle (requires @KeySequence on entities)

## Development Guidelines

### Adding New Features

1. **Choose the correct module**: System features go in `yolo-module-system`, infrastructure features in `yolo-module-infra`
2. **Follow the layer structure**: Controller → Service → DAL
3. **Use MapStruct for conversions**: Create converters in the `convert/` package
4. **API versioning**: Use `/admin-api/` prefix for admin APIs, `/app-api/` for user APIs

### Code Generation

The project includes a code generator in `yolo-module-infra`:
- Configured via `yolo.codegen.*` properties
- Generates Controller, Service, Mapper, DO, VO classes
- Uses Velocity templates

### Annotation Processors

The Maven compiler is configured with multiple annotation processors (order matters):
1. `spring-boot-configuration-processor`
2. `lombok`
3. `lombok-mapstruct-binding` (ensures Lombok works with MapStruct)
4. `mapstruct-processor`

### Multi-datasource Usage

Configured via `spring.datasource.dynamic.datasource`:
- `master`: Primary datasource (PostgreSQL)
- `slave`: Read replica (optional)
- Use `@DS("slave")` annotation to switch datasource

## API Documentation

- **Swagger UI**: http://localhost:48080/swagger-ui
- **Knife4j UI**: http://localhost:48080/doc.html (enhanced Swagger UI)
- **OpenAPI JSON**: http://localhost:48080/v3/api-docs

## Monitoring & Admin

- **Spring Boot Admin**: http://localhost:48080/admin
- **Actuator**: http://localhost:48080/actuator
- **Druid Monitor**: http://localhost:48080/druid (database connection pool)

## Common Issues

### Startup Problems
If you encounter startup issues, refer to: https://doc.iocoder.cn/quick-start/

### Database Connection
Ensure PostgreSQL is running and credentials in `application-local.yaml` are correct.

### Port Conflicts
Default port is 48080. Change via `server.port` in configuration files.

## Dependencies & Versions

- Java: 17+
- Spring Boot: 3.5.5
- MyBatis Plus: Latest (managed by yolo-dependencies)
- Lombok: 1.18.42
- MapStruct: 1.6.3
- Maven: 3.9+