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-devberjalan segera setelahcheckdanintegrationlulus, sementarae2eberjalan paralel untuk memantau regresi UI tanpa memblokir iterasi dev.main: Branch production (https://voice.p3mdi.id). Membutuhkan status checkcheck,integration, dane2esemuanya hijau sebelum merge maupun sebelumdeploy-prodberjalan.
- Optimasi Trigger CI: Perubahan yang hanya menyentuh
docs/**,**/*.md, ataumockup/**dilewati olehpushtrigger CI (.github/workflows/ci.yml), sementarapull_requesttetap menjalankan seluruh pemeriksaan.
2. Piramida Pengujian (116 Berkas Tes)
Section titled “2. Piramida Pengujian (116 Berkas Tes)”| 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). |
Karakteristik Teknis Penting Suite Tes
Section titled “Karakteristik Teknis Penting Suite Tes”- Validasi
search_pathKosong:tests/helpers/global-setup.tsmemaksaALTER DATABASE sv_test SET search_path TO ''dan menjalankanprisma migrate deploy. Hal ini menjamin setiap query$queryRawbaru yang lupa menulis prefixpublic.langsung gagal di tahap tes. - Pengujian Konkurensi / Race Condition: Menggunakan
testHooks.afterReadpadasubmitForm,pilih, danhapusKontenuntuk menjeda transaksi secara deterministik dan membuktikan mekanismeFOR SHARE/FOR UPDATEPostgreSQL mencegah kondisi balapan. - E2E Single Worker:
playwright.config.tsmengunciworkers: 1karena semua permintaan berasal dari127.0.0.1sehingga tidak memicu pembatas throttle IP (20 gagal / 10 menit). - 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 |
4. Definition of Done (DoD)
Section titled “4. Definition of Done (DoD)”Sebuah fitur atau perbaikan dinyatakan selesai apabila memenuhi seluruh kriteria berikut:
- Kepatuhan Lapisan: Aturan bisnis berada di
src/features/<domain>/, bukan di komponen UI; mutasi mengembalikanResult<T>dengan validasi Zod dan membaca ulang peran (muatPeran) di service. - Kepatuhan Desain & Aksesibilitas: Mematuhi
.ux-profile.mddan desain-sistem.md (tokenglobals.css,IconSVG proyek, WCAG 2.1 AA, target sentuh >= 44 px, dialog konfirmasi untuk aksi destruktif). - Kepatuhan Data & Keamanan: Migrasi SQL tersedia bila skema berubah; SQL mentah menggunakan prefix
public.; data rahasia/anonim tidak pernah memuat relasiusermaupun masuk ke Excel/AuditLog. - Verifikasi Otomatis:
npm run lint,npm run typecheck,npm run test:unit, dannpm run test:integrationlulus; fitur dengan alur UI utama memiliki cakupan Playwright E2E di viewport mobile. - Dokumentasi: Perubahan yang terlihat pengguna dicatat di
CHANGELOG.md(Belum dirilis), log permintaan didocs/enhancement-log.md, serta pembaruan dokumen teknis terkait sebelum rilis.
5. Architecture Decision Records (ADR)
Section titled “5. Architecture Decision Records (ADR)”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 SHAREsaat menulis jawaban/suara/penilaian, danSELECT id FROM public.forms FOR UPDATEsaat menutup/mengubah/menghapus konten atau memajukan tahap hackathon) ditambahpg_advisory_xact_lockuntuk 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, targetmigratedanrunnerdenganoutput: "standalone") yang bergabung ke jaringan eksternalcoolifytanpa membuka port host, serta menerapkanscripts/deploy-vps.shdengan 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(bukancreatedById), dengan pengecekan kepemilikan dikonten/kepemilikan.tsdanhackathon/kelola.tsyang membalasNOT_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.