Kos Kita

Masalah

Banyak kos kecil masih dikelola manual. Data kamar, penghuni, dan sewa bulanan dicatat sendiri, dan pembayaran dikonfirmasi satu per satu. Kos Kita menggabungkan semuanya dalam satu sistem. Pengunjung bisa melihat kamar, penghuni mendaftar dan membayar secara online, tagihan bulanan dibuat otomatis, dan setiap pemilik punya dashboard untuk kosnya sendiri. Superadmin memverifikasi pemilik baru sebelum kos mereka tampil.

Peran saya

Ini proyek tim lima orang (PBL). Saya pemilik repositori dan penanggung jawab backend, dengan sekitar 120 dari ~235 commit:

• Setup proyek, skema database, dan sebagian besar migration (15 dari 26)
• Arsitektur role: tiga panel Filament, middleware yang menjaganya, dan pembatasan data per pemilik
• Registrasi dengan OTP WhatsApp, logika booking dan DP, serta integrasi Midtrans (Snap + webhook)
• Cron job harian untuk tagihan dan denda keterlambatan
• Widget insight AI Gemini di dashboard pemilik
• Activity log (jejak audit) di 9 model, dan panel superadmin

Anggota tim lain mengerjakan katalog publik, halaman penghuni (riwayat tagihan, nota PDF), dan panel Filament penghuni.

Arsitektur

• Laravel 13 + Filament 5, MySQL. Blade untuk situs publik dan alur penghuni, Filament untuk tiga panel admin.
• Role disimpan di users.role (admin, penghuni, superadmin). User::canAccessPanel() menentukan panel mana yang boleh dibuka. Middleware memblokir pemilik yang belum diverifikasi dan penghuni yang pembayarannya belum disetujui.
• Efek samping ada di satu tempat. Saat status pembayaran berubah menjadi verified, event model Pembayaran menandai tagihan lunas, menempatkan penghuni di kamar, dan menandai kamar terisi. Alurnya sama, baik pembayaran lewat Midtrans maupun disetujui manual.

Database

Satu pemilik bisa punya beberapa kos, dan satu kos punya banyak kamar. Harga kamar bergantung pada jumlah penghuni (harga_kapasitas, JSON). tagihan adalah tagihan bulanan. pembayaran adalah percobaan pembayaran untuk tagihan itu, atau untuk biaya booking dan pendaftaran pemilik.

Endpoint utama

Tantangan teknis

Memercayai webhook Midtrans. Webhook tidak memakai isi request mentah-mentah. Midtrans\Notification mengambil ID transaksi lalu menanyakan status aslinya ke API Midtrans dengan server key, jadi POST palsu tidak bisa menandai pembayaran lunas. Status capture/settlement menjadi verified (kartu kredit dengan status challenge ditahan), sedangkan cancel/deny/expire menjadi rejected.

Notifikasi ganda. Midtrans bisa mengirim notifikasi yang sama lebih dari sekali, dan redirect browser bisa datang lebih dulu daripada webhook. Efek samping verifikasi hanya berjalan saat status berubah menjadi verified (getOriginal('status') !== 'verified'). Karena itu, notifikasi berulang tidak menempatkan penghuni dua kali atau memproses tagihan ulang.

DP dan tagihan pertama. Booking dikenai 50% harga kamar ditambah biaya booking Rp 50.000. Saat cron membuat tagihan bulanan pertama untuk penghuni itu, yang ditagih hanya sisa 50%.

Cron tagihan harian. app:process-billing-daily berjalan pukul 00:00 WIB. Penghuni ditagih pada tanggal yang sama dengan tanggal masuknya. Kalau tanggal masuknya 29–31, tagihan di bulan yang lebih pendek dibuat di hari terakhir bulan itu. Cron aman dijalankan ulang: penghuni yang sudah punya tagihan bulan ini dilewati, dan denda hanya ditambahkan ke tagihan lewat jatuh tempo yang belum didenda. Salah satu bug yang saya perbaiki adalah timezone scheduler yang belum WIB.

Insight AI yang hemat kuota. Widget pemilik merangkum data milik pemilik itu (okupansi per kos, tagihan bulan ini, tagihan tertunggak, laporan kerusakan yang belum selesai). Ringkasan itu dikirim ke Gemini 2.5 Flash dengan responseMimeType: application/json dan temperature 0.1, lalu hasilnya di-cache per pemilik selama 6 jam. Respons yang gagal atau rusak dicatat di log, dan widget menampilkan pesan untuk mencoba lagi, jadi dashboard tetap berfungsi.

Yang ingin saya perbaiki

• Menambahkan unique index tagihan(user_id, bulan, tahun) agar aturan satu tagihan per bulan dijamin database, bukan hanya oleh kode.
• Memindahkan panggilan Midtrans dan Gemini ke queue supaya respons pihak ketiga yang lambat tidak menahan halaman.
• Menambahkan feature test untuk transisi status pembayaran.
• Menghapus nama dan nomor HP penghuni dari data yang dikirim ke Gemini; angka agregat sudah cukup untuk insight.