jamesp/ppr-ng
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
86f1dc65f4aba42310e5cc87172302489aea37ab
ppr-ng/.copilot-instructions.md
James Pattinson 77b5080bbd Doc update and SQL init
2025-10-25 15:10:54 +00:00

15 KiB
Raw Blame History

PPR API Documentation for Copilot

General Information

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
  • Authentication: Bearer token required for most endpoints

Authentication

Get Access Token

curl -X POST "http://localhost:8001/api/v1/auth/login" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=admin&password=admin123"

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer"
}

PPR Management Endpoints

Create New PPR Entry

Endpoint: POST /api/v1/pprs/

Headers:

  • Content-Type: application/json
  • Authorization: Bearer {access_token}

Required Fields:

  • ac_reg (string): Aircraft registration (e.g., "G-TEST")
  • ac_type (string): Aircraft type (e.g., "C172")
  • captain (string): Captain's name
  • in_from (string): Origin airport ICAO code (e.g., "EGKB")
  • eta (datetime): Estimated time of arrival (ISO format: "2025-10-21T14:30:00")
  • pob_in (integer): Persons on board inbound

Optional Fields:

  • ac_call (string): Aircraft callsign
  • fuel (string): Fuel requirements
  • out_to (string): Destination airport ICAO code
  • etd (datetime): Estimated time of departure
  • pob_out (integer): Persons on board outbound
  • email (string): Contact email
  • phone (string): Contact phone
  • notes (string): Additional notes

Example Request:

curl -X POST "http://localhost:8001/api/v1/pprs/" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {token}" \
  -d '{
    "ac_reg": "G-TEST",
    "ac_type": "C172",
    "ac_call": "TEST01",
    "captain": "John Smith",
    "fuel": "FULL",
    "in_from": "EGKB",
    "eta": "2025-10-21T14:30:00",
    "pob_in": 2,
    "out_to": "EGGW",
    "etd": "2025-10-21T16:00:00", 
    "pob_out": 2,
    "email": "john.smith@example.com",
    "phone": "+44123456789",
    "notes": "Test PPR entry created via API"
  }'

Success Response (201):

{
  "ac_reg": "G-TEST",
  "ac_type": "C172",
  "ac_call": "TEST01",
  "captain": "John Smith",
  "fuel": "FULL",
  "in_from": "EGKB",
  "eta": "2025-10-21T14:30:00",
  "pob_in": 2,
  "out_to": "EGGW",
  "etd": "2025-10-21T16:00:00",
  "pob_out": 2,
  "email": "john.smith@example.com",
  "phone": "+44123456789",
  "notes": "Test PPR entry created via API",
  "id": 2,
  "status": "NEW",
  "landed_dt": null,
  "departed_dt": null,
  "created_by": "admin",
  "submitted_dt": "2025-10-21T19:45:46"
}

Get All PPRs

Endpoint: GET /api/v1/pprs/

Query Parameters:

  • skip (int): Number of records to skip (default: 0)
  • limit (int): Maximum records to return (default: 100)
  • status (string): Filter by status (NEW, CONFIRMED, CANCELED, LANDED, DELETED, DEPARTED)
  • date_from (date): Filter from date (YYYY-MM-DD)
  • date_to (date): Filter to date (YYYY-MM-DD)

Get Specific PPR

Endpoint: GET /api/v1/pprs/{ppr_id}

Update PPR

Endpoint: PUT /api/v1/pprs/{ppr_id} (full update) Endpoint: PATCH /api/v1/pprs/{ppr_id} (partial update)

Update PPR Status

Endpoint: PATCH /api/v1/pprs/{ppr_id}/status

Request Body:

{
  "status": "LANDED"
}

Available Statuses:

  • NEW: Newly submitted PPR
  • CONFIRMED: PPR confirmed by tower
  • CANCELED: PPR canceled
  • LANDED: Aircraft has landed
  • DEPARTED: Aircraft has departed
  • DELETED: PPR deleted (soft delete)

Delete PPR

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:

{
  "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

Endpoint: GET /api/v1/public/arrivals

Returns all PPRs with status "NEW" and ETA for today.

Get Today's Departures

Endpoint: GET /api/v1/public/departures

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

NEW -> CONFIRMED -> LANDED -> DEPARTED
    -> CANCELED
    -> DELETED

Datetime Format

All datetime fields use ISO 8601 format: YYYY-MM-DDTHH:MM:SS

Airport Codes

Use ICAO 4-letter codes (e.g., EGKB, EGGW, EGLL) for airport identifiers.

Error Responses

401 Unauthorized:

{
  "detail": "Could not validate credentials"
}

404 Not Found:

{
  "detail": "PPR record not found"
}

422 Validation Error:

{
  "detail": [
    {
      "loc": ["body", "ac_reg"],
      "msg": "Aircraft registration is required",
      "type": "value_error"
    }
  ]
}

WebSocket Real-time Updates

The API sends real-time updates via WebSocket for:

  • ppr_created: New PPR created
  • ppr_updated: PPR updated
  • status_update: PPR status changed
  • ppr_deleted: PPR deleted

Default Users

  • Username: admin
  • Password: admin123

Journal System

All PPR changes are automatically logged in a journal system for audit trail purposes.

Get PPR Journal Entries

Endpoint: GET /api/v1/pprs/{ppr_id}/journal

Response:

[
  {
    "id": 1,
    "ppr_id": 3,
    "entry": "PPR created for G-ADMIN",
    "user": "admin",
    "ip": "172.23.0.1",
    "entry_dt": "2025-10-21T20:01:01"
  },
  {
    "id": 2,
    "ppr_id": 3,
    "entry": "captain changed from 'Test Admin' to 'Updated Admin User'",
    "user": "admin",
    "ip": "172.23.0.1",
    "entry_dt": "2025-10-21T20:01:17"
  }
]

Automatic Journal Logging

The system automatically logs:

  • PPR creation
  • All field changes with old and new values
  • Status changes
  • User and IP address for each change

Web Interfaces

Public PPR Forms

  • URL: http://localhost:8082
  • 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
  • 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
  • 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

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

# 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

  1. Get access token
  2. Create PPR entry (status: NEW) → Shows on arrivals board
  3. Update status to LANDED → Shows on departures board
  4. Update status to DEPARTED → Removes from departures board

Testing Commands

# Store token
TOKEN=$(curl -s -X POST "http://localhost:8001/api/v1/auth/login" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=admin&password=admin123" | jq -r '.access_token')

# Create PPR
curl -X POST "http://localhost:8001/api/v1/pprs/" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"ac_reg":"G-TEST","ac_type":"C172","captain":"Test Pilot","in_from":"EGKB","eta":"2025-10-21T14:30:00","pob_in":2}'

# Check arrivals
curl -s "http://localhost:8001/api/v1/public/arrivals" | jq .

# Update status to LANDED
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

    # 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

    # 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

    # 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

Reference in New Issue View Git Blame Copy Permalink