# CLAUDE.md

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

## Project Overview

QAUP-Management is an airport collision avoidance and management system built on the RuoYi framework. It integrates vehicle tracking, spatial analysis, and real-time monitoring for airport operations with Spring Boot 3.x and PostgreSQL + PostGIS.

## Architecture

### Multi-Module Maven Structure
- **qaup-admin**: Main web application entry point containing controllers and startup configuration
- **qaup-collision**: Core collision avoidance system with spatial analysis, WebSocket communication, and real-time monitoring
- **qaup-framework**: Infrastructure layer with security, caching, and common configurations
- **qaup-system**: User management, RBAC, and system administration
- **qaup-common**: Shared utilities, constants, and base classes
- **qaup-quartz**: Scheduled job management
- **qaup-generator**: Code generation utilities

### Key Integration Pattern
The collision avoidance system integrates with RuoYi through `QuapDataAdapter` (qaup-collision/src/main/java/com/qaup/collision/common/adapter/QuapDataAdapter.java:37), which bridges the collision detection system with RuoYi's service layer, avoiding direct DAO dependencies.

## Data Collection and Processing Architecture

### Critical Design Principle: Complete Service Separation
**DataCollectorService and DataProcessingService MUST be completely separated**

#### Service Responsibilities
- **DataCollectorService** (250ms): 
  - Only collects raw position data from external APIs
  - Caches data in activeMovingObjectsCache with NULL speed/direction
  - NO calculations, NO processing, NO WebSocket sending
  - Purpose: High-frequency data collection to ensure no data loss

- **DataProcessingService** (1000ms):
  - Reads cached position data from DataCollectorService
  - Calculates speed and direction using SpeedCalculationService
  - Sends WebSocket position updates
  - Performs violation detection and path conflict detection
  - Saves data to database

#### Implementation Pattern
1. **DataCollectorService Methods**:
   - `collectAircraftData()`, `collectVehicleData()`, `collectUnmannedVehicleData()`
   - Store MovingObjects with NULL speed/direction in activeMovingObjectsCache
   - **FORBIDDEN**: No calculations, no WebSocket events, no processing

2. **DataProcessingService Methods**:
   - `performPeriodicDataProcessing()` - main processing loop
   - `calculateSpeedAndDirectionForAllObjects()` - calculate derived data
   - `sendPositionUpdatesForActiveObjects()` - WebSocket messaging
   - `performViolationDetection()` - rule engine integration
   - `saveUnmannedVehicleDataPeriodically()` - database persistence

#### Cache Sharing Pattern
- DataCollectorService owns activeMovingObjectsCache
- DataProcessingService receives cache reference via setActiveMovingObjectsCache()
- Both services share the same cache instance but have different responsibilities

#### Why Complete Service Separation is Critical
- **Data Integrity**: High-frequency collection prevents missing position updates
- **Performance**: Separating collection from processing reduces computational load
- **Accuracy**: Calculations based on processing intervals (1000ms) are more stable
- **Architecture Clarity**: Clear separation of concerns makes system more maintainable
- **Timing Consistency**: Avoids conflicts between collection and calculation frequencies

#### Violation of This Principle
**NEVER** place calculation logic in DataCollectorService methods. This will cause:
- WebSocket messages showing speed/direction as 0
- Inconsistent data due to frequency mismatch
- Architecture violations that are difficult to debug

## Development Commands

### Build and Run
```bash
# Full clean build (skip tests for faster builds)
mvn clean install -DskipTests

# Start backend from qaup-admin module
cd qaup-admin
mvn spring-boot:run

# Start frontend (Vue.js)
cd qaup-ui
npm run dev

# Production deployment using script
./ry.sh start
```

### Testing and Debugging
```bash
# Check port usage
lsof -ti:8080

# Kill process if needed
kill -9 <process-id>

# View logs
tail -f qaup-admin/app.log
```

## Technology Stack

### Backend
- **Spring Boot 3.5.3** with Java 17
- **PostgreSQL + PostGIS** for spatial data
- **MyBatis** for database operations
- **Redis** for caching and session management
- **WebSocket** for real-time communication
- **JTS + GeoTools** for spatial calculations

### Frontend
- **Vue 2.6.12** with Element UI
- **Axios** for API communication
- **ECharts** for data visualization

## Configuration

### Database Setup
1. PostgreSQL with PostGIS extension enabled
2. Run initialization scripts in order:
   - `sql/create_qaup_database.sql`
   - `sql/create_sys_vehicle_info_table.sql` 
   - `sql/create_sys_driver_info_table.sql`

### Key Configuration Files
- `qaup-admin/src/main/resources/application.yml`: Main configuration including database, Redis, and collision system settings
- `qaup-ui/vue.config.js`: Frontend build configuration
- `qaup-collision/src/main/resources/config/`: Spatial configuration files (airport_areas.yaml, airport_roads.yaml)

## Important Development Patterns

### Data Access
Always use `QuapDataAdapter` for accessing vehicle and driver data in collision module instead of direct service calls. This maintains clean separation between collision detection and system management.

### WebSocket Communication
Real-time data flows through WebSocket endpoints configured in collision module. Messages use `/topic` prefix for broadcasting to connected clients.

### Spatial Data
PostGIS integration handles geometric calculations. Coordinate system defaults to airport center at (120.0834104, 36.35406879).

### Performance Optimization
- Data collection interval: 250ms for high-frequency updates
- WebSocket push throttling: 1000ms to prevent frontend overload
- Redis caching with 60-second expiration for real-time data

## Version Management

### Version Control Files
- **VERSION.md**: Contains current version number (semantic versioning)
- **changelog.md**: Detailed change log following Keep a Changelog format

### Version Update Process
When making significant changes:
1. Update version number in VERSION.md
2. Add detailed changelog entry in changelog.md
3. Include version update in commit message
4. Use semantic versioning (MAJOR.MINOR.PATCH)

- **Admin Interface**: http://localhost:8080
- **API Documentation**: http://localhost:8080/swagger-ui/index.html
- **WebSocket Endpoint**: ws://localhost:8080/ws

## Common Issues

### Build Problems
- If Maven build fails, ensure Java 17 is active
- For dependency conflicts, use `mvn dependency:tree` to analyze

### Runtime Issues
- Check Redis connectivity if caching fails
- Verify PostGIS extension is properly installed for spatial operations
- WebSocket connection issues often relate to CORS configuration in SecurityConfig

### Speed/Direction Calculation Issues
- **CRITICAL**: Speed/direction calculations must ONLY occur in processing phase (1000ms), NEVER in collection phase (250ms)
- If speed appears as 0, check if calculations are incorrectly placed in collection phase
- Collection phase should store MovingObjects with NULL speed/direction values
- Processing phase should calculate and update speed/direction for all cached objects before WebSocket sending
- Ensure complete separation: Collection = data only, Processing = calculations only