Referensi Developer E-Pondok

E-Pondok adalah sistem kehadiran & relasi untuk pondok modern. Kamera browser di gerbang mencatat siapa yang datang dan pergi, buku tamu digital mengelola kunjungan, dan dashboard merangkai data itu jadi laporan serta peta relasi institusi yang hidup.

Dirancang untuk realitas pondok: dapat digunakan oleh banyak pondok (multi-tenancy) dan menjaga keamanan tanpa menambah beban operasional.

Apa yang didapat

• Kehadiran wajah tanpa sentuh dengan deteksi arah masuk/keluar otomatis, plus kios offline untuk gerbang.
• Anti-spoofing. Menolak foto, video, dan masker wajah palsu.
• Akademik: angkatan, hafalan, rapor, dan mutabaah yaumiyah dengan rekap per santri.
• Keuangan & penggajian: tagihan SPP, pembayaran QRIS/transfer, kwitansi email, payroll dari kehadiran nyata.
• Modul pondok: perpustakaan, UKS, asrama, PPDB online, tata tertib, inventaris, izin, EMIS, dan Asisten AI.
• Buku tamu digital dengan kategori, tujuan, dan kontribusi kunjungan.
• Kabar otomatis ke wali: email saat santri check-in/check-out, lengkap bukti foto.
• Dashboard ringkasan + analitik kehadiran.
• Login magic link tanpa kata sandi untuk semua pengguna.

Pondok = tenan

Satu pondok adalah satu tenan (tenant) yang terisolasi. Setiap pondok mendapat subdomain sendiri, misalnya pondokabc.epondok.id. Datanya tidak pernah bercampur dengan pondok lain meski berbagi satu basis data.

Tiga permukaan (surfaces)

• Apex. Domain induk epondok.id untuk landing publik, pendaftaran, checkout, dan dokumentasi ini.
• Platform. Subdomain platform.epondok.id untuk admin super yang mengelola akun, langganan, dan penyediaan pondok baru.
• Tenant. Subdomain *.epondok.id untuk aplikasi admin setiap pondok (dashboard, kehadiran, pengunjung, dan relasi).

Peran (roles)

Person di pondok mempunyai salah satu peran berikut:

Peran admin di sisi aplikasi: admin (akses penuh termasuk Penggajian & Keuangan), pengurus, dan platform (super-admin di apex).

Dari nol hingga kehadiran otomatis dalam lima langkah.

Halaman utama tenant. Ringkasan real-time dari seluruh modul. Sumber data: GET /api/dashboard.

Kartu ringkasan

• Kehadiran. Hadir hari ini, absen, terlambat, total populasi, dan tren harian.
• Pengunjung. Kunjungan hari ini, bulan ini, dan kunjungan dosen selama 3 tahun.
• Relasi. Relasi baru, mitra aktif, potensial, strategis, dan jaringan alumni.
• Follow-up. Jumlah tindak lanjut yang jatuh tempo.

Person adalah setiap individu di pondok (santri, ustaz, staf, atau pengurus). Operasi CRUD tersedia melalui /api/persons.

Enrollmen wajah

Pendaftaran wajah menangkap wajah, mengubahnya menjadi embedding 512 dimensi, lalu dan disimpan sebagai template terindeks per pondok. Saat pendaftaran, opsi checkDuplicates mencegah wajah yang sama didaftarkan dua kali, sedangkan qualityScore mencatat kualitas tangkapan.

capture frame
→ pemeriksaan anti-spoofing   // tolak foto/video/masker
→ embedding 512-d (InsightFace)
→ POST /api/persons/:id/enrollments
      { embedding, deviceId, qualityScore, checkDuplicates: true }

• POST /api/persons/:id/verify-face. Mencocokkan embedding baru dengan pendaftaran wajah person.
• DELETE /api/persons/:id/enrollments/:eid. Menonaktifkan pendaftaran wajah lama, bukan menghapusnya secara permanen.

Inti produk. Kamera check-in — halaman Check-in web di perangkat berkamera apa pun — menangkap wajah di gerbang → mencocokkannya dengan indeks wajah pondok → mendeteksi arah masuk/keluar secara otomatis → menyimpan kejadian dengan skor kepercayaan (confidence) dan, jika ada, ID perangkat (device_id).

Query

• GET /api/attendance. Daftar event (Paged), dengan filter personId, role, from, dan to.
• GET /api/attendance/presence. Menampilkan siapa yang sedang berada di dalam.
• GET /api/attendance/analytics. Menyediakan data masuk/keluar harian, yang paling sering terlambat, yang paling tepat waktu, serta filter rentang waktu dan peran.

Buku tamu digital. Setiap kunjungan dapat kategori, tujuan, check-in/out, dan nomor pengunjung (visitor_no).

Kategori

parent_guardianlecturerteachergovernment_officialcommunity_leaderalumnivendorgeneralother

Kontribusi kunjungan

Tiap kunjungan dapat mencatat kontribusi untuk pelaporan, seperti workshop, guest_lecture, training, mentoring, community_service, research_collaboration, recruitment_opportunity, dan other. Data yang dicatat mencakup topik, audiens, peserta, dan hasil.

Peta jejaring pondok agar tetap hidup dan terlacak.

Kontak

RelationshipContact menyimpan nama, lembaga, jabatan, keahlian, status (new / active / potential / alumni / strategic), dan catatan.

Tag kolaborasi

CollaborationTag (slug + label) dapat ditambahkan atau dihapus dari kontak untuk mengelompokkan mitra, misalnya pengajar-tamu dan beasiswa.

Follow-up

Tindak lanjut terjadwal: contact_id, due_date, assigned_to, status (open / in_progress / completed / cancelled). Filter overdue menyoroti yang sudah lewat jatuh tempo.

Semua modul berikut mengikuti pola yang sama: daftar terpaginasi (Paged<T>), tulis lewat POST/PATCH, hapus lunak (trash + restore), dan ekspor CSV. Rute lengkap ada di tabel Referensi API di bawah. Modul dengan tingkat paket tertentu menolak permintaan dengan 402 payment_required bila paket pondok belum mencakupnya.

Akademik

/api/academic — angkatan (cohorts) dengan impor massal, catatan hafalan per santri, dan periode rapor.

Mutabaah Yaumiyah

/api/mutabaah — template amal harian milik pondok, entri harian per santri dengan rating, dan GET /summary untuk rekap per santri: streak berjalan, streak terpanjang, progres per amal, dan rating rata-rata.

Penggajian

/api/payroll — profil gaji staf, pembuatan run payroll per periode dari kehadiran nyata (termasuk potongan keterlambatan), lalu kunci & kirim slip via email.

Kabar wali

/api/notifications — pengaturan email otomatis saat santri check-in/check-out (opsional dengan bukti foto), kanal Email/WhatsApp/Telegram, dan log pengiriman berisi status tiap notifikasi.

Perpustakaan

/api/perpustakaan — katalog buku, eksemplar per kode, peminjaman dengan jatuh tempo + pengingat email, dan reservasi.

Kesehatan (UKS)

/api/kesehatan — kunjungan klinik (keluhan → diagnosis → tindakan), pemberian obat, insiden, dan imunisasi.

Asrama

/api/asrama — gedung → kamar → ranjang, penempatan santri, dan gate pass izin keluar/pulang dengan persetujuan.

PPDB

/api/ppdb — formulir pendaftaran publik di subdomain pondok, verifikasi pendaftar, terima (otomatis jadi santri + tagihan uang masuk), dan pengaturan periode.

Keuangan

/api/finance — item biaya, tagihan per periode (dibuat otomatis per angkatan), pembayaran multi metode dengan kwitansi email, rekap tunggakan, dan pengingat pembayaran.

Tata tertib

/api/tata-tertib — katalog pasal berpoin, pencatatan pelanggaran, poin kumulatif per santri, dan sanksi bertahap.

Inventaris

/api/inventaris — aset dengan kondisi/lokasi/nilai, peminjaman barang, dan log mutasi.

Keperizinan

/api/keperizinan — izin pulang/keluar/sakit dengan alur ajukan → setuju/tolak → catat kembali, plus kabar ke wali.

EMIS

/api/emis — cek kelengkapan data santri untuk pelaporan EMIS Pesantren (hanya penanda, tanpa nilai NIK/NISN), ekspor CSV dengan urutan kolom terdokumentasi, dan /api/emis/santri/rows (JSON, memuat NIK; khusus admin/pengurus) yang dipakai dashboard untuk membuat ekspor .xlsx dan mengisi template EMIS yang diunggah — di browser.

Asisten AI

/api/asisten — ringkasan anomali santri dari data kehadiran/hafalan/UKS (/brief), dan Tanya Kitab di /api/asisten/kitab: unggah dan kelola korpus kitab, lalu tanya jawab dengan rujukan (jawaban mengalir lewat SSE).

API manajemen perangkat untuk klien perangkat keras. Saat ini kehadiran berjalan web-first, sehingga halaman Perangkat disembunyikan dari aplikasi admin dan pemakaian harian tidak memerlukan registrasi perangkat. Setiap kios yang didaftarkan punya identitas unik dan kuncinya sendiri; setiap permintaan sinkronisasi diverifikasi sebelum diproses, dan kios yang dicabut langsung ditolak.

• POST /api/devices/register. Mendaftarkan kios baru.
• POST /api/devices/:id/revoke. Mencabut akses sehingga kios tidak dapat melakukan sinkronisasi.
• POST /api/devices/:id/activate. Mengaktifkan kios kembali.
• last_seen_at melacak sinkronisasi terakhir.

Permukaan platform (platform.epondok.id) adalah ruang super-admin untuk menyediakan pondok baru, mengelola langganan, dan mengubah status pondok (active / suspended). Token platform terpisah dari token tenant karena keduanya menggunakan origin yang berbeda.

Satu sistem, banyak pondok. Setiap pondok mendapat subdomain & data terisolasi. Secara teknis: kolom pondok_id pada semua tabel tenan, resolver subdomain→pondok, dan JWT membawa pondokId sehingga setiap query terbatas pada pondok pemilik token.

Login tanpa kata sandi: minta tautan melalui email, lalu klik untuk masuk. Tautan hanya berlaku sekali dan kedaluwarsa cepat. Kata sandi tetap tersedia sebagai metode cadangan untuk admin platform.

Isolasi pondok dijaga berlapis: subdomain → pondok (resolver), pondok_id pada tiap baris, dan pondokId di JWT. Tidak ada titik akhir tenant yang bisa membaca data pondok lain. Semua lalu lintas terenkripsi saat transit (TLS).

Data pondok adalah amanah. Beberapa prinsip yang kami jaga:

• Isolasi antar-pondok. Data pondok Anda tidak pernah terbaca oleh pondok lain — dijaga berlapis di tingkat akses, bukan sekadar tampilan.
• Enkripsi saat transit. Semua lalu lintas berjalan di atas TLS.
• Wajah = template, bukan foto. Yang disimpan adalah template matematis 512 dimensi yang tidak bisa dibalik menjadi gambar wajah. Template bersifat per-pondok dan dapat dinonaktifkan kapan saja.
• Anti-spoofing. Frame diperiksa oleh model anti-spoofing sebelum diproses; foto, video, dan masker wajah palsu ditolak.
• Pemrosesan wajah di perangkat. Deteksi dan pembuatan template berjalan lokal di browser/perangkat gerbang — gambar mentah tidak dibagikan ke pihak lain.
• Hapus lunak + arsip. Data yang dihapus bisa dipulihkan selama masa sampah, lalu hilang dari semua daftar.
• Data sensitif tidak keluar pondok. NIK dan NISN hanya ada di unduhan EMIS admin/pengurus dan tidak pernah dikirim ke Kemenag atau pihak ketiga; template EMIS yang diunggah diisi di browser, bukan di server kami.

Sebelum template wajah dibuat, frame diperiksa oleh model anti-spoofing untuk membedakan wajah asli dari foto, video, atau masker. Hanya wajah asli yang diproses lebih lanjut. Pemeriksaan ini berjalan di perangkat gerbang (web maupun kios) tanpa mengirim gambar ke pihak ketiga.

Entitas inti dan field pentingnya:

Semua entitas tenan juga membawa pondok_id untuk isolasi.

API JSON di balik aplikasi. Semua rute daftar mengembalikan amplop terpaginasi:

Autentikasi integrasi

Selain token sesi admin, integrasi programatis dapat memakai kunci API: buat dari menu Pengaturan → Kunci API, lalu kirim header X-API-Key: pk_live_… pada setiap permintaan ke subdomain pondok. Kunci hanya ditampilkan sekali saat dibuat dan dapat dicabut kapan saja. Modul tertentu memerlukan paket tertentu — permintaan di luar paket mendapat 402 payment_required.

{
"items":  T[],
"total":  number,
"limit":  number,
"offset": number
}

Contoh request dengan token:

curl -H "Authorization: Bearer [REDACTED:Authorization header] header] \
"https://pondokabc.epondok.id/api/attendance?from=2026-01-01&limit=50"

Rute tenant

Rute platform (apex)