Notifications (Notifikasi)

1. Overview

Notifikasi memberi tahu pengguna tentang kejadian yang relevan, misalnya PO yang perlu diajukan atau data yang berubah. Notifikasi dibuat oleh BE dan dikirim ke pengguna lewat tiga kanal:

1. Kotak masuk (inbox) — daftar notifikasi di lonceng header (10 terbaru) dan halaman Akun → Notifikasi (lengkap, bisa dicari).
2. Notifikasi aplikasi (realtime) — toast yang muncul langsung saat aplikasi terbuka, lewat WebSocket (Laravel Reverb / Echo) pada channel privat tenant.users.{userId}.
3. Notifikasi browser (push) — notifikasi sistem operasi lewat Web Push, tetap muncul saat aplikasi tertutup (termasuk PWA yang di-install).

Setiap notifikasi membawa petunjuk tujuan (module, resource, operation, params), bukan URL. FE menerjemahkannya menjadi rute aplikasi sehingga pengguna bisa langsung membuka data terkait.

Hasil yang diharapkan: pengguna tidak melewatkan pekerjaan yang menunggu mereka, dan bisa langsung menuju data terkait dengan satu klik.

2. Problem

• Tugas yang menunggu seseorang (misalnya PO yang harus diajukan PIC) tidak diketahui tanpa membuka setiap modul.
• Pengguna yang tidak sedang membuka aplikasi melewatkan kejadian penting.
• Notifikasi tanpa tautan memaksa pengguna mencari data secara manual.

3. Goals & Non-goals

Goals

• Pengguna tahu ada notifikasi baru. Indikator: badge jumlah belum dibaca di lonceng, toast realtime.
• Pengguna bisa mengatur kanal. Indikator: toggle notifikasi aplikasi dan notifikasi browser.
• Notifikasi bisa ditindaklanjuti. Indikator: tombol Lihat Detail membuka data terkait.

Non-goals

• Preferensi notifikasi per jenis kejadian
• Notifikasi email / WhatsApp
• Menghapus notifikasi
• Membuat notifikasi manual dari UI (endpoint test hanya untuk pengujian)

4. User Scenarios

5. User Flow

1. Inbox — Semua notifikasi tersimpan dan tampil di lonceng serta halaman Notifikasi.
2. Realtime — Bila toggle “Notifikasi Aplikasi” aktif (default aktif, disimpan per browser), aplikasi terhubung ke channel privat pengguna. Setiap notifikasi baru memuat ulang daftar/jumlah dan menampilkan toast yang bisa diklik.
3. Push — Bila toggle “Notifikasi Browser” diaktifkan, browser meminta izin notifikasi, mendaftarkan service worker, membuat subscription dengan public key dari BE, lalu mengirim subscription ke BE.
4. Klik toast — Menandai notifikasi dibaca dan langsung membuka rute tujuan.
5. Klik notifikasi OS — Service worker memfokuskan tab aplikasi yang terbuka dan mengirim petunjuk tujuan; aplikasi membuka rutenya. Bila tidak ada tab, aplikasi dibuka di beranda.
6. Klik item inbox — Menandai dibaca bila belum, lalu membuka dialog detail (judul, waktu relatif, isi lengkap). Tombol Lihat Detail tampil bila tujuan bisa dipetakan ke rute.

Alternative paths

• Browser tidak mendukung push — toggle nonaktif dengan keterangan “Tidak didukung di browser ini”.
• Izin notifikasi ditolak — toggle nonaktif dengan keterangan “Izin ditolak — aktifkan dari pengaturan browser”.
• Gagal subscribe / unsubscribe — toast error, status toggle tidak berubah.
• Subscription lama dengan key berbeda — dihapus di BE dan browser, lalu dibuat ulang otomatis.
• Browser merotasi subscription — service worker membuat subscription baru dan mengirimkannya ke BE.

6. User Stories

Prioritas: P0 wajib untuk rilis, P1 penting, P2 kalau sempat.

US-01 — Lonceng notifikasi (P1)

Sebagai pengguna, saya ingin melihat notifikasi terbaru dari header, agar cepat tahu ada yang baru.

US-02 — Halaman notifikasi (P1)

Sebagai pengguna, saya ingin melihat semua notifikasi saya, agar bisa menemukan notifikasi lama.

US-03 — Detail dan navigasi (P1)

Sebagai pengguna, saya ingin membaca notifikasi lengkap dan membuka data terkait.

US-04 — Notifikasi aplikasi realtime (P1)

Sebagai pengguna, saya ingin notifikasi muncul langsung saat aplikasi terbuka.

US-05 — Notifikasi browser (push) (P1)

Sebagai pengguna, saya ingin menerima notifikasi walau aplikasi tertutup.

7. Document Structure

Notifikasi

Jumlah: total, unread_total.

Push subscription (dikirim FE): endpoint, expirationTime, keys.p256dh, keys.auth, content_encoding (aes128gcm, fallback aesgcm).

Pemetaan tujuan → rute

operation: view → /:id/detail, edit → /:id/edit, create → /add, lainnya → daftar.

8. Status Lifecycle

9. Permissions & Actions

Permissions

10. Business Rules

Aturan bisnis adalah ketentuan yang berlaku di semua layar dan semua aksi, siapa pun yang melakukannya. FE memakainya sebagai validasi di form, BE memakainya sebagai sumber kebenaran; jika keduanya berbeda, perilaku BE yang dianggap benar dan FE menyesuaikan.

• BR-01 BE tidak mengirim URL; hanya petunjuk tujuan (module, resource, operation, params). FE yang memetakan ke rute.
• BR-02 Preferensi realtime disimpan per browser (localStorage: notif-realtime), default aktif.
• BR-03 Subscription push berlaku per perangkat/browser; satu pengguna bisa punya banyak subscription.
• BR-04 Tombol Lihat Detail dan navigasi hanya tersedia bila module:resource ada di tabel pemetaan.
• BR-05 Izin notifikasi browser hanya diminta sebagai respons langsung klik pengguna.
• BR-06 Service worker harus selalu menampilkan notifikasi untuk setiap push yang diterima, walau payload rusak.
• BR-07 Service worker tidak boleh mencegat request (fetch handler inert) dan tidak boleh di-unregister di dev.

11. Edge Cases

Edge case adalah kondisi yang jarang terjadi tetapi pasti muncul di operasional nyata. Perilaku yang diharapkan ditetapkan di sini agar tidak diputuskan sendiri-sendiri saat implementasi.

12. API Contract

13. Dependencies

PRD terkait

• Purchase Order, Goods Receipt, dan modul lain — sumber kejadian notifikasi.
• Linked Devices — sesi perangkat (push terikat ke browser/perangkat).

Infrastruktur

• Laravel Reverb (WebSocket) dan Laravel Echo di FE.
• Service worker /sw.js dan manifest PWA; proxy matcher harus mengecualikan sw.js dan manifest.

Efek ke modul lain

• Menambah modul/resource baru yang mengirim notifikasi wajib menambah baris di tabel pemetaan rute (bagian 7).