martial-master/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 martial arts competition management system built on the **BladeX framework** (Spring Boot-based enterprise platform). The project is a monolithic Spring Boot application that manages martial arts competition events, including competitions, athletes, judges, schedules, venues, scores, and registration orders.

**Technology Stack:**
- Spring Boot 3.x (managed by BladeX BOM)
- MyBatis-Plus (ORM)
- Java 17
- MySQL database
- Redis for caching
- Knife4j/Swagger for API documentation
- BladeX 4.0.1.RELEASE enterprise framework

## Build and Run Commands

### Build Prerequisites

**IMPORTANT:** This project depends on the BladeX-Tool framework which must be compiled first.

**Step 1: Compile BladeX-Tool framework (required first time):**
```bash
cd /remote_dev/martial/martial-tool
mvn clean install -DskipTests
```
This compiles all 44 BladeX framework modules and installs them to your local Maven repository (~/.m2).

**Step 2: Compile martial-master project:**
```bash
cd /remote_dev/martial/martial-master
mvn clean package -DskipTests -Dmaven.test.skip=true
```
Note: `-Dmaven.test.skip=true` is required to skip test compilation as some test dependencies are not configured.

### Maven Build Commands

```bash
# Clean and compile the project
mvn clean compile

# Package the application (creates JAR in target/)
mvn clean package -DskipTests -Dmaven.test.skip=true

# Run the application
mvn spring-boot:run
```

### Runtime Requirements

Before running the application, ensure these services are available:

**Required Services:**
- **MySQL**: 127.0.0.1:33066 (high port) with database `martial_db`
  - Username: root
  - Password: WtcSecure901faf1ac4d32e2bPwd
  - Container: dev-mysql

- **Redis**: 127.0.0.1:63379 (high port)
  - Password: RedisSecure2024MartialXyZ789ABC
  - Database: 8
  - Container: dev-redis

**Services Management:**

```bash
# MySQL 容器管理
docker ps --filter "name=dev-mysql"
docker logs dev-mysql

# Redis 容器管理
cd /remote_dev/dev_tools/redis
docker-compose ps
docker-compose logs -f
docker-compose restart
```

**Application Server:**
- **Port**: 82 (configured in application.yml)
- **Main Class**: org.springblade.Application

### Running the Application

**Development mode:**
```bash
# Runs with dev profile (application-dev.yml)
mvn spring-boot:run -Dspring-boot.run.profiles=dev
```

**Or using the JAR file:**
```bash
cd /remote_dev/martial/martial-master
java -jar target/blade-api.jar --spring.profiles.active=dev
```

**Production mode:**
```bash
java -jar target/blade-api.jar --spring.profiles.active=prod
```

**Test mode:**
```bash
java -jar target/blade-api.jar --spring.profiles.active=test
```

**Access points after startup:**
- API Server: http://localhost:8123
- Swagger UI: http://localhost:8123/doc.html
- Druid Monitor: http://localhost:8123/druid (username: blade, password: 1qaz@WSX)

### Docker Commands

```bash
# Build Docker image
mvn clean package
docker build -t martial-api:latest .

# Run with Docker
docker run -p 8800:8800 martial-api:latest
```

## Database Setup

**Database name:** `martial_db`

**Connection Information:**
- Host: 127.0.0.1
- Port: 33066 (high port)
- Username: root
- Password: WtcSecure901faf1ac4d32e2bPwd

**Required setup steps:**
1. Database already created in dev-mysql container
2. Execute base BladeX schema (if not already present)
3. Execute martial arts tables: `doc/sql/mysql/martial-competition-tables.sql`
4. Execute menu configuration: `doc/sql/mysql/martial-competition-menu.sql`

**Database connection configuration:**
- Dev: `src/main/resources/application-dev.yml` (已配置高位端口)
- Test/Prod: 需要根据环境调整端口和密码

**Redis configuration:**
- Dev: localhost:63379 (high port)
- Password: RedisSecure2024MartialXyZ789ABC
- Database: 8

## Code Architecture

### Module Structure

The application follows a **modular monolithic architecture** under `org.springblade.modules`:

- **auth**: Authentication and authorization (token-based, multiple grant types: password, captcha, refresh, social)
- **system**: Core system functionality (users, roles, menus, departments, dictionaries, tenants)
- **resource**: Resource management (attachments, SMS, OSS storage)
- **desk**: Dashboard and notification features
- **develop**: Code generation and datasource management
- **martial**: **Martial arts competition domain** (main business module)

### Martial Arts Module Structure

Located in `src/main/java/org/springblade/modules/martial/`:

```
martial/
├── entity/          # Domain entities (9 tables)
│   ├── Athlete.java
│   ├── Competition.java
│   ├── Judge.java
│   ├── Project.java
│   ├── RegistrationOrder.java
│   ├── Result.java
│   ├── Schedule.java
│   ├── Score.java
│   └── Venue.java
├── mapper/          # MyBatis mappers
├── service/         # Service interfaces (extend BaseService)
├── controller/      # REST controllers (extend BladeController)
├── vo/              # View objects for API responses
└── dto/             # Data transfer objects
```

### BladeX Framework Conventions

**Base Classes:**
- All entities extend `org.springblade.core.mp.base.BaseEntity` (provides: id, createUser, createDept, createTime, updateUser, updateTime, status, isDeleted)
- All services extend `BaseService<T>` from MyBatis-Plus
- All controllers extend `BladeController` for standard CRUD operations

**Multi-tenancy:**
- Enabled by default with `tenant_id` column
- Use `@TenantDS` annotation on controllers for tenant data isolation
- Excluded tables configured in `application.yml` under `blade.tenant.exclude-tables`

**API Response Format:**
- All endpoints return `R<T>` wrapper (contains code, success, data, msg)
- Success: `R.data(entity)` or `R.status(boolean)`
- Failure: `R.fail(message)`

**Security:**
- Token-based authentication (stateless by default: `blade.token.state=false`)
- Skip authentication URLs configured in `blade.secure.skip-url`
- `/api/martial/**` endpoints are publicly accessible (configured in skip-url)

### MyBatis-Plus Configuration

**Mapper XML locations:** `classpath:org/springblade/**/mapper/*Mapper.xml`

**ID Generation:** Snowflake (`assign_id`)

**Logical delete:**
- Deleted: `is_deleted = 1`
- Not deleted: `is_deleted = 0`

**Field strategies:** NOT_NULL for insert/update operations

## Common Development Patterns

### Creating a New CRUD Module

1. **Create Entity** in `entity/` extending BaseEntity
2. **Create Mapper** interface in `mapper/` extending BaseMapper<Entity>
3. **Create Service** interface in `service/` extending BaseService<Entity>
4. **Create ServiceImpl** in `service/impl/` extending ServiceImpl<Mapper, Entity>
5. **Create Controller** in `controller/` extending BladeController
6. **Add VO** (optional) in `vo/` for custom response formats
7. **Add Mapper XML** (optional) in `src/main/resources/org/springblade/modules/{module}/mapper/` for complex queries

### Standard Controller Pattern

```java
@TenantDS
@RestController
@RequestMapping("/api/martial/{resource}")
@AllArgsConstructor
@Api(value = "Resource Management", tags = "Resource API")
public class ResourceController extends BladeController {

    private final IResourceService resourceService;

    @GetMapping("/detail")
    public R<Resource> detail(@RequestParam Long id) {
        return R.data(resourceService.getById(id));
    }

    @GetMapping("/list")
    public R<IPage<Resource>> list(Resource resource, Query query) {
        IPage<Resource> pages = resourceService.page(
            Condition.getPage(query),
            Condition.getQueryWrapper(resource)
        );
        return R.data(pages);
    }

    @PostMapping("/submit")
    public R submit(@RequestBody Resource resource) {
        return R.status(resourceService.saveOrUpdate(resource));
    }

    @PostMapping("/remove")
    public R remove(@RequestParam String ids) {
        return R.status(resourceService.deleteLogic(Func.toLongList(ids)));
    }
}
```

## Configuration Profiles

**Available profiles:**
- `dev`: Development (application-dev.yml)
- `test`: Testing (application-test.yml)
- `prod`: Production (application-prod.yml)

**Server port:** 8123 (configured in application.yml)

**Knife4j API 文档:**
- Enabled in all environments
- Access URL: `http://localhost:8123/doc.html`
- Basic auth: Disabled by default (可在配置中启用)
- Language: 中文 (Chinese)
- Features:
  - Swagger Models 展示
  - 文档管理
  - 请求缓存
  - 自定义页脚

## Key Dependencies

- **blade-core-boot**: Core framework components
- **blade-starter-tenant**: Multi-tenancy support
- **blade-starter-swagger**: API documentation
- **mybatis-plus-generator**: Code generator (scope: provided)
- **blade-starter-oss**: Object storage (MinIO, Aliyun OSS, Tencent COS, QiNiu)
- **blade-starter-sms**: SMS support (Aliyun, Tencent, YunPian)
- **easy-captcha**: Captcha generation

## Working with the Code

### Finding Files

**Entities:** Use pattern `src/main/java/**/entity/*.java`
**Mappers:** Use pattern `src/main/java/**/mapper/*.java`
**Controllers:** Use pattern `src/main/java/**/controller/*.java`
**SQL scripts:** Check `doc/sql/mysql/` for schema definitions

### Authentication Development

**Token grant types** (in `modules.auth.granter`):
- `PasswordTokenGranter`: Username/password login
- `CaptchaTokenGranter`: Captcha-based login
- `RefreshTokenGranter`: Refresh token
- `SocialTokenGranter`: Third-party OAuth login

**Token endpoint:** `BladeTokenEndPoint` at `/blade-auth/token`

### Cache Management

**Cache names** defined in `CacheNames.java`:
- User cache, dict cache, menu cache, etc.
- Use `CacheUtil.clear(CACHE_NAME)` after modifications

**Redis serialization:** Protostuff (configured in `blade.redis.serializer-type`)

## Project-Specific Notes

- The martial arts competition module entities are fully created but **Service implementations and some Controller methods may need completion**
- Menu permissions for martial module are configured via SQL in `doc/sql/mysql/martial-competition-menu.sql`
- API endpoints under `/api/martial/` are **publicly accessible** (no authentication required) as configured in skip-url
- The frontend is a separate Vue.js project (not in this repository)
- Mock data and test scripts available in `doc/doc/`