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):

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:

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

# 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:

# 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:

# Runs with dev profile (application-dev.yml)
mvn spring-boot:run -Dspring-boot.run.profiles=dev

Or using the JAR file:

cd /remote_dev/martial/martial-master
java -jar target/blade-api.jar --spring.profiles.active=dev

Production mode:

java -jar target/blade-api.jar --spring.profiles.active=prod

Test mode:

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

# 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
3. Create Service interface in service/ extending BaseService
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

@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/