182 lines
7.3 KiB
Markdown
182 lines
7.3 KiB
Markdown
# 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 |