Skip to content

API & Antarmuka Sistem (SV-API-001)

Field Nilai
ID Dokumen SV-API-001
Pilar Rekayasa Perangkat Lunak
Standar Acuan Interface Control Document (ICD) / IEEE 1016
Status Aktif / Tersinkronisasi dengan Kode
Terakhir Diperbarui 2026-11-21
Sumber Kebenaran src/lib/result.ts, src/app/**/route.ts, src/app/**/*actions.ts, src/features/impor/*, src/features/admin/import/*, src/features/notifikasi/*, src/features/auth/google.ts

Spesifikasi antarmuka sistem Sudirman Voice yang mencakup 15 HTTP Route Handlers (route.ts), 94 Server Actions di 24 berkas aksi, kontrak tipe Result<T>, spesifikasi impor/ekspor Excel & CSV, serta integrasi layanan eksternal.

1. Kontrak Respon Service (Result<T>) & Kode Galat Baku

Section titled “1. Kontrak Respon Service (Result<T>) & Kode Galat Baku”

Seluruh fungsi bisnis di src/features/ mengembalikan objek Result<T> (src/lib/result.ts) alih-alih melempar exception untuk kondisi kegagalan yang terduga:

export type Result<T> =
| { ok: true; data: T }
| { ok: false; error: { code: string; message: string; fields?: Record<string, string> } };
Kode Makna Semantik & Pemetaan HTTP/UI
VALIDATION Input gagal validasi Zod/skema atau batas ukuran/karakter; membawa fields per kolom
FORBIDDEN Aktor tidak memiliki izin peran atau mencoba aksi terlarang (memicu 403 di route/layout)
NOT_FOUND Entitas tidak ada atau milik peran/tim lain (anti-enumerasi → 404)
STATUS Status entitas tidak mengizinkan transisi atau aksi saat ini (mis. menerbitkan non-draf)
TERKUNCI Konten terkunci karena sudah ada jawaban/suara, atau tahapan hackathon sudah lanjut
TUTUP Form atau polling sudah melewati tenggat atau ditutup
SUDAH Pengguna sudah pernah mengisi form atau menandai selesai
LIMIT Batas harian tercapai (mis. maks. 5 aspirasi/hari, 5 laporan/24 jam, 3 permintaan data/24 jam, 3 kode email/15 menit)
JEDA Jeda minimal antar kiriman belum tercapai (mis. 30 detik pada Laporkan masalah)
KONFLIK Pelanggaran keanggotaan unik (1 Serdik hanya 1 tim per hackathon)
PENUH Jumlah anggota tim hackathon mencapai maksAnggota
MUNDUR Percobaan memundurkan status aspirasi
BENTROK Konflik konkurensi optimistik (status aspirasi telah diubah pengurus lain secara bersamaan)
SERI Nilai juri seri pada peringkat 1 suatu bidang hackathon; butuh urutan panitia sebelum diumumkan
BELUM Prasyarat belum siap (mis. email belum dicatat Admin, atau penilaian hackathon belum dibuka)
KODE Kode OTP email salah, kedaluwarsa (> 10 menit), sudah dipakai, atau melebihi 5 percobaan
KONFIGURASI Variabel layanan eksternal (SMTP / Google OAuth) belum diatur pada server
KIRIM Pengiriman email langsung mengalami kegagalan sementara pada SMTP
SELF_ADMIN / SELF_DEACTIVATE / LAST_ADMIN / SISTEM / EMPTY Pelanggaran aturan pengaman admin/peran atau hasil reset massal kosong

2. Katalog Lengkap HTTP Route Handlers (15 Rute)

Section titled “2. Katalog Lengkap HTTP Route Handlers (15 Rute)”

2.1 Rute API, Autentikasi & Pekerjaan Terjadwal (/api/*, /keluar)

Section titled “2.1 Rute API, Autentikasi & Pekerjaan Terjadwal (/api/*, /keluar)”
Metode & Path Auth & Keamanan Input / Query / Body Respons & Perilaku
GET /api/sehat Publik (tanpa auth, no-store) — 200 { ok: true }. Dipakai Docker HEALTHCHECK & monitor uptime
GET /api/auth/google/start Publik Query: no (No. Serdik), next (opsional, disaring safeNext) Membuat state, nonce, PKCE verifier; set cookie sv_oauth (10 mnt, path /api/auth/google); redirect ke Google OAuth
GET /api/auth/google/callback Cookie sv_oauth + OIDC token exchange Query: code, state, error Verifikasi state & klaim ID token; memanggil aktivasiGoogle(); set sv_session baru; hapus sv_oauth; redirect ke /ganti-pin
GET / POST /api/cron/pengingat Header Authorization: Bearer <CRON_SECRET> (timingSafeEqual, min. 24 char) — Menjalankan kirimPengingat() (tahap 6, 3, 1 jam form/polling wajib). 401 jika secret tidak valid; 200 { ok: true, terkirim }
GET / POST /api/cron/email Header Authorization: Bearer <CRON_SECRET> (maxDuration = 120) — Menjalankan antreRingkasanHarian() (>= 07.00 WIB) lalu kirimAntrean(). 200 { ok: true, ringkasanDiantre, terkirim, gagal, sisa, dilewati?, tertahan?, galat? }
POST /api/push sv_session + cek same-origin via Origin vs asalPermintaan() JSON Zod: { endpoint (https://), keys: { p256dh, auth } } Upsert langganan Web Push perangkat ke pengguna aktif (403 beda origin, 401 anonim, 400 invalid)
DELETE /api/push sv_session + cek same-origin JSON: { endpoint: string } Menghapus langganan Web Push milik pengguna untuk endpoint tersebut
POST /keluar Cookie sv_session (SameSite=Lax; metode lain ditolak 405) — Mencabut sesi di DB, menghapus cookie sv_session (maxAge: 0), redirect 303 ke <origin>/masuk

2.2 Rute Media Berotorisasi & Ekspor Excel (7 Rute)

Section titled “2.2 Rute Media Berotorisasi & Ekspor Excel (7 Rute)”
Metode & Path Auth & Otorisasi Respons & Header Khusus
GET /aspirasi-gambar/[kode]/[id] Login + (pengirim atau izin("aspirasi"); untuk foto bukti eventId juga semua pengguna login bila isPublik = true); lain → 404 Bytes gambar (Content-Type asli dari DB), Cache-Control: private, max-age=3600, X-Content-Type-Options: nosniff, Content-Security-Policy: default-src 'none'
GET /form-banner/[kode] Login + (pengelola peran form atau Serdik target saat form efektif TERBUKA/DITUTUP); lain → 404 Bytes banner (Cache-Control: private, max-age=86400, nosniff, CSP: default-src 'none')
GET /hackathon-gambar/[kode]/[id] Login + (anggota tim saat SUBMISI; semua login sejak PENILAIAN); lain → 404 Bytes tangkapan layar (Cache-Control: private, max-age=3600, nosniff, CSP: default-src 'none')
GET /kelola/form/[kode]/export requireIzin("form") + kepemilikan peranId .xlsx (no-store); form rahasia tanpa kolom identitas sama sekali
GET /kelola/polling/[kode]/export requireIzin("polling") + kepemilikan peranId .xlsx (no-store); sheet Rekap, Per Grup-Elemen, dan Responden (hanya jika anonim = false)
GET /kelola/hackathon/[kode]/excel requireIzin("hackathon") + kepemilikan peranId (mulai REKAP) .xlsx (no-store); sheet Peringkat, Nilai juri, Kriteria; 409 jika tahap sebelum REKAP
GET /lemusdik/aspirasi/export requireIzin("aspirasi") + query filter LemusdikFilter .xlsx (no-store, maks. 5000 baris); pengirim isRahasia selalu ditulis "Rahasia" pada kolom Pengirim, Grup, Elemen
GET /profil/privasi/unduh getCurrentUser() (401 bila belum login) .xlsx (no-store) berisi 6 sheet data pribadi milik pengguna tersebut (data-saya-<noSerdik>.xlsx)

3. Katalog Lengkap Server Actions (94 Aksi di 24 Berkas)

Section titled “3. Katalog Lengkap Server Actions (94 Aksi di 24 Berkas)”

Semua mutasi UI dijalankan melalui Next.js Server Actions dengan batas ukuran payload serverActions.bodySizeLimit = "4mb" (next.config.ts).

3.1 Autentikasi & Profil Dasar (masuk, aktivasi, ganti-pin, notifikasi, profil)

Section titled “3.1 Autentikasi & Profil Dasar (masuk, aktivasi, ganti-pin, notifikasi, profil)”
Berkas (di bawah src/app/) Fungsi Diekspor Penjaga & Catatan
masuk/actions.ts loginAction(prev, formData), devLoginAction(noSerdik) loginAction: throttle IP + lockout akun; devLoginAction: hanya jika isDevLoginEnabled()
aktivasi/actions.ts mintaKodeAction(prev, form), verifikasiKodeAction(prev, form) OTP 6 angka via email, langsung membuat sesi wajib ganti PIN
ganti-pin/actions.ts gantiPinAction(prev, formData) requireUser({ allowMustChange: true }), mencabut sesi lain
notifikasi/actions.ts markAllReadAction(), markReadAction(id) requireUser(), hanya menyentuh notifications milik user.id
profil/ganti-pin/actions.ts gantiPinProfilAction(prev, formData) requireUser(), memverifikasi PIN saat ini dengan mekanisme lockout
profil/laporkan/actions.ts kirimLaporanAction(input) requireUser(), batas 5/24 jam, jeda 30 dtk, melampirkan info teknis tanpa PII rahasia
profil/pengaturan-actions.ts setHackathonTampilAction(tampil), mintaKodeGantiEmailAction(email), konfirmasiGantiEmailAction(kode) setHackathonTampilAction: requireAdmin(); ganti email: requireUser()
profil/privasi/actions.ts setujuiAction(next), nantiAction(next), tarikAction(), kirimPermintaanAction(prev, form) requireUser(), mengelola persetujuan & permintaan_data (maks. 3/24 jam)

3.2 Partisipasi Serdik (aspirasi, form, polling, hackathon)

Section titled “3.2 Partisipasi Serdik (aspirasi, form, polling, hackathon)”

Seluruh aksi tulis peserta di bawah ini menegakkan pemeriksaan requireUser() dan pesanHanyaBaca(user.id) (menolak akun yang belum menyetujui Ketentuan Penggunaan Data):

Berkas (di bawah src/app/(app)/) Fungsi Diekspor
aspirasi/kirim/actions.ts kirimAction(prev, form) — wajib centang pernyataan itikad baik, maks. 5/hari WIB, maks. 3 gambar
aspirasi/[kode]/actions.ts keteranganAction(kode, prev, form) — mengirim KETERANGAN & menghapus flag mintaKeterangan
form/[kode]/actions.ts kirimFormAction(kode, answers), tandaiSelesaiAction(kode), batalkanTandaAction(kode)
polling/actions.ts pilihAction(kode, pilihan), batalPilihAction(kode)
hackathon/actions.ts buatTimAction(kode, prev, form), ubahNamaTimAction(timId, prev, form), tambahAnggotaAction(timId, prev, form), hapusAnggotaAction(timId, userId), keluarTimAction(timId), hapusTimAction(timId), simpanSubmisiAction(timId, kode, prev, form), beriBintangAction(submisiId, jumlah), hapusBintangAction(submisiId), simpanNilaiAction(submisiId, payload)

3.3 Manajemen Konten & Administrasi (kelola/*, lemusdik/*, admin/*)

Section titled “3.3 Manajemen Konten & Administrasi (kelola/*, lemusdik/*, admin/*)”
Berkas (di bawah src/app/(app)/) Izin Wajib Fungsi Diekspor
kelola/form/actions.ts requireIzin("form") buatFormAction, simpanPengaturanAction, simpanSkemaAction, terbitkanAction, tutupAction, bukaKembaliAction, duplikatAction, hapusFormAction, sembunyikanFormAction, jadikanTemplateAction, hapusTemplateAction, simpanBannerAction, hapusBannerAction, pratinjauImporAction, simpanImporAction (15 aksi)
kelola/polling/actions.ts requireIzin("polling") buatPollingAction, jadikanTemplatePollingAction, hapusTemplatePollingAction, simpanPollingAction, terbitkanPollingAction, tutupPollingAction, bukaKembaliPollingAction, duplikatPollingAction, hapusPollingAction, sembunyikanPollingAction, pratinjauImporAction, simpanImporAction (12 aksi)
kelola/hackathon/actions.ts requireIzin("hackathon") buatHackathonAction, ubahHackathonAction, aturBidangAction, aturJuriAction, pindahTahapAction, umumkanAction, tampilBerandaAction (7 aksi)
lemusdik/aspirasi/[kode]/actions.ts requireIzin("aspirasi") ubahStatusAction, prioritasAction, publikasiAction, batalPublikasiAction, tandaiAction, mintaKeteranganAction (6 aksi)
lemusdik/aspirasi/impor/actions.ts requireIzin("aspirasi") pratinjauAspAction, simpanAspAction (2 aksi)
lemusdik/kategori/actions.ts requireIzin("aspirasi") tambahKategoriAction, gantiNamaAction, pindahKategoriAction, aktifKategoriAction (4 aksi)
admin/serdik/actions.ts requireIzin("dataUser") atau requireAdmin() dataUser: resetPinAction, lepasEmailAction, unlockAction, updateUserAction, aturEmailAction. Admin: setRolesAction, setActiveAction, bulkResetAction (8 aksi)
admin/peran/actions.ts requireAdmin() simpanPeranAction, aktifPeranAction, pemegangAction (3 aksi)
admin/impor/actions.ts requireAdmin() previewImportAction, confirmImportAction (2 aksi)
admin/laporan/actions.ts requireAdmin() ubahStatusAction (1 aksi)
admin/permintaan-data/actions.ts requireAdmin() ubahPermintaanAction (1 aksi)

4. Kontrak Impor Berkas Excel & CSV (features/impor & features/admin/import)

Section titled “4. Kontrak Impor Berkas Excel & CSV (features/impor & features/admin/import)”
Fitur Impor Batas Berkas & Baris Pengenalan Kolom & Aturan Pencocokan
Data Serdik (admin/import/parse.ts) .xlsx / .csv, maks. 1 MB, maks. 1.000 baris, proteksi zip-bomb maks. 20 MB tak terkompresi Kolom wajib: NAMA, GRUP (1–4, menerima "Grup 1"), ELEMEN (1–3, menerima "Elemen 2"), NO SERDIK (1–400). Opsional: KELAS (<= 20 char), EMAIL* (menerima "Email SBM ITB"). Upsert by noSerdik; tidak menimpa email/PIN lama; akun baru menghasilkan pin-awal-*.xlsx.
Form & Survei (features/impor/form.ts) .xlsx / .csv, maks. 3 MB, maks. 2.000 baris, maks. 25 kolom pertanyaan Mengenali kolom Timestamp/Waktu, Email/Email Address, No. Serdik; sisanya pertanyaan dengan tebakan jenis otomatis (LIKERT, TANGGAL, CENTANG, PILIHAN, SINGKAT, PARAGRAF). Target hasil: DRAF, ARSIP (diimpor=true, tertutup), atau TEMPLATE. Serdik ganda mengambil baris terbaru; tanpa identitas bisa disimpan (userId=null, grup=0, elemen=0) atau dilewati.
Polling (features/impor/polling.ts) .xlsx / .csv, maks. 3 MB, maks. 2.000 baris, tepat 1 kolom pertanyaan, 2–6 opsi unik (<= 80 char) Mendukung mode SATU dan BANYAK (dipisah , ). Target hasil: DRAF, ARSIP, atau TEMPLATE.
Aspirasi Lama (features/impor/aspirasi.ts) .xlsx / .csv, maks. 3 MB, maks. 2.000 baris Kolom wajib: Isi/Aspirasi. Opsional: Waktu, Email/No. Serdik, Judul, Jenis, Kategori, Status, Rahasia. Baris tanpa identitas dapat disimpan rahasia atas nama pengimpor atau dilewati; diimpor=true (hanya terlihat pengelola).
Layanan Protokol & Endpoint Konfigurasi & Penanganan Kegagalan
Google OIDC HTTPS ke https://accounts.google.com/o/oauth2/v2/auth & POST https://oauth2.googleapis.com/token Memakai GOOGLE_CLIENT_ID & GOOGLE_CLIENT_SECRET, scope openid email, code_challenge_method=S256. Jika env kosong, tombol Google menampilkan galat konfigurasi dan jalur kode email / PIN tetap berjalan.
Web Push (VAPID) Protokol Web Push (web-push v3) Memakai NEXT_PUBLIC_VAPID_PUBLIC_KEY (ditanam saat docker build), VAPID_PRIVATE_KEY, VAPID_SUBJECT. Pengiriman per batch 20 langganan; status 404/410 otomatis menghapus endpoint kedaluwarsa dari push_subscriptions.
Hostinger SMTP SMTP TLS (nodemailer v10, port 465, maxConnections: 1, socketTimeout: 20_000) Memakai SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASS, EMAIL_FROM. Filter EMAIL_IZINKAN membatasi penerima di dev. Rate limit 421/451/452 menjeda antrean 30 menit tanpa mengurangi jatah percobaan (MAKS_PERCOBAAN = 3).
Neon PostgreSQL TLS TCP Postgres 16 via @prisma/adapter-pg (pg pooler & direct unpooled) DATABASE_URL untuk trafik runtime aplikasi; DATABASE_URL_UNPOOLED + schema=public untuk prisma migrate deploy dan setup.ts.