Skip to content

Spesifikasi Antarmuka & Server Actions — Soedirman Digital Repository (SDR)

Field Nilai
ID Dokumen SDR-API-001
Pilar Rekayasa Perangkat Lunak
Standar Acuan Interface Control Document (ICD) / IEEE 830
Status Aktif / Tersinkronisasi dengan Kode
Terakhir Diperbarui 2026-11-21
Sumber Kebenaran app/api/**, app/s/[alias]/page.tsx, proxy.ts, lib/actions/*.ts, lib/validations/*.ts, lib/repositories/public-queries.ts, lib/repositories/admin-service.ts

SDR tidak mengekspos REST API CRUD publik yang terbuka untuk mutasi; seluruh operasi baca katalog dieksekusi langsung di React Server Components melalui modul query terisolasi, sedangkan seluruh operasi tulis dijalankan melalui Next.js Server Actions (lib/actions/*.ts) dan tiga HTTP Route Handlers (app/api/**) ditambah satu rute pengalihan tautan pendek (/s/[alias]).

flowchart LR
    C["Client Components / Browser"] -->|"GET /api/health"| H["Health Handler"]
    C -->|"GET/POST /api/auth/*"| A["Auth.js Handler"]
    C -->|"POST /api/uploads (multipart)"| U["Upload Handler"]
    C -->|"GET /s/[alias] / go.p3mdi.id/[alias]"| S["Shortlink Redirector"]
    C -->|"RPC Server Actions"| SA["lib/actions/*.ts"]
    SA -->|"Validasi Zod + Guard + Audit + Revalidate"| DB[("PostgreSQL")]
    U -->|"Magic Bytes + Sharp WebP + S3/Disk"| ST[("Storage + MediaUpload")]

2.1 GET /api/health (app/api/health/route.ts)

Section titled “2.1 GET /api/health (app/api/health/route.ts)”

Digunakan oleh scripts/deploy-server.sh dan probe kesiapan kontainer.

  • Autentikasi: Publik (tanpa sesi).
  • Konfigurasi: dynamic = "force-dynamic", header Cache-Control: no-store, max-age=0.
  • Logika: Menjalankan prisma.$queryRaw dengan kueri SELECT 1.
  • Respons:
    • 200 OK: { "status": "ok", "timestamp": "<ISO-8601>" }
    • 503 Service Unavailable: { "status": "error" }

2.2 GET / POST /api/auth/[...nextauth] (app/api/auth/[...nextauth]/route.ts)

Section titled “2.2 GET / POST /api/auth/[...nextauth] (app/api/auth/[...nextauth]/route.ts)”

Endpoint internal Auth.js v5 (next-auth ^5.0.0-beta.32) yang mengekspor handlers (GET, POST) dari lib/auth/auth.ts (CSRF token, callback sesi JWT, serta endpoint sign-in/sign-out).

2.3 POST /api/uploads (app/api/uploads/route.ts)

Section titled “2.3 POST /api/uploads (app/api/uploads/route.ts)”

Endpoint unggahan berkas gambar terautentikasi yang memproksikan pemrosesan gambar di sisi server.

  • Autentikasi: Wajib sesi admin aktif (await requireAdmin(false)). Mengembalikan 401 Unauthorized jika belum masuk atau sesi dicabut.
  • Request Body (multipart/form-data):
    • file (wajib, File): Berkas JPEG, PNG, atau WebP.
    • kind (opsional, string): "COVER" | "BANNER" | "SCREENSHOT" (default "SCREENSHOT" jika tidak bernilai COVER/BANNER).
  • Validasi & Batasan:
    • content-length tidak boleh melebihi UPLOAD_MAX_BYTES * 1.5.
    • file.size tidak boleh melebihi UPLOAD_MAX_BYTES (default 5242880 byte / 5 MB).
    • Magic-byte sniffing (sniffImageFormat), batas 50 MP, strip EXIF, resize maksimal 2560px, dan konversi ke WebP (quality: 85).
  • Respons:
    • 200 OK:
      {
      "ok": true,
      "data": {
      "id": "uuid",
      "storageKey": "repositories/2026/11/cover-uuid.webp",
      "publicUrl": "https://.../repositories/2026/11/cover-uuid.webp",
      "width": 1280,
      "height": 720,
      "sizeBytes": 48120,
      "kind": "COVER"
      }
      }
    • 401 Unauthorized: { "ok": false, "error": "Akses tidak diizinkan. Silakan login sebagai administrator." }
    • 400 Bad Request: { "ok": false, "error": "<pesan galat validasi/format/ukuran>" }

2.4 GET /s/[alias] & Domain go.p3mdi.id (app/s/[alias]/page.tsx & proxy.ts)

Section titled “2.4 GET /s/[alias] & Domain go.p3mdi.id (app/s/[alias]/page.tsx & proxy.ts)”
  • Mekanisme Domain (proxy.ts): Permintaan ke hostname go.p3mdi.id (atau variabel SHORTLINK_HOSTNAME) selain /_next, /api, /images, /favicon, /s/ akan di-rewrite secara internal menjadi /s/<alias> (sementara / dialihkan ke NEXTAUTH_URL atau https://p3mdi.id).
  • Logika (app/s/[alias]/page.tsx):
    1. Menormalisasi alias via normalizeAlias(alias) (trim().toLowerCase()).
    2. Mengambil record short_links berdasarkan alias unik.
    3. Jika tidak ditemukan -> merender UI "Tautan tidak ditemukan".
    4. Jika isActive === false -> merender UI "Tautan dinonaktifkan".
    5. Jika aktif -> menaikkan clickCount ({ increment: 1 }) lalu memanggil redirect(shortLink.originalUrl).

Seluruh Server Action menggunakan pola nilai kembalian terstruktur agar Client Component dapat memetakan pesan status dan error per kolom formulir secara konsisten tanpa melempar exception yang tidak tertangani ke UI:

lib/actions/repository-actions.ts
export interface ActionResult<T = void> {
ok: boolean;
message?: string;
error?: string;
fieldErrors?: Record<string, string[]>;
data?: T;
}

(Varian identik digunakan oleh AdminActionResult, ShortLinkActionResult, SubmissionActionResult<T>, dan SystemSettingResult; sedangkan loginAction mengembalikan LoginActionState { ok: boolean; error?: string }.)


4. Katalog Lengkap Server Actions (lib/actions/*.ts)

Section titled “4. Katalog Lengkap Server Actions (lib/actions/*.ts)”

4.1 Autentikasi (lib/actions/auth-actions.ts)

Section titled “4.1 Autentikasi (lib/actions/auth-actions.ts)”
Fungsi Signature & Input Otorisasi Audit Trail Efek & Redirect
loginAction (prevState: LoginActionState | null, formData: FormData) => Promise<LoginActionState> (username, password) Publik ADMIN_LOGIN_SUCCESS / ADMIN_LOGIN_FAILED Memanggil signIn("credentials", { username, password, redirectTo: "/admin" }). Mengembalikan pesan khusus untuk RATE_LIMITED atau pesan generik "Username atau kata sandi tidak valid."
logoutAction () => Promise<void> Opsional (getOptionalAdmin()) ADMIN_LOGOUT Menaikkan admins.sessionVersion (increment: 1) lalu memanggil signOut({ redirectTo: "/admin/login" }).

4.2 Pengelolaan Karya Repositori (lib/actions/repository-actions.ts)

Section titled “4.2 Pengelolaan Karya Repositori (lib/actions/repository-actions.ts)”
Fungsi Signature Guard Validasi / Aturan Audit Action Revalidasi Path
createRepositoryAction (payload: unknown) => Promise<ActionResult<{ id: string; slug: string }>> requireAdmin(false) repositoryPublishSchema jika status === "PUBLISHED", selainnya repositoryDraftSchema; cek unik slug aktif REPOSITORY_CREATED (di admin-service.ts) /, /repositories, /repositories/[slug], /admin/repositories, /admin
updateRepositoryAction (id: string, payload: unknown) => Promise<ActionResult<{ id: string; slug: string }>> requireAdmin(false) Skema Draft/Publish, cek bentrok slug, ganti daftar RepositoryScreenshot, tautkan MediaUpload REPOSITORY_UPDATED (di admin-service.ts) /, /repositories, /repositories/[slug-lama & baru], /admin/repositories, /admin
deleteRepositoryAction / softDeleteRepository (repositoryId: string) => Promise<ActionResult> requireAdmin(false) Mengisi deletedAt = new Date(), menyetel isFeatured = false REPOSITORY_DELETED /, /repositories, /repositories/[slug], /admin/repositories, /admin
removeUploadAction (storageKey: string) => Promise<ActionResult> requireAdmin(false) Memastikan upload.uploadedById === admin.id; menghapus dari S3/disk dan media_uploads — —
togglePublicationStatus (repositoryId: string, currentStatus: RepositoryStatus) => Promise<ActionResult> requireAdmin(false) Sebelum DRAFT -> PUBLISHED: wajib punya title, slug, shortDescription, categoryId, developerName; mengisi publishedAt bila masih null REPOSITORY_PUBLISHED / REPOSITORY_UNPUBLISHED /admin/repositories, /admin, /, /repositories, /repositories/[slug]
toggleFeaturedStatus (repositoryId: string, currentFeatured: boolean) => Promise<ActionResult> requireAdmin(false) Membalik isFeatured REPOSITORY_FEATURED / REPOSITORY_UNFEATURED /admin/repositories, /admin, /, /repositories

4.3 Manajemen Kategori (lib/actions/category-actions.ts)

Section titled “4.3 Manajemen Kategori (lib/actions/category-actions.ts)”
Fungsi Signature Guard Validasi & Aturan Audit Action Revalidasi Path
createCategory (formData: FormData) => Promise<ActionResult> (name, slug, description) requireAdmin(false) name wajib; slug otomatis dari name bila kosong; tolak duplikasi slug atau name case-insensitive CATEGORY_CREATED /admin/categories, /admin, /, /repositories
updateCategory (id: string, formData: FormData) => Promise<ActionResult> requireAdmin(false) name dan slug wajib; cek konflik dengan kategori lain (id !== id) CATEGORY_UPDATED /admin/categories, /admin, /, /repositories
deleteCategory (id: string) => Promise<ActionResult> requireAdmin(false) Diblokir apabila masih memiliki Repository aktif (deletedAt: null) CATEGORY_DELETED /admin/categories, /admin, /, /repositories

4.4 Pengajuan Karya Publik & Persetujuan (lib/actions/submission-actions.ts)

Section titled “4.4 Pengajuan Karya Publik & Persetujuan (lib/actions/submission-actions.ts)”
Fungsi Signature Guard Validasi & Aturan Audit Action Revalidasi Path
submitPublicRepository (rawInput: PublicSubmissionFormData) => Promise<SubmissionActionResult<{ id: string }>> Publik (tanpa auth) publicSubmissionSchema + verifikasi categoryId ada di DB; simpan status PENDING — (belum mencatat SUBMIT_REPOSITORY di action publik ini) /admin/submissions
approveSubmission (submissionId: string) => Promise<SubmissionActionResult> requireAdmin(false) Transaksi atomik: pastikan status PENDING, buat slug unik (-1, -2, … bila bentrok), buat Repository berstatus PUBLISHED, perbarui pengajuan menjadi APPROVED APPROVE_REPOSITORY /admin/submissions, /admin/repositories, /repositories, /
rejectSubmission (submissionId: string, rejectionReason?: string) => Promise<SubmissionActionResult> requireAdmin(false) Transaksi atomik: pastikan status PENDING, ubah ke REJECTED dan simpan rejectionReason opsional REJECT_REPOSITORY /admin/submissions
Section titled “4.5 Tautan Pendek (lib/actions/shortlink-actions.ts)”
Fungsi Signature Guard Validasi & Aturan Audit Action Revalidasi Path
createShortLink (data: { title, originalUrl, alias, isActive? }) => Promise<ShortLinkActionResult> requireAdmin(false) shortLinkSchema (termasuk daftar RESERVED_ALIASES), cek unik alias CREATE_SHORTLINK /admin/shortlinks
updateShortLink (id: string, data: { title, originalUrl, alias, isActive? }) => Promise<ShortLinkActionResult> requireAdmin(false) shortLinkSchema, cek bentrok alias (NOT: { id }) UPDATE_SHORTLINK /admin/shortlinks
toggleShortLinkStatus (id: string, currentStatus: boolean) => Promise<ShortLinkActionResult> requireAdmin(false) Membalik isActive UPDATE_SHORTLINK /admin/shortlinks
deleteShortLink (id: string) => Promise<ShortLinkActionResult> requireAdmin(false) Cek eksistensi lalu hapus permanen DELETE_SHORTLINK /admin/shortlinks

4.6 Manajemen Administrator & Akun (lib/actions/admin-management-actions.ts)

Section titled “4.6 Manajemen Administrator & Akun (lib/actions/admin-management-actions.ts)”
Fungsi Signature Guard Validasi & Aturan Audit Action Revalidasi Path
createAdminAccount (formData: FormData) => Promise<AdminActionResult> requireSuperAdmin(false) name (>= 2), username (3–32, ^[a-z0-9_-]+$, unik), password (>= 12), confirmPassword cocok; peran dipaksa AdminRole.ADMIN ADMIN_CREATED /admin/administrators
toggleAdminStatus (adminId: string) => Promise<AdminActionResult> requireSuperAdmin(false) Dilarang menonaktifkan diri sendiri maupun SUPER_ADMIN aktif terakhir; nonaktifkan menaikkan sessionVersion ADMIN_ACTIVATED / ADMIN_DEACTIVATED /admin/administrators
resetAdminPassword (adminId: string, formData: FormData) => Promise<AdminActionResult> requireSuperAdmin(false) newPassword >= 12 karakter & cocok dengan confirmPassword; menaikkan sessionVersion ADMIN_PASSWORD_RESET /admin/administrators
updateAccountCredentials (formData: FormData) => Promise<AdminActionResult> requireAdmin(false) Wajib verifikasi currentPassword (Argon2id); boleh mengubah newUsername (3–32, unik) dan/atau newPassword (>= 8 karakter, berbeda dari sandi lama) ADMIN_PROFILE_UPDATED dan/atau ADMIN_PASSWORD_CHANGED /admin/settings, /admin/administrators, /admin

4.7 Pengaturan Sistem (lib/actions/system-settings-actions.ts)

Section titled “4.7 Pengaturan Sistem (lib/actions/system-settings-actions.ts)”
Fungsi Signature Guard Validasi & Aturan Audit Action Revalidasi Path
getHomepageDisplayLimit () => Promise<number> Publik (helper server) Membaca system_settings.key = "homepage_display_limit", default 5 jika belum diset atau gagal parse — —
updateHomepageDisplayLimit (limit: number) => Promise<SystemSettingResult> requireAdmin(true) (halaman UI membatasi hanya untuk SUPER_ADMIN) Math.max(0, limit) (0 berarti tanpa batas / tampilkan semua) ADMIN_PASSWORD_CHANGED *(entityType "SystemSetting", metadata { limit, mode }) * /, /admin/settings

5. Kontrak Validasi Zod (lib/validations/*.ts)

Section titled “5. Kontrak Validasi Zod (lib/validations/*.ts)”
  • repositoryDraftSchema:
    • title: string trim, 3–120 karakter.
    • slug: string trim, 3–150 karakter, regex ^[a-z0-9]+(?:-[a-z0-9]+)*$.
    • shortDescription: string trim, maksimal 300 karakter (default "").
    • categoryId: string UUID valid.
    • developerWebsite, productUrl, sourceCodeUrl, demoUrl: safeUrlSchema (http: atau https: saja via isValidHttpUrl()).
    • screenshots: array screenshotItemSchema (imageUrl, storageKey, altText <= 255, sortOrder >= 0), maksimal 10 item.
  • repositoryPublishSchema: Memperluas repositoryDraftSchema dengan superRefine: saat status === PUBLISHED, mewajibkan shortDescription.trim().length >= 10 dan developerName.trim().length >= 2.
  • shortLinkSchema:
    • title: string trim, 2–120 karakter.
    • originalUrl: wajib diawali http:// atau https:// dan lolos isValidHttpUrl().
    • alias: string trim, 2–64 karakter, regex ^[a-zA-Z0-9_-]+$, dinormalisasi ke huruf kecil (normalizeAlias), dan ditolak bila termasuk dalam RESERVED_ALIASES (admin, api, repositories, categories, s, ajukan, login, logout, _next, favicon.ico, images, uploads, fonts, static, public, dashboard, auth, settings).
    • isActive: boolean (default true).
  • publicSubmissionSchema:
    • submitterName: 2–100 karakter.
    • submitterEmail: format email opsional (nullable / string kosong diizinkan).
    • title: 3–120 karakter.
    • shortDescription: 10–500 karakter.
    • categoryId: UUID valid.
    • repositoryUrl: wajib http:// atau https://.
    • sourceCodeUrl: safeUrlSchema opsional.
    • coverUrl, deadline: string opsional nullable.
    • techStack: array string (default []).

6. Antarmuka Query Publik (lib/repositories/public-queries.ts)

Section titled “6. Antarmuka Query Publik (lib/repositories/public-queries.ts)”

Seluruh fungsi berikut hanya membaca entri yang memenuhi status = PUBLISHED dan deletedAt = null:

Fungsi Parameter Perilaku & Logika Khusus
listPublishedRepositories { query?, categorySlug?, sort = "latest", page = 1, pageSize = 12 } Jika pageSize <= 0, menggunakan batas 1000 (dipakai beranda saat mode tanpa batas). Pada sort === "latest", secara otomatis mengangkat karya kategori Formulir (slug = "formulir" atau name = "formulir") yang memiliki deadline antara now hingga now + 72 jam ke urutan teratas, diurutkan dari tenggat terdekat.
listFeaturedRepositories limit = 8 Mengambil karya dengan isFeatured: true, urut publishedAt DESC, id DESC.
getPublishedRepositoryBySlug slug: string Mengambil detail lengkap beserta kategori dan screenshots urut sortOrder ASC; mengembalikan null jika tidak ditemukan atau masih draf.
listCategories — Mengambil semua kategori urut nama ASC lengkap dengan repositoryCount karya terpublikasi aktif.
getRelatedRepositories (currentRepositoryId, categoryId, limit = 4) Mengambil maksimal 4 karya lain pada kategori yang sama (id !== currentRepositoryId).