EasyBook

Masalah

Pengelolaan sirkulasi buku pada perpustakaan konvensional kerap menghadapi sejumlah hambatan operasional: antrean pengembalian fisik yang lambat, kesulitan melacak peminjam yang lewat jatuh tempo (overdue), dan penagihan denda keterlambatan yang masih mengandalkan uang tunai dengan pencatatan manual yang rentan selisih pembukuan. Selain itu, anggota perpustakaan tidak memiliki kanal terstruktur untuk mengajukan judul buku baru yang mereka minati (book procurement requests), serta tidak adanya opsi akun berbayar (keanggotaan premium) untuk mendapatkan kuota pinjam lebih banyak. EasyBook dibangun sebagai layanan REST API perpustakaan digital komprehensif yang mengotomatiskan deteksi denda dan memfasilitasi transaksi nontunai langsung dari gawai anggota.

Peran saya

Proyek ini saya kembangkan secara mandiri sebagai Lead Backend Developer (hampir 180+ commit di repository perpus-service), bertanggung jawab merancang seluruh arsitektur backend, basis data MySQL, integrasi pihak ketiga, dan otomatisasi tugas berulang:

• Perancangan Basis Data Relasional (MySQL): Merancang skema relasi sirkulasi perpustakaan (user, buku, kategori, kategori_buku, peminjaman, pembayaran, koleksi_pribadi, ulasan, request_buku).
• Otomatisasi Cron Job Keterlambatan & Penagihan Denda: Mengembangkan scheduled cron task (node-cron) yang berjalan setiap pukul 09:00 WIB untuk memindai peminjaman jatuh tempo, memperbarui status menjadi terlambat, dan membuat invoice tagihan denda otomatis (Rp 5.000) tanpa redundansi.
• Integrasi Transaksi Nontunai Midtrans: Mengimplementasikan integrasi Midtrans Snap API dan webhook callback untuk memproses pelunasan denda keterlambatan dan pembayaran upgrade keanggotaan premium secara instan.
• Autentikasi Stateless & RBAC Granular: Mengamankan API menggunakan JSON Web Token (JWT) dengan proteksi berbasis hak akses untuk 3 peran: Peminjam/Member, Petugas Perpustakaan, dan Administrator.
• Sistem Pelaporan Otomatis (PDF & Email): Mengintegrasikan generator PDF (pdfkit-table) untuk mencetak rekonsiliasi sirkulasi dan denda, serta pengiriman notifikasi pengembalian buku lewat email menggunakan nodemailer.

Arsitektur sistem

Backend dirancang berbasis microservice REST API yang terisolasi dan mudah dihubungkan dengan berbagai antarmuka klien (web/mobile):

• Node.js Express Server: Menyediakan router modular (/buku, /peminjaman, /pembayaran, /user, /request, /ulasan) dengan parsing body JSON dan upload gambar sampul buku (multer).
• Midtrans Payment Gateway: Menghubungkan akun perpustakaan dengan opsi pembayaran digital (GoPay, QRIS, Transfer Virtual Account). Saat pembayaran terkonfirmasi, webhook Midtrans memicu perubahan status pembayaran dan membuka blokir peminjaman pengguna.
• Background Cron Engine (node-cron): Menjalankan pemeriksaan otomatis di latar belakang untuk menjaga keakuratan status inventaris dan denda tanpa perlu dipicu interaksi pengguna.
• MySQL Database Pool: Menggunakan mysql2 connection pooling untuk memastikan efisiensi koneksi saat menangani banyak request konkuren.

Endpoint utama

Tantangan teknis

1. Penagihan denda otomatis yang idempoten (bebas duplikasi). Cron job yang berjalan setiap pagi berisiko memasukkan tagihan denda berulang kali untuk peminjaman yang sama jika query tidak dikunci. Solusinya, query INSERT dibatasi klausa subquery NOT EXISTS.

2. Sinkronisasi stok buku fisik saat sirkulasi. Untuk mencegah peminjaman melebihi stok yang tersedia di rak (negative stock), operasi peminjaman memvalidasi stok aktif terlebih dahulu. Jika stok $>0$, stok dikurangi 1 secara atomik; dan saat buku dikembalikan, status pinjam ditandai selesai serta stok buku langsung ditambah kembali.

3. Keamanan verifikasi webhook pembayaran. Karena webhook Midtrans dikirim dari internet terbuka ke server, endpoint tidak boleh mempercayai data tanpa validasi. Parameter order_id, gross_amount, dan status transaksi diverifikasi dengan data tagihan di database sebelum hak istimewa akun di-upgrade ke status Premium atau status denda dinyatakan lunas.

4. Fleksibilitas metode pembayaran ganda (Tunai vs Nontunai). Meskipun sistem mendukung pembayaran digital penuh lewat Midtrans, sebagian anggota perpustakaan tetap memilih membayar denda secara langsung di loket kasir perpustakaan. Dibuat endpoint khusus pembayaranTunai yang hanya dapat diakses oleh petugas untuk mengesahkan pelunasan secara manual dengan jejak audit petugas yang jelas.

Yang ingin saya perbaiki

• Mengganti penulisan query SQL mentah menggunakan Query Builder atau ORM (seperti Prisma atau Kysely) untuk meningkatkan maintainability kode.
• Menambahkan integrasi scanner Barcode / QR Code untuk mempercepat proses check-in dan check-out buku di meja sirkulasi.
• Memisahkan cron job dan PDF generator ke worker thread atau service independen agar tidak membebani event loop utama Express.