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.

## 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
```bash
curl -X POST "http://localhost:8001/api/v1/auth/login" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=admin&password=admin123"
```

**Response:**
```json
{
  "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:**
```bash
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):**
```json
{
  "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:**
```json
{
  "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:**
```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

**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:**
```json
{
  "detail": "Could not validate credentials"
}
```

**404 Not Found:**
```json
{
  "detail": "PPR record not found"
}
```

**422 Validation Error:**
```json
{
  "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:**
```json
[
  {
    "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

- 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

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

```bash
# 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**
   ```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