tian/QAUP_Management
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
develop
QAUP_Management/CLAUDE.md

7.3 KiB
Raw Permalink Blame History

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

# 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

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

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