Skip to content

SDLC, Pengujian & Keputusan Arsitektur (SV-ENG-001)

Field Nilai
ID Dokumen SV-ENG-001
Pilar Rekayasa Perangkat Lunak
Standar Acuan ISO/IEC/IEEE 12207 & ISO/IEC/IEEE 29119
Status Aktif / Tersinkronisasi dengan Kode
Terakhir Diperbarui 2026-11-21
Sumber Kebenaran .github/workflows/ci.yml, .github/actions/*/action.yml, vitest.config.ts, playwright.config.ts, tests/**, package.json, docs/teknis/kontribusi.md

Dokumen siklus hidup pengembangan perangkat lunak (SDLC), strategi pengujian menyeluruh, pipeline CI/CD, Definition of Done, serta Architecture Decision Records (ADR) Sudirman Voice. Untuk konvensi penulisan kode harian, format commit, dan pembaruan dokumentasi rilis, lihat kontribusi.md.

1. Siklus Pengembangan & Gerbang Rilis (Release Gates)

Section titled “1. Siklus Pengembangan & Gerbang Rilis (Release Gates)”
flowchart LR
  Dev["Pengembangan Fitur (Branch Lokal)"] -->|"Push ke dev"| CI["CI Paralel: check, integration, e2e"]
  CI -->|"check + integration HIJAU"| DeployDev["Deploy Otomatis ke voice-dev.p3mdi.id"]
  DeployDev -->|"Uji coba & PR ke main"| GatePR["Syarat Merge: check + integration + e2e HIJAU"]
  GatePR -->|"Push / Merge ke main"| DeployProd["Deploy Otomatis ke voice.p3mdi.id"]
  • Branching Model:
    • dev: Branch integrasi dan uji coba aktif (https://voice-dev.p3mdi.id). deploy-dev berjalan segera setelah check dan integration lulus, sementara e2e berjalan paralel untuk memantau regresi UI tanpa memblokir iterasi dev.
    • main: Branch production (https://voice.p3mdi.id). Membutuhkan status check check, integration, dan e2e semuanya hijau sebelum merge maupun sebelum deploy-prod berjalan.
  • Optimasi Trigger CI: Perubahan yang hanya menyentuh docs/**, **/*.md, atau mockup/** dilewati oleh push trigger CI (.github/workflows/ci.yml), sementara pull_request tetap menjalankan seluruh pemeriksaan.
Lapisan Alat & Konfigurasi Jumlah Berkas Cakupan & Lingkungan Eksekusi
Unit Test Vitest (--project unit, environment: "node") 35 (tests/unit/*.test.ts) Aturan murni tanpa DB: validasi PIN, No. Serdik, waktu WIB, sanitasi HTML .pendahuluan, parser tabel impor CSV/XLSX, validasi klaim Google OIDC, RBAC bisa(), aturan aspirasi/form/polling/hackathon/laporan, manifest PWA, guard seed & dev-login.
Integration Test Vitest (--project integration, fileParallelism: false, testTimeout: 30_000) 60 (tests/integration/*.test.ts) Service terhadap PostgreSQL 16 asli di 127.0.0.1:5433 (sv_test). Menguji isolasi search_path = '', transaksi & row lock konkurensi (form-race.test.ts, polling-race.test.ts, admin-actions.test.ts), kerahasiaan aspirasi/form/polling, impor contoh (impor-contoh.test.ts), antrean email, pengingat, serta seed hackathon.
End-to-End (E2E) Test Playwright (workers: 1, fullyParallel: false, 390×844 mobile Chromium) 21 (tests/e2e/*.spec.ts) Build produksi penuh (npm run build && npm start -p 3100, DEV_LOGIN="", NODE_ENV="production"). Menguji alur pengguna nyata di HP: masuk, aktivasi, reset PIN, kunci akun, peran, Mode Kelola, aspirasi, form, form tautan, polling, hackathon (tim/nilai/kelola/alur), impor, privasi, profil/notifikasi, serta audit header keamanan & CSP (keamanan.spec.ts).
  1. Validasi search_path Kosong: tests/helpers/global-setup.ts memaksa ALTER DATABASE sv_test SET search_path TO '' dan menjalankan prisma migrate deploy. Hal ini menjamin setiap query $queryRaw baru yang lupa menulis prefix public. langsung gagal di tahap tes.
  2. Pengujian Konkurensi / Race Condition: Menggunakan testHooks.afterRead pada submitForm, pilih, dan hapusKonten untuk menjeda transaksi secara deterministik dan membuktikan mekanisme FOR SHARE / FOR UPDATE PostgreSQL mencegah kondisi balapan.
  3. E2E Single Worker: playwright.config.ts mengunci workers: 1 karena semua permintaan berasal dari 127.0.0.1 sehingga tidak memicu pembatas throttle IP (20 gagal / 10 menit).
  4. Cakupan Keamanan Browser (keamanan.spec.ts): Memverifikasi keberadaan seluruh header keamanan pada respons HTTP serta menelusuri 9 rute utama untuk memastikan nol pelanggaran Content Security Policy di konsol Chromium.

3. Pipeline CI/CD (.github/workflows/ci.yml)

Section titled “3. Pipeline CI/CD (.github/workflows/ci.yml)”

Composite action .github/actions/siapkan/action.yml menyiapkan Node 24, menginstal dependensi (npm ci, yang memicu postinstall -> prisma generate), dan mengaktifkan cache .next/cache.

Job CI Dependensi Langkah Utama
check — npm run lint, npm run typecheck (next typegen && tsc --noEmit), npm run test:unit
integration Service postgres:16 (5433:5432, sv_test) npm run test:integration (menguji 60 berkas dengan search_path = '')
e2e Service postgres:16 (5433:5432, sv_test) npx playwright install --with-deps chromium, npm run test:e2e; unggah artefak playwright-report/ & test-results/ bila gagal (retensi 7 hari)
deploy-dev [check, integration] (push ke dev) Menjalankan .github/actions/deploy-vps (lingkungan: dev) lewat SSH terbatas ke ~/bin/deploy-sudirman-voice
deploy-prod [check, integration, e2e] (push ke main) Menjalankan .github/actions/deploy-vps (lingkungan: prod) lewat SSH terbatas ke ~/bin/deploy-sudirman-voice

Sebuah fitur atau perbaikan dinyatakan selesai apabila memenuhi seluruh kriteria berikut:

  1. Kepatuhan Lapisan: Aturan bisnis berada di src/features/<domain>/, bukan di komponen UI; mutasi mengembalikan Result<T> dengan validasi Zod dan membaca ulang peran (muatPeran) di service.
  2. Kepatuhan Desain & Aksesibilitas: Mematuhi .ux-profile.md dan desain-sistem.md (token globals.css, Icon SVG proyek, WCAG 2.1 AA, target sentuh >= 44 px, dialog konfirmasi untuk aksi destruktif).
  3. Kepatuhan Data & Keamanan: Migrasi SQL tersedia bila skema berubah; SQL mentah menggunakan prefix public.; data rahasia/anonim tidak pernah memuat relasi user maupun masuk ke Excel/AuditLog.
  4. Verifikasi Otomatis: npm run lint, npm run typecheck, npm run test:unit, dan npm run test:integration lulus; fitur dengan alur UI utama memiliki cakupan Playwright E2E di viewport mobile.
  5. Dokumentasi: Perubahan yang terlihat pengguna dicatat di CHANGELOG.md (Belum dirilis), log permintaan di docs/enhancement-log.md, serta pembaruan dokumen teknis terkait sebelum rilis.

ADR-001: Next.js App Router + Server Actions dengan Pola Result<T>

Section titled “ADR-001: Next.js App Router + Server Actions dengan Pola Result<T>”
  • Konteks: Dibutuhkan pengembangan cepat antara antarmuka interaktif dan akses database terpadu tanpa duplikasi kontrak REST API manual.
  • Keputusan: Menggunakan Server Components untuk pembacaan langsung dan Server Actions untuk mutasi, yang membungkus service domain pengembali Result<T> (ok/fail).
  • Konsekuensi: Type safety end-to-end terjamin dari Zod ke UI, penanganan error terstruktur per field (fields), dan logika bisnis murni dapat diuji langsung lewat Vitest tanpa meniru HTTP server.

ADR-002: Penguncian Baris PostgreSQL FOR UPDATE / FOR SHARE untuk Konkurensi

Section titled “ADR-002: Penguncian Baris PostgreSQL FOR UPDATE / FOR SHARE untuk Konkurensi”
  • Konteks: Dua aksi bersamaan (mis. pengelola menutup form atau mengubah skema sementara Serdik mengirimkan jawaban) berisiko menghasilkan inkonsistensi atau menghapus form yang sudah terisi.
  • Keputusan: Memakai penguncian baris eksplisit PostgreSQL (SELECT id FROM public.forms FOR SHARE saat menulis jawaban/suara/penilaian, dan SELECT id FROM public.forms FOR UPDATE saat menutup/mengubah/menghapus konten atau memajukan tahap hackathon) ditambah pg_advisory_xact_lock untuk keutuhan Admin dan cron harian.
  • Konsekuensi: Konkurensi terserialisasi aman di level database tanpa memerlukan broker antrean eksternal atau distributed lock terpisah.

ADR-003: Penyimpanan Gambar BYTEA di PostgreSQL vs Object Storage

Section titled “ADR-003: Penyimpanan Gambar BYTEA di PostgreSQL vs Object Storage”
  • Konteks: Aplikasi membutuhkan lampiran foto aspirasi/bukti, banner form, dan tangkapan layar hackathon dengan kontrol akses ketat per sesi.
  • Keputusan: Mengompresi dan menghapus EXIF/GPS di browser lalu menyimpan biner gambar di tabel BYTEA (aspiration_images, form_banner, hackathon_gambar), disajikan lewat Route Handler terotorisasi.
  • Konsekuensi: Tidak memerlukan kredensial/bucket S3 tambahan, penghapusan entitas otomatis bersih lewat ON DELETE CASCADE, dan kontrol otorisasi terjamin di server. Terbatas oleh kuota storage DB (kapasitas optimal ~1.000–2.500 gambar pada tier 0,5 GB).

ADR-004: Migrasi Hosting ke VPS Docker Compose di Belakang Traefik (vs Vercel)

Section titled “ADR-004: Migrasi Hosting ke VPS Docker Compose di Belakang Traefik (vs Vercel)”
  • Konteks: Sejak versi 1.2.0, aplikasi dipindahkan dari Vercel ke VPS Hostinger milik organisasi yang juga menjalankan aplikasi lain di belakang coolify-proxy (Traefik).
  • Keputusan: Membangun multi-stage Docker image (node:24-bookworm-slim, target migrate dan runner dengan output: "standalone") yang bergabung ke jaringan eksternal coolify tanpa membuka port host, serta menerapkan scripts/deploy-vps.sh dengan automatic healthcheck rollback.
  • Konsekuensi: Bebas batas durasi/body serverless Vercel (4,5 MB), biaya tetap, namun memerlukan pembacaan header proxy (x-real-ip, x-forwarded-host, x-forwarded-proto) secara disiplin (asalPermintaan(), getClientIp()).

ADR-005: Kepemilikan Konten Berbasis Peran (peranId) & Anti-Enumerasi NOT_FOUND

Section titled “ADR-005: Kepemilikan Konten Berbasis Peran (peranId) & Anti-Enumerasi NOT_FOUND”
  • Konteks: Pengurus tim (Lemusdik, Seksi Riset, atau peran baru buatan Admin) dapat berganti personel tanpa memutus akses pengelolaan form/polling/hackathon milik tim tersebut.
  • Keputusan: Konten dimiliki oleh peranId (bukan createdById), dengan pengecekan kepemilikan di konten/kepemilikan.ts dan hackathon/kelola.ts yang membalas NOT_FOUND (404) untuk kode milik peran lain.
  • Konsekuensi: Rotasi pengurus hanya cukup menambah/mencabut UserPeran; keamanan informasi terjaga karena pengguna berizin dari satu peran tidak dapat mendeteksi keberadaan draf/konten milik peran lain.