# πŸ“‹ HANDOFF β€” Status Proyek & Agenda Selanjutnya > Dokumen ini ditulis untuk diberikan ke sesi Claude (atau developer) yang baru, > supaya langsung paham konteks tanpa perlu baca ulang seluruh riwayat chat > sebelumnya. Untuk detail arsitektur teknis lengkap, baca `ARCHITECTURE.md`. > Untuk detail teknis per modul, baca `README.md` di masing-masing folder > modul (`app/Modules/{Nama}/README.md`) β€” dokumen ini sengaja tidak > mengulang semua detail itu, cuma rangkuman status + keputusan lintas modul > yang perlu diketahui sebelum lanjut kerja. **Untuk gaya penulisan kode, > struktur, namespace, dan contoh konkret tiap lapisan (Model/Action/ > Controller/Request/Resource/Route/Blade), baca `STYLE_GUIDE.md`** β€” > dibaca SEBELUM mulai menulis kode di modul apa pun, supaya tidak perlu > minta contoh file dulu di awal seperti sesi-sesi sebelumnya. --- ## 🏫 Tentang Proyek Sistem LMS + Tata Kelola Sekolah untuk **TK** (bagian dari ekosistem "SAQ"), fokus utama akhirnya ke **Finance/SPP**, dibangun bertahap dari fondasi data dulu. Urutan modul yang disepakati: **Core β†’ Student β†’ Academic β†’ Finance** (Teacher sengaja dilewati dulu, lihat bagian "Urutan Modul Selanjutnya"). - **Instalasi tunggal per sekolah** (bukan SaaS/multi-tenant) β€” tapi skema `jenjang` dirancang skalabel untuk sekolah yang punya lebih dari 1 jenjang pendidikan (PAUD/TK/SD/dst) di bawah 1 instalasi yang sama. - **Laravel 13**, PHP 8.3, MySQL, testing pakai **Pest** (belum ada test otomatis untuk modul selain Auth β€” dicatat sebagai utang di tiap README modul) - Arsitektur **Modular DDD ringan** β€” 1 modul = 1 folder mandiri di `app/Modules/`, logika bisnis di `Actions/` (1 class = 1 fitur), Controller cuma nerima input & kasih respons - Frontend admin: **Blade + Tailwind + Alpine.js** (Vite), layout `layouts.staff` - Frontend orang tua: **React terpisah**, konsumsi lewat API (Sanctum) β€” **catatan penting**: sampai saat ini baru **endpoint API**-nya yang dibangun (Auth, Student minimal, Finance/Invoice lengkap, Profil parent). Halaman React-nya sendiri **belum ada satupun** β€” itu pekerjaan terpisah yang belum dimulai. --- ## βœ… Status Modul ### Auth β€” stabil, sudah mencakup User/Role/Permission Management + Profil (Staf & Parent) Login staf (email+password / OTP WA) & orang tua (OTP WA/password), aktivasi akun orang tua by nomor HP, reset password, permission berbasis Spatie. WhatsApp Gateway masih stub/testing pakai **Fonnte (unofficial)** β€” URL & token gateway sudah dipasang di `.env`, provider official belum dipilih. **Detail lengkap:** `app/Modules/Auth/README.md` β€” termasuk bagian **"Rencana Masa Depan: Delegasi Akses Multi-Akun"** (konsep matang, belum dieksekusi β€” supaya ayah & ibu bisa pantau anak dari akun masing-masing tanpa gabung identitas). ⚠️ README modul ini belum di-update mengikuti seluruh progress di bawah β€” perlu di-refresh sebelum sesi berikutnya baca detail teknisnya. **Fitur baru yang sudah dibangun (di luar yang sudah ada sebelumnya):** - **User Management (staf)** β€” CRUD penuh (`/users`), permission `user.manage`. Multi-role per user (`syncRoles()`), search by nama/email/ nomor HP (normalisasi format `0`↔`62` biar akurat), filter by role, list di-scope cuma role ber-`guard_name = 'web'` (parent/role guard lain otomatis gak nongol). Guard bisnis: gak bisa hapus akun sendiri, gak bisa melepas role `superadmin` dari akun terakhir yang megangnya. - **Role & Permission Management** β€” CRUD Role (`/roles`), permission `role.manage`. Checkbox permission dikelompokkan otomatis per domain (`explode('.', $name)[0]` dari penamaan `{domain}.manage`/`{domain}.view` yang sudah baku). Role `superadmin` dikunci total (gak bisa diedit/ dihapus/diganti nama lewat UI ini β€” tetap bypass semua permission lewat `Gate::before`, bukan dari isi `role_has_permissions`). - **Kolom baru di `users`**: `name`, `username` (unique, buat rencana profil publik `/profil/{username}`, format slug lowercase+strip), `avatar` (path storage disk `public`, upload otomatis di-crop persegi + resize 300Γ—300 PNG pakai GD, file lama dihapus tiap ganti). - **Halaman "Profil Saya" β€” staf** (`/profile`, guard `web`): edit nama/ username/avatar, ganti email, ganti nomor HP, ganti password β€” 3 yang terakhir wajib konfirmasi `current_password`, dengan rate limiter khusus `sensitive-profile-update` (10x/menit by `auth()->id()`, bukan reuse limiter `login` yang key-nya email/HP body request β€” gak relevan buat konteks yang sudah login). - **Profil parent** (API, guard `sanctum`, `ParentProfileApiController`) β€” reuse Action/Request yang sama persis dengan staf buat nama/username/ avatar/email/password (Action-nya emang gak peduli guard). **Ganti nomor HP beda pola**: wajib verifikasi OTP ke nomor **baru** dulu (bukan cuma modal `current_password`) β€” karena nomor HP itu kanal OTP login satu-satunya buat parent yang belum set password. Berhasil verifikasi β†’ `users.phone_number` **dan** `parents.phone_number` di-update bareng dalam 1 `DB::transaction()` (update `parents` sengaja lewat `DB::table()`, BUKAN import Model β€” modul Auth itu fondasi, gak boleh import Model dari modul Student, lihat bagian "Keputusan Lintas Modul"). - **`otp_codes.action_type`** β€” nambah value baru `change_phone` (dari awalnya cuma `login`/`activation`/`reset_password`). Kolom `phone_number` di tabel ini sekarang diisi juga buat kasus `change_phone` (nomor baru yang mau diverifikasi), bukan cuma `activation` lagi. - **`SetParentCredentialsAction` diperbaiki** β€” sekarang cuma bisa jalan kalau `email` DAN `password` user itu masih `NULL` (endpoint "lengkapi data pertama kali"), ditolak kalau salah satu sudah terisi (harus lewat jalur ganti email/password reguler yang minta konfirmasi password lama). Sebelumnya bisa overwrite kredensial diam-diam tanpa bukti kepemilikan. **Ganti nomor HP parent β€” diperkuat lebih lanjut (dual-path + revoke sesi):** - **Bug nyata ditemukan & diperbaiki**: `GenerateOtpAction` awalnya kirim OTP ke `$user->phone_number` (nomor LAMA) alih-alih `$phoneNumber` param (nomor BARU) β€” baru ketauan pas testing manual `change_phone`, karena itu satu-satunya kasus di mana nomor tujuan beda dari nomor tersimpan di `$user`. Fix: notifiable SELALU dituju ke `$phoneNumber` param, gak lagi `$user ?? new class(...)`. - **Dual-path konfirmasi** (`RequestPhoneChangeOtpRequest`): parent yang sudah `setCredentials()` wajib `current_password` dulu sebelum minta OTP ke nomor baru (`required`); parent OTP-only field itu `prohibited` (gak boleh diisi sama sekali) β€” supaya parent yang nomor lamanya udah hilang/mati (skenario paling umum orang butuh fitur ini) tetap bisa pakai, gak kejebak jalan buntu wajib verifikasi nomor lama dulu (riset "dual-OTP" yang sempat diusulkan, sengaja TIDAK diadopsi mentah karena gak cocok konteks project kecil ini). - **Revoke sesi/token lain** setelah sukses ganti nomor (`ConfirmParentPhoneChangeAction`) β€” device lain langsung ke-logout, kecuali device yang dipakai konfirmasi. Versi minimal sebelum fitur "Manajemen sesi/perangkat aktif" penuh dibangun. - Cooldown 24 jam setelah sukses ganti β€” **sengaja di-skip**, bukan prioritas sekarang. **Bug & celah desain yang tercatat, status per sesi ini:** - ~~Request OTP aktivasi parent tidak validasi keberadaan data `parents` dulu~~ β€” **sudah diperbaiki** (`Rule::exists('parents','phone_number') ->whereNull('user_id')` kondisional di `RequestOtpRequest`, khusus `action_type=activation`). - ~~`ActivateParentAccountAction` pakai `assignRole('parent')` tanpa guard eksplisit~~ β€” **sudah diperbaiki**, sekarang eksplisit `assignRole(Role::findByName('parent', 'sanctum'))`. Sebelumnya "kebetulan benar" karena urutan resolusi guard Spatie (`Guard::getNames()`, ambil guard pertama yang provider-nya cocok ke `App\Models\User`), bukan by desain β€” rapuh kalau nanti ada guard baru yang provider-nya juga `users`. - ~~`SetParentCredentialsAction` bisa overwrite kredensial tanpa bukti kepemilikan~~ β€” **sudah diperbaiki**, lihat poin di atas. - ~~`GenerateOtpAction` kirim OTP `change_phone` ke nomor lama, bukan nomor baru~~ β€” **sudah diperbaiki**, lihat poin "Ganti nomor HP parent" di atas. Ada 2 baris Role `parent` sempat ketemu di database (`id 5` guard `web`, `id 6` guard `sanctum`) β€” peninggalan sebelum bug guard `assignRole` diperbaiki, sudah dihapus salah satunya, TAPI **cek ulang manual** jangan sampai ada user yang masih nyangkut ke baris yang salah. - **Belum diperbaiki**: `ActivateParentAccountAction` commit transaksi (bikin user, link parent, assign role) **sebelum** controller bikin token Sanctum secara terpisah di luar transaksi itu β€” kalau pembuatan token gagal, akun sudah terlanjur aktif tapi user tidak dapat token & tidak bisa aktivasi ulang (stuck). Perbaikan diusulkan (perluas transaksi mencakup `createToken`) tapi menunggu konfirmasi pemilik project sebelum dieksekusi. **Fitur baru: status pengiriman WhatsApp (delivery status), belum selesai diverifikasi end-to-end:** - `WhatsappGatewayInterface` diperluas β€” `send()` sekarang balikin DTO `WhatsappSendResult` (bukan `bool` polos, biar `messageId` provider bisa disimpan buat korelasi webhook), tambah method baru `parseStatusWebhook(array $payload): WhatsappDeliveryStatus`. - 3 DTO/enum baru: `WhatsappSendResult`, `WhatsappDeliveryState` (`sent`| `invalid`|`pending`|`expired`|`unknown`), `WhatsappDeliveryStatus`. - `FonnteWhatsappGateway` β€” **ganti nama** dari `PenyediaLayananWhatsappGateway` (sekarang isinya spesifik ke bentuk payload Fonnte, gak lagi generic). - `otp_codes` β€” 2 kolom baru: `gateway_message_id` (buat korelasi), `delivery_status` (diupdate webhook). - `WhatsappWebhookController` (`POST /api/webhooks/whatsapp/status`, diamankan `?token=` di query string β€” **sengaja hardcode di controller, BUKAN bagian `WhatsappGatewayInterface`**, dicatat sebagai utang adaptabilitas yang disengaja karena baru ada 1 provider buat acuan bentuknya) + `OtpDeliveryStatusApiController` (`GET /api/otp/delivery-status`, publik, buat React polling). - **3 pekerjaan manual yang masih tertunda** (di luar jangkauan Claude): binding `AuthModuleServiceProvider` belum dipindah ke `FonnteWhatsappGateway`, `OtpCode` Model `$fillable` belum ditambah 2 kolom baru, file lama `PenyediaLayananWhatsappGateway.php` belum dihapus. - **Testing**: alur inti (kirim OTP, dst) sudah kebukti jalan lewat `127.0.0.1` β€” TIDAK butuh domain publik sama sekali (itu cuma jalur outbound). Verifikasi `delivery_status` **belum selesai** β€” butuh domain publik (Fonnte manggil BALIK ke sistem kita, jalur inbound). Sempat coba `loca.lt` (localtunnel), ketauan gak reliable (halaman interstisial buat pengunjung baru + koneksi suka putus sendiri), direkomendasikan pindah ke `cloudflared tunnel --url http://localhost:8000` (gak ada interstisial di free tier-nya) β€” belum dikonfirmasi hasil akhirnya oleh pemilik project. ### Core β€” CRUD lengkap, permission `core.manage` 5 entitas: **AcademicYear** (tahun ajaran, 1 aktif di seluruh sistem), **Jenjang** (TK, dst β€” skalabel multi-jenjang), **GradeLevel** (TK-A/TK-B, di bawah Jenjang), **Semester** (Ganjil/Genap per tahun ajaran, 1 aktif di seluruh sistem, punya rentang tanggal nyata bukan cuma label), **Classroom** (ruang kelas, master data lintas sistem β€” bisa dipakai >1 rombel sekaligus karena ada shift). Semua staf-only (Blade) kecuali `AcademicYear` yang juga punya API read-only untuk orang tua. **Detail:** `app/Modules/Core/README.md`. ### Student β€” CRUD lengkap, permission `student.manage` `Student` & `ParentProfile` (model sudah ada dari awal project). Fitur kunci: **auto-match orang tua by nomor HP** (`FindOrCreateParentByPhoneAction`) β€” kakak-adik otomatis berbagi 1 data `parents`, dengan lookup AJAX di form yang prefill & lock field kalau nomor sudah terdaftar. Update data siswa & data orang tua sengaja 2 form terpisah (1 orang tua bisa punya banyak anak). `phone_number` orang tua tidak bisa diubah lewat form staf biasa (itu identitas login) β€” **satu-satunya jalur resmi ganti nomor HP parent sekarang lewat "Profil Saya" milik parent sendiri + verifikasi OTP, lihat modul Auth**. Staf: full CRUD (Blade). Orang tua: read-only, cuma lihat anak sendiri lewat `StudentApiController` (**masih sangat minimal** β€” cuma 1 endpoint `GET /api/students` pakai relasi `ParentProfile->students`, belum ada endpoint detail/lain-lain). **Detail:** `app/Modules/Student/README.md`. ### Academic β€” kerangka CRUD selesai, permission `academic.manage` 3 entitas: **ClassGroup** (Rombel, gabungan konsep "Kelas"+"Rombel" jadi 1 entitas), **ClassGroupStudent** (plotting siswa β€” **tabel HISTORI**, bukan status tunggal, karena pindah rombel didukung dengan log lengkap `moved_at`/`moved_out_at`), **ReportCard** (kerangka Rapor administratif: catatan + status draft/published, **belum ada nilai per mapel** β€” nunggu modul Exam/Learning). Staf: full CRUD + halaman "Plotting Siswa" khusus (tempatkan/pindahkan). Orang tua: read-only, rombel aktif anak + rapor yang sudah **published saja** (draft tidak pernah terlihat). **Detail:** `app/Modules/Academic/README.md`. ### Finance β€” βœ… ALUR MANUAL SUDAH LENGKAP END-TO-END BillingType β†’ PaymentChannel β†’ BillingTariff β†’ StudentTariffMapping (+ Bulk Mapping) β†’ Invoice (generate massal SPP bulanan + manual untuk tagihan sekali bayar) β†’ InvoicePayment (pencatatan manual, status invoice auto-recalculate) β†’ 4 Laporan Keuangan (rekap bulanan, tunggakan, per kanal, breakdown komponen biaya pakai aturan **FIFO**) β†’ API orang tua read-only (list & detail invoice, ringkasan tunggakan). **Detail super lengkap ada di `app/Modules/Finance/README.md`** β€” baca itu dulu sebelum lanjut kerja di modul ini, jangan tanya ulang hal yang sudah didokumentasikan di situ (pola bulk action, urutan `@vite` vs `app.js`, format `invoice_number`, aturan FIFO breakdown, dll). **Satu-satunya yang tersisa**: integrasi **Finpay** (`PaymentGatewayTransaction`, `WebhookLogs`) β€” skema tabel sudah ada dari awal project, providernya belum final. Selain itu: download PDF invoice, endpoint "Bayar Sekarang", dan **halaman React sisi orang tua belum dibangun sama sekali** (baru endpoint API-nya). ### Modul lain (Teacher, Admission, Learning, Attendance, Exam, Notification, ELibrary, Canteen) β€” belum digarap sama sekali, masih peta jangka panjang di `ARCHITECTURE.md`. --- ## πŸ—ΊοΈ Progres & Agenda Selanjutnya ``` βœ… 1. Core β€” Tahun Ajaran, Jenjang, Grade Level, Semester, Classroom βœ… 2. Student β€” Siswa & Orang Tua/Wali βœ… 3. Academic β€” Rombel, Plotting Siswa, kerangka Rapor βœ… 4. Finance β€” Alur manual lengkap (lihat detail di README modul) βœ… 5. Auth β€” User/Role/Permission Management (Blade) + Profil Saya (staf & parent) πŸ‘‰ 6. Finance β€” Proses pembayaran + integrasi payment Gateway Finpay (SELANJUTNYA) ``` **Yang bisa jadi agenda selanjutnya** (belum ada urutan resmi disepakati, diskusikan dulu sama pemilik project sebelum eksekusi): - **Integrasi Finpay** β€” begitu provider final, tinggal isi `PaymentGatewayTransaction` & `WebhookLogs` di modul Finance yang sudah ada kerangkanya. - **Halaman React sisi orang tua** β€” endpoint API Auth, Student (minimal), Finance/Invoice, dan Profil parent sudah siap dikonsumsi, pembuatan halaman React dibangun terpisah oleh tim lain dan sedang dalam progress. - **Teacher** β€” sengaja terus dilewati sejauh ini. `class_groups.homeroom_teacher_id` sudah disiapkan nullable (kolom polos, belum FK constraint) supaya bisa diisi belakangan tanpa migrasi ulang. - **Halaman profil publik `/profil/{username}`** β€” kolom `username` sudah ada & bisa diisi (lewat "Profil Saya"), tapi halaman yang benar-benar menampilkannya berdasarkan slug ini **belum dibangun** β€” tujuan awal kolom ini (buat URL profil publik, berlaku lintas tipe user: staf, parent, nanti student) belum tercapai sepenuhnya sampai halaman ini ada. - **Manajemen sesi/perangkat aktif** β€” terutama relevan buat parent: `ParentAuthController::login()` bikin token Sanctum baru tiap login (`createToken('parent-app')`), jadi 1 akun bisa punya banyak token aktif bersamaan (multi-device) tanpa ada cara lihat/cabut salah satunya dari sisi user. Makin relevan begitu "Delegasi Akses Multi-Akun" (lihat README Auth) dieksekusi. - **Notifikasi keamanan saat data sensitif berubah** β€” kirim WA/email ke kontak **lama** (bukan yang baru) begitu email/nomor HP/password diganti lewat "Profil Saya" (staf maupun parent), supaya kalau perubahan itu gak sah, pemilik asli akun langsung tau. Scope-nya lebih luas dari catatan lama "notifikasi kalau password direset" β€” sekarang ada 3 kanal sensitif (email, HP, password), bukan cuma password. - **Audit `last_login_at` / `last_login_ip`** β€” kolom baru di `users`, diupdate tiap login sukses (staf & parent, semua jalur: email+password, OTP WA). Berguna buat admin (lihat kapan staf terakhir aktif di halaman "Pengguna") maupun parent sendiri (info dasar keamanan). - Modul lain (Admission/PPDB, Learning, Attendance, Exam, Notification, ELibrary, Canteen) β€” belum digarap sama sekali. --- ## 🧭 Keputusan Lintas Modul yang Wajib Diikuti Konsisten Ini pola-pola yang **berulang** di semua modul yang sudah dibangun β€” kalau lanjut ke modul manapun, ikuti pola yang sama, jangan improvisasi pola baru tanpa didiskusikan dulu: - **Satu entitas "hanya 1 aktif di seluruh sistem"** (AcademicYear, Semester) β†’ Action `Activate*Action` yang menonaktifkan semua yang lain dalam 1 `DB::transaction()` sebelum mengaktifkan yang dipilih. - **Hapus data yang masih dipakai β†’ `ValidationException::withMessages()`**, bukan biarkan error SQL mentah. Selalu guard di level Action, meski FK constraint di database juga sudah `restrictOnDelete()` (defense in depth). Tapi kalau memang tidak ada tabel lain yang bergantung, tidak perlu dipaksa nambah guard kosongan (lihat contoh `DeleteStudentTariffMappingAction` di Finance). - **Arah dependency SATU ARAH**: modul yang lebih "fondasi" (Core, **juga Auth**) **tidak pernah** import Model dari modul yang mengonsumsinya (Student, Academic, Finance). Guard/Action yang perlu tahu atau ubah data di modul lain, query lewat `DB::table()` by nama tabel, bukan import Model cross-module. Contoh konkret terbaru: `ConfirmParentPhoneChangeAction` (modul Auth) update tabel `parents` (milik modul Student) lewat `DB::table('parents')`, bukan import `ParentProfile`. - **Spatie Permission β€” guard SELALU eksplisit, jangan andalkan resolusi implisit.** `assignRole('nama')`/`Role::findByName('nama')` tanpa guard eksplisit resolve guard dari `Guard::getNames()` (ambil guard pertama di `config/auth.php` yang provider-nya cocok ke model User) β€” bisa "kebetulan benar" sekarang tapi rapuh kalau config berubah. Selalu tulis `assignRole(Role::findByName('nama', 'web'|'sanctum'))` eksplisit. Kasus nyata: `ActivateParentAccountAction` (lihat status Auth di atas). - **Permission per-domain, singular, bukan ikut nama tabel**: `core.manage`, `student.manage`, `academic.manage`, `finance.manage`, `user.manage`, `role.manage` β€” bukan `core.manages`/`students.manage`/dst. Semua di-seed lewat `PermissionSeeder` (`database/seeders/`). **CRUD Role & Permission sekarang sudah ada lewat UI** (modul Auth, `/roles`, `/users`) β€” role `superadmin` dikunci gak bisa diubah/dihapus lewat UI itu. - **Data sensitif (email/nomor HP/password) yang bisa diubah user sendiri via "Profil Saya" wajib lapisan konfirmasi ekstra** β€” pola standar: minta `current_password` (rule bawaan Laravel `'current_password'`) buat channel yang **staf** kontrol penuh (email, password). **Kecuali** kalau channel itu sendiri yang jadi satu-satunya bukti kepemilikan akun (kasus nomor HP milik **parent**, karena itu kanal OTP login) β€” di situ wajib verifikasi OTP ke nilai **baru** dulu, bukan cuma modal password lama. Route yang minta `current_password` dikasih rate limiter khusus `sensitive-profile-update` (beda dari limiter `login`, karena konteksnya sudah-login, key-nya `auth()->id()` bukan email/HP body request). - **Normalisasi nomor HP terpusat** β€” logic (buang non-digit, ganti awalan `0`β†’`62`) ada di 2 tempat yang **beda tujuan, dua-duanya tetap perlu**: mutator `phoneNumber()` di `App\Models\User` (urus format yang tersimpan), dan trait `Modules\Auth\Requests\Concerns\NormalizesPhoneNumber` dipakai di tiap Form Request yang terima input nomor HP (urus supaya rule `unique`/`exists` membandingkan nilai dalam format yang sama dengan yang ada di database, SEBELUM sempat disimpan lewat mutator). - **API Controller (parent-facing) pecah logic ke Action class**, Controller cuma manggil & format response β€” pola diambil dari `ParentAuthController` (modul Auth, paling matang), bukan query langsung di Controller. - **Layout Blade staf**: `layouts.staff` (BUKAN `layouts.app`). Ada component `x-status-badge` (varian success/warning/danger, TIDAK ada varian netral/abu-abu β€” untuk status "tidak aktif" pakai `` manual) dan `x-icon-badge`. - **Padding input**: `class="... px-3.5 py-2.5 text-sm ..."` β€” pernah kelewat di awal (bug berulang), jangan lupa lagi. **Input password** beda pola (lihat `login.blade.php`/`profile/edit.blade.php`): `px-4 py-2.5 pr-11`, `focus:ring-2 focus:ring-{color}-500 focus:border-{color}-500`, wajib toggle show/hide (`x-data="{ show: false }"`, ikon `ti-eye`/`ti-eye-off`, 1 `x-data` terpisah per field biar independen). - **Accordion sidebar yang baru dibuka scroll otomatis ke posisi terlihat** β€” method `toggleGroup(name)` di `x-data` root `