# CONTEXT: BUMIMAS CONNECT

Baca file ini sepenuhnya sebelum menulis kode apa pun. Ikuti aturan di sini. Jika ada yang bertentangan dengan permintaan baru, tanyakan dulu sebelum melanggar.

## 1. Proyek

**BUMIMAS CONNECT** adalah web app internal untuk PT. Bumi Mas Antarnusa (perusahaan penempatan Pekerja Migran Indonesia, atau P3MI, berkantor di Sidoarjo, Jawa Timur). Fokus awal: PMI yang ditempatkan di Malaysia.

**Masalah yang diselesaikan:** setelah PMI berangkat, perusahaan tidak punya cara terstruktur untuk tahu apakah PMI sudah pulang, memperpanjang kontrak, pindah majikan, atau di mana lokasinya. Data selama bekerja ada di sistem Malaysia dan majikan, bukan di perusahaan.

**Solusi:** PMI melapor status secara berkala lewat web app (dengan lokasi dan foto, hanya atas persetujuan mereka). Admin memantau lewat dashboard, pengingat terklasifikasi, notifikasi, direktori alumni, dan pelatihan wajib sampai 100%.

**Dua peran:** `admin` (staf perusahaan) dan `user` (PMI/alumni).

## 2. Aturan Keras (jangan dilanggar)

1. **Dilarang** membuat scraping, bot login otomatis, atau integrasi tidak resmi ke SiskoP2MI, Sipermit, FWCMS, atau sistem imigrasi Malaysia. Aplikasi ini sistem internal yang terpisah. Pengecekan ke sistem itu dilakukan manual oleh staf, lalu hasilnya dicatat di aplikasi.
2. **Dilarang** pelacakan lokasi di latar belakang atau real-time. Lokasi hanya diambil saat PMI menekan tombol (check-in). Web app tidak bisa dan tidak boleh melacak diam-diam.
3. Izin **lokasi dan kamera** hanya diminta setelah PMI menekan tombol dan setelah layar penjelasan (consent) ditampilkan. Tidak ada permintaan izin saat halaman dibuka.
4. Penolakan izin **tidak boleh memblokir** pelaporan status. Sediakan fallback.
5. **NIK dan nomor paspor** wajib terenkripsi di database. Tampilan selalu dimasking (contoh `3578 **** **** 0012`). Membuka NIK penuh hanya untuk admin dan wajib tercatat di audit log.
6. Tidak ada pengenalan wajah, tidak ada perekaman audio atau video.
7. Foto dan dokumen disimpan di disk **private**, bukan folder publik. Akses admin lewat signed URL sementara.
8. Semua teks antarmuka **berbahasa Indonesia**. Kode, nama tabel, dan komentar kode dalam bahasa Inggris.
9. Jangan menambah paket besar tanpa alasan. Utamakan fitur bawaan Laravel.
10. Jangan memakai data PMI asli untuk seed atau contoh. Pakai data fiktif.

## 3. Tech Stack

| Komponen | Pilihan |
|---|---|
| Framework | Laravel (versi stabil terbaru), PHP 8.3 atau lebih baru |
| Database | SQLite |
| Frontend | Blade + Livewire + Alpine.js + Tailwind CSS |
| Autentikasi | Laravel session auth; 2FA tidak digunakan |
| Peta | Leaflet + tile OpenStreetMap |
| Queue | driver `database` |
| Scheduler | Laravel Scheduler (zona waktu `Asia/Jakarta`) |
| Notifikasi | Database + email. Push web (PWA) opsional. WhatsApp tahap berikutnya |
| Ekspor | Laravel Excel, DomPDF |
| PWA | Web app manifest + service worker |
| Test | Pest |

### Catatan SQLite
- Aktifkan `foreign_keys`, mode WAL, dan `busy_timeout`. Gunakan opsi di `config/database.php` bila tersedia di versi Laravel yang dipakai, atau jalankan PRAGMA di service provider.
- SQLite hanya melayani satu penulis dalam satu waktu. Hindari transaksi panjang. Proses berat lewat queue.
- Foto dan dokumen **tidak** disimpan di database, hanya path-nya.
- Backup harian dengan `.backup` SQLite ke lokasi terpisah.
- Gunakan Eloquent dan migrasi standar agar mudah pindah ke MySQL atau PostgreSQL nanti.

## 4. Peran dan Hak Akses

Kolom `role` (enum `admin`, `user`) di tabel `users`. Jaga dengan middleware dan Laravel Policy.

| Kemampuan | Admin | User (PMI) |
|---|---|---|
| Kelola akun dan data PMI | Ya | Tidak |
| Lihat data PMI | Semua (NIK dimasking) | Hanya dirinya |
| Lapor status, check-in lokasi dan foto | Tidak | Ya |
| Peta lokasi terakhir | Ya | Tidak |
| Pengingat dan kirim notifikasi | Ya | Menerima |
| Kelola kursus dan penugasan | Ya | Mengikuti |
| Direktori alumni | Ya | Hanya profil sendiri |
| Consent | Lihat riwayat | Beri dan cabut sendiri |
| Audit log dan laporan | Ya | Tidak |

Rute admin memakai prefix `/admin` dan middleware `role:admin`. User tidak boleh mengakses rute admin (balas 403).

## 5. Fitur Utama

1. **Autentikasi:** login email atau nomor HP, ganti kata sandi saat login pertama, rate limiting.
2. **Data PMI dan kontrak (admin):** identitas, penempatan, kontrak, PLKS, kontak keluarga, sponsor, status. Impor dari Excel atau CSV.
3. **Lapor status (user):** 4 pilihan (Masih bekerja, Pindah majikan, Perpanjang, Sudah pulang) + opsional lokasi dan foto.
4. **Dashboard admin:** ringkasan status, PMI belum lapor, kontrak berakhir 30 hari ke depan.
5. **Pengingat terklasifikasi:** berdasarkan hari sejak laporan terakhir (lihat bagian 8).
6. **Notifikasi:** template, kirim ke satu, kelompok, atau semua PMI, lewat queue.
7. **Peta lokasi (admin):** hanya lokasi terakhir yang dibagikan, dengan waktu dan akurasi.
8. **Know Your Alumni:** direktori PMI berstatus pulang, filter negara, pekerjaan, tahun, keahlian, ketersediaan.
9. **Pelatihan:** kursus, modul, penugasan wajib, progres, sertifikat terkunci sampai 100%.
10. **Audit log dan laporan:** catat aksi sensitif, ekspor Excel atau PDF.

## 6. Model Data (ringkas)

| Tabel | Isi utama |
|---|---|
| `users` | id, name, email, phone, password, role, is_active |
| `pmi_profiles` | user_id, nik (encrypted), nik_hash, passport_no (encrypted), passport_expiry, birth_date, country, employer, job_title, job_category, partner_agency, departed_at, status, last_report_at |
| `contracts` | pmi_profile_id, start_date, end_date, plks_expiry, extension_no, notes |
| `family_contacts` | pmi_profile_id, name, relation, phone, is_primary |
| `check_ins` | pmi_profile_id, reported_status, note, lat, lng, accuracy_m, location_source (gps/manual/none), location_denied_reason, photo_path, created_at |
| `consents` | user_id, type (location/camera/data_processing), version, granted, granted_at, revoked_at, ip, user_agent |
| `reminders` | pmi_profile_id, type, due_date, severity, status, handled_by, handled_note |
| `documents` | pmi_profile_id, type, file_path (private), uploaded_at, expires_at |
| `courses` | title, description, category, duration_min, is_active |
| `course_modules` | course_id, type (video/pdf/quiz/live), title, position, pass_score, live_url, live_at |
| `course_assignments` | course_id, pmi_profile_id, is_mandatory, due_date, assigned_by |
| `module_progress` | assignment_id, module_id, completed_at, score, attendance_verified_by |
| `certificates` | course_assignment_id, number, issued_at, file_path |
| `alumni_skills` | pmi_profile_id, skill_tag (+ kolom `is_available_for_placement` di `pmi_profiles`) |
| `audit_logs` | user_id, action, target_type, target_id, meta, ip, created_at |

**Status PMI (enum):** `aktif_bekerja`, `perpanjang`, `pindah_majikan`, `sudah_pulang`, `tidak_diketahui`.

**NIK:** simpan dengan cast `encrypted`. Untuk pencarian dan keunikan, simpan `nik_hash` (HMAC SHA-256 dengan kunci aplikasi). Jangan mencari di kolom terenkripsi.

## 7. Izin Lokasi dan Kamera (implementasi)

### Umum
- Wajib HTTPS (kecuali `localhost` saat development).
- Header di semua respons: `Permissions-Policy: geolocation=(self), camera=(self), microphone=()`.
- Alur: PMI menekan tombol, tampil layar penjelasan (tujuan, data, siapa yang melihat, lama simpan, cara cabut), PMI setuju, catat ke `consents`, baru panggil API browser.
- Consent dapat dicabut kapan saja. Setelah dicabut, hentikan permintaan data terkait.

### Lokasi
```js
navigator.geolocation.getCurrentPosition(onSuccess, onError, {
  enableHighAccuracy: true,
  timeout: 15000,
  maximumAge: 0,
});
```
- Simpan: latitude, longitude, akurasi (meter), waktu.
- Cek status izin lewat Permissions API (`granted`, `denied`, `prompt`) untuk menyesuaikan tampilan.
- Jika ditolak atau gagal: petunjuk mengaktifkan izin + input manual (negara, kota, tempat kerja) dengan `location_source = manual`.
- Admin hanya melihat lokasi terakhir. Riwayat lokasi hanya untuk admin dengan alasan tercatat di audit log.

### Kamera
```js
const stream = await navigator.mediaDevices.getUserMedia({
  video: { facingMode: 'user' }, // 'environment' untuk foto dokumen
  audio: false,
});
// tampilkan di <video>, ambil frame ke <canvas>, hentikan stream setelah ambil
// kompres JPEG kualitas 0.8, sisi terpanjang maksimal 1280 px, lalu unggah
```
- Setelah foto diambil, panggil `stream.getTracks().forEach(t => t.stop())`.
- Fallback jika kamera ditolak atau tidak ada: `<input type="file" accept="image/*" capture>`.
- Server: validasi jenis file dan ukuran (maksimal 5 MB), hapus metadata EXIF, simpan di disk private dengan nama acak.

### Batasan teknis (jangan dijanjikan lebih)
Web app tidak bisa mengambil lokasi di latar belakang. Ini **check-in lokasi**, bukan pelacakan langsung.

## 8. Logika Bisnis Penting

**Klasifikasi pengingat** (command terjadwal harian pukul 06:00 WIB, `php artisan pmi:classify`), berdasarkan hari sejak `last_report_at`:
- Sudah lapor (dalam periode)
- Belum lapor 1-7 hari
- Belum lapor 8-30 hari
- Belum lapor lebih dari 30 hari

**Pengingat berbasis tanggal:**
- Kontrak berakhir: 90, 30, dan 7 hari sebelumnya.
- PLKS (berlaku 12 bulan): 3 bulan sebelum habis.
- Paspor: 6 bulan sebelum habis.
- Status `tidak_diketahui` lebih dari 30 hari memunculkan tugas eskalasi (hubungi sponsor atau tanyakan ke KP2MI/BP3MI).

**Pelatihan:**
- Progres kursus = modul selesai dibagi total modul.
- Modul selesai: video ditonton sampai habis, atau kuis lulus (nilai minimal 70), atau dokumen ditandai dibaca. Kelas virtual: kehadiran lewat kode kehadiran atau verifikasi admin.
- Sertifikat PDF dibuat otomatis hanya saat progres 100%. Sebelum itu tampilkan terkunci.
- Kursus dapat ditugaskan sebagai wajib dengan tenggat. Kirim pengingat otomatis mendekati tenggat.
- Kehadiran di platform luar (Zoom, Meet) tidak terbaca otomatis. Jangan berpura-pura bisa.

## 9. Keamanan

- Enkripsi NIK dan paspor, masking di tampilan, audit log untuk aksi sensitif.
- CSRF aktif, validasi lewat Form Request, rate limiting pada login dan pengiriman notifikasi.
- Sesi kedaluwarsa otomatis dan akses admin dibatasi dengan autentikasi serta role.
- Policy pada setiap model sensitif. Jangan mengandalkan penyembunyian tombol di UI.
- Jangan mencatat NIK, lokasi, atau isi foto ke log aplikasi.
- Data pribadi mengacu pada UU No. 27 Tahun 2022 tentang Pelindungan Data Pribadi. Konfirmasi detail kepatuhan dengan penasihat hukum.

## 10. Desain UI

- Modern, minimalis, warna lembut. Mobile-first, juga rapi di desktop.
- Palet mengikuti gambar referensi (keputusan pemilik proyek, menggantikan teal lama): primary biru navy `#0036B1`, gradien hero dan tombol utama `#00246F` ke `#4A6EC6`, aksen pastel mint, amber, peach, coral, biru langit, lavender. Background `#F5F6FA`, kartu putih, teks `#17233C` dan `#7C8798`.
- Chip status pastel: Sudah lapor (hijau sage), Belum lapor 1-7 hari (amber), 8-30 hari (peach), lebih dari 30 hari (coral), Sudah pulang (biru langit), Perpanjang (lavender).
- Font Plus Jakarta Sans. Radius 20 px untuk kartu. Ikon outline konsisten.
- Hindari: gradien neon, glassmorphism, ilustrasi stok, chart pengisi yang tidak berguna.
- Kontras teks WCAG AA, target sentuh minimal 44 px.

## 11. Struktur Folder yang Diharapkan

```
app/
  Enums/PmiStatus.php
  Http/Controllers/Admin/...
  Http/Controllers/User/...
  Http/Middleware/EnsureRole.php, SecurityHeaders.php
  Livewire/Admin/..., Livewire/User/...
  Models/...
  Policies/...
  Services/ReminderClassifier.php, CheckInService.php, CertificateService.php
  Console/Commands/ClassifyPmi.php
database/migrations, database/seeders (data fiktif)
resources/views/admin, resources/views/user, resources/js (geolocation.js, camera.js)
tests/Feature, tests/Unit
```

## 12. Urutan Pengerjaan

Kerjakan per fase, satu fase per sesi. Setelah tiap fase: jalankan test dan jelaskan apa yang berubah.

1. **Fase 0:** scaffold Laravel, SQLite, Tailwind, auth, role middleware, security headers.
2. **Fase 1 (MVP):** data PMI dan kontrak, consent, lapor status, check-in lokasi dan kamera, dashboard admin, pengingat terklasifikasi.
3. **Fase 2:** notifikasi, peta lokasi, Know Your Alumni, ekspor laporan.
4. **Fase 3:** pelatihan (kursus, modul, progres, aturan 100%, sertifikat).
5. **Fase 4:** audit log lengkap, PWA, uji keamanan, perbaikan.

## 13. Cara Bekerja (untuk AI)

- Tulis migrasi, model, policy, dan test bersamaan dengan fiturnya.
- Test wajib untuk: policy peran, consent sebelum lokasi dan foto, penolakan izin tidak memblokir laporan, masking NIK, sertifikat terkunci sebelum 100%.
- Jangan mengubah file di luar cakupan permintaan. Jelaskan jika perlu.
- Jika ada keputusan yang belum jelas (retensi data, frekuensi laporan, platform kelas virtual), **tanya**, jangan menebak.
- Sebelum selesai, periksa daftar Aturan Keras (bagian 2).

## 14. Pertanyaan Terbuka (jangan diasumsikan)

1. Apakah selfie wajib atau opsional pada setiap laporan?
iya, Wajib
2. Frekuensi laporan yang diharapkan (bulanan atau per 3 bulan)?
per 3 bulan
3. Masa retensi lokasi, foto, dan dokumen?
1 tahun
4. Platform kelas virtual yang dipakai (Zoom, Google Meet, lainnya)?
Google Meet
5. Apakah KP2MI menyediakan API resmi untuk P3MI?
tidak ada
6. Jumlah PMI aktif dan staf admin (untuk menilai kecukupan SQLite)?
10 orang PMI aktif dan 5 staff admin

## 15. Modul Tambahan: Cek Akhir Kontrak & Deteksi IP

Modul aditif mandiri (add-on) untuk memantau masa akhir kontrak PMI dari H-90 hingga H+90 tanpa mengubah tabel data utama:

1. **Prinsip Utama:**
   - Tabel baru independen: `contract_watches`, `contact_attempts`, `check_links`, `link_visits`.
   - Menggunakan foreign key `pmi_profile_id` ke data profil PMI lama.
   - Saklar fitur: `CEK_KONTRAK_ENABLED=true` (dikendalikan via `config('features.cek_kontrak')`).
   - Jadwal pemindaian berkala harian: `php artisan kontrak:scan`.

2. **Alur Deteksi IP & Perlindungan Bot:**
   - **GET `/c/{token}`:** Halaman form publik dibuka. Tidak mencatat baris apa pun di database untuk mencegah pencatatan palsu dari bot pratinjau (WhatsApp link preview, Facebook scraper, dll).
   - **POST `/c/{token}`:** Kunjungan dicatat setelah tombol aksi ditekan PMI. User-agent bot/crawler otomatis ditolak (HTTP 400).
   - **Trusted Proxies:** Dikonfigurasi di `bootstrap/app.php` dengan variabel `TRUSTED_PROXIES` agar IP asli klien terbaca akurat di balik Nginx/CDN.
   - **GeoIP Lokal:** Resolusi negara melalui `GeoIpService` membaca file offline `storage/app/geo/GeoLite2-Country.mmdb` (tanpa membocorkan IP ke API eksternal).
   - **Hierarki Keputusan:** Mesin keputusan (`ContractDecisionEngine`) menetapkan tingkat keyakinan dengan urutan prioritas: **GPS > Jawaban PMI / Kontak Staf > IP**.

3. **Perlindungan Privasi:**
   - Pernyataan persetujuan (*consent*) eksplisit mencantumkan tujuan pemantauan, pembatasan akses, dan masa simpan.
   - Di tampilan admin staf, IP disamarkan secara default (`xxx.xxx.xxx.***`).
   - Ketika kasus pemantauan dikonfirmasi atau ditutup oleh staf, metode `LinkVisit::redactIp()` otomatis mengaburkan oktet terakhir IPv4 (contoh `180.252.164.88` menjadi `180.252.164.0`) atau menghapus IPv6, namun tetap mempertahankan kode negara (`ip_country`).
