Arrivals Board
This commit is contained in:
James Pattinson
255
.copilot-instructions.md
Normal file
255
.copilot-instructions.md
Normal file
@@ -0,0 +1,255 @@
|
||||
# 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`
|
||||
|
||||
## Development URLs
|
||||
|
||||
- API Base: http://localhost:8001/api/v1
|
||||
- Public Web Interface: http://localhost:8082
|
||||
- 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"}'
|
||||
```
|
||||
Reference in New Issue
Block a user