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 Galat Standar
Section titled “Kode Galat Standar”| 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). |
5. Integrasi Layanan Eksternal
Section titled “5. Integrasi Layanan Eksternal”| 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. |