# CLAUDE.md

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

## Project Overview

YueKeDuo (约客多) is a ride-hailing platform built with Spring Cloud microservices architecture. The system includes management backend, user/passenger services, driver services, dispatch services, and message push services, all coordinated through Eureka service registry and Zuul API gateway.

## Architecture

### Microservices Structure

The project follows a multi-module Spring Cloud architecture with the following services:

- **EurekaYKDTravel** - Service registry (port 8000/8001)
- **ZuulYKDTravel** - API gateway (port 5000) - routes `/user/**`, `/driver/**`, `/dispatch/**` to respective services
- **ManagementYKDTravel** - Admin backend (port 8010 prod, 8080 test, 7080 dev)
- **UserYKDTravel** - User/passenger API service (port 8006)
- **DriverYKDTravel** - Driver API service (port 8007)
- **DispatchYKDTravel** - Dispatch/scheduling service (port 8008 admin, 8080 REST)
- **MessagePushTravel** - Message push service (port 6000)

Each business service (Management, User, Driver, Dispatch) typically contains:
- `guns-admin` - Main application module with web/API controllers
- `guns-core` - Core business logic and utilities
- `guns-generator` - MyBatis code generator

### Technology Stack

- **Framework**: Spring Boot 2.0.4, Spring Cloud Finchley.SR1
- **Persistence**: MyBatis Plus 2.3, MySQL 5.7/8.0
- **Security**: Apache Shiro 1.8.0 (admin), JWT token (API endpoints prefixed with `/gunsApi`)
- **Template Engine**: Beetl 2.8.5 (frontend pages)
- **Cache**: Redis (session, cache), EhCache
- **Message Queue**: RabbitMQ (ConnectionFactory configured)
- **Database**: 
  - MySQL - main business data (default database: `yuekeduo`)
  - MongoDB - trajectory/location tracking (port 27009)
  - Redis - cache and session (port 6410 prod, 7560 test, 6379 dev)
- **Connection Pool**: Druid 1.1.10
- **API Documentation**: Swagger (integrated via swagger-spring-boot-starter)

### Package Structure

Controllers follow the pattern: `com.stylefeng.guns.modular.<module>.controller`
DAOs follow: `com.stylefeng.guns.modular.<module>.dao`
MyBatis mappers are scanned from: `com.stylefeng.guns.modular.*.dao`

MyBatis XML mapper files can be located either:
- In `src/main/resources` with matching package structure
- In `src/main/java` alongside Java classes (configured in build resources)

## Build & Run

### Environment Profiles

The project uses Maven profiles for different environments:
- `dev` - Development (default, active by default)
- `test` - Testing environment
- `prod` - Production environment

Activate a profile during build with `-P<profile>`:
```bash
mvn clean package -Ptest -DskipTests
```

### Building Services

**Build all modules of a multi-module service:**
```bash
cd ManagementYKDTravel
mvn clean package -Pprod -DskipTests
```

**Build specific module only:**
```bash
cd ManagementYKDTravel
mvn -pl guns-admin -am clean package -Pprod -DskipTests
```

The `-pl` specifies the module, `-am` includes dependencies (core, generator).

Build artifacts are generated in each module's `target/` directory.

### Running Services

Services are Spring Boot applications. Main entry point is typically `GunsApplication.java` in the `guns-admin` module.

**Start order for full system:**
1. Infrastructure: MySQL, Redis, MongoDB
2. EurekaYKDTravel (service registry)
3. Business services: UserYKDTravel, DriverYKDTravel, DispatchYKDTravel
4. ZuulYKDTravel (gateway)
5. ManagementYKDTravel (admin backend)
6. MessagePushTravel

**Run from IDE:**
Run `GunsApplication.main()` with VM argument:
```
-Dspring.profiles.active=dev
```

**Run from command line:**
```bash
java -jar guns-admin/target/management-1.0.0.jar --spring.profiles.active=dev
```

### Database Setup

Ensure MySQL database is created with proper character set:
```sql
CREATE DATABASE yuekeduo CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;
```

SQL initialization scripts are located in `src/main/resources/sql/` directories.

## Development Conventions

### Configuration

- Environment-specific configurations: `application-{profile}.yml`
- Main config loads profile via `application.yml`: `spring.profiles.active: @spring.active@`
- The `@spring.active@` placeholder is replaced by Maven resource filtering based on active profile
- Configuration precedence: external config > application-{profile}.yml > application.yml

### Code Generation

The project includes MyBatis Plus code generator in `guns-generator` modules. Use `CodeController` endpoints to generate:
- Entity classes
- Mapper interfaces
- Mapper XML files
- Service classes
- Controller scaffolding

### Logging

Configured via `logback.xml`. Business logs use `@BussinessLog` annotation for AOP-based logging. Logs capture user operations asynchronously via `ScheduledThreadPoolExecutor`.

### Frontend Pages

- Views located in: `src/main/webapp/WEB-INF/view/`
- Static resources: `src/main/webapp/static/`
- Uses Beetl template engine with layouts in `/common/` directory
- JavaScript follows singleton pattern per page (one global variable per page in `static/modular/`)

### API Endpoints

- Admin Shiro-protected: most endpoints
- JWT-protected API: endpoints starting with `/gunsApi`
- Swagger documentation available (check `@ApiOperation`, `@ApiImplicitParams` annotations)

## Key Features

### Data Scope Interceptor
MyBatis interceptor that filters data by department ID for role-based data access control. Add `DataScope` parameter to mapper methods to enable filtering.

### Map + Wrapper Pattern
Controllers return Maps wrapped by custom wrapper classes that transform raw data (e.g., adding `sexName` field for gender display) before sending to frontend.

### Business Log Recording
`@BussinessLog` annotation on controller methods triggers AOP logging. Use `LogObjectHolder.me().set()` to cache object state before edits for comparison.

## Common Tasks

### Adding a New Feature Module

1. Use code generator via `CodeController` to scaffold entity, mapper, service, controller
2. Create mapper XML in `src/main/java/com/stylefeng/guns/modular/<module>/dao/mapping/`
3. Create view HTML in `src/main/webapp/WEB-INF/view/system/<module>/`
4. Create page JavaScript in `src/main/webapp/static/modular/system/<module>/`
5. Add menu entries via admin backend or SQL

### Debugging Database Issues

- Check MyBatis mapper scanning: `@MapperScan("com.stylefeng.guns.modular.*.dao")` in `GunsApplication`
- Verify mapper XML location matches package or is in resources with correct path
- Enable MyBatis SQL logging in application.yml:
  ```yaml
  logging:
    level:
      com.stylefeng.guns.modular: DEBUG
  ```

### Working with Eureka Services

Services register with Eureka using configuration:
```yaml
eureka:
  client:
    service-url:
      defaultZone: http://username:password@host:port/eureka/
```

Check service registration at `http://localhost:8000` (Eureka dashboard).

### Testing

Run tests with Maven:
```bash
mvn test -P<profile>
```

Tests are typically in `src/test/java` with Spring Boot test annotations.

## Production Deployment

Refer to `约客多出行系统全模块部署方案.md` for complete deployment guide including:
- Server directory structure
- Startup scripts
- Nginx reverse proxy configuration
- Environment validation checklist

Production domain: `rideapi.yuekeduo.com.cn`
- `/resources/**` → local static files
- `/user/**`, `/driver/**`, `/dispatch/**` → Zuul gateway → respective services
- Other paths → Management backend

## Important Notes

- Mapper XML files can exist in `src/main/java` due to Maven build configuration including `**/*.xml` from source
- The project uses Guns framework v4.1 conventions (see `DispatchYKDTravel/README.md` for Guns documentation)
- JWT authentication and MD5 signature mechanism used for `/gunsApi` endpoints
- Session management via Redis when Spring Session is enabled
- File uploads can use local directory (`/home/yuekeduo/server/resources`) or cloud storage (COS/OSS/OBS)
- Third-party integrations: SMS, JPush, payment gateways, map services, facial recognition require production credentials