初始化提交

2025-12-22 16:17:46 +08:00
commit 368639f275
1153 changed files with 124430 additions and 0 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -0,0 +1,205 @@
+# 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+