Panduan Teknis (Tim IT)

Dokumen ini untuk tim IT yang mengelola instalasi, konfigurasi, dan operasional server talentasyskoo.

Prasyarat

Komponen	Versi Minimum
Node.js	20.x
npm	10.x
Database	MySQL / MariaDB / PostgreSQL (via Prisma)
OS	Linux (disarankan untuk production)

Instalasi Lokal

# Clone repository
git clone [url-repo]
cd talentasyskoo.nexussinergi.id

# Install dependensi
npm install

# Salin environment
cp .env.example .env   # atau buat manual

# Setup database
npx prisma db push --accept-data-loss
npx prisma generate

# Seed data demo lengkap (reset + isi ulang)
npm run db:seed

# Jalankan development server
npm run dev

Aplikasi berjalan di http://localhost:3000.

Environment Variables

Variabel	Wajib	Deskripsi
`DATABASE_URL`	Ya	Connection string Prisma ke database
`NEXTAUTH_SECRET`	Ya	Secret JWT session & QR penjemputan
`NEXTAUTH_URL`	Ya (prod)	URL publik aplikasi, mis. `https://sekolah.sch.id`
`CRON_SECRET`	Ya (prod)	Token autentikasi endpoint cron
`MIDTRANS_SERVER_KEY`	Untuk bayar	Server key Midtrans
`NEXT_PUBLIC_MIDTRANS_CLIENT_KEY`	Untuk bayar	Client key Midtrans (public)
`NODE_ENV`	Auto	`development` atau `production`

Contoh `.env`

DATABASE_URL="mysql://user:pass@localhost:3306/talentasyskoo"
NEXTAUTH_SECRET="ganti-dengan-string-random-panjang"
NEXTAUTH_URL="https://talentasyskoo.nexussinergi.id"
CRON_SECRET="cron-secret-produksi-anda"
MIDTRANS_SERVER_KEY="SB-Mid-server-..."
NEXT_PUBLIC_MIDTRANS_CLIENT_KEY="SB-Mid-client-..."

Keamanan: Jangan commit file .env ke repository. Gunakan secret manager di production.

Database

Schema & Migrasi

Proyek menggunakan Prisma ORM. Schema ada di prisma/schema.prisma.

# Terapkan schema ke database
npx prisma db push

# Regenerasi Prisma Client (wajib setelah ubah schema)
npx prisma generate

# Buka Prisma Studio (GUI database)
npx prisma studio

Seed Data

# Disarankan — push schema + seed penuh
npm run db:seed

# Hanya seed (tanpa push schema)
npx tsx prisma/seed.ts

Script npm run db:seed menjalankan prisma db push --accept-data-loss lalu tsx prisma/seed.ts. Seed TRUNCATE semua tabel lalu mengisi data demo lengkap.

File seed	Isi
`prisma/seed.ts`	Data dasar: user, siswa, kelas, kurikulum Merdeka, keuangan
`prisma/seed-advanced.ts`	Kamus kosakata, Cambridge/IB, multi-track dasar
`prisma/seed-observasi-modules.ts`	Indikator perkembangan, observasi multi-hari, lampiran, intervensi + consent
`prisma/seed-demo-features.ts`	Pelatihan guru, kuis, progress, sertifikasi, media, inventaris
`prisma/seed-extended.ts`	RKAS, HRIS, penjemputan, UKS, rapor, kantin, publik

Akun demo setelah seed:

Peran	Email	Password
Admin	`admin@talentasyskoo.id`	`password`
Guru	`guru@talentasyskoo.id`	`password`
Orang Tua	`ortu@talentasyskoo.id`	`password`

Siswa demo: Kiki (NISN 202601001, TK-A), Michael Jr. (202601003, TK-B Cambridge), Budi (202601002, SD).

Backup

Lakukan backup database secara berkala:

# MySQL
mysqldump -u user -p talentasyskoo > backup_$(date +%Y%m%d).sql

# PostgreSQL
pg_dump talentasyskoo > backup_$(date +%Y%m%d).sql

Cron Jobs

Sistem memiliki endpoint cron yang harus dipanggil terjadwal (crontab atau layanan eksternal).

Generate Tagihan Otomatis

Endpoint: GET /api/cron/generate-tagihan

Autentikasi: Header Authorization: Bearer {CRON_SECRET} atau query ?token={CRON_SECRET}

Fungsi: Membuat tagihan bulanan untuk kategori dengan isAutoGenerate: true, memfilter siswa per jenjang kategori.

Jadwal disarankan: Setiap hari pukul 06:00 — sistem cek tanggal terbit per kategori.

# Contoh crontab
0 6 * * * curl -H "Authorization: Bearer $CRON_SECRET" https://domain.com/api/cron/generate-tagihan

Reminder Tagihan Jatuh Tempo

Endpoint: GET /api/cron/reminder-tagihan

Autentikasi: Sama seperti di atas.

Fungsi: Kirim notifikasi pengingat ke orang tua untuk tagihan yang mendekati/melewati jatuh tempo.

0 8 * * * curl -H "Authorization: Bearer $CRON_SECRET" https://domain.com/api/cron/reminder-tagihan

Payment Gateway (Midtrans)

Konfigurasi

Daftar akun Midtrans (sandbox untuk testing).
Masukkan MIDTRANS_SERVER_KEY dan NEXT_PUBLIC_MIDTRANS_CLIENT_KEY di .env.
Set webhook URL di dashboard Midtrans: https://domain.com/api/webhooks/midtrans

Alur Pembayaran

sequenceDiagram
  participant Ortu
  participant App
  participant Midtrans
  participant Webhook
  Ortu->>App: Klik Bayar Tagihan
  App->>Midtrans: Create transaction
  Midtrans->>Ortu: Halaman pembayaran
  Ortu->>Midtrans: Selesaikan bayar
  Midtrans->>Webhook: POST notification
  Webhook->>App: Update status SETTLEMENT

Mode Sandbox vs Production

Sandbox: NODE_ENV=development, gunakan kunci SB-Mid-...
Production: NODE_ENV=production, gunakan kunci production Midtrans

Quiet Hours

Dikonfigurasi via Admin → Konfigurasi Sistem:

Kunci	Nilai contoh
`QUIET_HOURS_ENABLED`	`true`
`QUIET_HOURS_START`	`21:00`
`QUIET_HOURS_END`	`06:00`

Logika di src/lib/komunikasi.ts — memblokir pengiriman pesan orang tua ke guru di luar jam tersebut (zona WIB).

Multi-Jenjang (TK / SD)

JenjangSwitcher menyimpan jenjang aktif di cookie/session. Data kategori tagihan, pengaturan, dan filter siswa mengikuti jenjangId.

Build & Deployment Production

# Build
npm run build

# Start
npm run start

Checklist Production

NEXTAUTH_URL mengarah ke domain HTTPS
NEXTAUTH_SECRET dan CRON_SECRET diganti dari default
Database production terpisah dari development
Cron jobs terkonfigurasi
Webhook Midtrans production aktif
Backup database terjadwal
SSL/TLS aktif (HTTPS)

Reverse Proxy (Nginx)

server {
    listen 443 ssl;
    server_name sekolah.sch.id;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
}

Restart Setelah Perubahan Schema

Jika terjadi error Cannot read properties of undefined (reading 'findMany') setelah update schema:

npx prisma generate
# Restart Next.js server
npm run dev   # atau pm2 restart

Panduan Orang Tua Panduan Developer