Panduan Developer

Dokumen ini untuk pengembang yang akan memelihara atau mengembangkan codebase talentasyskoo.

Stack Teknologi

Penting: Baca AGENTS.md — versi Next.js ini memiliki breaking changes dari versi yang umum diketahui. Dokumentasi internal ada di node_modules/next/dist/docs/.

Struktur Folder

src/
├── app/
│   ├── (public)/          # Portal publik + panduan
│   ├── admin/             # Dashboard admin
│   ├── guru/              # Portal guru
│   ├── orangtua/          # Portal orang tua
│   ├── login/             # Halaman login
│   ├── ppdb/              # PPDB publik
│   └── api/
│       ├── auth/          # next-auth handler
│       ├── cron/          # Cron tagihan
│       └── webhooks/      # Midtrans webhook
├── components/
│   ├── admin/             # AdminSidebar, dll.
│   ├── guru/
│   ├── orangtua/
│   ├── public/
│   └── panduan/
└── lib/
    ├── auth.ts            # next-auth config
    ├── prisma.ts          # Prisma singleton
    ├── notifikasi.ts      # Helper notifikasi
    ├── komunikasi.ts      # Quiet hours
    ├── penjemputan.ts     # JWT QR token
    ├── kantin.ts          # Utilitas kantin
    └── panduan.ts         # Reader markdown panduan

prisma/
├── schema.prisma              # Skema database
├── seed.ts                    # Seed utama (reset + orchestration)
├── seed-advanced.ts           # Multi-kurikulum, kamus kosakata
├── seed-observasi-modules.ts  # Observasi unified, intervensi, consent
├── seed-demo-features.ts      # Pelatihan guru, media, inventaris
├── seed-extended.ts           # Modul extended (RKAS, HRIS, dll.)
└── seed-keuangan.js

docs/
└── panduan/               # Sumber markdown user guide

Autentikasi & Otorisasi

Konfigurasi Auth

File: src/lib/auth.ts

• Provider: Credentials (email + password, bcrypt)
• Session strategy: JWT
• Callback menambahkan role dan id ke token/session

Middleware

File: src/middleware.ts

• Melindungi route /admin, /guru, /orangtua
• Redirect ke /login jika belum autentikasi
• Validasi role — admin tidak bisa akses portal guru, dll.

Role

Pola Pengembangan

Server Components (default)

Halaman di app/ umumnya Server Component — fetch data langsung via Prisma:

export default async function Page() {
  const data = await prisma.siswa.findMany();
  return <div>...</div>;
}

Client Components

Gunakan "use client" untuk interaktivitas (form state, chart, QR scanner):

*Client.tsx   — suffix konvensi untuk client components

Server Actions

File actions.ts di sebelah page.tsx:

"use server";
import { revalidatePath } from "next/cache";

export async function simpanData(formData: FormData) {
  // ... prisma mutation
  revalidatePath("/admin/modul");
}

Validasi Form

Gunakan zod di server actions untuk validasi input (lihat src/app/admin/keuangan/pengaturan/actions.ts).

Model Prisma Kunci

Modul Khusus — Referensi Kode

Menambah Modul Baru

1. Schema: Tambah model/field di prisma/schema.prisma → npx prisma db push && npx prisma generate
2. Server actions: Buat actions.ts dengan validasi zod
3. Page: Server component di src/app/[portal]/[modul]/page.tsx
4. Client UI: Pisahkan ke *Client.tsx jika perlu state
5. Sidebar: Tambah entry di AdminSidebar.tsx / GuruSidebar.tsx / OrangTuaSidebar.tsx
6. Panduan: Update docs/panduan/0X-*.md yang relevan
7. Lint & typecheck: npm run lint && npx tsc --noEmit

Testing Manual

npm run dev          # Development
npm run build        # Pastikan build sukses
npx tsc --noEmit     # Type check
npm run lint         # ESLint

Konvensi Styling

• Tailwind utility classes
• Portal Admin/Guru: sidebar gelap #0c1a2e, aksen amber
• Portal Orang Tua: aksen orange-rose gradient
• Portal Publik: slate + premium layout
• Komponen kartu: rounded-2xl/3xl, border-slate-200, shadow-sm

Diagram Arsitektur Data

flowchart TB
  subgraph client [Browser]
    Public[Portal Publik]
    Admin[Admin UI]
    Guru[Guru UI]
    Ortu[Ortu UI]
  end
  subgraph nextjs [Next.js App Router]
    RSC[Server Components]
    SA[Server Actions]
    API[API Routes]
  end
  subgraph data [Data Layer]
    Prisma[Prisma ORM]
    DB[(Database)]
  end
  subgraph external [External]
    Midtrans[Midtrans]
    Cron[Cron Scheduler]
  end
  Public --> RSC
  Admin --> RSC
  Admin --> SA
  Guru --> SA
  Ortu --> SA
  RSC --> Prisma
  SA --> Prisma
  API --> Prisma
  Prisma --> DB
  API --> Midtrans
  Cron --> API