# CLAUDE.md

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

## Build & Run Commands

```bash
# Build the project
./mvnw clean package

# Run the application
./mvnw spring-boot:run

# Run all tests
./mvnw test

# Run a single test class
./mvnw test -Dtest=TestClassName

# Run a single test method
./mvnw test -Dtest=TestClassName#methodName
```

## Project Overview

- **Framework**: Spring Boot 3.2.3 with Java 21
- **ORM**: MyBatis Plus 3.5.5
- **Database**: MySQL 8.0.33
- **Cache**: Redis (Spring Data Redis)
- **API Docs**: Swagger UI at `/swagger-ui.html`
- **Auth**: JWT (jjwt 0.11.5)

## Architecture

Base package: `icu.sunway.ai_spring_example`

This project follows a layered architecture with MyBatis Plus:

| Layer | Location | Pattern |
|-------|----------|---------|
| Controller | `Controller/{EntityName}Controller/` | One subdirectory per entity |
| Service | `Service/` | Interface `I{Name}Service` extends `IService<Entity>` |
| Service Impl | `Service/Implements/` | `{Name}ServiceImpl` extends `ServiceImpl<Mapper, Entity>` |
| Mapper | `Mapper/` | `{Name}Mapper` extends `BaseMapper<Entity>` |
| Entity | `Entity/` | Lombok + MyBatis Plus annotations |
| Config | `Config/` | CORS, Security, Redis, OpenAPI |
| Utils | `Utils/` | Utility classes |

## Key Utilities

- **ResponseUtils**: Standard API responses - `ResponseUtils.success(data)` / `ResponseUtils.fail(message)`
- **PageUtils**: Pagination - `PageUtils.createPage(page, limit)` returns `Page<T>` for MyBatis Plus
- **RedisUtils**: Redis operations (inject with `@Resource`)
- **JsonUtils**: JSON serialization - `JsonUtils.toJson()` / `JsonUtils.toObject()`
- **ValidationUtils**: Input validation (email, phone, URL, IP, password strength, etc.)

## Configuration

- Copy `application-example.yaml` to `application.yaml` and fill in database/Redis credentials
- `application.yaml` is gitignored (contains sensitive data)
- Uses dynamic multi-datasource (primary datasource named "master")

## Security Notes

- Current `SecurityConfig` is permissive (all requests allowed) - configure for production
- Stateless session management configured for JWT authentication