Skip to content

Standar Rekayasa Perangkat Lunak & Pengujian — Soedirman Digital Repository (SDR)

Field Nilai
ID Dokumen SDR-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 AGENTS.md, package.json, tsconfig.json, eslint.config.mjs, .github/workflows/ci-deploy.yml, scripts/*

1. Konvensi Basis Kode & Aturan Next.js 16

Section titled “1. Konvensi Basis Kode & Aturan Next.js 16”
  • TypeScript Strict Mode (tsconfig.json): "strict": true, target "ES2017", resolusi modul "bundler", JSX "react-jsx", serta alias impor tunggal "@/*": ["./*"] (tidak menggunakan folder src/).
  • ESLint (eslint.config.mjs): Menggunakan konfigurasi flat ESLint v9 dengan preset eslint-config-next/core-web-vitals dan eslint-config-next/typescript, mengecualikan .next/**, out/**, build/**, dan next-env.d.ts.

Sesuai peringatan AGENTS.md yang dikelola oleh next dev, Next.js 16.4.5 memiliki konvensi khusus yang wajib dipatuhi pengembang:

  1. Request Proxy (proxy.ts) menggantikan middleware.ts: Ekspor fungsi proxy(request: NextRequest) dan objek config.matcher di root proyek.
  2. Dynamic APIs Asinkron: Pada Server Component App Router (page.tsx dan generateMetadata), params dan searchParams bertipe Promise<...> sehingga wajib di-await sebelum diakses.
  3. Referensi Lokal Terpadu: Sebelum memakai API Next.js baru, rujuk dokumentasi versi terpasang di node_modules/next/dist/docs/.
  4. Penandaan Server-Side: Modul sensitif tidak boleh diimpor dari komponen "use client"; gunakan server-only dan batas Server Actions.
  • Antarmuka pengguna (UI), pesan validasi Zod, serta dokumentasi: Menggunakan Bahasa Indonesia yang baku, jelas, dan konsisten.
  • Simbol kode (nama variabel, fungsi, model Prisma, skrip): Menggunakan Bahasa Inggris (camelCase untuk fungsi/variabel, PascalCase untuk komponen/model, kebab-case untuk slug dan file skrip).

Branch utama produksi adalah master. Setiap pull request maupun push ke master memicu workflow .github/workflows/ci-deploy.yml dengan gerbang verifikasi pada job verify (ubuntu-24.04, Node.js 24):

flowchart LR
    PR["Push / Pull Request ke master"] --> G1["bash -n scripts/deploy-server.sh"]
    G1 --> G2["npm ci & db:generate & db:validate"]
    G2 --> G3["npm run typecheck (tsc --noEmit)"]
    G3 --> G4["npm run lint (advisory / continue-on-error)"]
    G4 --> G5["npm audit --omit=dev --audit-level=high"]
    G5 --> G6["Gitleaks v8.24.2 Secret Scan"]
    G6 --> G7["Docker Build sdr-ci:SHA"]
    G7 -->|"Hanya push ke master"| CD["Job Deploy via SSH ke VPS Produksi"]
Gerbang Kualitas Perintah Sifat Kegagalan
Validasi sintaks skrip deploy bash -n scripts/deploy-server.sh Blocking
Generasi & validasi skema Prisma npm run db:generate && npm run db:validate Blocking
Pemeriksaan tipe TypeScript npm run typecheck Blocking
Pemeriksaan linter Next.js npm run lint Advisory (continue-on-error: true)
Audit kerentanan dependensi produksi npm audit --omit=dev --audit-level=high Blocking
Pemindaian kebocoran rahasia Git ghcr.io/gitleaks/gitleaks:v8.24.2 Blocking
Verifikasi build container produksi docker build --build-arg NEXT_PUBLIC_SITE_URL=https://repo.p3mdi.id -f Dockerfile . Blocking

3. Perintah Pengembangan, Verifikasi, dan Pemeliharaan

Section titled “3. Perintah Pengembangan, Verifikasi, dan Pemeliharaan”
Perintah Target Eksekusi Kegunaan
npm run dev next dev Menjalankan server pengembangan lokal
npm run build prisma generate && prisma migrate deploy && next build Build produksi penuh disertai deploy migrasi
npm run start next start Menjalankan hasil build produksi
npm run typecheck tsc --noEmit Memeriksa seluruh tipe TypeScript
npm run lint eslint Menjalankan pemeriksaan ESLint
npm run db:validate prisma validate Memvalidasi sintaks prisma/schema.prisma
npm run db:generate prisma generate Menghasilkan Prisma Client ke generated/prisma/
npm run db:migrate prisma migrate dev Membuat dan menerapkan migrasi pengembangan
npm run db:deploy prisma migrate deploy Menerapkan migrasi tertunda di lingkungan target
npm run db:seed tsx prisma/seed.ts Menjalankan seeding kategori, Super Admin, dan demo (dev)
npm run db:create-admin tsx scripts/create-admin.ts Membuat/memperbarui akun SUPER_ADMIN dari env
npm run db:check tsx scripts/check-db.ts Menampilkan ringkasan isi tabel database
npm run db:studio prisma studio Membuka antarmuka web Prisma Studio

3.2 Katalog Skrip Verifikasi & Pengujian (scripts/*.ts)

Section titled “3.2 Katalog Skrip Verifikasi & Pengujian (scripts/*.ts)”

Proyek menyediakan skrip verifikasi deterministik berbasis tsx yang menguji database PostgreSQL nyata, hash Argon2id, query publik, otorisasi Server Actions, serta pemrosesan gambar:

Skrip Cara Menjalankan Cakupan Pengujian
scripts/security-audit.ts npx tsx scripts/security-audit.ts Memeriksa .gitignore, memindai .next/static/**/*.js dari kebocoran env sensitif, dan memvalidasi 5 security header di next.config.ts.
scripts/test-admin-system.ts npx tsx scripts/test-admin-system.ts Menguji lookup superadmin case-insensitive, verifikasi Argon2id, pembuatan akun ADMIN, audit log, deaktivasi + increment sessionVersion, proteksi Super Admin aktif terakhir, reset sandi, dan isolasi log global vs pribadi.
scripts/verify-phase1.ts npx tsx scripts/verify-phase1.ts Memverifikasi koneksi SELECT 1, 6 kategori awal, akun admin seed Argon2id, relasi repositori-screenshot, 5 indeks kustom PostgreSQL, dan penolakan duplikat lower(name).
scripts/verify-phase2.ts npx tsx scripts/verify-phase2.ts Memverifikasi query listFeaturedRepositories, listPublishedRepositories (paginasi, search, filter kategori), detail by slug, isolasi DRAFT, hitungan kategori, dan karya terkait.
scripts/verify-phase3.ts npx tsx scripts/verify-phase3.ts Menguji verifikasi Argon2id, timing defense dummy hash, rate limiter (5 gagal -> lockout -> reset), penolakan UNAUTHORIZED pada 5 aksi admin anonim, proteksi RESTRICT kategori, dan pengecekan sessionVersion.
scripts/verify-phase4.ts npx tsx scripts/verify-phase4.ts Menguji magic-byte sniffing + konversi WebP sharp, penolakan file MZ..., isolasi draft, publikasi, reorder screenshot, dan soft delete. (Catatan: Uji 3 pada verify-phase4.ts mengharapkan validasi wajib coverUrl/screenshots dari fase awal, sedangkan repositoryPublishSchema saat ini membolehkan publikasi tanpa cover/screenshot demi mendukung entri tautan & Formulir.)
scripts/verify-phase5.ts npx tsx scripts/verify-phase5.ts Menguji perjalanan pengunjung publik, isolasi draft/terhapus, penolakan anonim pada 9 Server Action admin, sanitasi XSS (sanitizeOverview), penolakan skema URL berbahaya (javascript:, data:, file:), penolakan file palsu, serta validasi sitemap.ts & robots.ts.

3.3 Skrip Pemeliharaan & Operasional (scripts/*.ts & .sh)

Section titled “3.3 Skrip Pemeliharaan & Operasional (scripts/*.ts & .sh)”
Skrip Fungsi
scripts/media-cleanup.ts Menghapus objek dan baris media_uploads yatim (repositoryId: null, usia > 24 jam) serta baris auth_rate_limits kedaluwarsa (> 24 jam). Default dry-run; gunakan --apply untuk eksekusi.
scripts/repositories-purge.ts Menghapus permanen repositori soft-deleted melewati REPOSITORY_RETENTION_DAYS (default 30 hari) beserta seluruh file media terkait. Default dry-run; gunakan --apply untuk eksekusi.
scripts/migrate-admin-v2.ts Utilitas migrasi satu kali (idempoten) untuk menaikkan tabel admins versi awal ke skema RBAC multi-admin dan audit_logs.
scripts/deploy-server.sh Skrip Continuous Deployment produksi di VPS (/usr/local/sbin/sdr-deploy).

ADR-001: Arsitektur Monolit Modular Next.js App Router

Section titled “ADR-001: Arsitektur Monolit Modular Next.js App Router”
  • Konteks: Sistem perlu melayani katalog publik SEO-friendly sekaligus panel kurasi admin tanpa menambah kompleksitas infrastruktur layanan mikro atau broker antrean.
  • Keputusan: Mengimplementasikan seluruh UI publik, panel admin, Server Actions, Route Handlers, dan layanan domain dalam satu aplikasi Next.js 16 (Dockerfile tunggal) dengan batas modul tegas di lib/.
  • Konsekuensi: Deployment dan sinkronisasi tipe TypeScript dari PostgreSQL hingga komponen UI sangat cepat dan sederhana; namun seluruh beban kerja (termasuk pemrosesan sharp) berjalan dalam proses Node.js yang sama sehingga batas ukuran unggahan dijaga pada 5 MB.

ADR-002: Pencarian Katalog Berbasis PostgreSQL pg_trgm dan Kolom search_text

Section titled “ADR-002: Pencarian Katalog Berbasis PostgreSQL pg_trgm dan Kolom search_text”
  • Konteks: Katalog memerlukan pencarian case-insensitive pada judul, deskripsi singkat, nama pengembang, tag, dan teknologi tanpa mengoperasikan engine pencarian terpisah (Elasticsearch/Meilisearch).
  • Keputusan: Menggunakan kolom terdenormalisasi repositories.search_text yang diperbarui setiap kali karya disimpan (buildSearchText), diindeks dengan indeks GIN gin_trgm_ops (pg_trgm), dan dipadukan dengan kondisi OR pada query Prisma.
  • Konsekuensi: Nol dependensi infrastruktur tambahan dan konsistensi baca langsung setelah transaksi penyimpanan selesai.

ADR-003: Elemen Native <dialog> & Sistem Desain Terpadu P3MDI

Section titled “ADR-003: Elemen Native <dialog> & Sistem Desain Terpadu P3MDI”
  • Konteks: Draft MVP awal mengusulkan tema gelap Steam-like, shadcn/ui, @tiptap, @dnd-kit, dan sonner. Dalam implementasi akhir, aplikasi harus seragam dengan identitas portal P3MDI (#14254d / #c9a227) serta menjaga ukuran bundle klien tetap ringan.
  • Keputusan: Membangun token desain P3MDI di app/globals.css, membungkus <dialog> native lewat ModalDialog & ConfirmDialog, menyusun pengurutan screenshot dengan tombol terakses (ScreenshotManager), dan memakai umpan balik status inline role="status" / role="alert".
  • Konsekuensi: Mengurangi dependensi pihak ketiga secara drastis, meningkatkan kepatuhan fokus trap dan Esc bawaan browser, serta menjaga konsistensi visual lintas aplikasi P3MDI.

ADR-004: Adapter Penyimpanan Ganda S3-Kompatibel dengan Fallback Disk Lokal

Section titled “ADR-004: Adapter Penyimpanan Ganda S3-Kompatibel dengan Fallback Disk Lokal”
  • Konteks: Pengembangan lokal sering berjalan tanpa container MinIO aktif, sementara produksi membutuhkan objek S3-kompatibel.
  • Keputusan: lib/storage/s3-adapter.ts mencoba PutObjectCommand via @aws-sdk/client-s3 terlebih dahulu dan secara otomatis beralih menulis ke public/uploads/{storageKey} saat menerima galat koneksi (ECONNREFUSED, TimeoutError, fetch failed). Penghapusan (deleteStorageObject) membersihkan keduanya secara aman.
  • Konsekuensi: Developer lokal dapat menguji unggahan gambar segera setelah npm run dev tanpa setup MinIO, sedangkan produksi tetap memanfaatkan bucket S3/MinIO yang dikonfigurasi lewat env.

ADR-005: Unggahan Gambar Diproksikan Melalui Server (POST /api/uploads)

Section titled “ADR-005: Unggahan Gambar Diproksikan Melalui Server (POST /api/uploads)”
  • Konteks: Kredensial S3 tidak boleh terekspos ke klien dan setiap berkas wajib lolos pemeriksaan magic bytes serta pelucutan metadata EXIF sebelum dipublikasikan.
  • Keputusan: Semua unggahan dikirim sebagai multipart/form-data ke POST /api/uploads, diautentikasi dengan requireAdmin(false), divalidasi sniffImageFormat(), diproses dengan sharp menjadi WebP tanpa EXIF, baru diunggah ke penyimpanan dengan nama berkas UUID server-side.
  • Konsekuensi: Berkas berbahaya (seperti SVG berisikan skrip atau executable berkedok .png) dan data GPS EXIF tertolak sebelum menyentuh storage maupun database.