init push

2026-07-16 22:16:45 +07:00
commit 8b068bdb10
1021 changed files with 332816 additions and 0 deletions
--- a/docs/contacts_module.md
+++ b/docs/contacts_module.md
@@ -0,0 +1,129 @@
+# 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
+      }
+    }
+  }
+}
+```