wirabasalamah
137edc12b7
Some checks are pending
CI - Production Readiness / Verify (push) Waiting to run
190 lines
4.5 KiB
Markdown
190 lines
4.5 KiB
Markdown
<!--
|
||
Project Documentation
|
||
Scope: WhatsApp Inbox Platform
|
||
-->
|
||
|
||
# WhatsApp Inbox Platform – Dokumentasi Kode
|
||
|
||
Dokumen ini menjelaskan arsitektur dan alur utama aplikasi supaya mudah dipahami saat onboarding, debug, atau audit.
|
||
|
||
## 1. Gambaran Sistem
|
||
|
||
Stack yang dipakai:
|
||
|
||
- Frontend + backend: Next.js 15 (App Router).
|
||
- Database: PostgreSQL + Prisma ORM.
|
||
- Autentikasi custom: cookie session berbasis payload ter-tanda-tangan.
|
||
- Job worker: campaign retry worker berbasis script Node.
|
||
- Proses produksi: PM2 + Nginx sebagai reverse proxy.
|
||
- Logging dan health check: endpoint internal + script operasi.
|
||
|
||
## 2. Struktur Folder Penting
|
||
|
||
`app/`
|
||
Himpunan route Next.js, termasuk endpoint autentikasi dan halaman admin.
|
||
|
||
`lib/`
|
||
Modul inti:
|
||
|
||
- auth/session.
|
||
- prisma client.
|
||
- util i18n.
|
||
- request url utility.
|
||
- audit & rate limit.
|
||
|
||
`prisma/`
|
||
Skema dan migrasi database.
|
||
|
||
`scripts/`
|
||
Operasional dan maintenance:
|
||
|
||
- ops scripts.
|
||
- job scripts.
|
||
|
||
`public/`
|
||
Asset statis.
|
||
|
||
## 3. Alur Autentikasi
|
||
|
||
### 3.1 Login
|
||
|
||
1. POST ke `/auth/login`.
|
||
2. Validasi rate limit, credential, dan status user.
|
||
3. Jika valid, session dibuat dan disimpan di cookie `wa_inbox_session`.
|
||
4. Cookie diset dengan:
|
||
- `httpOnly`.
|
||
- `sameSite: "lax"`.
|
||
- `secure` sesuai env/protocol.
|
||
- `domain` dari `SESSION_COOKIE_DOMAIN` bila di-set.
|
||
- `maxAge` dari nilai session TTL.
|
||
5. Response diarahkan ke route default sesuai role.
|
||
|
||
File:
|
||
- `app/auth/login/route.ts`
|
||
|
||
### 3.2 Middleware Guard
|
||
|
||
Setiap request (kecuali API) dilewati middleware untuk validasi:
|
||
|
||
- Mengecek session cookie.
|
||
- Redirect ke `/login?next=...` jika tidak ada session.
|
||
- Mengarahkan user ke default path role jika sudah login dan masuk halaman publik tertentu.
|
||
- Redirect unauthorized jika role tidak punya akses.
|
||
- Menangani locale cookie fallback.
|
||
|
||
File:
|
||
- `middleware.ts`
|
||
|
||
### 3.3 Parse Session
|
||
|
||
Session token dibuat dari payload user lalu ditandatangani dengan HMAC.
|
||
|
||
Modul inti:
|
||
- `lib/auth.ts`
|
||
|
||
Berisi:
|
||
- tipe session.
|
||
- validasi role.
|
||
- serialisasi/deserialisasi cookie.
|
||
- helper konfigurasi session (`getSessionTtlSeconds`, `getSessionCookieDomain`).
|
||
|
||
## 4. Konfigurasi Session dan Cookie
|
||
|
||
### 4.1 TTL Session
|
||
|
||
Nilai diambil dari env:
|
||
|
||
- `SESSION_TTL_SECONDS` (prioritas utama).
|
||
- `SESSION_TTL_HOURS` (fallback legacy).
|
||
|
||
Default fallback tetap saat env tidak ada.
|
||
|
||
### 4.2 Cookie Hardening
|
||
|
||
Untuk environment HTTPS/prod:
|
||
|
||
- `COOKIE_SECURE=true`.
|
||
- `SESSION_COOKIE_DOMAIN=web.zappcare.id` (jika pakai subdomain).
|
||
- `SESSION_COOKIE_DOMAIN` akan diabaikan untuk localhost/127.0.0.1.
|
||
|
||
## 5. Modul dan Script Operasional
|
||
|
||
### 5.1 Script Deploy Aman
|
||
|
||
`scripts/ops-safe-restart.sh`:
|
||
|
||
- cek `.env`.
|
||
- install dependency (`npm ci`).
|
||
- build.
|
||
- deploy migration Prisma (`npm run db:deploy`).
|
||
- restart/start PM2.
|
||
- optional healthcheck.
|
||
- save PM2 state.
|
||
|
||
NPM script:
|
||
- `npm run ops:safe-restart`
|
||
|
||
### 5.2 Script Verifikasi Session
|
||
|
||
`scripts/ops-session-check.mjs`:
|
||
|
||
- login otomatis via akun health check.
|
||
- verifikasi cookie sesi terbit.
|
||
- validasi TTL.
|
||
- cek akses page protected (`/super-admin`) dengan cookie sesi.
|
||
|
||
NPM script:
|
||
- `npm run ops:session-check`
|
||
|
||
### 5.3 Dokumentasi Operasional Terkait
|
||
|
||
- `ops-runbook.md`
|
||
- `production-readiness-checklist.md`
|
||
|
||
## 6. Catatan Debug Umum
|
||
|
||
### Gejala: Kembali ke halaman login setelah klik menu
|
||
|
||
Penyebab paling umum:
|
||
- sesi tidak tersimpan karena cookie `secure/domain` tidak cocok.
|
||
- domain/protocol HTTPS mismatch.
|
||
- proses logout tidak sengaja terpicu.
|
||
- path/role mismatch pada middleware.
|
||
|
||
Pengecekan:
|
||
- lihat response headers:
|
||
- `X-Auth-Session`
|
||
- `X-Auth-Session-Has-Cookie`
|
||
- `X-Auth-Base-Url`
|
||
- cek cookie di browser devtools (nama `wa_inbox_session`, secure/domain/path/maxAge).
|
||
- cek log aplikasi (`pm2 logs ...` + `grep AUTH`).
|
||
|
||
### Gejala: Loop redirect login (bahasa Inggris / error invalid credential)
|
||
|
||
Pastikan:
|
||
- `AUTH_SECRET` ada di env prod.
|
||
- `APP_URL` / `OPS_BASE_URL` sesuai domain HTTPS.
|
||
- `COOKIE_SECURE` sesuai mode.
|
||
- Nginx tidak strip header `Cookie`.
|
||
|
||
## 7. Catatan Implementasi Khusus
|
||
|
||
- Logout flow sudah difokuskan ke request non-prefetch agar tidak terpicu by mistake pada prefetch link.
|
||
- Script yang diubah untuk mencegah kegagalan sesi karena navigasi prefetch.
|
||
- Penambahan debugging header di middleware/login untuk mempercepat root cause analysis.
|
||
|
||
## 8. Dependency Environment Wajib (Ringkas)
|
||
|
||
- `DATABASE_URL`
|
||
- `AUTH_SECRET`
|
||
- `APP_URL`
|
||
- `SESSION_TTL_SECONDS`
|
||
- `COOKIE_SECURE`
|
||
- `SESSION_COOKIE_DOMAIN` (jika dibutuhkan)
|
||
- `WHATSAPP_*`, `CAMPAIGN_*`, dan token internal sesuai fitur aktif.
|
||
|
||
Lihat juga:
|
||
- `ops-runbook.md`
|
||
- `production-readiness-checklist.md`
|
||
- `.env.example`
|