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

mvn clean install

Run the application

# 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

# 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

# Run all tests
mvn test

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

Package for deployment

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:

cd sql/tools
python3 convertor.py postgres > output.sql

Quick Database Setup with Docker

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+