ppr-ng/.copilot-instructions.md

PPR API Documentation for Copilot

General Information

As you perform more tests, document in this file the steps you are taking to avoid repetition.

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)

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.

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 Arrivals/Departures Board

• URL: http://localhost:8082
• Features: Real-time arrivals and departures display
• Authentication: None required

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
• Authentication: Username/password prompt (uses API token)

Development URLs

• API Base: http://localhost:8001/api/v1
• Public Web Interface: http://localhost:8082
• Admin Interface: http://localhost:8082/admin.html
• API Documentation: http://localhost:8001/docs
• Database: localhost:3307 (MySQL)

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"}'