248 lines
7.5 KiB
Markdown
248 lines
7.5 KiB
Markdown
# NextGen PPR System
|
||
|
||
A modern, containerized Prior Permission Required (PPR) system for aircraft operations management.
|
||
|
||
## Architecture
|
||
|
||
- **Backend**: FastAPI with Python 3.11
|
||
- **Database**: MySQL 8.0
|
||
- **Cache**: Redis 7
|
||
- **Container**: Docker & Docker Compose
|
||
|
||
## Features
|
||
|
||
- 🚀 **Modern API**: RESTful API with automatic OpenAPI documentation
|
||
- 🔐 **Authentication**: JWT-based authentication system with role-based access
|
||
- <20> **Transactional Email**: SMTP-based email notifications for PPR submissions and cancellations
|
||
- <20>📊 **Real-time Updates**: WebSocket support for live tower updates
|
||
- <20> **Comprehensive Reporting**: Advanced reporting with filtering, search, and CSV/XLS export
|
||
- <20>🗄️ **Self-contained**: Fully dockerized with local database
|
||
- 🔍 **Documentation**: Auto-generated API docs at `/docs`
|
||
- 🧪 **Testing**: Comprehensive test suite with data population utilities
|
||
- 📱 **Mobile Ready**: Responsive design for tower operations
|
||
- 🔄 **Public Forms**: Enhanced public PPR submission and editing with intelligent field lookups
|
||
- 📋 **Audit Trail**: Complete journal system tracking all PPR changes
|
||
|
||
## Quick Start
|
||
|
||
### Prerequisites
|
||
- Docker and Docker Compose installed
|
||
|
||
### 1. Start the System
|
||
```bash
|
||
cd nextgen
|
||
./start.sh
|
||
```
|
||
|
||
### 2. Access the Services
|
||
- **API Documentation**: http://localhost:8001/docs
|
||
- **API Base URL**: http://localhost:8001/api/v1
|
||
- **Public Web Interface**: http://localhost:8082
|
||
- **Admin Interface**: http://localhost:8082/admin.html
|
||
- **Reports Interface**: http://localhost:8082/reports.html
|
||
- **Database**: localhost:3307 (user: ppr_user, password: [configured in .env])
|
||
- **phpMyAdmin**: http://localhost:8083
|
||
|
||
### 3. Default Login
|
||
- **Username**: admin
|
||
- **Password**: [configured in database - see init_db.sql]
|
||
|
||
## API Endpoints
|
||
|
||
### Authentication
|
||
- `POST /api/v1/auth/login` - Login and get JWT token
|
||
|
||
### PPR Management
|
||
- `GET /api/v1/pprs` - List PPR records (with filtering by status, date range)
|
||
- `POST /api/v1/pprs` - Create new PPR
|
||
- `GET /api/v1/pprs/{id}` - Get specific PPR
|
||
- `PUT /api/v1/pprs/{id}` - Update PPR
|
||
- `PATCH /api/v1/pprs/{id}` - Partially update PPR
|
||
- `PATCH /api/v1/pprs/{id}/status` - Update PPR status
|
||
- `DELETE /api/v1/pprs/{id}` - Delete PPR
|
||
- `GET /api/v1/pprs/{id}/journal` - Get PPR activity journal
|
||
|
||
### Public Endpoints (No Auth Required)
|
||
- `GET /api/v1/public/arrivals` - Today's arrivals
|
||
- `GET /api/v1/public/departures` - Today's departures
|
||
- `POST /api/v1/public/pprs` - Submit public PPR
|
||
- `GET /api/v1/public/edit/{token}` - Get PPR for public editing
|
||
- `PATCH /api/v1/public/edit/{token}` - Update PPR publicly
|
||
- `DELETE /api/v1/public/cancel/{token}` - Cancel PPR publicly
|
||
|
||
### User Management (Admin Only)
|
||
- `GET /api/v1/auth/users` - List users
|
||
- `POST /api/v1/auth/users` - Create user
|
||
- `GET /api/v1/auth/users/{id}` - Get user details
|
||
- `PUT /api/v1/auth/users/{id}` - Update user
|
||
- `DELETE /api/v1/auth/users/{id}` - Delete user
|
||
|
||
### Reference Data
|
||
- `GET /api/v1/airport/lookup/{code}` - Lookup airport by ICAO code
|
||
- `GET /api/v1/aircraft/lookup/{reg}` - Lookup aircraft by registration
|
||
|
||
### Real-time
|
||
- `WebSocket /ws/tower-updates` - Live updates for tower operations
|
||
|
||
## Web Interfaces
|
||
|
||
### Public PPR Forms
|
||
- **URL**: http://localhost:8082
|
||
- **Features**:
|
||
- PPR submission form with intelligent aircraft/airport lookups
|
||
- Date/time pickers with 15-minute intervals
|
||
- Email notifications for submissions
|
||
- Public editing/cancellation via secure tokens
|
||
|
||
### Admin Interface
|
||
- **URL**: http://localhost:8082/admin.html
|
||
- **Features**:
|
||
- Complete PPR management (CRUD operations)
|
||
- Advanced filtering by status, date range
|
||
- Inline editing with modal interface
|
||
- Journal/audit trail viewing
|
||
- Quick status updates (Confirm, Land, Depart, Cancel)
|
||
- New PPR entry creation
|
||
- User management (administrators only)
|
||
- Real-time WebSocket updates
|
||
|
||
### Reports Interface
|
||
- **URL**: http://localhost:8082/reports.html
|
||
- **Features**:
|
||
- Comprehensive PPR reporting with date range filtering
|
||
- Search across aircraft, captain, and airport fields
|
||
- Status-based filtering
|
||
- CSV and XLS export functionality
|
||
- Responsive table with all PPR details
|
||
|
||
## Development
|
||
|
||
### Local Development
|
||
```bash
|
||
cd backend
|
||
pip install -r requirements.txt
|
||
uvicorn app.main:app --reload
|
||
```
|
||
|
||
### Database Management
|
||
```bash
|
||
# Connect to database
|
||
docker exec -it ppr_nextgen_db mysql -u ppr_user -p ppr_nextgen
|
||
|
||
# When prompted for password, use the value from .env (DB_PASSWORD)
|
||
```
|
||
|
||
### Testing
|
||
```bash
|
||
cd backend
|
||
pytest tests/
|
||
```
|
||
|
||
## Additional Features
|
||
|
||
### Email Notifications
|
||
The system includes transactional email support for:
|
||
- **PPR Submissions**: Automatic email confirmation to submitters
|
||
- **PPR Cancellations**: Notification emails when PPRs are cancelled
|
||
- **SMTP Configuration**: Configurable SMTP settings via environment variables
|
||
|
||
### Test Data Generation
|
||
A comprehensive test data population script is included:
|
||
```bash
|
||
# Generate test PPR records
|
||
docker exec -it ppr_nextgen_api python populate_test_data.py
|
||
|
||
# Or run the convenience script
|
||
./populate_test_data.sh
|
||
```
|
||
|
||
This creates diverse PPR records across all statuses with realistic aircraft and airport data for testing purposes.
|
||
|
||
### Audit Trail
|
||
Complete activity logging system tracks:
|
||
- All PPR field changes with before/after values
|
||
- Status transitions with timestamps
|
||
- User actions and IP addresses
|
||
- Automatic journal entries for all modifications
|
||
|
||
## Environment Variables
|
||
|
||
Key environment variables (configured in docker-compose.yml):
|
||
|
||
- `DB_HOST` - Database host
|
||
- `DB_USER` - Database username
|
||
- `DB_PASSWORD` - Database password
|
||
- `DB_NAME` - Database name
|
||
- `SECRET_KEY` - JWT secret key
|
||
- `ACCESS_TOKEN_EXPIRE_MINUTES` - Token expiration time
|
||
|
||
### Email Configuration
|
||
- `SMTP_SERVER` - SMTP server hostname
|
||
- `SMTP_PORT` - SMTP server port (default: 587)
|
||
- `SMTP_USERNAME` - SMTP authentication username
|
||
- `SMTP_PASSWORD` - SMTP authentication password
|
||
- `SMTP_TLS` - Enable TLS (default: true)
|
||
- `FROM_EMAIL` - Sender email address
|
||
- `BASE_URL` - Base URL for email links
|
||
|
||
## Database Schema
|
||
|
||
The system uses an improved version of the original schema with:
|
||
|
||
- **users** - User authentication
|
||
- **submitted** - PPR records with status tracking
|
||
- **journal** - Activity logs with foreign keys
|
||
- **airports** - Airport reference data
|
||
- **aircraft** - Aircraft registration database
|
||
|
||
## Data Migration
|
||
|
||
To migrate data from the old system:
|
||
|
||
1. Export data from the old database
|
||
2. Transform to new schema format
|
||
3. Import into the new system
|
||
|
||
## Time Zone Handling
|
||
|
||
The system uses UTC (Coordinated Universal Time) as the standard for all time storage and display in aviation contexts:
|
||
|
||
- **Database Storage**: All times are stored in UTC
|
||
- **Admin Console Display**: Times are displayed in UTC (with Z suffix)
|
||
- **Data Entry**: Times are entered as local time in the New PPR entry form, then automatically converted to UTC for storage
|
||
- **API**: All datetime fields in API responses are UTC ISO strings
|
||
|
||
This ensures consistency across different time zones and complies with aviation standards where UTC is the international standard.
|
||
|
||
## Performance
|
||
|
||
- Database connection pooling
|
||
- Indexed columns for fast queries
|
||
- Redis caching (ready for implementation)
|
||
- Async/await for non-blocking operations
|
||
|
||
## Monitoring
|
||
|
||
Access logs and monitoring:
|
||
|
||
```bash
|
||
# View API logs
|
||
docker-compose logs -f api
|
||
|
||
# View database logs
|
||
docker-compose logs -f db
|
||
|
||
# System health check
|
||
curl http://localhost:8001/health
|
||
```
|
||
|
||
## Stopping the System
|
||
|
||
```bash
|
||
docker-compose down
|
||
```
|
||
|
||
To remove volumes (database data):
|
||
```bash
|
||
docker-compose down -v
|
||
``` |