# RANCANGAN BACKEND TRUKCO (4 TAHAP)

SAVAR DINAMIKA TEKNOLOGI | PHP 8 (framework sendiri) + MySQL | Status: RANCANGAN revisi 2 (21 November 2026), belum dieksekusi, menunggu aba-aba

Label yang dipakai: **[Fakta]** tertulis di dokumen sumber; **[Usulan]** keputusan rancangan saya, dapat diubah; **[Tidak tahu]** tidak ditemukan pada sumber yang saya baca.

---

## 0. Dasar rancangan dan batas pengetahuan

**Yang saya baca**
- TRUKCO_create_tabel.sql: seluruhnya (40 tabel).
- TRUKCO_PRD_v1.1b: seluruhnya.
- TRUKCO_Kontrak_API_v1.1b: seluruh bagian 1 sampai 3 dan 5 (138 endpoint), bagian 6 sampai 10 (skema, katalog galat, parameter, status, notifikasi, jurnal, konflik K-01 sampai K-22, celah SQL G-xx, keputusan terbuka). Bagian 4 (uraian fitur) hanya saya baca judulnya karena isinya dipetakan ulang oleh bagian 5.
- TRUKCO_Simulasi_34_Tabel_v1.1b: sebagian (konfigurasi, top-up S07, neraca dan invarian I-1 sampai I-11, tabel perubahan T-xx, definisi kolom dompet dan top-up). Sisanya belum saya baca.

**Yang tidak saya baca**
- TRUKCO_Deskripsi_Aplikasi_v1.1b (bukan bagian daftar dari Anda).
- Dokumentasi resmi Midtrans, Google Maps Platform, dan FCM. Penulis kontrak juga tidak memverifikasinya (Kontrak bagian 9.2). Seluruh detail format pesan pihak ketiga pada dokumen ini adalah pengetahuan saya dan **belum terverifikasi**; harus dicocokkan dengan dokumentasi resmi sebelum dikode.

**Catatan konsistensi sumber [Fakta]**
- Berkas bernama v1.1b, tetapi footer Kontrak API mencetak "v1.0 (Draf)". Saya tidak tahu versi mana yang berlaku; rancangan ini mengikuti isi berkas v1.1b.
- EP-W01: teks sukses menulis 403 untuk tanda tangan tidak sah, sedangkan galat khusus dan katalog menulis 401 (TANDA_TANGAN_TIDAK_SAH). Rancangan memakai 401 mengikuti katalog; perlu keputusan.
- Kontrak sendiri menyatakan kode HTTP pada katalog galat adalah usulan dan perlu diseragamkan.
- URL contoh Kontrak memakai alamat ngrok; rancangan hanya memakai prefiks `/api/v1`.

---

## 1. Ringkasan keputusan arsitektur

| No | Topik | Keputusan | Status |
| --- | --- | --- | --- |
| 1 | Bahasa dan basis data | PHP 8.x, MySQL (InnoDB, utf8mb4_unicode_ci), koneksi `SET time_zone='+07:00'`, PHP `Asia/Jakarta` | Fakta (PRD/SQL); versi PHP minor: Usulan |
| 2 | Framework | Framework sendiri, tanpa Laravel; dependensi pihak ketiga sekecil mungkin (hanya ekstensi bawaan: pdo_mysql, openssl, curl, mbstring, fileinfo) | Fakta (permintaan); daftar ekstensi: Usulan |
| 3 | Pola lapisan | Router, Middleware, Controller tipis, Service (aturan bisnis), Repository (SQL), Integrasi (adapter) | Usulan |
| 4 | Autentikasi | JWT akses berumur pendek, token refresh buram yang dirotasi, deteksi pemakaian ulang mencabut seluruh rantai | Fakta (kontrak); umur token: Tidak tahu |
| 5 | Galat | Amplop `galat{kode,pesan,rincian,trace_id}` + header X-Trace-Id; 96 kode pada Kontrak 6.2 menjadi sumber tunggal berkas `config/galat.php`, dokumentasi dibangkitkan dari berkas itu | Fakta; mekanisme dokumentasi: Usulan |
| 6 | Uang | Bilangan bulat rupiah (BIGINT/int 64-bit); tanpa float; buku besar berentri ganda, hanya-tambah | Fakta |
| 7 | Tanpa cron | Seluruh batas waktu dievaluasi lazy saat permintaan masuk (J10), dijaga `kunci_penjadwal` | Fakta |
| 8 | Idempotensi | 20 endpoint wajib Idempotency-Key; kunci jurnal unik per akibat uang | Fakta |
| 9 | Top-up | Midtrans Snap + webhook EP-W01 bertanda tangan, dedup, jurnal `topup:{id}` | Fakta (INT-001); bentuk pesan: belum terverifikasi |
| 10 | Peta | Google Maps hanya dari server (proxy); kunci tidak dikirim ke klien | Fakta (INT-003); API yang dipakai: Usulan |
| 11 | Notifikasi | FCM v1; kegagalan push tidak boleh menggagalkan alur bisnis; polling sebagai cadangan | Fakta |
| 12 | Penjaga kelengkapan | Berkas `docs/endpoint-138.json` + perintah `php bin/trukco cek:rute` gagal bila rute terdaftar tidak persis 138 | Usulan |
| 13 | Pengemasan | ZIP, tanpa UI, jalan dengan `php -S 127.0.0.1:8000 -t public` | Fakta (permintaan) |

---

## 1A. Keputusan yang sudah diambil (21 November 2026)

Dari jawaban Anda dan asumsi wajar saya. Bagian ini mengalahkan pernyataan "belum diputuskan" pada bagian lain dokumen.

| No | Topik | Keputusan | Sumber |
| --- | --- | --- | --- |
| 1 | Biaya Driver (CFG-08) | Dibaca dari `jenis_truk.biaya_driver` (kolom sudah ada) ke variabel. Bila kosong, NULL, atau 0: dipakai **nilai 1** supaya perhitungan tetap berjalan. Nilai 1 ditandai `status_nilai = belum_ditetapkan` pada EP-A06 dan ditulis sebagai peringatan di log aplikasi. Admin menetapkan nilai sebenarnya lewat EP-A15. | Anda |
| 2 | Penyetuju kedua pencairan driver | Direktur: Admin mengajukan (EP-A24), Direktur memutuskan (EP-R08) | Anda |
| 3 | Payout penarikan pelanggan | Manual lewat Admin (EP-A26 dengan bukti mutasi); antarmuka payout otomatis disiapkan untuk penyedia kelak | Anda |
| 4 | Cara masuk Pelanggan dan Driver | Nomor HP + kata sandi. OTP hanya untuk memverifikasi kontak (registrasi, ubah kontak, dan pembuktian kepemilikan kontak pada lupa sandi). Masuk dengan OTP tidak dibuat. | Anda |
| 5 | Perubahan tabel | Seluruh migrasi celah (Bagian 3.1) disetujui; tabel baru yang diperlukan saya putuskan sendiri | Anda (wewenang umum) |
| 6 | Parameter lain yang kosong | Dibaca dari tabel `konfigurasi` ke variabel; bila kosong dipakai nilai awal dari `config/parameter.php`: radius dan sejenisnya sesuai PRD; CFG-18 = 60 menit; CFG-20 = top-up 50.000 sampai 10.000.000, penarikan minimum 50.000; CFG-24 = 60 menit; CFG-25 = 4.000; CFG-26 = 2.500; CFG-27 = 120 menit; CFG-28 = 10 menit; CFG-29 = 7 hari; CFG-30 = 1 hari kerja; pencairan driver minimum 100.000; kecepatan rata-rata 40 km/jam. Nilai ini berasal dari asumsi Simulasi, bukan tarif resmi. Kode PARAMETER_BELUM_DITETAPKAN tetap ada di katalog dan hanya muncul bila suatu kunci tidak memiliki nilai awal. | Saya |
| 7 | Token dan OTP | JWT HS256; akses 15 menit; refresh 30 hari; OTP 6 digit, 5 menit, 5 percobaan, jeda kirim ulang 60 detik | Saya |
| 8 | Sandi dan batas login | Sandi minimal 8 karakter berisi huruf dan angka; karena masuk hanya dengan sandi, login dibatasi 5 kegagalan per akun dan per IP dalam 15 menit lalu ditunda dengan jawaban TERLALU_BANYAK_PERMINTAAN (429) dan Retry-After | Saya |
| 9 | Pembulatan biaya BBM | Dibulatkan ke atas | Saya |
| 10 | Kode pesanan | 10 karakter acak unik (huruf besar dan angka tanpa karakter ambigu), dicoba ulang bila bentrok; format TRK-tanggal pada gambar tidak dipakai (K-20) | Saya |
| 11 | Suspend | 14 hari (CFG-22); pulih otomatis saat masa habis tanpa syarat tambahan (OPN-09) | Saya |
| 12 | Kompensasi | Batas per laporan = total pesanan terkait, selain batas saldo Dana Operasional (OPN-35) | Saya |
| 13 | Admin membuat Direktur | Diizinkan, tetapi hanya satu Direktur aktif; pembuatan kedua ditolak VALIDASI_GAGAL dengan rincian; tercatat di audit (KP-10) | Saya |
| 14 | Pindahan dan Truk Fuso | Pindahan `tersedia=false`; server hanya memakai empat kode master PUB, PBB, CDE, CDD; nama tampilan ditangani klien (K-04, K-05) | Saya |
| 15 | Daftar bank | Seed awal bank besar Indonesia (kode dan nama), dapat diubah; harus dicocokkan dengan penyedia payout bila kelak dipasang | Saya |
| 16 | Settlement top-up | Pekerjaan `impor_settlement` membukukan settlement T+1 hari kerja menurut aturan Simulasi; belum diverifikasi terhadap Midtrans | Saya |
| 17 | Batas berkas dan penyimpanan | 5 MB per berkas; JPG, PNG, PDF | Saya |

**Peringatan atas keputusan 1 [Fakta turunan dari rumus harga]:** dengan Biaya Driver = 1, Hak Driver pesanan hampir sama dengan komponen BBM saja. Pesanan nyata yang dibuat sebelum Admin menetapkan nilai sebenarnya akan terkunci pada harga itu (BR-014). Karena itu EP-A06 menampilkan penanda dan log memberi peringatan; menetapkan nilai sebenarnya sebelum peluncuran tetap perlu dilakukan.

---

## 2. Arsitektur framework sendiri

### 2.1 Struktur direktori [Usulan]

```
trukco/
  public/index.php            front controller (satu-satunya berkas web)
  bin/trukco                  CLI: migrasi, seed, cek:rute, cek:invarian, galat:dokumen, jalankan:pekerjaan
  config/                     app.php, db.php, jwt.php, galat.php, parameter.php, integrasi.php, rute-meta.php
  routes/api.php              daftar rute + metadata (ID EP, peran, idempotensi, kelompok laju)
  app/
    Inti/                     Aplikasi, Kontainer, Router, Permintaan, Respons, Pipa Middleware,
                              Validator, Konfigurasi, Log, Waktu (jam yang dapat diganti saat uji), Galat
    Middleware/               TraceId, Pemeliharaan, PembatasLaju, Autentikasi, Peran, StatusAkun,
                              WajibGantiSandi, Idempotensi
    Basis/                    Koneksi PDO, Transaksi, PembangunKueri ringan, Migrator
    Domain/                   Harga, MesinStatusPesanan, KebijakanPembatalan, Pencocokan,
                              Dompet (BukuBesar), Verifikasi Driver, Sanksi, Rekonsiliasi
    Layanan/                  satu kelas per modul (Auth, Akun, Pesanan, Dompet, Topup, Penarikan, ...)
    Repositori/               akses SQL per tabel
    Integrasi/                MidtransKlien, PetaKlien, FcmKlien, PengirimOtp (antarmuka), PayoutKlien (antarmuka)
    Pengendali/               satu kelas per kelompok endpoint
    Penjadwal/                PenjadwalLazy + satu kelas per pekerjaan (Bagian 8)
  database/migrations/        0000_baseline.sql (skrip 40 tabel tanpa diubah), 0001_celah_*.sql (Bagian 3)
  database/seed/              jenis_truk, jenis_bbm, master_truk, konfigurasi, tarif_penarikan, dompet sistem
  storage/                    berkas/ (di luar public), log/, cache/
  docs/                       endpoint-138.json, galat.md (dibangkitkan), openapi ringkas (opsional)
  tests/                      uji unit, uji kontrak HTTP, uji invarian
  .env.example, README.md
```

### 2.2 Alur satu permintaan

1. `public/index.php` memuat autoloader sendiri (PSR-4), membaca `.env`, membuat trace_id 16 karakter heksadesimal (sama dengan `log_audit.trace_id`).
2. Router mencocokkan metode + path ke rute; metadata rute memuat ID EP, peran yang diizinkan, apakah Idempotency-Key wajib, dan kelompok pembatas laju.
3. Urutan middleware: TraceId, Pemeliharaan (503 PEMELIHARAAN), PembatasLaju (429), Autentikasi (JWT), StatusAkun, WajibGantiSandi (hanya EP-U09 lolos), Peran (BR-003: pemeriksaan di server pada setiap permintaan), Idempotensi, lalu Pengendali.
4. Pengendali memvalidasi masukan (Validator; kesalahan menjadi VALIDASI_GAGAL dengan `rincian` per bidang), memanggil Layanan, menerima objek hasil, dan Respons membentuk JSON snake_case Indonesia.
5. Galat apa pun dilempar sebagai `GalatAplikasi(kode)`; penangan global menerjemahkan ke HTTP + amplop dari `config/galat.php`; galat tak terduga menjadi KESALAHAN_SERVER dengan trace_id dan tanpa membocorkan detail.
6. Setelah respons terkirim: pengiriman push FCM yang tertunda (Bagian 9.3).

### 2.3 Konvensi yang dikunci dari Kontrak [Fakta]

- Prefiks `/api/v1`; JSON; nama bidang snake_case Indonesia; waktu ISO 8601 dengan +07:00; uang bilangan bulat rupiah.
- Identitas sumber daya pada URL memakai `kode_publik` CHAR(10), bukan id berurutan (kecuali yang memang memakai id, misalnya EP-A02).
- Paginasi kursor: `kursor`, `batas` (bawaan 20, maksimum 100); kursor dibuat buram (isi: kunci urut terakhir + id) [Usulan].
- Header: Authorization Bearer, X-Perangkat, Idempotency-Key (maksimum 80 karakter) pada 20 endpoint.
- TIDAK_DITEMUKAN dipakai juga untuk sumber daya milik orang lain, supaya keberadaannya tidak bocor.

---

## 3. Basis data

**Prinsip [Usulan]:** skrip SQL asli (40 tabel) dimuat apa adanya sebagai `0000_baseline.sql`. Setiap perubahan untuk menutup celah Kontrak diletakkan di berkas migrasi terpisah, sehingga Anda dapat menerima atau menolak per celah. Tidak ada perubahan SQL yang saya buat tanpa persetujuan Anda (KP-12).

### 3.1 Migrasi celah yang diusulkan

| ID | Perubahan | Dibutuhkan oleh | Tahap | Tingkat kebutuhan |
| --- | --- | --- | --- | --- |
| G-02 | Tambah `reset_sandi` pada enum `kode_otp.tujuan` | EP-U03, U04, U08 | 1 | Perlu bila lupa sandi dipakai |
| G-03 | Tabel baru `perangkat_fcm` (pengguna_id, token, platform, nama_perangkat, dibuat_at, dicabut_at) | EP-U14, U15, FCM | 1 | Wajib untuk FCM |
| G-04, G-22 | Kolom `isi`, `referensi_tipe`, `referensi_kode` pada `notifikasi` | EP-U20, U21 | 1 | Wajib untuk bentuk respons |
| G-12 | Kolom `persetujuan_at`; nilai status `penghapusan_diminta` | EP-U02, U16 | 1 | Wajib (FR-004, FR-005) |
| G-14 | Tabel `master_bank` | EP-U29, U18 | 1 | Wajib; isi daftar bank: Tidak tahu |
| G-13 | Pastikan satu baris per jenis dompet sistem lewat seed + pemeriksaan aplikasi | semua jurnal | 1 | Wajib |
| T-01 (rancangan) | Tabel `berkas_sementara` (token, pengguna_id, tujuan, path, mime, ukuran, kedaluwarsa_at, dipakai_at) | EP-U25 | 1 | Wajib (SQL tidak punya) |
| T-02 (rancangan) | Tabel `pembatas_laju` (kunci, jendela_mulai, jumlah) | TERLALU_BANYAK_PERMINTAAN | 1 | Usulan; alternatif: berkas cache |
| G-28 | Kolom `token_snap`, `url_pembayaran` pada `topup` | EP-P18, P20 | 2 | Perlu agar tautan bayar dapat dilanjutkan |
| G-15 | Isi `kota_domisili`, `lat_basis`, `lon_basis` dari pemilih lokasi EP-D01 | EP-D01 | 2 | Tanpa perubahan SQL |
| G-07 | Server mengisi nilai bawaan `keterangan_barang` bila kosong, atau kolom dibuat NULL | EP-P05 | 3 | Pilih salah satu |
| G-06 | Nilai `keberatan` pada `laporan.jenis` (atau pakai `lainnya` + menahan_finalisasi) | EP-P13 | 3 | Pilih salah satu |
| G-23 | Hitung ulang jarak jemput pada EP-P05, atau tambah kolom pada `estimasi_pesanan` | EP-P04, P05 | 3 | Pilih salah satu |
| G-24, G-25 | Tidak ada tabel pelanggaran; bukti sanksi perlu tabel lampiran atau diabaikan | EP-A21 | 3 | Keputusan produk |
| G-05 | Kolom `disetujui_oleh`, `disetujui_at` pada `penarikan` (atau status menunggu persetujuan) | EP-A24, R07, R08 | 4 | Wajib untuk persetujuan kedua |
| G-26 | Kolom `bukti_path` pada `penarikan` | EP-A26 | 4 | Wajib (FR-056) |
| G-17 | Tolak `pengembalian` pada `setoran_perusahaan.jenis` di aplikasi | EP-A27 | 4 | Tanpa perubahan SQL |
| G-21 | Jadikan `tarif_penarikan` satu-satunya sumber tarif | EP-P17, P22 | 4 | Tanpa perubahan SQL |
| G-11 | Riwayat konfigurasi dibaca dari `log_audit` | EP-A36 | 1 | Tanpa perubahan SQL |
| G-08 | Layanan Pindahan | EP-P01 | - | Ditunda; Pindahan dikirim `tersedia=false` |

Catatan: kolom lain pada tabel `kode_otp`, `kunci_idempotensi`, `kunci_penjadwal`, `webhook_pembayaran` mengikuti skrip SQL; nama kolom persisnya dipastikan saat implementasi, bukan dari ingatan.

### 3.2 Seed awal [Usulan]
`jenis_truk` (PUB, PBB, CDE, CDD; `biaya_driver` diisi 1 sebagai nilai awal dan ditandai belum ditetapkan, Bagian 1A no. 1), `jenis_bbm`, `master_truk`, `riwayat_harga_bbm` awal (asumsi Rp16.000 Pertamax dan Rp24.000 Dexlite; satuan masih asumsi OPN-19), `konfigurasi` (30 kunci pada Kontrak 6.3; nilai kosong tetap kosong), `tarif_penarikan` Rp5.000, dan satu baris untuk setiap dompet sistem (perusahaan_tertahan, perusahaan_pendapatan, perusahaan_operasional, kas_bank, piutang_gateway, transit_penarikan). Akun Direktur/Admin pertama dibuat lewat `bin/trukco` dengan kata sandi sementara dan `wajib_ganti_sandi=1`.

### 3.3 Aturan akses data
- Semua tindakan bisnis satu transaksi DB: status + jurnal + riwayat + audit + notifikasi (kegagalan satu bagian membatalkan seluruhnya).
- Kunci pesimistis `SELECT ... FOR UPDATE` pada baris pesanan dan pada baris driver saat penerimaan tawaran; dompet memakai kunci optimistis `dompet.versi` dengan percobaan ulang terbatas (3 kali) saat bentrok; urutan penguncian dompet menurut id menaik untuk mencegah deadlock [Usulan].
- Deteksi deadlock MySQL (kode 1213): ulangi transaksi maksimum 3 kali, lalu KESALAHAN_SERVER.

---

## 4. Autentikasi dan otorisasi

### 4.1 Token
| Aspek | Rancangan | Status |
| --- | --- | --- |
| Token akses | JWT; klaim: `sub` (pengguna_id), `rol`, `sid` (id sesi/perangkat), `iat`, `exp`, `jti`, `wgs` (wajib ganti sandi) | Usulan |
| Algoritma | HS256 dengan rahasia dari `.env` (`JWT_RAHASIA`, minimal 32 byte acak); ruang untuk `kid` agar rahasia dapat dirotasi | Usulan; algoritma: Tidak tahu |
| Umur token akses | Dapat diatur lewat `.env`; nilai awal usulan 15 menit | Tidak tahu (belum ditetapkan) |
| Token refresh | 32 byte acak (base64url), disimpan hanya sebagai hash SHA-256 pada `token_refresh`; umur nilai awal usulan 30 hari | Tidak tahu (umur) |
| Rotasi | EP-U06: token lama dicabut, baris baru dibuat, `digantikan_oleh_id` menautkan rantai | Fakta |
| Pemakaian ulang | Token yang sudah dirotasi dipakai lagi: seluruh rantai dicabut, jawab REFRESH_DIGUNAKAN_ULANG (401) | Fakta |
| Logout | EP-U07 mencabut token refresh sesi itu | Fakta |
| Pencabutan massal | Penonaktifan akun staf (EP-A33), reset sandi staf (EP-A34), ganti sandi (EP-U09) mencabut token refresh | Fakta (A33, A34); U09: Usulan |

### 4.2 Pendaftaran, OTP, sandi
- Pelanggan dan Driver (diputuskan, Bagian 1A no. 4): daftar dengan sandi, kontak diverifikasi dengan OTP; masuk dengan nomor HP + sandi (EP-U05). OTP hanya untuk verifikasi kontak: registrasi (EP-U02/U03/U04), ubah kontak (EP-U12/U13), dan pembuktian kepemilikan kontak pada lupa sandi (EP-U03/U04/U08). Apakah EP-U04 pada registrasi langsung menerbitkan token dicocokkan dengan spesifikasi EP-U04 saat implementasi. Karena masuk hanya dengan sandi, pembatasan percobaan login (Bagian 1A no. 8) diperketat dan sandi di-hash dengan ARGON2ID/BCRYPT.
- Admin dan Direktur: nomor/email + sandi, tanpa OTP (BR-006); sandi sementara memaksa ganti (WAJIB_GANTI_SANDI; hanya EP-U09 lolos).
- Hash sandi: `password_hash` dengan ARGON2ID bila tersedia, jika tidak BCRYPT; aturan kekuatan sandi belum ditetapkan (FR-002), sehingga SANDI_TIDAK_MEMENUHI_SYARAT memakai aturan awal usulan (panjang minimal 8, ada huruf dan angka) [Usulan].
- OTP: panjang 6 digit, kedaluwarsa 5 menit, maksimum 5 percobaan, jeda kirim ulang 60 detik: seluruhnya parameter `.env`, nilai awal Usulan; sumber menyatakan nilai ini belum ditetapkan. Kode OTP disimpan sebagai hash bila kolom mengizinkan. Galat: OTP_SALAH, OTP_KEDALUWARSA, OTP_BATAS_PERCOBAAN, OTP_TERLALU_SERING, OTP_KIRIM_GAGAL.
- Respons EP-U05 menyertakan `langkah_berikut` (S-01) yang diturunkan dari peran, status, dan status pendaftaran driver.
- Pesan KREDENSIAL_SALAH sengaja tidak menyebut mana yang salah; KONTAK_SUDAH_TERDAFTAR dan NIK_SUDAH_TERDAFTAR tidak merinci.

### 4.3 Otorisasi
- Metadata rute menetapkan peran; middleware menolak dengan AKSES_DITOLAK (403). Kepemilikan (pelanggan hanya pesanannya; driver hanya tawaran/pesanannya) diperiksa di Layanan dan dijawab TIDAK_DITEMUKAN.
- Aturan khusus [Fakta]: Direktur hanya baca pada konfigurasi; Admin tidak boleh memanggil endpoint Direktur (EP-R02/R03/R08) dan sebaliknya; nomor HP pihak lawan tidak pernah dikirim; rating hanya terlihat Admin; dokumen driver hanya dapat dibuka Admin dan pemilik.
- Status akun diperiksa pada setiap permintaan: AKUN_BELUM_AKTIF, AKUN_NONAKTIF, AKUN_DITANGGUHKAN, AKUN_DIBLOKIR; status driver: DRIVER_BELUM_DISETUJUI, DRIVER_DITANGGUHKAN, DOKUMEN_KEDALUWARSA; dompet: DOMPET_DIBEKUKAN.

---

## 5. Galat terdokumentasi

- **Sumber tunggal:** `config/galat.php` berisi 96 kode dari Kontrak 6.2: kode, HTTP, arti, dan kelompok. Pesan manusia berbahasa Indonesia ditulis di berkas yang sama.
- **Dokumentasi:** `php bin/trukco galat:dokumen` membangkitkan `docs/galat.md` (tabel kode, HTTP, arti, endpoint pemicu) dari `config/galat.php` dan metadata rute; dokumen dan kode tidak dapat berbeda.
- **Uji:** setiap kode pada katalog harus punya paling sedikit satu uji pemicu pada tahap tempat endpoint pemicunya dibangun; perintah `php bin/trukco cek:galat` gagal bila ada kode yang tidak dirujuk oleh satu pun rute atau uji.
- **Amplop:** `{"galat":{"kode":"...","pesan":"...","rincian":[{"bidang":"...","pesan":"..."}],"trace_id":"..."}}` + header X-Trace-Id; 429 menyertakan Retry-After [Usulan]. Klien memutuskan dari `kode`, bukan dari `pesan`.
- **Pembagian per tahap:** kode autentikasi, akun, berkas, validasi umum: Tahap 1; kode peta, top-up, gateway, driver/verifikasi: Tahap 2; kode pesanan, pembatalan, laporan, rating, sanksi, jadwal, chat: Tahap 3; kode penarikan, pencairan, setoran, rekonsiliasi, bukti: Tahap 4.

---

## 6. Idempotensi, transaksi, dan buku besar

### 6.1 Idempotency-Key (20 endpoint)
Daftar: EP-P05, P08, P09, P11, P18, P22, D11, D16, D17, D18, D19, A18, A24, A25, A26, A27, R02, R03, R04, R08.
- Tanpa header: VALIDASI_GAGAL (Usulan; Kontrak menyebut wajib tetapi tidak menyebut kodenya).
- Kunci baru: baris `kunci_idempotensi` status `proses` + hash isi permintaan (metode + path + badan kanonik); setelah selesai disimpan respons dan status `selesai`.
- Kunci sama + isi sama + selesai: respons tersimpan dikirim ulang tanpa mengulang akibat.
- Kunci sama + isi berbeda, atau yang pertama masih `proses`: IDEMPOTENSI_BENTROK (409).
- Lapis kedua pada buku besar: `jurnal_dompet.kunci_idempotensi` UNIQUE (contoh `bayar_dp:{id}`, `pelunasan:{id}`, `batal:{id}`, `tolak:{id}`, `penarikan:{id}`, `topup:{id}`, `finalisasi:{id}`), sehingga pengulangan internal (pekerjaan lazy, webhook ganda) tidak menggandakan uang.

### 6.2 Buku besar
- Dompet: pelanggan, driver, perusahaan_tertahan, perusahaan_pendapatan, perusahaan_operasional, kas_bank, piutang_gateway, transit_penarikan; saldo tidak boleh negatif (CHECK + pemeriksaan aplikasi).
- `jurnal_dompet` (header) + `entri_dompet` (baris debit/kredit, `saldo_setelah`); jurnal tidak boleh dihapus atau diubah; koreksi hanya lewat jurnal pembalik (`membalik_jurnal_id`).
- Satu komponen `BukuBesar::catat(jenis, kunci, entri[], konteks)` adalah satu-satunya pintu perubahan saldo. Komponen ini menolak jurnal yang debit-nya tidak sama dengan kredit-nya sebelum menulis apa pun.
- Jenis jurnal tetap mengikuti Kontrak 6.6 (topup, settlement_topup, bayar_dp, bayar_pelunasan, refund, dp_hangus, finalisasi, penarikan_pelanggan, pencairan_driver, penarikan_direktur, transfer_bank_berhasil, pembalik, setoran_dana, kompensasi) [Fakta; G-27].
- Invarian yang diperiksa oleh `php bin/trukco cek:invarian` (dari Simulasi, I-1 sampai I-11 [Fakta]): jurnal seimbang; saldo dompet = jumlah entri; saldo_setelah terakhir = saldo; tidak ada saldo negatif; kas_bank + piutang_gateway = jumlah dompet kewajiban; perusahaan_tertahan = DP + pelunasan pesanan yang belum final/batal; tidak ada bentrok jadwal pada pesanan terkunci satu driver; harga tiap pesanan cocok hitung ulang; transit_penarikan = 0 setelah semua penarikan diputuskan; kunci idempotensi jurnal unik.
- Pencatatan biaya gateway top-up: pada contoh Simulasi S07-e jurnal top-up hanya mencatat `nominal` (piutang_gateway debit, dompet pelanggan kredit); biaya gateway tidak dijurnal terpisah dan dibebankan di atas nominal kepada pelanggan. Rancangan mengikuti contoh itu. Selisih settlement yang sebenarnya dari Midtrans menjadi item rekonsiliasi (belum terverifikasi terhadap Midtrans; asumsi A-04).

---

## 7. Domain pesanan

### 7.1 Harga (EP-P04, EP-P05) [Fakta: Kontrak 2.8]
```
satuan   = ceil((jarak_jemput + jarak_antar) / 3)
biaya_bbm   = satuan x SOJ x harga_bbm_per_liter
biaya_admin = ceil(5% x biaya_bbm)
total       = biaya_bbm + biaya_driver + biaya_admin
dp          = ceil(50% x total);  pelunasan = total - dp
hak_driver  = biaya_bbm + biaya_driver
```
- Hitungan bilangan bulat saja: jarak diproses sebagai bilangan bulat dalam persepuluh km (1 desimal km → x10), SOJ x100, sehingga `ceil` memakai `intdiv`.
- Vektor uji wajib lulus: 12 km + 38 km, SOJ 2,45, Rp16.000, Biaya Driver Rp125.000 (uji): satuan 17, BBM 666.400, admin 33.320, total 824.720, DP 412.360, pelunasan 412.360, hak driver 791.400; Total 1.000.001 → DP 500.001, pelunasan 500.000.
- Aturan pembulatan `biaya_bbm` bila SOJ x harga x satuan tidak bulat tidak tertulis pada sumber (contoh sumber menghasilkan bilangan bulat). Diputuskan: dibulatkan ke atas, konsisten dengan komponen lain (Bagian 1A no. 9). Ini keputusan saya, bukan fakta dokumen.
- Biaya Driver kosong (CFG-08): dipakai nilai 1 (Bagian 1A no. 1) sehingga harga tetap terhitung; vektor uji memakai nilai uji Rp125.000 yang diberikan eksplisit. Harga dikunci saat pesanan dibuat (BR-014); HARGA_BERUBAH (409) bila total terhitung berbeda dari `total_disetujui`.

### 7.2 Status pesanan [Fakta: Kontrak 6.4]
13 status: menunggu_driver_dp, dp_terbayar, driver_tiba, menunggu_pelunasan, lunas, dalam_perjalanan, selesai, selesai_final, dibatalkan_sistem, ditolak, dibatalkan_pelanggan, dibatalkan_driver, pelanggan_tidak_melunasi. Penanda pembayaran (`dp_dibayar_at`, `lunas_at`, driver diterima) terpisah dari status. Perpindahan hanya lewat `MesinStatusPesanan` (tabel transisi yang diizinkan); tiap perpindahan menulis `riwayat_status_pesanan` dengan pelaku. `tahap_ui` diturunkan di server (K-12, Usulan).

### 7.3 Pencocokan dan penerimaan [Fakta]
- Saat pesanan dibuat: pilih acak 4 sampai 7 driver siap dalam 30 km jarak jalan (CFG-01, CFG-16), satu gelombang, notifikasi pesanan_baru; baris `penawaran_pesanan` per driver.
- Pra-saring driver siap dengan kotak pembatas dan jarak garis lurus dari `posisi_driver_terakhir`, lalu jarak jalan dari Google Maps hanya untuk kandidat; GPS usang (CFG-28) bukan siap.
- Terima (EP-D11): dalam satu transaksi: kunci baris driver, periksa bentrok jadwal (JADWAL_BENTROK), lalu `UPDATE pesanan SET driver_id=? WHERE id=? AND driver_id IS NULL`; baris terpengaruh 0 → PESANAN_SUDAH_DIAMBIL; penawaran lain menjadi `diambil_lain`.
- Pesanan terkunci setelah DP dibayar. Pelanggan tidak boleh punya pesanan lain yang jadwalnya tumpang tindih (PESANAN_BENTROK_PELANGGAN, Usulan).

### 7.4 Pembatalan [Fakta: Kontrak 2.8]
| Keadaan | Perlakuan |
| --- | --- |
| Sebelum DP dibayar | tanpa_biaya |
| DP dibayar, belum ada driver | refund_penuh (100% DP) |
| Lebih dari 4 jam sebelum jemput (tepat 4 jam 00 menit dihitung lebih dari 4 jam) | refund_30: refund = ceil(30% DP); sisa dibagi driver 30% (dibulatkan ke bawah) dan SAVAR sisanya |
| Kurang dari 4 jam | hangus: driver floor(30% DP), SAVAR sisanya |
| Pelunasan sudah dibayar | dikembalikan 100% |
| Driver membatalkan | refund 100% + pelanggaran tercatat |
| Setelah dalam_perjalanan | pelanggan tidak boleh batal (PEMBATALAN_TIDAK_DIIZINKAN); jalur laporan |

Uji angka: DP 412.360 → refund 123.708, driver 86.595, SAVAR 202.057; bila hangus: driver 123.708, SAVAR 288.652. Jumlah pembagian harus sama dengan DP. EP-P10 (pratinjau) dan EP-P11 (eksekusi) memakai satu kelas `KebijakanPembatalan`; KEBIJAKAN_BERUBAH (409) bila batas 4 jam terlewati antara pratinjau dan eksekusi.

### 7.5 Finalisasi, laporan, rating, sanksi [Fakta]
- Selesai → masa tunggu 48 jam (CFG-17) → finalisasi lazy: Hak Driver ke dompet driver, sisa ke perusahaan_pendapatan, rating dibuka; laporan terbuka yang menahan finalisasi menunda proses.
- Laporan dan keputusan: pelanggan_tidak_melunasi dibenarkan → DP hangus (driver 30%, SAVAR sisa); driver_tidak_datang dibenarkan → dibatalkan_driver + refund 100% DP dan pelunasan; kompensasi dibayar dari perusahaan_operasional hanya ke pelanggan pelapor dan tidak boleh membuat saldo negatif (DANA_OPERASIONAL_KURANG).
- Sanksi: peringatan_1, peringatan_2, lalu suspend pada pelanggaran ketiga (BR-064); lama suspend 14 hari (CFG-22; Simulasi memakai 7 hari sebagai asumsi, tidak dipakai).

---

## 8. Evaluasi lazy (tanpa cron)

Penjadwal dipicu oleh EP-U24 (`/sinkron`), endpoint detail pesanan (EP-P07, EP-D15), dan pembacaan antrean tawaran (EP-D10). Setiap pekerjaan merebut kunci di `kunci_penjadwal` dengan satu `UPDATE ... WHERE nama_pekerjaan=? AND (dikunci_sampai IS NULL OR dikunci_sampai < NOW())`; hanya proses yang `affected_rows=1` yang menjalankan pekerjaan, mencatat `terakhir_jalan_at` dan selisih keterlambatan (`terlambat_maks_menit`). Tiap pekerjaan dibatasi jumlah barisnya per putaran dan dilanjutkan pada permintaan berikutnya.

| Pekerjaan | Tahap mulai | Kunci jurnal | Keterangan |
| --- | --- | --- | --- |
| bersihkan_registrasi_otp | 1 | bersih_otp:{tanggal} | Batas waktu: Tidak tahu; parameter `.env` |
| cek_dokumen_driver | 2 | dokumen:{id}:{tanggal} | Dokumen lewat berlaku_sampai → kedaluwarsa, driver Offline |
| kedaluwarsakan_topup | 2 | - | Top-up `menunggu` melewati CFG-27 → `kedaluwarsa` (tidak ada pada tabel 6.7; Usulan) |
| impor_settlement | 2 | settlement:{ref} | CFG-30; sumber data settlement: Tidak tahu (impor manual atau API Midtrans) |
| batalkan_dp_kedaluwarsa | 3 | dp_batas:{pesanan_id} | DP 60 menit |
| tolak_pesanan_timeout | 3 | tolak_timeout:{pesanan_id} | 120 menit tanpa driver |
| finalisasi_pesanan | 3 | finalisasi:{pesanan_id} | 48 jam |
| pulihkan_suspend | 3 | suspend:{id} | Syarat pemulihan: Tidak tahu (OPN-09) |
| rekonsiliasi_harian | 4 | rekon:{tanggal} | Dibuat otomatis bila Admin belum menjalankan |

Cadangan opsional [Usulan]: `php bin/trukco jalankan:pekerjaan` menjalankan kelas pekerjaan yang sama dari cron eksternal bila kelak pemilik produk menghendaki ketepatan waktu; tidak diwajibkan.

---

## 9. Integrasi pihak ketiga

Seluruh integrasi berada di balik antarmuka sehingga dapat diganti dan diuji dengan adapter palsu. Kunci dan rahasia hanya dari `.env`, tidak pernah dikirim ke klien dan tidak masuk log.

### 9.1 Midtrans (top-up)
Alur [rancangan; format pesan dari pengetahuan saya, belum terverifikasi dengan dokumentasi resmi]:
1. **EP-P18** (Idempotency-Key): validasi nominal (CFG-20 min/maks; kosong → PARAMETER_BELUM_DITETAPKAN), hitung `biaya_gateway` (CFG-25) dan `total_bayar = nominal + biaya_gateway`, buat baris `topup` status `menunggu` dengan `order_id_gateway` unik dan `kedaluwarsa_at` (CFG-27), panggil Midtrans Snap (server key, Basic Auth, `order_id`, `gross_amount = total_bayar`, masa kedaluwarsa) dan simpan `token_snap`/`url_pembayaran` (G-28). Kegagalan pemanggilan: GATEWAY_GAGAL (502) dan baris top-up tidak dibiarkan `menunggu`.
2. **EP-W01** (tanpa JWT): baca badan mentah; verifikasi tanda tangan; hitung `kunci_dedup = hash(order_id, status, gross_amount, keabsahan)`; sisipkan ke `webhook_pembayaran` (jika sudah ada: hanya naikkan `jumlah_diterima` dan `diterima_terakhir_at`, tanpa jurnal baru, jawab 200). Tanda tangan tidak sah: catat `tidak_valid`, saldo tidak berubah, jawab TANDA_TANGAN_TIDAK_SAH. `gross_amount` harus sama dengan `topup.total_bayar` (bandingkan numerik; format string Midtrans belum terverifikasi). Status berhasil: jurnal `topup:{id}`, `topup.status=berhasil`, `dibayar_at`, notifikasi push; status gagal/kedaluwarsa hanya memperbarui `topup.status`.
3. **Cara verifikasi tanda tangan** (belum terverifikasi): SHA-512 dari penggabungan order_id + status_code + gross_amount + server key, dibandingkan dengan `signature_key` memakai `hash_equals`. Lapis pengaman tambahan [Usulan]: konfirmasi status ke API status Midtrans sebelum membukukan.
4. **EP-P20/EP-P21:** detail menampilkan tautan bayar yang tersimpan; pembatalan memanggil API pembatalan Midtrans (belum terverifikasi) lalu status `dibatalkan`.
5. Lingkungan sandbox/produksi dipilih dari `.env`; URL webhook didaftarkan tim backend pada dasbor Midtrans.

### 9.2 Google Maps
- **EP-P02** pencarian tempat, **EP-P03** geocoding balik, jarak/durasi jalan untuk EP-P04 dan pencocokan: seluruhnya dari server. Pilihan API yang tepat (Places, Geocoding, Routes/Distance Matrix) belum saya verifikasi; antarmuka `PetaKlien` memisahkan pilihan itu.
- `dalam_wilayah` (BR-001: Jawa, Bali, Sumatera) ditentukan dari komponen wilayah administratif hasil geocoding terhadap daftar provinsi pada konfigurasi [Usulan]; di luar wilayah → LOKASI_DI_LUAR_WILAYAH.
- Galat: RUTE_TIDAK_DITEMUKAN (422), LAYANAN_PETA_GAGAL (502), JARAK_MELEBIHI_BATAS (>1000 km, CFG-02), TIDAK_ADA_TRUK_TERSEDIA.
- Cache jawaban jarak berumur pendek pada `storage/cache` untuk menekan biaya [Usulan]. Waktu tunggu pendek (mis. 5 detik) dan satu percobaan ulang.

### 9.3 FCM
- Token perangkat dari EP-U14/U15 pada `perangkat_fcm` (G-03). Pengiriman memakai FCM HTTP v1 dengan token OAuth2 akun layanan (JWT bertanda RS256 ditukar ke token akses, di-cache) [belum terverifikasi].
- Push dikumpulkan selama transaksi dan dikirim **setelah commit dan setelah respons dikirim**; kegagalan hanya dicatat di log, tidak membatalkan bisnis (Fakta). Token tidak terdaftar dibersihkan (`dicabut_at`). Baris `notifikasi` tetap menjadi sumber kebenaran sehingga polling (EP-U20, U21, U24) bekerja walau push gagal.
- Jenis notifikasi mengikuti katalog Kontrak 6.5 (24 jenis).

### 9.4 Pengirim OTP dan payout
- **PengirimOtp** (SMS, email): penyedia **[Tidak tahu]**. Dibangun antarmuka + adapter `log` (pengembangan, OTP ke berkas log) + adapter penyedia setelah dipilih. OTP tidak pernah dikembalikan pada respons API.
- **PayoutKlien** (penarikan pelanggan EP-P22, J15): penyedia dan dukungan bank **[Tidak tahu]** (INT-002, G-14); status J16/OPN-11 (dompet lewat mitra berlisensi) **[Tidak tahu]**. Dibangun antarmuka + adapter manual: penarikan berstatus `diproses` lalu diselesaikan Admin lewat EP-A26 dengan bukti mutasi, sampai penyedia ditetapkan.

### 9.5 Penyimpanan berkas
EP-U25 menerima unggahan ke `storage/berkas` (di luar `public`), nama acak, validasi MIME dengan `finfo` + daftar ekstensi, token sementara berumur pendek; EP-U26 mengalirkan berkas setelah pemeriksaan peran/kepemilikan; pembukaan oleh Admin dicatat ke `log_audit`. Batas ukuran **[Tidak tahu]** (BERKAS_TERLALU_BESAR): parameter `.env`; BERKAS_TIDAK_VALID untuk isi tidak sah.

---

## 10. Keamanan dan privasi [Fakta kecuali ditandai]

- NIK: dienkripsi (AES-256-GCM via openssl, kunci dari `.env`, awalan id kunci) pada kolom VARBINARY + hash HMAC-SHA256 berkunci terpisah untuk pencarian unik dan daftar hitam; tampilan selalu tersamar (BR-030). Algoritma enkripsi: Usulan.
- Nomor rekening: dienkripsi + empat digit terakhir; nama pemilik dicocokkan dengan nama akun (REKENING_NAMA_TIDAK_COCOK).
- Nomor HP lawan bicara tidak pernah dikirim; rating hanya Admin; chat hanya baca oleh Admin.
- Pembatas laju per IP dan per akun, lebih ketat untuk OTP dan login; TERLALU_BANYAK_PERMINTAAN + Retry-After.
- Header respons aman (X-Content-Type-Options, Cache-Control: no-store untuk respons berisi data pribadi/uang), CORS dibatasi lewat `.env` [Usulan].
- `log_audit` untuk setiap tindakan Admin/Direktur yang mengubah data atau uang (BR-004), ditulis dalam transaksi yang sama; tidak ada endpoint yang mengubah atau menghapusnya.
- Retensi pelacakan dan chat 10 tahun (CFG-23): tidak ada penghapusan otomatis pada rancangan.
- Penghapusan akun: EP-U16 ditolak AKUN_MASIH_BERSALDO bila saldo lebih dari Rp0 (BR-070).

---

## 11. Konfigurasi, observabilitas, pengemasan

- `.env.example`: DB_*, APP_ENV, JWT_RAHASIA, umur token, parameter OTP, kunci enkripsi NIK/rekening, MIDTRANS_*, GOOGLE_MAPS_KEY, FCM_PROYEK + kredensial akun layanan, CORS, batas berkas.
- Parameter bisnis dibaca dari tabel `konfigurasi` (30 kunci) dengan cache per permintaan; nilai kosong memakai nilai awal dari `config/parameter.php` (Bagian 1A no. 6) dan ditandai `belum_ditetapkan` pada EP-A06; PARAMETER_BELUM_DITETAPKAN (menyebut kode CFG-xx) hanya untuk kunci tanpa nilai awal.
- Log JSON baris per permintaan (trace_id, rute, status, durasi) tanpa rahasia dan tanpa data pribadi mentah.
- Pengemasan: ZIP berisi struktur Bagian 2.1 tanpa UI; README memuat langkah `php bin/trukco migrasi`, `php bin/trukco seed`, `php -S 127.0.0.1:8000 -t public`, dan contoh pemanggilan `curl`.

---

## 12. Strategi pengujian

| Lapis | Isi |
| --- | --- |
| Unit | Harga (vektor Bagian 7.1), kebijakan pembatalan (Bagian 7.4), mesin status, validator, JWT, hash/enkripsi |
| Kontrak HTTP | Server bawaan PHP + `curl`: setiap endpoint: bentuk respons sama dengan Kontrak bab 5, setiap galat khusus dapat dipicu dengan HTTP dan kode benar, setiap peran yang ditolak mendapat AKSES_DITOLAK |
| Idempotensi | Tiga skenario per 20 endpoint: kunci sama isi sama, kunci sama isi beda, permintaan serentak |
| Uang | Setiap perubahan uang menghasilkan jurnal seimbang; tidak ada saldo negatif; `cek:invarian` I-1 sampai I-11 lulus setelah setiap rangkaian uji |
| Konkurensi | Dua driver menerima tawaran bersamaan (satu menang); dua pembayaran DP bersamaan; webhook ganda |
| Integrasi | Adapter palsu Midtrans/Maps/FCM/OTP/payout; uji tanda tangan sah dan tidak sah |
| Audit | Setiap tindakan staf mengubah data/uang tercatat di `log_audit` |
| Kelengkapan | `php bin/trukco cek:rute` = 138 rute; `cek:galat` = tiap kode terpakai |

Skrip bantu analisis di luar PHP (bila ada) dijalankan dengan `python3 <berkas>`.

---

## 13. Empat tahap

Urutan mengikuti ketergantungan data: identitas dan referensi dulu, lalu driver dan uang masuk, lalu seluruh alur pesanan, terakhir uang keluar, rekonsiliasi, dan Direktur. Kontrak menyarankan 10 langkah (Bagian 10.1); rancangan ini menggabungkannya menjadi 4 tahap tanpa mengubah urutan ketergantungannya.

### Tahap 1. Fondasi, identitas, dan data referensi (41 endpoint)

**Tujuan:** kerangka berjalan, akun dapat mendaftar/masuk/keluar, token berfungsi, data master dan konfigurasi tersedia, jejak audit dan berkas siap.

**Dibangun**
- Inti framework (Bagian 2), Migrator, seed, CLI `bin/trukco`, `cek:rute`, `galat:dokumen`.
- Katalog galat penuh (96 kode) + amplop + X-Trace-Id + penangan global.
- Middleware: TraceId, Pemeliharaan, PembatasLaju, Autentikasi, StatusAkun, WajibGantiSandi, Peran, Idempotensi (mekanisme umum).
- Auth penuh (Bagian 4), OTP (adapter log), akun, perangkat FCM (tersimpan), rekening bank, penghapusan akun, notifikasi (baca/tandai), `/sinkron` (penjadwal lazy dengan pekerjaan `bersihkan_registrasi_otp`), berkas sementara dan akses berkas, master (jenis truk, model truk, bank), bantuan (isi dinamis, boleh kosong).
- Konfigurasi, harga BBM, Biaya Driver, riwayat konfigurasi dari `log_audit`; manajemen akun staf dan jejak audit.
- Pembuatan dompet pengguna dan seed dompet sistem; `BukuBesar` kerangka (belum dipakai transaksi).

**Migrasi:** 0000 baseline, G-02, G-03, G-04/G-22, G-12, G-13 (seed), G-14, T-01, T-02.

**Endpoint:** EP-U01 sampai EP-U30 (30), EP-A06, A07, A08, A09, A15, A36 (6), EP-A31 sampai A35 (5).

**Kriteria selesai:** 41 rute terdaftar dan lolos uji kontrak; rotasi dan pemakaian ulang token teruji; WAJIB_GANTI_SANDI hanya melepas EP-U09; seluruh kode galat Tahap 1 dapat dipicu; `docs/galat.md` terbangkitkan.

**Keputusan:** seluruhnya sudah diambil (Bagian 1A no. 4, 5, 7, 8, 13, 15). Sisa yang tidak dapat saya putuskan: penyedia SMS/email OTP; selama belum ada, OTP dikirim lewat adapter `log` sehingga pembangunan dan pengujian tidak berhenti.

### Tahap 2. Driver, peta, dompet, dan top-up Midtrans (27 endpoint)

**Tujuan:** driver dapat mendaftar dan diverifikasi; pelanggan dapat mencari lokasi dan mengisi dompet lewat Midtrans; uang masuk tercatat benar.

**Dibangun**
- Pendaftaran driver, dokumen (sembilan jenis), ronde pengajuan, status, online/offline, posisi terakhir; antrean verifikasi Admin, keputusan (setuju/tolak/perbaikan/tahan/blokir + daftar hitam), koreksi model, daftar driver, peta sebaran; pekerjaan `cek_dokumen_driver`.
- `PetaKlien` (pencarian, balik, jarak) dan layanan; `GET /layanan`.
- `BukuBesar` aktif untuk top-up; dompet, mutasi, pratinjau biaya, top-up (buat/daftar/detail/batal), `MidtransKlien`, webhook EP-W01 dengan tanda tangan + dedup; pekerjaan `kedaluwarsakan_topup` dan `impor_settlement`.

**Migrasi:** G-28; G-15 tanpa perubahan SQL.

**Endpoint:** EP-D01 sampai D09 (9) dan EP-D23 (1); EP-A01 sampai A05 (5) dan EP-A10 (1); EP-P01 sampai P03 (3); EP-P15 sampai P21 (7); EP-W01 (1).

**Kriteria selesai:** 27 rute teruji; webhook valid, ganda, dan palsu menghasilkan 1 jurnal / 0 jurnal tambahan / 0 jurnal; invarian I-1 sampai I-5 lulus; keputusan verifikasi menulis `verifikasi_driver`, `log_audit`, notifikasi dalam satu transaksi.

**Keputusan:** parameter CFG memakai nilai awal (Bagian 1A no. 6) dan settlement memakai aturan T+1 (no. 16). Sisa yang tidak dapat saya putuskan: kunci Midtrans sandbox dan kunci Google Maps (rahasia akun Anda; diisi pada `.env`); pengujian di sandbox memerlukan kunci itu, sedangkan pengujian lain berjalan dengan adapter palsu. Format pesan Midtrans/Maps dicocokkan dengan dokumentasi resmi pada awal tahap ini.

### Tahap 3. Alur pesanan penuh (43 endpoint)

**Tujuan:** satu pesanan dapat berjalan dari estimasi sampai finalisasi, termasuk pembatalan, chat, posisi, laporan, rating, dan sanksi.

**Dibangun**
- Estimasi harga per jenis truk, pembuatan pesanan (kunci harga, kode_publik), daftar dan detail, salinan pesanan; pencocokan 4 sampai 7 driver; tawaran, terima/tolak atomik; bayar DP, tiba, bayar pelunasan, berangkat, selesai; pembatalan pelanggan dan driver dengan pratinjau; lapor pelanggan tidak melunasi; posisi truk; chat; keberatan; rating; laporan pelanggan/driver dan keputusan Admin (termasuk kompensasi); sanksi dan pencabutan; rute, chat, rating untuk Admin; laporan kinerja driver; daftar dan detail pesanan staf.
- `Harga`, `MesinStatusPesanan`, `KebijakanPembatalan`, `Pencocokan`; pekerjaan lazy `batalkan_dp_kedaluwarsa`, `tolak_pesanan_timeout`, `finalisasi_pesanan`, `pulihkan_suspend`.

**Migrasi:** G-07, G-06, G-23, G-24/G-25 sesuai keputusan.

**Endpoint:** EP-P04 sampai P14 (11); EP-D10 sampai D21 (12: D10, D11, D12, D13, D14, D15, D16, D17, D18, D19, D20, D21); EP-U31 sampai U37 (7); EP-A11 sampai A14 (4) dan EP-A16 sampai A22 (7); EP-S01, S02 (2).

**Kriteria selesai:** vektor harga dan pembatalan lulus; hanya satu driver menang pada penerimaan serentak; semua jurnal seimbang; invarian I-1 sampai I-5, I-7 sampai I-9, I-11 lulus; setiap transisi status tercatat; uji lazy: pekerjaan berulang tidak menggandakan jurnal.

**Keputusan:** tidak ada yang memblokir. Biaya Driver memakai nilai 1 bila kosong (Bagian 1A no. 1); pembulatan, kode pesanan, suspend, kompensasi, Pindahan/Fuso sudah diputuskan (no. 9 sampai 12, 14). Hal klien yang tetap di luar backend: tampilan rating, telepon, foto driver (KP-04) mengikuti PRD, yaitu tidak dikirim.

### Tahap 4. Uang keluar, rekonsiliasi, laporan, dan Direktur (27 endpoint)

**Tujuan:** penarikan pelanggan, pencairan driver dengan persetujuan kedua, setoran dana, penarikan Direktur, rekonsiliasi harian, dan laporan staf; pengerasan akhir.

**Dibangun**
- `PayoutKlien` (adapter manual), penarikan pelanggan (biaya Rp5.000), pencairan driver (diajukan Admin, disetujui Direktur, konfirmasi transfer, penyelesaian `perlu_cek` dengan bukti mutasi), setoran dana (diusulkan Admin, diputuskan Direktur), penarikan Direktur, rekening perusahaan.
- Rekonsiliasi (manual dan lazy), item selisih, laporan keuangan, pesanan, mutasi, dompet perusahaan, beranda Direktur.
- Pengerasan: tinjauan keamanan, uji beban ringan, `cek:invarian` penuh I-1 sampai I-11, `cek:rute` = 138, `cek:galat` tanpa kode yatim, README dan paket ZIP akhir.

**Migrasi:** G-05, G-26; G-17 dan G-21 tanpa perubahan SQL.

**Endpoint:** EP-P22 sampai P24 (3); EP-D22 (1); EP-A23 sampai A30 (8); EP-S03 sampai S09 (7); EP-R01 sampai R08 (8).

**Kriteria selesai:** penarikan gagal dibalik dengan jurnal pembalik; `transit_penarikan` kembali nol setelah semua diputuskan; pengaju dan penyetuju pencairan berbeda; kompensasi dan pencairan tidak membuat saldo negatif; laporan keuangan sama dengan jumlah `entri_dompet` periode itu.

**Keputusan:** tidak ada yang memblokir. Penyetuju kedua = Direktur (no. 2); payout manual lewat Admin (no. 3); CFG-26 memakai nilai awal (no. 6); `saldo_bank` rekonsiliasi diisi manual oleh Admin menurut Kontrak; G-05 dan G-26 disetujui (no. 5). Hal hukum mengenai mitra dompet berlisensi (OPN-11) tetap berada di luar keputusan teknis ini dan perlu dinilai penasihat hukum Anda; saya tidak tahu hasilnya.

### Ringkasan hitungan

| Tahap | EP-U | EP-W | EP-P | EP-D | EP-A | EP-S | EP-R | Jumlah |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| 1 | 30 | 0 | 0 | 0 | 11 | 0 | 0 | 41 |
| 2 | 0 | 1 | 10 | 10 | 6 | 0 | 0 | 27 |
| 3 | 7 | 0 | 11 | 12 | 11 | 2 | 0 | 43 |
| 4 | 0 | 0 | 3 | 1 | 8 | 7 | 8 | 27 |
| Jumlah | 37 | 1 | 24 | 23 | 36 | 9 | 8 | 138 |

Cocok dengan target Anda: 37 + 1 + 24 + 23 + 36 + 9 + 8 = 138. Tabel di Bagian 14 dibangkitkan oleh skrip dari matriks Kontrak 3.3 dan diperiksa bahwa setiap ID muncul tepat satu kali.

---

## 14. Keterlacakan 138 endpoint

Kolom Idem = Idempotency-Key wajib. Tahap = tahap pembangunan.

| ID | Metode | Path | Peran | Idem | Tahap | Catatan |
| --- | --- | --- | --- | --- | --- | --- |
| EP-U01 | GET | /api/v1/sistem/info | Publik | - | 1 |  |
| EP-U02 | POST | /api/v1/auth/registrasi | Publik | - | 1 |  |
| EP-U03 | POST | /api/v1/auth/otp/kirim | Publik | - | 1 | OTP; tujuan reset_sandi butuh G-02 |
| EP-U04 | POST | /api/v1/auth/otp/verifikasi | Publik | - | 1 | OTP; terbitkan token |
| EP-U05 | POST | /api/v1/auth/login | Publik | - | 1 |  |
| EP-U06 | POST | /api/v1/auth/token/refresh | Publik | - | 1 | Rotasi refresh; REFRESH_DIGUNAKAN_ULANG |
| EP-U07 | POST | /api/v1/auth/logout | Pelanggan, Driver, Admin, Direktur | - | 1 |  |
| EP-U08 | POST | /api/v1/auth/sandi/reset | Publik | - | 1 |  |
| EP-U09 | POST | /api/v1/auth/sandi/ganti | Pelanggan, Driver, Admin, Direktur | - | 1 | Satu-satunya yang lolos WAJIB_GANTI_SANDI |
| EP-U10 | GET | /api/v1/akun/saya | Pelanggan, Driver, Admin, Direktur | - | 1 |  |
| EP-U11 | PATCH | /api/v1/akun/saya | Pelanggan, Driver, Admin, Direktur | - | 1 |  |
| EP-U12 | POST | /api/v1/akun/kontak/otp | Pelanggan, Driver | - | 1 |  |
| EP-U13 | POST | /api/v1/akun/kontak/verifikasi | Pelanggan, Driver | - | 1 |  |
| EP-U14 | POST | /api/v1/akun/perangkat | Pelanggan, Driver, Admin, Direktur | - | 1 | Simpan token FCM (G-03) |
| EP-U15 | DELETE | /api/v1/akun/perangkat/{perangkat_id} | Pelanggan, Driver, Admin, Direktur | - | 1 | Cabut token FCM (G-03) |
| EP-U16 | POST | /api/v1/akun/hapus | Pelanggan, Driver | - | 1 |  |
| EP-U17 | GET | /api/v1/akun/rekening | Pelanggan, Driver | - | 1 |  |
| EP-U18 | POST | /api/v1/akun/rekening | Pelanggan, Driver | - | 1 |  |
| EP-U19 | DELETE | /api/v1/akun/rekening/{id} | Pelanggan, Driver | - | 1 |  |
| EP-U20 | GET | /api/v1/notifikasi | Pelanggan, Driver, Admin, Direktur | - | 1 | Butuh G-04, G-22 |
| EP-U21 | GET | /api/v1/notifikasi/ringkasan | Pelanggan, Driver, Admin, Direktur | - | 1 | Butuh G-04, G-22 |
| EP-U22 | POST | /api/v1/notifikasi/{id}/baca | Pelanggan, Driver, Admin, Direktur | - | 1 |  |
| EP-U23 | POST | /api/v1/notifikasi/baca-semua | Pelanggan, Driver, Admin, Direktur | - | 1 |  |
| EP-U24 | GET | /api/v1/sinkron | Pelanggan, Driver, Admin, Direktur | - | 1 | Pemicu penjadwal lazy |
| EP-U25 | POST | /api/v1/berkas/sementara | Pelanggan, Driver, Admin, Direktur | - | 1 | Tabel berkas_sementara (T-01) |
| EP-U26 | GET | /api/v1/berkas/{tipe}/{id} | Pelanggan, Driver, Admin, Direktur | - | 1 | Akses Admin diaudit |
| EP-U27 | GET | /api/v1/master/jenis-truk | Pelanggan, Driver, Admin, Direktur | - | 1 |  |
| EP-U28 | GET | /api/v1/master/model-truk | Driver, Admin, Direktur | - | 1 |  |
| EP-U29 | GET | /api/v1/master/bank | Pelanggan, Driver, Admin | - | 1 | Butuh master_bank (G-14) |
| EP-U30 | GET | /api/v1/bantuan | Pelanggan, Driver, Admin, Direktur | - | 1 | Isi belum diketahui (K-17) |
| EP-U31 | GET | /api/v1/pesanan/{kode}/chat | Pelanggan, Driver | - | 3 |  |
| EP-U32 | POST | /api/v1/pesanan/{kode}/chat | Pelanggan, Driver | - | 3 |  |
| EP-U33 | POST | /api/v1/pesanan/{kode}/chat/dibaca | Pelanggan, Driver | - | 3 |  |
| EP-U34 | POST | /api/v1/pesanan/{kode}/rating | Pelanggan, Driver | - | 3 |  |
| EP-U35 | POST | /api/v1/pesanan/{kode}/laporan | Pelanggan, Driver | - | 3 |  |
| EP-U36 | GET | /api/v1/laporan | Pelanggan, Driver | - | 3 |  |
| EP-U37 | GET | /api/v1/laporan/{kode} | Pelanggan, Driver | - | 3 |  |
| EP-W01 | POST | /api/v1/webhook/midtrans | Webhook | - | 2 | Tanpa JWT; tanda tangan + dedup; jurnal topup:{id} |
| EP-P01 | GET | /api/v1/layanan | Pelanggan | - | 2 | Pindahan tersedia=false (K-05) |
| EP-P02 | GET | /api/v1/lokasi/cari | Pelanggan, Driver | - | 2 | Google Maps (server) |
| EP-P03 | GET | /api/v1/lokasi/balik | Pelanggan, Driver | - | 2 | Google Maps (server) |
| EP-P04 | POST | /api/v1/pesanan/estimasi | Pelanggan | - | 3 | Harga; butuh CFG-08 |
| EP-P05 | POST | /api/v1/pesanan | Pelanggan | Ya | 3 | Kunci harga; HARGA_BERUBAH; kode_publik |
| EP-P06 | GET | /api/v1/pesanan | Pelanggan | - | 3 |  |
| EP-P07 | GET | /api/v1/pesanan/{kode} | Pelanggan | - | 3 |  |
| EP-P08 | POST | /api/v1/pesanan/{kode}/bayar-dp | Pelanggan | Ya | 3 | Jurnal bayar_dp |
| EP-P09 | POST | /api/v1/pesanan/{kode}/bayar-pelunasan | Pelanggan | Ya | 3 | Jurnal bayar_pelunasan |
| EP-P10 | GET | /api/v1/pesanan/{kode}/pratinjau-batal | Pelanggan | - | 3 | Pratinjau kebijakan batal |
| EP-P11 | POST | /api/v1/pesanan/{kode}/batal | Pelanggan | Ya | 3 | Jurnal refund/dp_hangus |
| EP-P12 | GET | /api/v1/pesanan/{kode}/posisi | Pelanggan | - | 3 |  |
| EP-P13 | POST | /api/v1/pesanan/{kode}/keberatan | Pelanggan | - | 3 |  |
| EP-P14 | GET | /api/v1/pesanan/{kode}/salinan | Pelanggan | - | 3 |  |
| EP-P15 | GET | /api/v1/dompet | Pelanggan, Driver | - | 2 |  |
| EP-P16 | GET | /api/v1/dompet/mutasi | Pelanggan, Driver | - | 2 |  |
| EP-P17 | GET | /api/v1/dompet/pratinjau-biaya | Pelanggan | - | 2 |  |
| EP-P18 | POST | /api/v1/dompet/topup | Pelanggan | Ya | 2 | Midtrans Snap; G-28 |
| EP-P19 | GET | /api/v1/dompet/topup | Pelanggan | - | 2 |  |
| EP-P20 | GET | /api/v1/dompet/topup/{kode} | Pelanggan | - | 2 |  |
| EP-P21 | POST | /api/v1/dompet/topup/{kode}/batal | Pelanggan | - | 2 |  |
| EP-P22 | POST | /api/v1/dompet/penarikan | Pelanggan | Ya | 4 | Payout (adapter manual); biaya Rp5.000 |
| EP-P23 | GET | /api/v1/dompet/penarikan | Pelanggan | - | 4 |  |
| EP-P24 | GET | /api/v1/dompet/penarikan/{kode} | Pelanggan | - | 4 |  |
| EP-D01 | POST | /api/v1/driver/pendaftaran | Driver | - | 2 |  |
| EP-D02 | GET | /api/v1/driver/pendaftaran | Driver | - | 2 |  |
| EP-D03 | PUT | /api/v1/driver/pendaftaran | Driver | - | 2 |  |
| EP-D04 | POST | /api/v1/driver/pendaftaran/ulang | Driver | - | 2 |  |
| EP-D05 | PATCH | /api/v1/driver/truk | Driver | - | 2 |  |
| EP-D06 | PUT | /api/v1/driver/dokumen/{jenis} | Driver | - | 2 |  |
| EP-D07 | GET | /api/v1/driver/status | Driver | - | 2 |  |
| EP-D08 | PUT | /api/v1/driver/online | Driver | - | 2 |  |
| EP-D09 | POST | /api/v1/driver/posisi | Driver | - | 2 |  |
| EP-D10 | GET | /api/v1/driver/tawaran | Driver | - | 3 |  |
| EP-D20 | GET | /api/v1/driver/tawaran/{kode} | Driver | - | 3 |  |
| EP-D11 | POST | /api/v1/driver/tawaran/{kode}/terima | Driver | Ya | 3 | Penerimaan atomik; JADWAL_BENTROK |
| EP-D12 | POST | /api/v1/driver/tawaran/{kode}/tolak | Driver | - | 3 |  |
| EP-D13 | POST | /api/v1/driver/pesanan/{kode}/lapor-tidak-lunas | Driver | - | 3 |  |
| EP-D14 | GET | /api/v1/driver/pesanan | Driver | - | 3 |  |
| EP-D15 | GET | /api/v1/driver/pesanan/{kode} | Driver | - | 3 |  |
| EP-D16 | POST | /api/v1/driver/pesanan/{kode}/tiba | Driver | Ya | 3 |  |
| EP-D17 | POST | /api/v1/driver/pesanan/{kode}/berangkat | Driver | Ya | 3 |  |
| EP-D18 | POST | /api/v1/driver/pesanan/{kode}/selesai | Driver | Ya | 3 |  |
| EP-D19 | POST | /api/v1/driver/pesanan/{kode}/batal | Driver | Ya | 3 | Refund 100% + pelanggaran |
| EP-D21 | GET | /api/v1/driver/sanksi | Driver | - | 3 |  |
| EP-D22 | GET | /api/v1/driver/pencairan | Driver | - | 4 |  |
| EP-D23 | GET | /api/v1/driver/dokumen | Driver | - | 2 |  |
| EP-A01 | GET | /api/v1/admin/driver/verifikasi | Admin | - | 2 |  |
| EP-A02 | GET | /api/v1/admin/driver/{id} | Admin | - | 2 |  |
| EP-A03 | POST | /api/v1/admin/driver/{id}/keputusan | Admin | - | 2 | Blokir mengisi daftar_hitam |
| EP-A04 | PATCH | /api/v1/admin/driver/{id}/model | Admin | - | 2 |  |
| EP-A05 | GET | /api/v1/admin/driver | Admin | - | 2 |  |
| EP-A06 | GET | /api/v1/admin/konfigurasi | Admin, Direktur | - | 1 |  |
| EP-A07 | PUT | /api/v1/admin/konfigurasi/{kunci} | Admin | - | 1 | Audit nilai lama/baru |
| EP-A08 | GET | /api/v1/admin/harga-bbm | Admin | - | 1 |  |
| EP-A09 | POST | /api/v1/admin/harga-bbm | Admin | - | 1 |  |
| EP-A15 | PUT | /api/v1/admin/jenis-truk/{kode}/biaya-driver | Admin | - | 1 | CFG-08 |
| EP-A10 | GET | /api/v1/admin/peta-driver | Admin | - | 2 |  |
| EP-A11 | GET | /api/v1/admin/pesanan/{kode}/rute | Admin | - | 3 |  |
| EP-A12 | GET | /api/v1/admin/pesanan/{kode}/chat | Admin | - | 3 |  |
| EP-A13 | GET | /api/v1/admin/pesanan/{kode}/rating | Admin | - | 3 |  |
| EP-A14 | GET | /api/v1/admin/laporan-kinerja-driver | Admin | - | 3 |  |
| EP-A16 | GET | /api/v1/admin/laporan | Admin | - | 3 |  |
| EP-A17 | GET | /api/v1/admin/laporan/{kode} | Admin | - | 3 |  |
| EP-A19 | POST | /api/v1/admin/laporan/{kode}/tinjau | Admin | - | 3 |  |
| EP-A18 | POST | /api/v1/admin/laporan/{kode}/keputusan | Admin | Ya | 3 | Dampak dana sesuai jenis laporan |
| EP-A20 | GET | /api/v1/admin/driver/{id}/sanksi | Admin | - | 3 |  |
| EP-A21 | POST | /api/v1/admin/driver/{id}/sanksi | Admin | - | 3 | Urutan sanksi; G-24, G-25 |
| EP-A22 | POST | /api/v1/admin/sanksi/{id}/cabut | Admin | - | 3 |  |
| EP-A23 | GET | /api/v1/admin/pencairan | Admin | - | 4 |  |
| EP-A24 | POST | /api/v1/admin/pencairan | Admin | Ya | 4 | Persetujuan kedua oleh Direktur (usulan) |
| EP-A25 | POST | /api/v1/admin/pencairan/{kode}/konfirmasi-transfer | Admin | Ya | 4 | Hasil transfer + referensi bank |
| EP-A26 | POST | /api/v1/admin/penarikan/{kode}/selesaikan | Admin | Ya | 4 | Bukti mutasi; G-26 |
| EP-A27 | POST | /api/v1/admin/setoran | Admin | Ya | 4 | Setoran hanya diusulkan Admin |
| EP-A28 | GET | /api/v1/admin/rekening-perusahaan | Admin, Direktur | - | 4 |  |
| EP-A29 | POST | /api/v1/admin/rekonsiliasi | Admin | - | 4 | Rekonsiliasi harian |
| EP-A30 | PATCH | /api/v1/admin/rekonsiliasi/{tanggal}/item/{id} | Admin | - | 4 |  |
| EP-A31 | GET | /api/v1/admin/staf | Admin | - | 1 |  |
| EP-A32 | POST | /api/v1/admin/staf | Admin | - | 1 |  |
| EP-A33 | PATCH | /api/v1/admin/staf/{id}/status | Admin | - | 1 |  |
| EP-A34 | POST | /api/v1/admin/staf/{id}/reset-sandi | Admin | - | 1 |  |
| EP-A35 | GET | /api/v1/admin/audit | Admin | - | 1 |  |
| EP-A36 | GET | /api/v1/admin/konfigurasi/{kunci}/riwayat | Admin, Direktur | - | 1 |  |
| EP-S01 | GET | /api/v1/staf/pesanan | Admin, Direktur | - | 3 |  |
| EP-S02 | GET | /api/v1/staf/pesanan/{kode} | Admin, Direktur | - | 3 |  |
| EP-S03 | GET | /api/v1/staf/rekonsiliasi | Admin, Direktur | - | 4 |  |
| EP-S04 | GET | /api/v1/staf/rekonsiliasi/{tanggal} | Admin, Direktur | - | 4 |  |
| EP-S05 | GET | /api/v1/staf/dompet-perusahaan | Admin, Direktur | - | 4 |  |
| EP-S06 | GET | /api/v1/staf/laporan/keuangan | Admin, Direktur | - | 4 |  |
| EP-S07 | GET | /api/v1/staf/laporan/pesanan | Admin, Direktur | - | 4 |  |
| EP-S08 | GET | /api/v1/staf/laporan/mutasi | Admin, Direktur | - | 4 |  |
| EP-S09 | GET | /api/v1/staf/setoran | Admin, Direktur | - | 4 |  |
| EP-R01 | GET | /api/v1/direktur/beranda | Direktur | - | 4 |  |
| EP-R02 | POST | /api/v1/direktur/setoran/{kode}/keputusan | Direktur | Ya | 4 | Direktur memutuskan setoran |
| EP-R03 | POST | /api/v1/direktur/penarikan | Direktur | Ya | 4 | Hanya perusahaan_pendapatan |
| EP-R04 | POST | /api/v1/direktur/penarikan/{kode}/hasil | Direktur | Ya | 4 |  |
| EP-R05 | GET | /api/v1/direktur/penarikan | Direktur | - | 4 |  |
| EP-R06 | GET | /api/v1/direktur/penarikan/{kode} | Direktur | - | 4 |  |
| EP-R07 | GET | /api/v1/direktur/pencairan | Direktur | - | 4 |  |
| EP-R08 | POST | /api/v1/direktur/pencairan/{kode}/persetujuan | Direktur | Ya | 4 | Jurnal pencairan_driver; G-05 |

---

## 15. Hal yang tidak diketahui dan keputusan terbuka (ringkas)

**Tidak diketahui [Tidak tahu]**
- Sumber tidak menetapkan umur token, algoritma JWT, parameter OTP, aturan sandi, batas ukuran berkas, dan interval polling; nilai awalnya saya putuskan pada Bagian 1A (interval polling tidak saya tetapkan karena ditentukan klien).
- Penyedia SMS/email OTP; penyedia payout dan bank yang didukung; hasil OPN-11 (mitra berlisensi); isi menu Bantuan; aturan layanan Pindahan; pemetaan "Truk Fuso" ke master.
- Aturan pembulatan `biaya_bbm` untuk hasil tidak bulat; sumber data settlement Midtrans.
- Format sebenarnya pesan Midtrans, Google Maps, FCM, dan perilaku settlement (asumsi A-04 pada Simulasi belum diverifikasi).

**Keputusan pemilik produk yang memblokir:** tidak ada lagi. Seluruh butir Kontrak 9.1 sudah diputuskan pada Bagian 1A. Yang tetap berada di luar kendali saya: kunci Midtrans dan Google Maps, penyedia SMS/email OTP, penyedia payout otomatis, dan penilaian hukum OPN-11. Semuanya sudah diberi jalur sementara agar pembangunan tidak berhenti.

**Hipotesis yang saya ajukan (keyakinan sedang)**
- Menggabungkan 10 langkah Kontrak menjadi 4 tahap tidak menimbulkan ketergantungan mundur. Dasarnya penalaran saya atas spesifikasi endpoint; belum diuji dengan kode dan dapat meleset pada detail (misalnya endpoint tahap awal yang ternyata membaca data tahap berikutnya, seperti EP-A02/EP-A05 yang menampilkan sanksi dan saldo).

---

## 16. Aba-aba berikutnya

Rancangan ini belum dieksekusi. Setelah aba-aba dari Anda, urutan kerja yang saya usulkan: (1) keputusan sudah lengkap (Bagian 1A), (2) saya membangun Tahap 1 dan menyerahkannya sebagai ZIP yang dapat dijalankan, (3) lanjut Tahap 2, 3, 4 setelah Anda menyetujui hasil tiap tahap.
