jamesp/ppr-ng
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Doc update and SQL init

Browse Source
This commit is contained in:
James Pattinson
2025-10-25 15:10:54 +00:00
parent 7643c179fb
commit 77b5080bbd
10 changed files with 417 additions and 48 deletions
Download Patch File Download Diff File Expand all files Collapse all files

261
.copilot-instructions.md
View File

@@ -2,7 +2,17 @@
General Information
As you perform more tests, document in this file the steps you are taking to avoid repetition.
As you perform more tests, document in this file the steps you are taking to avoid repetition.
## System Overview
The NextGen PPR system includes:
- **FastAPI Backend** with comprehensive REST API
- **MySQL Database** with full PPR tracking and audit trails
- **Web Interfaces** for public submission, admin management, and reporting
- **Email Notifications** for PPR submissions and cancellations
- **Real-time Updates** via WebSocket for live tower operations
- **Test Data Generation** utilities for development and testing
## API Base URL
- Development: `http://localhost:8001/api/v1`
@@ -145,6 +155,58 @@ curl -X POST "http://localhost:8001/api/v1/pprs/" \
**Endpoint:** `DELETE /api/v1/pprs/{ppr_id}` (soft delete - sets status to DELETED)
## User Management Endpoints (Admin Only)
### List Users
**Endpoint:** `GET /api/v1/auth/users`
### Create User
**Endpoint:** `POST /api/v1/auth/users`
**Request Body:**
```json
{
"username": "newuser",
"password": "securepassword",
"role": "OPERATOR"
}
```
**Available Roles:**
- `ADMINISTRATOR`: Full access including user management
- `OPERATOR`: PPR management access
- `READ_ONLY`: View-only access
### Get User Details
**Endpoint:** `GET /api/v1/auth/users/{user_id}`
### Update User
**Endpoint:** `PUT /api/v1/auth/users/{user_id}`
### Delete User
**Endpoint:** `DELETE /api/v1/auth/users/{user_id}`
## Reference Data Endpoints
### Lookup Airport
**Endpoint:** `GET /api/v1/airport/lookup/{icao_code}`
Returns airport details for the given ICAO code.
### Lookup Aircraft
**Endpoint:** `GET /api/v1/aircraft/lookup/{registration}`
Returns aircraft details for the given registration.
## Reference Data Endpoints
## Public Endpoints (No Authentication Required)
### Get Today's Arrivals
@@ -159,6 +221,40 @@ Returns all PPRs with status "NEW" and ETA for today.
Returns all PPRs with status "LANDED" and ETD for today.
### Submit Public PPR
**Endpoint:** `POST /api/v1/public/pprs/`
**Headers:**
- `Content-Type: application/json`
**Request Body:** Same as authenticated PPR creation (see above)
**Notes:**
- No authentication required
- Sends confirmation email if email provided
- Returns PPR with public edit token
### Get PPR for Public Editing
**Endpoint:** `GET /api/v1/public/edit/{token}`
Returns PPR details for public editing using the token from email.
### Update PPR Publicly
**Endpoint:** `PATCH /api/v1/public/edit/{token}`
**Request Body:** Same as authenticated PPR update
**Notes:** Only allowed if PPR status is not processed (not LANDED, DEPARTED, CANCELED, or DELETED)
### Cancel PPR Publicly
**Endpoint:** `DELETE /api/v1/public/cancel/{token}`
Cancels PPR using public token and sends cancellation email.
## Data Models
### PPR Status Enum
@@ -256,10 +352,14 @@ The system automatically logs:
## Web Interfaces
### Public Arrivals/Departures Board
### Public PPR Forms
- **URL:** http://localhost:8082
- **Features:** Real-time arrivals and departures display
- **Authentication:** None required
- **Features:**
- PPR submission with intelligent aircraft/airport field lookups
- Date/time pickers with 15-minute intervals
- Email notifications for submissions
- Public editing/cancellation via secure email tokens
- Real-time validation and feedback
### Admin Interface
- **URL:** http://localhost:8082/admin.html
@@ -270,15 +370,80 @@ The system automatically logs:
- Journal/audit trail viewing
- Quick status updates (Confirm, Land, Depart, Cancel)
- New PPR entry creation
- User management (administrators only)
- Real-time WebSocket updates
- **Authentication:** Username/password prompt (uses API token)
### Reports Interface
- **URL:** http://localhost:8082/reports.html
- **Features:**
- Comprehensive PPR reporting with date range filtering (defaults to current month)
- Search across aircraft registration, callsign, captain name, and airports
- Status-based filtering
- CSV and XLS export functionality
- Responsive table displaying all PPR fields
- Real-time data loading with authentication
## Development URLs
- API Base: 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
- API Documentation: http://localhost:8001/docs
- Database: localhost:3307 (MySQL)
- phpMyAdmin: http://localhost:8083
## Email System
The system includes transactional email support:
### Configuration
Email settings are configured via environment variables:
- `SMTP_SERVER`: SMTP server hostname
- `SMTP_PORT`: SMTP server port (default: 587)
- `SMTP_USERNAME`: SMTP authentication username
- `SMTP_PASSWORD`: SMTP authentication password
- `FROM_EMAIL`: Sender email address
- `BASE_URL`: Base URL for email links
### Email Templates
- **PPR Submitted**: Sent when public PPR is created
- **PPR Cancelled**: Sent when PPR is cancelled (by user or admin)
### Email Content
Emails include:
- PPR details (aircraft, times, contact info)
- Secure edit/cancel links with tokens
- Formatted HTML with system branding
## Test Data Generation
The system includes comprehensive test data generation utilities:
### Generate Test PPRs
```bash
# Run from host
./populate_test_data.sh
# Or run directly in container
docker exec -it ppr_nextgen_api python populate_test_data.py
```
### What It Creates
- **93 PPR records** across all statuses (NEW, CONFIRMED, LANDED, DEPARTED, CANCELED)
- **Diverse aircraft types** from the loaded aircraft database
- **Realistic airport combinations** from the loaded airport data
- **Varied captains and contact details**
- **Proper date/time distributions** across different time periods
- **Status distribution** matching real-world usage patterns
### Test Data Features
- Aircraft registrations with proper formatting
- Realistic passenger counts and fuel requirements
- Geographic distribution across UK airports
- Time-based distribution for testing date filters
- Email addresses for testing notification system
## Example Workflow
@@ -309,4 +474,90 @@ curl -X PATCH "http://localhost:8001/api/v1/pprs/1/status" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-d '{"status":"LANDED"}'
```
# Test public PPR submission (no auth required)
curl -X POST "http://localhost:8001/api/v1/public/pprs/" \
-H "Content-Type: application/json" \
-d '{"ac_reg":"G-PUBLIC","ac_type":"PA28","captain":"Public User","in_from":"EGGW","eta":"2025-10-21T15:00:00","pob_in":1,"email":"test@example.com"}'
# Test filtering by date range
curl -s "http://localhost:8001/api/v1/pprs/?date_from=2025-10-01&date_to=2025-10-31&limit=10" \
-H "Authorization: Bearer $TOKEN" | jq .
# Test user management (admin only)
curl -s "http://localhost:8001/api/v1/auth/users" \
-H "Authorization: Bearer $TOKEN" | jq .
# Generate test data
docker exec -it ppr_nextgen_api python populate_test_data.py
```
## Enhanced Features
### Intelligent Form Lookups
- **Aircraft Lookup**: Auto-suggests aircraft type based on registration
- **Airport Lookup**: Provides airport name and location for ICAO codes
- **Real-time Validation**: Immediate feedback on form inputs
### Advanced Date/Time Handling
- **15-Minute Intervals**: All time pickers use 15-minute increments
- **Separate Date/Time Fields**: Improved UX with dedicated date and time inputs
- **UTC Storage**: All times stored in UTC for consistency
### Comprehensive Reporting
- **Date Range Filtering**: Filter PPRs by custom date ranges
- **Multi-field Search**: Search across registration, callsign, captain, airports
- **Export Functionality**: CSV and XLS download with all PPR data
- **Responsive Design**: Works on desktop and mobile devices
### Audit Trail System
- **Complete Change History**: Every field change is logged
- **User Tracking**: Who made changes and when
- **IP Address Logging**: Security tracking for all actions
- **Automatic Journal Entries**: No manual logging required
## Example Complete Workflow
1. **Public Submission**
```bash
# User submits PPR via public form
curl -X POST "http://localhost:8001/api/v1/public/pprs/" \
-H "Content-Type: application/json" \
-d '{"ac_reg":"G-WORKFLOW","ac_type":"C152","captain":"Workflow Test","in_from":"EGKB","eta":"2025-10-21T14:00:00","pob_in":1,"email":"workflow@example.com"}'
```
2. **Email Notification Sent**
- User receives confirmation email with edit/cancel links
3. **Admin Processing**
```bash
# Admin confirms PPR
curl -X PATCH "http://localhost:8001/api/v1/pprs/1/status" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-d '{"status":"CONFIRMED"}'
```
4. **Status Updates**
```bash
# Mark as landed
curl -X PATCH "http://localhost:8001/api/v1/pprs/1/status" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-d '{"status":"LANDED","timestamp":"2025-10-21T14:05:00Z"}'
# Mark as departed
curl -X PATCH "http://localhost:8001/api/v1/pprs/1/status" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-d '{"status":"DEPARTED","timestamp":"2025-10-21T15:30:00Z"}'
```
5. **Public Editing/Cancellation**
- User can edit or cancel using token from email
- System sends cancellation email if cancelled
6. **Reporting**
- Access reports at http://localhost:8082/reports.html
- Filter by date range, status, search terms
- Export to CSV/XLS for analysis