380 lines
17 KiB
Markdown
380 lines
17 KiB
Markdown
# Panduan Status Helikopter: AOG, MCF, NSR & Cara Menerbangkannya Lagi
|
||
|
||
> Dokumen ini menjelaskan **kapan sebuah helikopter berhenti boleh terbang**, **kenapa**, dan **langkah apa yang harus dilakukan supaya boleh terbang lagi** — lengkap dengan endpoint yang dipakai di tiap langkah.
|
||
>
|
||
> Ditulis supaya bisa dimengerti baik oleh tim operasional maupun developer. Bagian teknis (endpoint, field) ada di tiap langkah, tapi alurnya diceritakan dulu dengan bahasa sederhana.
|
||
>
|
||
> Semua endpoint berawalan `/api/v1` dan butuh login.
|
||
|
||
---
|
||
|
||
## 1. Istilah Penting (versi gampang)
|
||
|
||
Sebelum masuk alur, kenali dulu pemainnya:
|
||
|
||
| Istilah | Bahasa gampangnya |
|
||
|---|---|
|
||
| **Complaint** | Laporan kerusakan/keluhan pada helikopter. "Ada yang rusak nih." |
|
||
| **MEL** (Minimum Equipment List) | Aturan: kerusakan ini boleh ditunda berapa lama sebelum pesawat **wajib** berhenti. Ada kelas A/B/C/D (makin besar = makin lama boleh ditunda). |
|
||
| **NON-MEL** | Kerusakan yang **tidak boleh ditunda sama sekali** → pesawat langsung berhenti. |
|
||
| **AOG** (Aircraft On Ground) | Status "pesawat dikandangkan, **tidak boleh terbang**". |
|
||
| **NSR** (Non-Safety Release) | Keputusan: "kerusakan ini aman ditunda, **boleh terbang dulu**" walau belum diperbaiki. |
|
||
| **Action Taken** | Tindakan perbaikan sementara yang dicatat, supaya pesawat boleh terbang lagi — tapi **belum dianggap selesai resmi**. |
|
||
| **EASA Release** (CRS Part-145) | Surat resmi "**pesawat sudah diperbaiki & layak terbang**". Inilah yang benar-benar **menutup** kerusakan. |
|
||
| **MCF** (Maintenance Check Flight) | Penerbangan uji setelah perbaikan besar. Selama wajib MCF, pesawat berstatus khusus. |
|
||
| **Fleet Status** | Data kondisi tiap helikopter: jadwal perawatan, jam terbang, status, dll. |
|
||
|
||
**Inti yang paling sering bikin bingung** (akan diulang lagi nanti):
|
||
> **Boleh terbang lagi** ≠ **kerusakan selesai.**
|
||
> - Pesawat bisa **boleh terbang lagi** lewat *Action Taken* atau *NSR* — tapi laporannya **masih terbuka**.
|
||
> - Kerusakan baru **benar-benar selesai (ditutup)** ketika **EASA Release ditandatangani (sign)** — bukan sekadar dibuat.
|
||
|
||
---
|
||
|
||
## 2. Status Helikopter & Urutannya
|
||
|
||
Helikopter selalu ada di salah satu dari 4 status ini. Status **dihitung otomatis** dari kondisi data (bukan diisi manual):
|
||
|
||
| Status | Artinya |
|
||
|---|---|
|
||
| `mcf` | Wajib penerbangan uji (Maintenance Check Flight) dulu |
|
||
| `aog` | Dikandangkan, tidak boleh terbang |
|
||
| `booked` | Sedang dipakai misi |
|
||
| `available` | Sehat, siap terbang |
|
||
|
||
**Kalau beberapa kondisi terjadi bersamaan, yang menang urutannya begini:**
|
||
|
||
```
|
||
MCF > AOG > Booked > Available
|
||
```
|
||
|
||
Contoh: helikopter yang sedang wajib MCF **dan** punya kerusakan AOG → tetap tampil `mcf` (karena MCF paling tinggi). Ini sama persis dengan sistem Wucher lama.
|
||
|
||
---
|
||
|
||
## 3. Gambaran Besar: 3 Jalan Sebuah Helikopter Berhenti Terbang
|
||
|
||
Ada **3 sebab** helikopter jadi tidak boleh terbang. Tiap sebab punya cara keluar sendiri:
|
||
|
||
| Sebab berhenti | Jadi status | Cara terbang lagi |
|
||
|---|---|---|
|
||
| **A. Ada kerusakan** (complaint) | `aog` | EASA Release disign (atau ditunda dulu via Action/NSR) |
|
||
| **B. Jadwal perawatan jatuh tempo** (otomatis) | `aog` | Perbarui jadwal/selesai inspeksi → hitung ulang |
|
||
| **C. Wajib penerbangan uji** (MCF) | `mcf` | Selesaikan MCF dengan hasil "passed" |
|
||
|
||
Tiga sebab ini dibahas satu per satu di bawah.
|
||
|
||
---
|
||
|
||
## 4. JALAN A — Helikopter Rusak (Complaint → AOG → Perbaikan)
|
||
|
||
Ini alur paling sering. Ceritanya berurutan:
|
||
|
||
### Langkah 1 — Catat kerusakannya
|
||
Begitu ada kerusakan, buat laporan (complaint).
|
||
|
||
`POST /complaints/create` (permission `complaint.create`)
|
||
|
||
```jsonc
|
||
{
|
||
"data": {
|
||
"type": "complaint_create",
|
||
"attributes": {
|
||
"helicopter_id": "019d6771-5fb5-7337-837f-bc5ed85181a1",
|
||
"description": "Getaran di Engine 2 saat cruise",
|
||
"mel_severity": 0, // lihat tabel di Langkah 2
|
||
"aircraft_hours_at_report": "1245.3"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### Langkah 2 — Tentukan seberapa parah (klasifikasi MEL)
|
||
Field `mel_severity` menentukan **kapan pesawat harus berhenti**:
|
||
|
||
| `mel_severity` | Kelas | Boleh terbang sampai kapan? |
|
||
|---|---|---|
|
||
| `0` | NON-MEL | **Tidak boleh sama sekali** → AOG seketika |
|
||
| `1` | A | Maksimal **1 hari**, lewat itu → AOG |
|
||
| `2` | B | Maksimal **3 hari** → AOG |
|
||
| `3` | C | Maksimal **10 hari** → AOG |
|
||
| `4` | D | Maksimal **120 hari** → AOG |
|
||
| *(dikosongkan)* | belum diklasifikasi | Statusnya `pending_classification`, **belum bikin AOG** sampai diklasifikasi |
|
||
|
||
> Klasifikasi bisa diisi belakangan lewat `PATCH /complaints/update/:id` (field `mel_severity`). Sistem mencatat siapa & kapan mengklasifikasi (audit `mel_classified_by/at`).
|
||
|
||
Selama kerusakan ini bikin AOG, di Fleet Status detail helikopter akan **muncul** data `complaints` + `easa`. Kalau sudah tidak AOG, dua data itu hilang sendiri.
|
||
|
||
### Langkah 3 (opsional) — Mau terbang dulu sebelum diperbaiki tuntas?
|
||
Kadang pesawat perlu tetap operasi sambil menunggu perbaikan resmi. Ada **2 cara**, dan ini beda fungsi:
|
||
|
||
**Cara 3a — Action Taken (tindakan sementara sudah dilakukan):**
|
||
`PATCH /complaints/update/:id` isi `action_taken`.
|
||
|
||
```jsonc
|
||
{ "data": { "type": "complaint_update", "id": "<complaint_id>",
|
||
"attributes": {
|
||
"action_taken": "Kencangkan engine mount, cek torsi OK",
|
||
"aircraft_hours_at_fix": "1250.1"
|
||
} } }
|
||
```
|
||
→ Pesawat **boleh terbang lagi**, tapi laporan **masih terbuka**.
|
||
|
||
**Cara 3b — NSR (kerusakan aman ditunda):**
|
||
`PATCH /complaints/update/:id` isi `is_nsr: true` (**butuh permission khusus `complaint.nsr`**).
|
||
|
||
```jsonc
|
||
{ "data": { "type": "complaint_update", "id": "<complaint_id>",
|
||
"attributes": {
|
||
"is_nsr": true,
|
||
"nsr_reason": "Dirilis di bawah MEL, defect ditunda"
|
||
} } }
|
||
```
|
||
→ Pesawat **boleh terbang lagi**, laporan **masih terbuka**. Sistem mencatat siapa yang memutuskan NSR (`nsr_decided_by/at`).
|
||
|
||
> **Beda Action Taken vs NSR:**
|
||
> - *Action Taken* = "sudah saya tangani sementara".
|
||
> - *NSR* = "belum ditangani, tapi memang **boleh ditunda** dengan aman".
|
||
> Keduanya sama-sama bikin pesawat boleh terbang lagi, dan **sama-sama belum menutup laporan**.
|
||
>
|
||
> Membatalkan NSR: kirim `is_nsr: false` → aturan AOG berlaku lagi.
|
||
|
||
### Langkah 4 — Tutup kerusakan secara resmi (EASA Release)
|
||
Inilah langkah yang **benar-benar menyelesaikan** kerusakan. Tiga sub-langkah:
|
||
|
||
**4a. Buat surat EASA-nya** (boleh draft / belum lengkap dulu):
|
||
`POST /easa-releases/create` (permission `easa_release.create`)
|
||
|
||
> ⚠️ **Syarat boleh membuat EASA:** semua complaint terbuka helikopter itu **harus sudah di-*Action Taken* atau di-NSR dulu** (Langkah 3). Kalau masih ada yang "mentah", create ditolak (`ErrEASAReleaseComplaintsPendingAction`). Jadi Langkah 3 itu **pintu masuk** ke Langkah 4.
|
||
|
||
**4b. Lengkapi datanya** (kalau tadi masih draft):
|
||
`PATCH /easa-releases/update/:id`
|
||
|
||
**4c. TANDA TANGAN (sign) — ini momen kerusakan benar-benar ditutup:**
|
||
`POST /easa-releases/sign/:id` (permission `easa_release.sign`, **tanpa body** — penandatangan = user yang sedang login).
|
||
|
||
```bash
|
||
POST /api/v1/easa-releases/sign/019d6772-471c-7b70-b42a-d94020ef61e4
|
||
```
|
||
|
||
**Sebelum bisa sign, 5 field ini WAJIB terisi:**
|
||
|
||
| Field | Contoh |
|
||
|---|---|
|
||
| `easa_date` | `2026-06-16` |
|
||
| `easa_ac_hours` | `1245.3` |
|
||
| `easa_location` | `LOWI` |
|
||
| `easa_wo_no` | `WO-2026-001` |
|
||
| `easa_signer_id` | `145.A.50` |
|
||
|
||
Kalau ada yang kosong → ditolak (`ErrEASAReleaseIncompleteForSign`) beserta daftar `missing_sign_fields`. Aturannya tegas: **EASA yang belum lengkap tidak boleh dianggap selesai.**
|
||
|
||
> **Jalan pintas:** kalau datanya sudah lengkap dari awal, kamu bisa langsung sign **saat create** — tambahkan `"sign": true` di body create. (Catatan: flag `sign` ini **hanya ada di create**, tidak ada di update.)
|
||
|
||
**Begitu sign berhasil, otomatis terjadi:**
|
||
1. Surat EASA tercatat `signed_at` + `signed_by`.
|
||
2. **Semua complaint terbuka** helikopter itu ditutup → statusnya jadi `serviced`.
|
||
3. Karena tidak ada lagi kerusakan yang menggantung → **AOG hilang**, data `complaints`/`easa` di Fleet Status ikut hilang.
|
||
4. Tercatat di riwayat (history): "Release to Service (EASA signed)".
|
||
|
||
### Ringkasan Jalan A (urut)
|
||
```
|
||
Rusak → buat complaint → klasifikasi MEL
|
||
→ (opsional) Action Taken / NSR ➜ boleh terbang, laporan MASIH terbuka
|
||
→ EASA create → EASA lengkapi → EASA SIGN ✅ ➜ laporan DITUTUP, AOG hilang
|
||
```
|
||
|
||
---
|
||
|
||
## 5. JALAN B — Jadwal Perawatan Jatuh Tempo (AOG Otomatis)
|
||
|
||
### Apa ini?
|
||
Tiap helikopter punya jadwal inspeksi di Fleet Status (mis. inspeksi tiap 100 jam, atau jatuh tempo di tanggal tertentu). Kalau **jam terbang** atau **tanggal** sudah melewati batas, sistem **otomatis** men-AOG-kan pesawat — tanpa perlu ada yang lapor.
|
||
|
||
### Cara masuk AOG
|
||
Diatur di Fleet Status, tiap jadwal punya:
|
||
- `due` = batas normal (boleh berupa **jam**, mis. `1200`, atau **tanggal**, mis. `2026-09-01`)
|
||
- `ext` = batas perpanjangan (kalau diisi, ini yang dipakai menggantikan `due`)
|
||
|
||
Saat jam/tanggal aktual melewati batas → status jadi `aog` dengan keterangan otomatis (`AOG: ... next due reached`).
|
||
|
||
> Engine yang tidak aktif di helikopter (flag `NR1`/`NR2` = false) **dilewati** — jadwal engine itu tidak ikut bikin AOG.
|
||
|
||
### Kapan sistem menghitung ulang?
|
||
AOG jenis ini **disimpan**, jadi perlu pemicu untuk berubah:
|
||
- Saat data penerbangan (flight data) dibuat/diubah/dihapus.
|
||
- Saat Fleet Status helikopter itu di-update.
|
||
- **Otomatis tiap 1 jam** (cron) — supaya AOG berbasis tanggal tetap nyala walau tidak ada aktivitas.
|
||
|
||
### Cara terbang lagi
|
||
Perbarui jadwalnya supaya tidak lagi lewat tempo (mis. setelah inspeksi selesai, isi `due`/`ext` yang baru):
|
||
|
||
`PATCH /fleet-status/update/:id`
|
||
```jsonc
|
||
{ "data": { "type": "fleet_status_update", "id": "<fleet_status_id>",
|
||
"attributes": { "maintenance_schedules": [
|
||
{ "inspection_type": "100H", "due": "1400", "ext": "" }
|
||
] } } }
|
||
```
|
||
Pada perhitungan ulang berikutnya, AOG otomatis ini dilepas. (Catatan: sistem hanya melepas AOG yang dibuatnya sendiri secara otomatis; AOG manual tidak disentuh.)
|
||
|
||
---
|
||
|
||
## 6. JALAN C — Wajib Penerbangan Uji (MCF)
|
||
|
||
### Apa ini?
|
||
Setelah pekerjaan perawatan besar, helikopter kadang wajib menjalani **penerbangan uji (MCF)** dulu sebelum dianggap normal. Selama wajib MCF, statusnya `mcf` (mengalahkan AOG).
|
||
|
||
### Langkah 1 — Tandai wajib MCF (cukup minimal)
|
||
`POST /mcf/create` (permission `mcf.create`) — body cukup `helicopter_id` saja (+ `notes` opsional). Tujuannya hanya menandai pesawat ini wajib MCF.
|
||
|
||
```jsonc
|
||
{ "data": { "type": "mcf_create",
|
||
"attributes": {
|
||
"helicopter_id": "019d6771-5fb5-7337-837f-bc5ed85181a1",
|
||
"notes": "Wajib MCF setelah kerja engine mount"
|
||
} } }
|
||
```
|
||
|
||
### Langkah 2 — Selesaikan MCF setelah terbang uji
|
||
`POST /mcf/complete/:helicopter_id` (permission `mcf.complete`) — **pakai helicopter_id**, bukan id MCF. Wajib isi semua field hasil uji:
|
||
|
||
```jsonc
|
||
{ "data": { "type": "mcf_complete",
|
||
"attributes": {
|
||
"af_hours": "1245.3",
|
||
"landing_count": 3,
|
||
"utc_time": "2026-06-17T08:30:00Z", // format RFC3339
|
||
"date": "2026-06-17", // format YYYY-MM-DD
|
||
"result": "passed", // passed atau failed
|
||
"notes": "Getaran dalam batas normal"
|
||
} } }
|
||
```
|
||
|
||
**Hasilnya menentukan:**
|
||
|
||
| `result` | Yang terjadi |
|
||
|---|---|
|
||
| `passed` | MCF beres → pesawat **lepas dari status MCF** (kembali ke status lain sesuai kondisi) |
|
||
| `failed` | Pesawat **tetap MCF**, hasil gagal dicatat ke riwayat → ulangi sampai `passed` |
|
||
|
||
> Catatan: kalau tidak ada MCF terbuka untuk helikopter itu, complete ditolak (`409`).
|
||
|
||
---
|
||
|
||
## 7. Melihat Riwayat (History)
|
||
|
||
Semua kejadian penting di atas — dari kerusakan dilaporkan, diklasifikasi, NSR, perbaikan, EASA disign, hasil MCF, sampai AOG otomatis nyala/mati — **tercatat otomatis** dalam satu garis waktu (timeline) per helikopter. Berguna untuk audit: *siapa* melakukan *apa* dan *kapan*.
|
||
|
||
### Di mana lihatnya?
|
||
`GET /fleet-status/history/:helicopter_id` (permission `flight.read`)
|
||
|
||
```bash
|
||
GET /api/v1/fleet-status/history/019d6771-5fb5-7337-837f-bc5ed85181a1?page=1&page_size=20
|
||
```
|
||
|
||
- Diurutkan **terbaru di atas**.
|
||
- Mendukung halaman: `page` (default 1) & `page_size` (default 20).
|
||
- Timeline ini **gabungan dua sumber**: catatan perawatan yang diselesaikan (service log) + semua kejadian aksi (complaint, EASA, MCF, AOG).
|
||
|
||
### Kejadian apa saja yang tercatat?
|
||
|
||
| `action` | Tercatat ketika… |
|
||
|---|---|
|
||
| `complaint_filed` | Laporan kerusakan dibuat |
|
||
| `mel_classified` | Kerusakan diklasifikasi MEL (A/B/C/D atau NON-MEL) |
|
||
| `nsr_done` | NSR diberikan (boleh terbang walau defect terbuka) |
|
||
| `nsr_cancelled` | NSR dibatalkan |
|
||
| `action_taken` | Tindakan perbaikan sementara dicatat |
|
||
| `easa_created` | Surat EASA dibuat (draft) |
|
||
| `easa_signed` | **EASA ditandatangani → kerusakan ditutup** |
|
||
| `mcf_result` | Hasil MCF diisi (`passed`/`failed`) |
|
||
| `aog_set` | AOG otomatis dinyalakan (jadwal jatuh tempo) |
|
||
| `aog_cleared` | AOG otomatis dilepas |
|
||
| `serviced` | Inspeksi/perawatan diselesaikan |
|
||
|
||
### Bentuk responsnya
|
||
|
||
Tiap baris timeline berisi: kapan, jenisnya, aksinya, pesan, dan **siapa pelakunya** (nama langsung tersedia di `actor_name`).
|
||
|
||
```jsonc
|
||
{
|
||
"data": [
|
||
{
|
||
"at": "2026-06-17T10:15:00Z",
|
||
"entity_type": "easa_release",
|
||
"entity_id": "019d6772-471c-7b70-b42a-d94020ef61e4",
|
||
"action": "easa_signed",
|
||
"message": "Release to Service (EASA signed)",
|
||
"actor": "019e91e6-2908-7f37-93e6-015ed1b7587d",
|
||
"actor_name": "John Doe"
|
||
},
|
||
{
|
||
"at": "2026-06-17T09:40:00Z",
|
||
"entity_type": "complaint",
|
||
"action": "action_taken",
|
||
"message": "Action taken — Kencangkan engine mount, cek torsi OK",
|
||
"actor_name": "Jane Tech"
|
||
}
|
||
],
|
||
"meta": { "page_number": 1, "page_size": 20, "total": 12 }
|
||
}
|
||
```
|
||
|
||
> Selain timeline ini, daftar **kerusakan per helikopter** (beserta status terkini, NSR, action, dan EASA terkait) bisa dilihat lewat `GET /complaints/get-by-helicopter/:helicopter_id`, dan kondisi terkini helikopter (status + complaint + EASA aktif) lewat `GET /fleet-status/get-by-helicopter/:helicopter_id`.
|
||
|
||
---
|
||
|
||
## 8. Tabel Endpoint Ringkas
|
||
|
||
| Mau apa | Endpoint | Permission |
|
||
|---|---|---|
|
||
| Lapor kerusakan | `POST /complaints/create` | `complaint.create` |
|
||
| Klasifikasi MEL / Action Taken / NSR | `PATCH /complaints/update/:id` | `complaint.update` (+`complaint.nsr` utk NSR) |
|
||
| Lihat kerusakan per helikopter | `GET /complaints/get-by-helicopter/:helicopter_id` | `complaint.read` |
|
||
| Buat surat EASA | `POST /easa-releases/create` | `easa_release.create` |
|
||
| Lengkapi EASA | `PATCH /easa-releases/update/:id` | `easa_release.update` |
|
||
| **Tanda tangan EASA (tutup kerusakan)** | `POST /easa-releases/sign/:id` | `easa_release.sign` |
|
||
| Tandai wajib MCF | `POST /mcf/create` | `mcf.create` |
|
||
| **Selesaikan MCF** | `POST /mcf/complete/:helicopter_id` | `mcf.complete` |
|
||
| Atur jadwal perawatan & jam | `POST /fleet-status/create` · `PATCH /fleet-status/update/:id` | `flight.create` / `flight.update` |
|
||
| Lihat status + complaint + EASA | `GET /fleet-status/get-by-helicopter/:helicopter_id` | `flight.read` |
|
||
| Lihat riwayat helikopter | `GET /fleet-status/history/:helicopter_id` | `flight.read` |
|
||
|
||
---
|
||
|
||
## 9. Tanya–Jawab Cepat (FAQ)
|
||
|
||
**T: Kerusakan dianggap selesai saat EASA dibuat atau saat disign?**
|
||
J: Saat **disign**. Membuat (create) atau melengkapi (update) EASA **belum** menutup apa pun. Penutupan complaint terjadi tepat di endpoint `sign`.
|
||
|
||
**T: Bedanya Action Taken, NSR, dan EASA Sign?**
|
||
J:
|
||
- **Action Taken** & **NSR** → bikin pesawat **boleh terbang lagi**, tapi laporan **masih terbuka**.
|
||
- **EASA Sign** → **menutup** laporan secara resmi (status `serviced`).
|
||
|
||
**T: Kalau cuma isi Action Taken, kapan laporannya hilang dari daftar AOG?**
|
||
J: AOG-nya langsung hilang begitu Action Taken diisi (pesawat boleh terbang). Tapi laporannya **tetap tercatat terbuka** sampai EASA disign.
|
||
|
||
**T: Kenapa saya tidak bisa membuat EASA?**
|
||
J: Kemungkinan masih ada complaint yang belum di-Action/NSR. Selesaikan Langkah 3 dulu untuk tiap complaint terbuka.
|
||
|
||
**T: Helikopter wajib MCF tapi juga ada kerusakan AOG, tampil yang mana?**
|
||
J: Tampil `mcf`, karena MCF prioritas tertinggi.
|
||
|
||
**T: AOG karena jadwal jatuh tempo kok tidak langsung hilang setelah saya update jadwal?**
|
||
J: AOG jenis ini dihitung ulang saat ada flight data baru, update fleet status, atau otomatis tiap 1 jam. Tunggu pemicu berikutnya.
|
||
|
||
**T: Di mana saya bisa lihat riwayat apa saja yang sudah terjadi pada satu helikopter?**
|
||
J: Di `GET /fleet-status/history/:helicopter_id` — timeline lengkap (terbaru di atas) berisi siapa melakukan apa & kapan. Lihat §7.
|
||
|
||
---
|
||
|
||
## 10. Catatan untuk Developer
|
||
|
||
- **AOG karena kerusakan** dihitung *saat dibaca* (real-time dari complaint terbuka) → berubah instan, tidak perlu job.
|
||
- **AOG karena jadwal** *disimpan* di helikopter → perlu pemicu (flight data / update fleet / cron 1 jam). Hanya AOG otomatis yang dilepas otomatis; AOG manual tidak.
|
||
- **MCF mengalahkan AOG** dalam prioritas status.
|
||
- **Penutupan kerusakan hanya lewat EASA sign** — `action_taken` & `is_nsr` hanya mengangkat larangan terbang, tidak menutup laporan.
|
||
- **Masa tenggang MEL dihitung dalam HARI** (A=1, B=3, C=10, D=120) di `internal/domain/complaint/model.go` fungsi `MELDeadline` (`* 24 * time.Hour`).
|