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
```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)

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

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