| 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/* |
- 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:
- Request Proxy (
proxy.ts) menggantikan middleware.ts: Ekspor fungsi proxy(request: NextRequest) dan objek config.matcher di root proyek.
- Dynamic APIs Asinkron: Pada Server Component App Router (
page.tsx dan generateMetadata), params dan searchParams bertipe Promise<...> sehingga wajib di-await sebelum diakses.
- Referensi Lokal Terpadu: Sebelum memakai API Next.js baru, rujuk dokumentasi versi terpasang di
node_modules/next/dist/docs/.
- 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 |
| 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 |
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. |
| 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). |
- 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.
- 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.
- 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.
- 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.
- 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.