This commit is contained in:
189
docs/code-documentation.md
Normal file
189
docs/code-documentation.md
Normal file
@ -0,0 +1,189 @@
|
||||
<!--
|
||||
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`
|
||||
Reference in New Issue
Block a user