# Contacts Module (HEMS)

## Endpoint listing
- `GET /api/v1/contacts?role=pilot`
- `GET /api/v1/contacts?role=pilot&pilot_category=freelance`
- `GET /api/v1/contacts?role=pilot&pilot_category=dry_lease`
- `GET /api/v1/contacts?role=doctor`
- `GET /api/v1/contacts?role=air_rescuer`
- `GET /api/v1/contacts?role=technician`
- `GET /api/v1/contacts?role=flight_assistant`
- `GET /api/v1/contacts?role=staff`

## Sensitive action flow (PIN)
1. Client memanggil endpoint sensitif.
2. API balas `202` dan memberi tahu `action` PIN yang dibutuhkan.
3. Client verifikasi PIN ke `/api/v1/auth/pin/verify`.
4. Backend mengembalikan token verifikasi singkat.
5. Client kirim ulang request sensitif dengan header `X-PIN-Verification-Token`.

## Contoh payload

### 1) Create pilot
```json
{
  "data": {
    "type": "contact_pilot_create",
    "attributes": {
      "role_id": "<ROLE_ID_PILOT>",
      "email": "pilot1@hems.local",
      "username": "pilot1",
      "first_name": "Marco",
      "last_name": "Pilot",
      "mobile_phone": "+62811111111",
      "timezone": "Asia/Jakarta",
      "pilot": {
        "pilot_category": "freelance",
        "short_name": "M. Pilot",
        "license_no": "LIC-P-1001",
        "has_ifr_qualification": true,
        "total_flight_minutes": 12500,
        "location": "Jakarta"
      }
    }
  }
}
```

### 2) Update doctor
```json
{
  "data": {
    "type": "contact_doctor_update",
    "attributes": {
      "is_active": true,
      "doctor": {
        "short_name": "dr. Ana",
        "medical_license_no": "DOC-7788",
        "specialization": "Anesthesiology",
        "is_chief_physician": false
      }
    }
  }
}
```

Rule:
- `data.type` wajib mengikuti role, mis. `contact_pilot_create`, `contact_air_rescuer_create`, `contact_staff_update`.
- Hanya satu object profile role yang boleh dikirim, dan harus sesuai dengan `data.type`.

### 3) PIN verify sebelum aksi sensitif
```json
{
  "data": {
    "type": "auth_pin_verify",
    "attributes": {
      "pin": "123456",
      "action": "31f8bb88-a95f-43be-8fd8-129e1355d6a5"
    }
  }
}
```

### 4) Response `202` saat PIN dibutuhkan
```json
{
  "data": {
    "type": "pin_verification_required",
    "attributes": {
      "required": true,
      "action": "31f8bb88-a95f-43be-8fd8-129e1355d6a5",
      "method": "pin",
      "status": 202
    }
  }
}
```

### 5) List response ringkas
```json
{
  "data": {
    "type": "contacts",
    "attributes": {
      "items": [
        {
          "id": "0195f43e-5030-7d2a-8b8a-020063f5ab03",
          "role_code": "pilot",
          "role_name": "pilot",
          "pilot_category": "dry_lease",
          "username": "pilot_dl_1",
          "email": "pilot.dl1@hems.local",
          "first_name": "Rama",
          "last_name": "Wijaya",
          "short_name": "R. Wijaya",
          "license_no": "LIC-P-9988",
          "location": "Surabaya",
          "mobile_phone": "+62822222222",
          "is_active": true
        }
      ],
      "meta": {
        "total": 1,
        "limit": 20,
        "offset": 0
      }
    }
  }
}
```