# PRD — Pembinaan, Apresiasi, dan Prestasi Siswa - **Status:** Implementasi source selesai — siap commit/review, belum deploy production - **Versi:** 1.0 - **Tanggal:** 24 Agustus 2026 - **Produk:** UtiVerse — Homeroom Workspace / Wali Kelas - **Nama fitur:** Pembinaan Wali Kelas serta Apresiasi & Prestasi Siswa --- ## 0. Cara menggunakan PRD ini Dokumen ini adalah kontrak implementasi. Agent/IDE yang melanjutkan pekerjaan wajib: 1. Membaca dokumen ini sampai selesai sebelum mengubah kode. 2. Memeriksa `git status`, branch, migration, route, model, service, halaman, dan test aktual karena repository dapat berubah setelah PRD dibuat. 3. Mengerjakan fase secara berurutan. Jangan memulai fase berikutnya sebelum Definition of Done fase aktif terpenuhi. 4. Tidak mengedit migration lama yang sudah pernah dijalankan; selalu membuat migration baru. 5. Menjaga data `student_homeroom_notes` lama. Migrasi data harus dapat dilacak dan tidak menghapus sumber lama pada versi pertama. 6. Menjaga lifecycle Catatan Pelanggaran yang sudah ada. Penanganan pelanggaran tidak boleh disalin menjadi Pembinaan Wali Kelas. 7. Memakai `HomeroomAccessService`, `PeriodContext`, dan histori enrollment untuk isolasi kelas/periode. 8. Menjalankan verification commands pada fase aktif dan menyimpan hasilnya di bagian checkpoint. 9. Mencentang checklist hanya setelah kode dan bukti verifikasinya selesai. Kode yang baru ditulis tetapi belum diuji tetap `[ ]`. 10. Jika konteks/token hampir habis, berhenti pada perubahan yang atomik dan aman; jangan meninggalkan migration setengah jadi atau UI yang menunjuk route yang belum tersedia. 11. Pada handoff, tuliskan fase aktif, item terakhir, file yang diubah, test yang lulus, test yang belum dijalankan, risiko, dan langkah berikutnya. 12. Jangan melakukan push atau deployment kecuali diminta secara eksplisit. ### Status implementasi - [x] PRD dan keputusan batas domain disusun. - [x] Phase 0 — Safety net dan kontrak domain. - [x] Phase 1 — Skema baru dan backfill data lama. - [x] Phase 2 — Pembinaan Wali Kelas. - [x] Phase 3 — Apresiasi & Prestasi. - [x] Phase 4 — Profil siswa, dashboard, dan publikasi ke siswa. - [x] Phase 5 — Laporan DOCX. - [x] Phase 6 — Cutover Catatan Wali Kelas lama dan analytics. - [x] Phase 7 — Hardening, QA, dokumentasi, dan rollout. **Checkpoint terakhir:** Seluruh Phase 0–7 selesai pada 24 Agustus 2026. Final gate: 120 test/1.387 assertion, typecheck, production build, scoped Pint, diff check, route contract, rollback/rerun migration MySQL, browser QA empat role dan tiga viewport, serta verifikasi tiga jenis DOCX melalui Microsoft Word. Full Pint hanya melaporkan debt lama di luar file perubahan. Source belum di-commit/push dan migration production belum dijalankan; langkah berikutnya adalah review pengguna, commit/push bila diminta, lalu deployment dengan backup dan migration gate pada panduan wali kelas. ### Format checkpoint wajib setelah setiap fase ```text Tanggal/waktu: Branch dan HEAD: Fase aktif: Checklist yang baru selesai: File yang diubah: Migration/data command yang dijalankan: Test lulus: Test belum dijalankan: QA manual: Risiko/temuan tersisa: Langkah berikutnya: ``` --- ## 1. Ringkasan keputusan produk Homeroom Workspace mempunyai empat domain yang berbeda. Nama menu dan penyimpanan data harus mengikuti perbedaan ini. | Domain | Makna | Cakupan | Lifecycle | Contoh | |---|---|---|---|---| | Catatan Pelanggaran | Kasus kedisiplinan/insiden | Satu siswa | Open → tindak lanjut → resolved/reopen | Membolos, perkelahian, pelanggaran tata tertib | | Pembinaan Wali Kelas | Kegiatan pembinaan non-kasus | Seluruh kelas, kelompok, atau individual | Dicatat sebagai kegiatan selesai; follow-up opsional | Pembinaan Senin, refleksi Jumat, motivasi belajar | | Apresiasi | Pengakuan positif dari wali kelas | Satu atau beberapa siswa | Internal atau dipublikasikan ke siswa | Konsisten membantu teman, kemajuan belajar | | Prestasi | Capaian formal akademik/nonakademik | Satu atau beberapa siswa | Internal atau dipublikasikan ke siswa | Juara lomba, peserta terbaik, penghargaan sekolah | ### Keputusan utama 1. **Catatan Pelanggaran tetap berdiri sendiri.** Tindakan awal, pemanggilan orang tua, konseling, penyelesaian, dan pembukaan kembali kasus tetap dicatat pada timeline kasus. 2. **Pembinaan tidak menjadi salinan penanganan pelanggaran.** Timeline profil siswa sudah menggabungkan kasus dan tindak lanjut sehingga duplikasi hanya akan membuat laporan ganda dan membingungkan. 3. **Pembinaan klasikal adalah kebutuhan utama.** Pembinaan rutin Senin/Jumat dicatat sekali untuk kelas dengan snapshot seluruh peserta, bukan dibuat menjadi puluhan catatan individual. 4. **Pembinaan individual hanya untuk konteks non-pelanggaran.** Contoh: motivasi belajar, adaptasi, kebiasaan belajar, kesejahteraan, atau pendampingan umum. 5. **Apresiasi dan Prestasi menjadi modul tersendiri.** Keduanya tidak lagi disimpan sebagai jenis generik `positive` pada Catatan Wali Kelas. 6. **Data positif lama dipertahankan.** Catatan `positive` lama dibackfill menjadi Apresiasi internal agar tidak tiba-tiba terlihat oleh siswa. 7. **Tidak ada poin, XP, ranking, atau leaderboard.** Modul ini membangun rekam jejak positif, bukan kompetisi mengumpulkan penghargaan. 8. **DOCX adalah keluaran resmi utama.** Minimal tersedia rekap kelas dan riwayat individual untuk Pembinaan serta Apresiasi & Prestasi. ### Contoh penempatan yang benar | Situasi | Dicatat di | |---|---| | Wali memberi pengarahan disiplin kepada seluruh kelas setiap Senin | Pembinaan Klasikal | | Lima siswa mengikuti refleksi belajar | Pembinaan Kelompok | | Satu siswa perlu motivasi karena menurun tetapi tidak melanggar | Pembinaan Individual | | Siswa melanggar dan dipanggil bersama orang tua | Tindak lanjut Catatan Pelanggaran | | Setelah satu kasus, wali mengingatkan seluruh kelas tanpa menyebut pelaku | Pembinaan Klasikal baru, tanpa tautan ke kasus | | Siswa konsisten menjadi teman belajar yang baik | Apresiasi | | Siswa meraih Juara II lomba tingkat kabupaten | Prestasi | --- ## 2. Latar belakang masalah Fitur `Catatan Wali Kelas` saat ini mempunyai tipe `general`, `coaching`, dan `positive`. Struktur tersebut terlalu generik karena semua entri hanya mempunyai siswa, tipe, tanggal, dan isi bebas. Dampaknya: - pencapaian positif tidak mempunyai judul, kategori, tingkat, hasil, atau penyelenggara; - pembinaan seluruh kelas harus dicatat berulang untuk setiap siswa atau tidak tercatat dengan benar; - pembinaan individual berpotensi tumpang tindih dengan tindak lanjut pelanggaran; - dashboard lebih menonjolkan pelanggaran daripada rekam positif siswa; - `positive` terasa seperti label catatan, bukan penghargaan; - laporan belum dapat menghasilkan rekap Apresiasi & Prestasi yang terstruktur; - siswa belum mempunyai tampilan penghargaan yang dipublikasikan wali kelas; - data lama tidak boleh hilang ketika domain baru diperkenalkan. --- ## 3. Tujuan, indikator keberhasilan, dan non-goals ### 3.1 Tujuan utama - Wali kelas dapat mencatat pembinaan klasikal mingguan dalam waktu kurang dari dua menit. - Satu kegiatan pembinaan dapat mencakup seluruh kelas, kelompok terpilih, atau satu siswa. - Penanganan pelanggaran hanya dicatat satu kali pada domain kasus. - Wali kelas dapat memberi Apresiasi atau mencatat Prestasi dengan data yang jelas. - Penghargaan yang dipublikasikan dapat dilihat oleh siswa pemiliknya. - Wali kelas dapat mengunduh DOCX sesuai kelas, siswa, periode, dan filter. - Semua data mematuhi kelas, tahun pelajaran, semester, dan mode arsip. - Data Catatan Wali Kelas lama tetap tersedia setelah cutover. ### 3.2 Indikator keberhasilan - Pembinaan seluruh kelas menghasilkan satu session dan snapshot peserta yang benar. - Tidak ada entri pembinaan otomatis ketika follow-up pelanggaran dibuat. - Apresiasi dan Prestasi dapat difilter terpisah. - Prestasi menampilkan kategori, tingkat, hasil, dan penyelenggara bila diisi. - Siswa hanya melihat penghargaan miliknya yang berstatus dipublikasikan. - Wali kelas/guru lain tidak dapat melihat atau mengubah data kelas di luar kewenangannya. - Arsip periode dapat dibaca tetapi tidak dapat dimutasi. - DOCX data nihil, satu entri, dan banyak entri dapat dibuka dan tidak bocor lintas kelas. - Query daftar/dashboard tidak bertambah linear terhadap jumlah siswa. ### 3.3 Non-goals versi pertama - Tidak membuat leaderboard, ranking siswa, XP, badge otomatis, atau reward marketplace. - Tidak mengubah nilai akademik berdasarkan Apresiasi/Prestasi. - Tidak membuat jadwal otomatis yang langsung mencatat pembinaan setiap Senin/Jumat; kegiatan hanya dicatat jika benar-benar dilaksanakan. - Tidak memberi akses orang tua karena akun orang tua belum tersedia. - Tidak mengirim WhatsApp otomatis. - Tidak menghubungkan Pembinaan Klasikal ke identitas pelaku suatu kasus. - Tidak mengunggah lampiran bukti pada versi pertama; hanya referensi bukti berbentuk teks/nomor dokumen/URL opsional. File privat menjadi fase lanjutan terpisah. - Tidak menghapus tabel atau data `student_homeroom_notes` lama pada rollout pertama. - Tidak membuat sertifikat kompetisi resmi otomatis. Lembar penghargaan DOCX adalah catatan sekolah, bukan pengganti sertifikat penyelenggara. --- ## 4. Terminologi - **Pembinaan Klasikal:** pembinaan untuk seluruh roster aktif kelas pada periode tersebut. - **Pembinaan Kelompok:** pembinaan untuk beberapa siswa yang dipilih dari kelas yang sama. - **Pembinaan Individual:** pembinaan non-pelanggaran untuk satu siswa. - **Session Pembinaan:** satu kegiatan pada satu tanggal, dengan judul, kategori, ringkasan, hasil, dan peserta. - **Snapshot peserta:** daftar siswa yang menjadi sasaran pembinaan saat session dibuat; tidak berubah ketika siswa naik/pindah kelas. - **Apresiasi:** pengakuan wali kelas terhadap usaha, sikap, perkembangan, atau kontribusi positif. - **Prestasi:** capaian formal yang mempunyai konteks kategori, tingkat, hasil, atau penyelenggara. - **Internal:** hanya terlihat oleh wali kelas/admin yang berwenang. - **Dipublikasikan:** dapat dilihat siswa pemilik melalui portal siswa. - **Legacy note:** data lama pada `student_homeroom_notes`. --- ## 5. Pengguna dan akses ### 5.1 Wali kelas Wali kelas aktif dapat: - melihat data kelas/periode yang menjadi tanggung jawabnya; - membuat, mengubah, dan menghapus Pembinaan pada periode aktif; - memilih peserta hanya dari roster kelas yang sah; - membuat, mengubah, menghapus, mempublikasikan, atau membatalkan publikasi Apresiasi/Prestasi; - mengunduh DOCX sesuai kelas dan periode; - membuka arsip periode yang memang pernah menjadi tanggung jawabnya dalam mode read-only. Catatan yang dibuat pengguna lain hanya dapat diubah sesuai policy: pencatat atau admin. Pergantian wali tidak memindahkan kepemilikan mutation historis. ### 5.2 Admin Admin dapat mengakses kelas sesuai capability admin existing, melakukan koreksi, serta mengekspor laporan. Semua mutation dan export harus masuk audit log. ### 5.3 Guru non-wali Guru non-wali tidak memperoleh akses hanya karena menu frontend terlihat atau mengetahui URL. Controller/policy wajib menolak akses. ### 5.4 Siswa Siswa hanya dapat: - melihat Apresiasi/Prestasi miliknya yang dipublikasikan; - melihat detail yang memang ditandai untuk siswa; - mengunduh riwayat penghargaannya sendiri bila endpoint DOCX siswa diaktifkan. Siswa tidak dapat melihat Pembinaan internal, penghargaan internal, penghargaan siswa lain, catatan pelanggaran siswa lain, atau identitas pencatat yang tidak perlu ditampilkan. --- ## 6. Alur produk ### 6.1 Pembinaan klasikal rutin 1. Wali membuka **Pembinaan Wali Kelas**. 2. Menekan **Catat Pembinaan**. 3. Scope default adalah **Seluruh kelas**. 4. Sistem mengambil roster aktif sesuai kelas dan tahun pelajaran, lalu menampilkan jumlah peserta yang akan disnapshot. 5. Wali mengisi tanggal, kategori, judul/topik, ringkasan materi, hasil, dan tindak lanjut opsional. 6. Ketika disimpan, session dan seluruh participant dibuat dalam satu transaction. 7. Entri tampil pada daftar pembinaan dan timeline setiap peserta tanpa menduplikasi record utama. Contoh kategori awal: - Rutin/Apel kelas - Kedisiplinan umum - Belajar dan akademik - Karakter - Sosial dan relasi - Kesejahteraan - Karier - Lainnya ### 6.2 Pembinaan kelompok atau individual 1. Wali memilih scope **Kelompok** atau **Individual**. 2. Hanya siswa dari kelas/periode yang sah yang dapat dipilih. 3. Individual mensyaratkan tepat satu siswa; Kelompok mensyaratkan minimal dua siswa. 4. Pembinaan harus non-pelanggaran. 5. Jika konteksnya merupakan tindakan terhadap kasus aktif, UI menampilkan petunjuk untuk membuka detail Catatan Pelanggaran. ### 6.3 Penanganan pelanggaran Alur existing dipertahankan: 1. Pelanggaran dibuat sebagai kasus `open`. 2. Tindak lanjut menambah timeline kasus dan mengubah status sesuai lifecycle. 3. Pemanggilan orang tua, pembinaan karena kasus, konseling, penyelesaian, dan reopen tetap berada pada kasus. 4. `HomeroomStudentOverviewService` menampilkan follow-up tersebut pada timeline siswa. 5. Sistem tidak membuat `homeroom_guidance_session` secara otomatis. ### 6.4 Memberikan Apresiasi 1. Wali membuka **Apresiasi & Prestasi**. 2. Menekan **Beri Apresiasi**. 3. Memilih satu atau beberapa siswa dari kelas yang sama. 4. Mengisi judul, kategori, tanggal, dan deskripsi. 5. Memilih status **Internal** atau **Tampilkan kepada siswa**. 6. Jika beberapa siswa dipilih, server membuat satu record per siswa dalam transaction agar setiap siswa mempunyai riwayat individual. Kategori Apresiasi awal: - Karakter - Kedisiplinan positif - Kepemimpinan - Kepedulian sosial - Perkembangan belajar - Kreativitas - Tanggung jawab - Lainnya ### 6.5 Mencatat Prestasi Field wajib: - siswa; - judul prestasi; - kategori; - tanggal; - tingkat; - hasil/pencapaian; - deskripsi singkat. Field opsional: - penyelenggara; - referensi bukti, nomor dokumen, atau URL; - status publikasi. Kategori Prestasi awal: - Akademik - Olahraga - Seni dan budaya - Keagamaan - Organisasi/kepemimpinan - Teknologi - Lingkungan/sosial - Lainnya Tingkat Prestasi: - Kelas - Sekolah - Kecamatan - Kabupaten/Kota - Provinsi - Nasional - Internasional ### 6.6 Publikasi ke siswa - Default record baru adalah `internal` kecuali wali secara sadar mengaktifkan publikasi. - Perubahan menjadi `student` menyimpan `published_at` dan `published_by`. - Pembatalan publikasi menyembunyikan record dari portal siswa tanpa menghapus data internal. - Notifikasi database tidak menjadi bagian versi pertama; publikasi cukup membuat record terlihat pada portal siswa. - Data legacy hasil backfill selalu `internal` untuk mencegah kebocoran catatan lama. ### 6.7 Arsip - Pemilih tahun pelajaran/semester memakai pola Homeroom existing. - Periode lama yang sah dapat dibaca dan diekspor. - Create, update, delete, publish, dan unpublish ditolak pada periode arsip. - Nama siswa/kelas pada laporan mengikuti data periode yang benar, bukan sekadar kelas terkini. --- ## 7. Struktur data Semua tabel dibuat melalui migration baru. ### 7.1 `homeroom_guidance_sessions` | Kolom | Tipe | Catatan | |---|---|---| | `id` | bigint | Primary key | | `class_id` | FK `synced_classes` | Kelas pada periode | | `academic_year_id` | FK `academic_years` | Wajib | | `semester_id` | FK nullable `semesters` | Sesuai PeriodContext | | `scope` | string(20) | `class`, `group`, `individual` | | `category` | string(30) | Allow-list kategori pembinaan | | `guidance_date` | date | Harus berada dalam periode | | `title` | string(160) | Judul/topik | | `summary` | text | Materi/ringkasan pembinaan | | `outcome` | text nullable | Hasil/refleksi | | `follow_up` | text nullable | Rencana tindak lanjut non-kasus | | `recorded_by` | FK `users` | Pencatat | | `updated_by` | FK nullable `users` | Aktor edit terakhir | | `legacy_homeroom_note_id` | FK nullable unique | Jejak backfill catatan lama | | `deleted_at` | timestamp nullable | Soft delete | | timestamps | | | Index minimum: - `(class_id, academic_year_id, semester_id, guidance_date)`; - `(scope, category)`; - unique nullable `legacy_homeroom_note_id`. ### 7.2 `homeroom_guidance_participants` | Kolom | Tipe | Catatan | |---|---|---| | `id` | bigint | Primary key | | `guidance_session_id` | FK | Cascade delete bersama session | | `student_id` | FK `synced_students` | Snapshot peserta | | timestamps | | | Unique index: `(guidance_session_id, student_id)`. Aturan: - scope `class`: participant harus sama dengan roster aktif saat dibuat; - scope `individual`: tepat satu participant; - scope `group`: minimal dua participant; - semua participant wajib anggota kelas dan tahun pelajaran yang sama; - perubahan roster di masa depan tidak mengubah participant lama. ### 7.3 `student_recognitions` | Kolom | Tipe | Catatan | |---|---|---| | `id` | bigint | Primary key | | `class_id` | FK `synced_classes` | Kelas saat penghargaan dicatat | | `student_id` | FK `synced_students` | Pemilik record | | `academic_year_id` | FK `academic_years` | Wajib | | `semester_id` | FK nullable `semesters` | Sesuai periode | | `type` | string(20) | `appreciation`, `achievement` | | `title` | string(180) | Judul penghargaan/prestasi | | `category` | string(30) | Allow-list sesuai tipe | | `recognized_on` | date | Tanggal apresiasi/prestasi | | `description` | text | Uraian | | `level` | string(30) nullable | Hanya Prestasi | | `result` | string(160) nullable | Hasil, mis. Juara II | | `organizer` | string(180) nullable | Penyelenggara | | `evidence_reference` | string(500) nullable | Nomor dokumen/URL/referensi teks | | `visibility` | string(20) | `internal`, `student` | | `published_at` | timestamp nullable | Waktu publikasi | | `published_by` | FK nullable `users` | Aktor publikasi | | `recorded_by` | FK `users` | Pencatat | | `updated_by` | FK nullable `users` | Aktor edit terakhir | | `legacy_homeroom_note_id` | FK nullable unique | Sumber note positif lama | | `deleted_at` | timestamp nullable | Soft delete | | timestamps | | | Index minimum: - `(class_id, academic_year_id, semester_id, recognized_on)`; - `(student_id, academic_year_id, semester_id, recognized_on)`; - `(class_id, type, category)`; - `(student_id, visibility, recognized_on)`; - unique nullable `legacy_homeroom_note_id`. ### 7.4 Validasi lintas field - `appreciation`: `level`, `result`, dan `organizer` boleh kosong dan tidak dipaksakan. - `achievement`: `level` dan `result` wajib; `organizer` opsional. - `visibility=student`: `published_at` dan `published_by` wajib diset server-side. - `visibility=internal`: publikasi boleh null; unpublish tidak menghapus histori audit. - Judul, deskripsi, dan referensi harus disanitasi saat masuk DOCX. --- ## 8. Strategi data lama ### 8.1 Prinsip - `student_homeroom_notes` tidak dihapus pada versi pertama. - Backfill tidak boleh memodifikasi atau menghapus row lama. - Setiap row hasil backfill menyimpan `legacy_homeroom_note_id` yang unique. - Backfill harus idempotent dan aman dijalankan ulang. - Data lama tidak dipublikasikan otomatis kepada siswa. ### 8.2 Pemetaan | Type lama | Tujuan baru | Nilai default | |---|---|---| | `general` | Pembinaan Individual | category `other`, title `Catatan wali kelas lama` | | `coaching` | Pembinaan Individual | category `other`, title `Pembinaan individual lama` | | `positive` | Apresiasi | category `other`, title `Apresiasi dari catatan positif`, visibility `internal` | Setiap general/coaching menghasilkan satu session dan satu participant. ### 8.3 Pelaksanaan backfill - Gunakan migration/service yang memproses data per chunk. - Lakukan insert dalam transaction kecil agar tidak mengunci seluruh tabel lama. - Skip row yang sudah mempunyai pasangan `legacy_homeroom_note_id`. - Log jumlah sumber, sukses, skip, dan gagal tanpa menulis isi sensitif ke log. - Feature test wajib membuktikan rerun tidak menggandakan data. - Rollback migration baru menghapus tabel baru tetapi meninggalkan sumber lama tetap utuh. ### 8.4 Cutover - Menu baru tidak menulis ke `student_homeroom_notes`. - Selama Phase 1–5, route lama tetap tersedia untuk regression safety tetapi tidak lagi ditautkan setelah layar baru stabil. - Pada Phase 6, `GET /homeroom/notes` menjadi halaman transisi/redirect yang mengarahkan pembinaan ke modul Pembinaan dan tipe `positive` ke Apresiasi & Prestasi. - Mutation route lama dinonaktifkan setelah seluruh link/form lama diganti dan regression test diperbarui. - Tabel/model legacy tetap disimpan minimal satu rollout penuh dan baru boleh dibahas untuk dihapus pada PRD lain. --- ## 9. Backend boundaries ### 9.1 Class baru yang direncanakan - `HomeroomGuidanceSession` model. - `HomeroomGuidanceParticipant` model. - `StudentRecognition` model. - `HomeroomGuidanceController`. - `StudentRecognitionController`. - `StudentRecognitionPortalController`. - `StoreHomeroomGuidanceRequest` dan `UpdateHomeroomGuidanceRequest`. - `StoreStudentRecognitionRequest` dan `UpdateStudentRecognitionRequest`. - `HomeroomGuidanceService`: transaction, participant snapshot, dan audit. - `StudentRecognitionService`: bulk create, publish/unpublish, dan audit. - `HomeroomRecognitionReportService`: query dataset DOCX tanpa N+1. - Policy atau Gate khusus untuk view/mutation setiap model. ### 9.2 Class existing yang perlu diperluas - `HomeroomStudentOverviewService`: gabungkan guidance dan recognition ke timeline. - `HomeroomDashboardService`: ringkasan jumlah pembinaan/apresiasi/prestasi. - `HomeroomAnalyticsService`: ganti `positive_notes` dengan data recognition terstruktur. - `HomeroomDocxService`: renderer laporan Pembinaan dan Recognition. - `HomeroomReportController`: endpoint DOCX baru. - `AuthenticatedLayout.tsx`: menu baru dan penggantian label Catatan Wali Kelas. - `Homeroom/Dashboard.tsx`: quick actions baru. - `Homeroom/StudentShow.tsx`: section Pembinaan dan Apresiasi & Prestasi. ### 9.3 Aturan service - Semua create multi-table memakai database transaction. - Participant/recipient divalidasi ulang server-side; pilihan UI tidak dianggap aman. - Periode dan tanggal diverifikasi melalui service existing. - Create/update/delete/publish/unpublish/export masuk `SystemAuditLog`. - Deskripsi audit hanya menyimpan ID, kelas, tipe, dan jumlah record; tidak menyimpan isi catatan sensitif. - Bulk appreciation/achievement gagal seluruhnya jika satu siswa tidak sah; tidak boleh partial success diam-diam. --- ## 10. Route contract Nama route dapat disesuaikan dengan konvensi aktual, tetapi URL dan boundary berikut menjadi kontrak produk. ### 10.1 Pembinaan Wali Kelas ```text GET /homeroom/guidance POST /homeroom/guidance GET /homeroom/guidance/{guidance} PUT /homeroom/guidance/{guidance} DELETE /homeroom/guidance/{guidance} ``` ### 10.2 Apresiasi & Prestasi ```text GET /homeroom/recognitions POST /homeroom/recognitions GET /homeroom/recognitions/{recognition} PUT /homeroom/recognitions/{recognition} DELETE /homeroom/recognitions/{recognition} POST /homeroom/recognitions/{recognition}/publish POST /homeroom/recognitions/{recognition}/unpublish ``` ### 10.3 DOCX ```text GET /homeroom/reports/guidance/docx GET /homeroom/reports/guidance/student/{student}/docx GET /homeroom/reports/recognitions/docx GET /homeroom/reports/recognitions/student/{student}/docx GET /homeroom/reports/recognitions/{recognition}/docx ``` ### 10.4 Portal siswa ```text GET /student/recognitions GET /student/recognitions/export/docx ``` Endpoint siswa selalu mengambil `student_id` dari akun login, bukan request. --- ## 11. Struktur frontend dan UX ### 11.1 Navigasi Wali Kelas Urutan menu yang direkomendasikan: 1. Ringkasan Wali Kelas 2. Biodata Siswa 3. Absensi Harian 4. Pembinaan Wali Kelas 5. Catatan Pelanggaran 6. Apresiasi & Prestasi 7. Voting Kelas ### 11.2 Dashboard Quick action minimum: - Catat Absensi - Catat Pembinaan - Catat Pelanggaran - Beri Apresiasi - Catat Prestasi - Unduh Laporan Metric/tren tidak menampilkan nama atau ranking: - jumlah session pembinaan; - jumlah siswa yang menerima apresiasi; - jumlah prestasi; - jumlah kasus; - komunikasi orang tua. ### 11.3 Halaman Pembinaan - Filter kelas, periode, scope, kategori, rentang tanggal, dan siswa. - Kartu/row menampilkan tanggal, judul, scope, kategori, jumlah peserta, pencatat. - Form mobile-first dengan scope sebagai pilihan jelas. - Scope seluruh kelas menampilkan konfirmasi jumlah roster. - Scope kelompok memakai multi-select/search siswa. - Detail menampilkan peserta snapshot, ringkasan, hasil, dan follow-up. - Mode arsip menampilkan banner read-only. ### 11.4 Halaman Apresiasi & Prestasi - Tab atau segmented control **Semua / Apresiasi / Prestasi**. - Filter siswa, kategori, tingkat, status publikasi, dan rentang tanggal. - Tombol **Beri Apresiasi** dan **Catat Prestasi** terpisah agar form tidak terasa generik. - Prestasi menampilkan tingkat dan hasil sebagai metadata utama. - Status Internal/Ditampilkan ke siswa terlihat tanpa membuka detail. - Aksi publish/unpublish mempunyai konfirmasi. ### 11.5 Profil siswa Wali Kelas Tambahkan ringkasan terpisah: - Pembinaan yang melibatkan siswa; - Apresiasi; - Prestasi; - Pelanggaran/tindak lanjut existing; - komunikasi orang tua existing. Timeline terpadu memakai `kind` berbeda: - `violation` - `follow_up` - `guidance` - `recognition_appreciation` - `recognition_achievement` - `parent_communication` Satu event hanya muncul sekali. Guidance klasikal tampil pada tiap peserta melalui pivot, tetapi sumber datanya tetap satu session. ### 11.6 Portal siswa - Halaman **Apresiasi & Prestasi Saya**. - Hanya data `visibility=student` milik akun login. - Kartu Apresiasi dan Prestasi dibedakan secara visual, tetapi tidak memakai ranking. - Siswa tidak dapat mengubah data. - Empty state bersifat positif dan tidak membocorkan adanya record internal. ### 11.7 Mobile contract - Nyaman pada 320×568 dan 390×844. - Tidak ada horizontal scroll. - Target sentuh minimum 44 px. - Multi-select siswa tidak membuat modal melewati viewport. - Primary action tetap terlihat dan tidak tertutup navigasi bawah/safe area. - Metadata panjang memakai wrap, bukan memaksa lebar halaman. --- ## 12. Laporan DOCX Gunakan pola existing `HomeroomDocxService` dan template `resources/documents/templates/homeroom-report.docx` agar kop, tabel, sanitasi, nama file, file sementara, dan signature konsisten. ### 12.1 Rekap Pembinaan Kelas Memuat: - kelas, wali kelas, tahun pelajaran/semester, rentang tanggal; - jumlah session menurut scope/kategori; - tanggal, judul, scope, kategori, jumlah peserta, ringkasan, hasil, follow-up, pencatat; - keterangan bahwa session klasikal memakai snapshot peserta; - tanda tangan Wali Kelas dan pihak Mengetahui. ### 12.2 Riwayat Pembinaan Individual Memuat seluruh session yang menyertakan siswa sesuai filter, termasuk session klasikal dan kelompok. Jangan menggandakan satu session. ### 12.3 Rekap Apresiasi & Prestasi Kelas Memuat: - jumlah Apresiasi dan Prestasi; - nama siswa, tanggal, tipe, judul, kategori, tingkat, hasil, penyelenggara, status publikasi; - filter dan periode; - tanda tangan Wali Kelas dan pihak Mengetahui. ### 12.4 Riwayat Apresiasi & Prestasi Individual Memuat identitas siswa serta seluruh penghargaan sesuai filter. Record internal dapat masuk laporan wali kelas, tetapi export milik siswa hanya memuat record yang dipublikasikan. ### 12.5 Lembar Penghargaan Satu Entri Memuat satu Apresiasi/Prestasi, identitas siswa, deskripsi, tingkat/hasil/penyelenggara bila ada, tanggal, dan tanda tangan Wali Kelas. Dokumen diberi label **Lembar Penghargaan UtiVerse**, bukan sertifikat resmi penyelenggara. ### 12.6 Keamanan dokumen - Otorisasi dilakukan sebelum query dataset dan sebelum render. - Semua filter divalidasi. - Teks kontrol dibersihkan sebelum dimasukkan ke OOXML. - Nama file disanitasi. - File dibuat di storage private dan dihapus setelah streaming. - Data nihil tetap menghasilkan dokumen valid. - Export masuk audit log tanpa menyalin isi sensitif. --- ## 13. Compatibility contract 1. Lifecycle `StudentViolation` dan `StudentViolationFollowUp` tidak berubah arti. 2. Tindak lanjut pelanggaran tidak membuat Pembinaan secara otomatis. 3. Timeline siswa tetap menampilkan violation dan follow-up existing. 4. Absensi harian/mapel, status T, rekap XLSX/DOCX, biodata, komunikasi, Voting, dan laporan pelanggaran existing tetap berjalan. 5. Data `student_homeroom_notes` lama tidak dihapus. 6. Data positif lama tidak dipublikasikan otomatis. 7. Tidak ada mutation arsip. 8. Tidak ada akses lintas kelas, periode, atau siswa. 9. Menu frontend bukan mekanisme otorisasi. 10. Tidak ada XP, ranking, atau leaderboard berdasarkan recognition. 11. Tidak ada detail pelanggaran siswa yang bocor melalui Pembinaan Klasikal. 12. Route laporan pelanggaran existing tetap berfungsi setelah route DOCX baru ditambahkan. --- ## 14. Tahap implementasi wajib ### Phase 0 — Safety net dan kontrak domain - [x] Rekam kondisi awal branch, status worktree, route, migration, dan focused test existing. - [x] Verifikasi characterization coverage Catatan Wali `general/coaching/positive` existing. - [x] Verifikasi regression coverage bahwa follow-up pelanggaran hanya muncul sekali pada timeline. - [x] Tambahkan test otorisasi kelas/periode yang akan dipakai modul baru. - [x] Tetapkan enum/constant kategori, scope, type, level, dan visibility pada satu sumber backend. - [x] Pastikan full route pelanggaran, pembinaan lama, profile timeline, dan DOCX existing tercakup safety net. - [x] Jalankan focused Homeroom dan StudentViolation tests sebelum schema diubah. - [x] Perbarui checkpoint PRD dengan hasil nyata. **Status Phase 0:** Selesai 24 Agustus 2026. Coverage existing telah mengunci lifecycle note `general/coaching/positive`, isolasi kelas/periode, timeline violation/follow-up, dan export DOCX. Baseline menemukan lalu memperbaiki penanganan exception laporan yang mengubah 403 menjadi 302. Verifikasi: Homeroom 32 test/337 assertion; StudentViolation 7 test/77 assertion. **Definition of Done:** perilaku existing terdokumentasi melalui test; batas Pelanggaran vs Pembinaan vs Recognition terkunci; belum ada perubahan schema produksi. ### Phase 1 — Skema baru dan backfill data lama - [x] Buat migration tabel `homeroom_guidance_sessions`. - [x] Buat migration tabel `homeroom_guidance_participants`. - [x] Buat migration tabel `student_recognitions`. - [x] Buat model, relation, casts, dan constants. - [x] Implementasikan backfill idempotent dari `student_homeroom_notes`. - [x] Pastikan catatan positif legacy menjadi Apresiasi `internal`. - [x] Pastikan general/coaching legacy menjadi Pembinaan Individual dengan satu participant. - [x] Test migration up/down pada database testing. - [x] Test rerun/backfill tidak menggandakan record. - [x] Test row legacy tetap utuh setelah rollback tabel baru. - [x] Jalankan formatting, focused test, dan diff check. - [x] Perbarui checkpoint PRD. **Status Phase 1:** Selesai 24 Agustus 2026. Migration baru bersifat additive; backfill memakai jejak legacy unique, aman dijalankan ulang, dan rollback tidak menghapus sumber lama. Verifikasi: 2 test/14 assertion khusus migration; 34 test/351 assertion seluruh Homeroom; scoped Pint dan `git diff --check` lulus. **Definition of Done:** schema dan backfill aman, idempotent, dapat di-rollback tanpa kehilangan data lama, serta belum mengubah UI pengguna. ### Phase 2 — Pembinaan Wali Kelas - [x] Implementasikan request validation, service transaction, controller, policy/Gate, dan route. - [x] Implementasikan roster snapshot untuk scope klasikal. - [x] Implementasikan validasi participant individual/kelompok. - [x] Implementasikan list, filter, create, detail, edit, dan soft delete. - [x] Implementasikan banner/mutation guard mode arsip. - [x] Tambahkan menu dan quick action Pembinaan. - [x] Tambahkan timeline `guidance` pada profil siswa tanpa N+1. - [x] Tambahkan audit log create/update/delete. - [x] Test lintas kelas, lintas periode, guru non-wali, wali lama, dan admin. - [x] Test scope class/group/individual dan perubahan roster setelah pencatatan. - [x] QA mobile 320×568 dan 390×844 serta desktop. - [x] Perbarui checklist dan checkpoint. **Status Phase 2:** Selesai 24 Agustus 2026. Pembinaan tetap terpisah dari penanganan pelanggaran; satu session menyimpan snapshot peserta dan muncul satu kali pada timeline setiap siswa. Verifikasi: 3 test/57 assertion khusus Pembinaan; 37 test/410 assertion seluruh Homeroom; QA browser lokal 320×568, 390×844, dan desktop tanpa horizontal overflow; production build, scoped Pint, dan `git diff --check` lulus. Typecheck global masih tertahan dua error baseline lama yang tidak disentuh fase ini. **Definition of Done:** pembinaan klasikal, kelompok, dan individual non-pelanggaran dapat dipakai dari HP; participant historis benar; tidak ada duplikasi dengan pelanggaran. ### Phase 3 — Apresiasi & Prestasi - [x] Implementasikan request validation, service, controller, policy/Gate, dan route. - [x] Implementasikan bulk create transaction untuk beberapa siswa. - [x] Implementasikan form Apresiasi dan Prestasi yang terpisah secara UX. - [x] Implementasikan list/detail/filter type, kategori, tingkat, siswa, tanggal, dan visibility. - [x] Implementasikan edit, soft delete, publish, dan unpublish. - [x] Tambahkan menu dan quick actions Apresiasi/Prestasi. - [x] Tambahkan audit log seluruh mutation. - [x] Test field wajib/opsional berdasarkan type. - [x] Test bulk create all-or-nothing dan membership server-side. - [x] Test data legacy tidak terlihat oleh siswa. - [x] QA mobile dan desktop. - [x] Perbarui checklist dan checkpoint. **Status Phase 3:** Selesai 24 Agustus 2026. Wali dapat memilih satu atau beberapa siswa, membedakan apresiasi harian dari prestasi formal, dan mengontrol publikasi tanpa notifikasi otomatis. Verifikasi: 3 test/67 assertion khusus recognition; 37 test/410 assertion seluruh Homeroom; QA browser lokal 320×568, 390×844, dan desktop; production build, scoped Pint, dan `git diff --check` lulus. Typecheck global tetap tertahan dua error baseline lama yang tidak disentuh fase ini. **Definition of Done:** wali dapat membuat rekam positif terstruktur dan memisahkan Apresiasi dari Prestasi tanpa akses lintas kelas atau publikasi tidak sengaja. ### Phase 4 — Profil siswa, dashboard, dan publikasi ke siswa - [x] Gabungkan guidance dan recognition ke overview/timeline siswa. - [x] Pastikan satu session klasikal muncul sekali per siswa peserta. - [x] Tambahkan ringkasan Pembinaan, Apresiasi, dan Prestasi pada profil wali kelas. - [x] Perbarui dashboard dan analytics tanpa ranking/nama siswa. - [x] Buat halaman portal siswa untuk recognition published. - [x] Pastikan endpoint siswa mengambil student dari login. - [x] Pastikan publikasi tidak bergantung pada notifikasi; notifikasi database tetap di luar scope versi pertama. - [x] Test internal vs published, unpublish, pemilik vs siswa lain, dan data nihil. - [x] Test query count tetap bounded terhadap jumlah siswa. - [x] QA portal siswa dan dashboard pada viewport mobile/desktop. - [x] Perbarui checkpoint PRD. **Status Phase 4:** Selesai 24 Agustus 2026. Timeline wali memisahkan follow-up kasus, pembinaan non-pelanggaran, dan penghargaan; portal siswa bersifat ownership-bound serta published-only. Verifikasi: 5 test/138 assertion khusus recognition/portal/integrasi, bounded query saat roster diperbesar, QA responsif wali dan siswa, production build, scoped Pint, dan `git diff --check` lulus. **Definition of Done:** profil terpadu akurat; siswa hanya melihat penghargaan published miliknya; dashboard tetap agregat dan performant. ### Phase 5 — Laporan DOCX - [x] Implementasikan dataset service untuk Pembinaan. - [x] Implementasikan dataset service untuk Apresiasi & Prestasi. - [x] Implementasikan rekap Pembinaan kelas DOCX. - [x] Implementasikan riwayat Pembinaan individual DOCX. - [x] Implementasikan rekap Recognition kelas DOCX. - [x] Implementasikan riwayat Recognition individual DOCX. - [x] Implementasikan Lembar Penghargaan satu entri DOCX. - [x] Implementasikan export published-only untuk siswa. - [x] Tambahkan tombol export sesuai halaman/filter. - [x] Test data nihil, satu, banyak, Unicode, multiline, filter, dan nama file. - [x] Test otorisasi dan file sementara terhapus. - [x] Render/inspect DOCX secara struktural dan buka sampel di Microsoft Word; LibreOffice bila tersedia. - [x] Perbarui checkpoint PRD dengan perbedaan verifikasi struktural dan visual. **Status Phase 5:** Selesai 24 Agustus 2026. Tersedia rekap kelas dan riwayat individual untuk Pembinaan serta Apresiasi/Prestasi, Lembar Penghargaan satu entri, dan riwayat published-only milik siswa. Verifikasi struktural: 8 test/94 assertion khusus laporan dan 16 test/291 assertion bersama modul guidance/recognition; production build, scoped Pint, serta `git diff --check` lulus. Verifikasi visual: tiga sampel dibuka dan diekspor melalui Microsoft Word, lalu seluruh tiga halaman PNG diperiksa tanpa overflow, pemotongan, atau placeholder tersisa. Renderer LibreOffice tidak tersedia pada mesin QA, sehingga pemeriksaan visual menggunakan engine Microsoft Word yang terpasang. Artefak QA sementara telah dihapus. **Definition of Done:** seluruh DOCX valid, sesuai filter/periode, tidak bocor lintas kelas, dapat dibuka, dan mempunyai audit export. ### Phase 6 — Cutover Catatan Wali Kelas lama dan analytics - [x] Ganti seluruh link/form `Catatan Wali Kelas` dengan dua modul baru. - [x] Ubah `GET /homeroom/notes` menjadi transisi/redirect aman. - [x] Nonaktifkan mutation legacy setelah tidak ada consumer tersisa. - [x] Pastikan data legacy tampil melalui modul baru hasil backfill. - [x] Ganti label/payload `positive_notes` menjadi recognition terstruktur dengan compatibility sementara bila dibutuhkan. - [x] Perbarui laporan individual lama agar tidak menggandakan legacy dan recognition. - [x] Search seluruh repo untuk consumer `StudentHomeroomNote` dan route `/homeroom/notes`. - [x] Jalankan seluruh regression Homeroom/StudentViolation/Report. - [x] Perbarui checkpoint PRD. **Status Phase 6:** Selesai 24 Agustus 2026. Form dan halaman generik lama telah dikeluarkan dari UI; profil siswa sekarang mengarahkan wali ke Pembinaan atau Apresiasi & Prestasi. `GET /homeroom/notes` mempertahankan kompatibilitas tautan lama melalui redirect berdasarkan type, sedangkan POST/PUT/DELETE selalu `410 Gone` dan tidak mengubah arsip legacy. Analytics tidak lagi mengirim `positive_notes`; sumber positif resmi adalah appreciation/achievement terstruktur. Query overview serta laporan lama mengecualikan row legacy yang sudah mempunyai pasangan backfill. Search repo menyisakan model/relation, migration/regression test, fallback orphan legacy, dan empat route transisi yang memang disengaja. Verifikasi: 47 test/597 assertion regression Homeroom terpilih lulus; focused report sesudah test anti-duplikasi 9 test/99 assertion; production build, scoped Pint, dan `git diff --check` lulus. **Definition of Done:** pengguna tidak lagi masuk ke form generik lama; semua data lama tetap terbaca; tidak ada double count atau double render. ### Phase 7 — Hardening, QA, dokumentasi, dan rollout - [x] Jalankan full PHP test suite. - [x] Jalankan typecheck, production build, scoped/full Pint sesuai debt existing, dan `git diff --check`. - [x] Jalankan route contract check. - [x] Verifikasi migration up/down dan backfill pada salinan database/testing. - [x] QA browser wali kelas/admin/guru non-wali/siswa. - [x] QA 320×568, 390×844, dan desktop tanpa horizontal overflow/console error. - [x] Buka sampel semua DOCX di Word; LibreOffice bila tersedia. - [x] Perbarui `docs/PANDUAN-WALI-KELAS.md`. - [x] Tambahkan panduan perbedaan Pelanggaran, Pembinaan, Apresiasi, dan Prestasi. - [x] Catat langkah deployment/migration production tanpa menjalankannya jika belum diminta. - [x] Tandai PRD complete hanya setelah seluruh acceptance criteria lulus. **Status Phase 7:** Selesai 24 Agustus 2026. Final gate lulus: full PHP 120 test/1.387 assertion; typecheck tanpa error; production build; scoped Pint pada seluruh file perubahan; `git diff --check`; dan kontrak 11 route laporan/transisi/portal. Full Pint read-only masih melaporkan debt formatting lama pada file di luar perubahan ini, sehingga tidak dilakukan rewrite massal. Migration baru diverifikasi melalui regression migration serta rollback/rerun batch 33 pada MySQL lokal: tabel legacy tetap ada, tabel structured hilang saat rollback dan kembali saat migrate. Percobaan `migrate:fresh` SQLite terhenti pada migration lama 8 Juli yang memakai SQL MySQL `MODIFY`, sebelum mencapai migration fitur ini; kegagalan tersebut bukan berasal dari migration baru. QA browser lulus untuk wali, admin, guru non-wali, dan siswa pada 320×568, 390×844, serta 1440×900 tanpa horizontal overflow atau console error. Seluruh fixture, akun, session, screenshot, dan dokumen QA sementara telah dihapus. Deployment production, commit, dan push belum dilakukan. **Definition of Done:** fitur siap dipakai sekolah, dokumentasi operasional jelas, regression existing aman, dan status deployment dilaporkan terpisah dari source code. --- ## 15. Acceptance test minimum ### 15.1 Batas domain - [x] Follow-up pelanggaran tidak membuat guidance/recognition. - [x] Timeline follow-up tampil sekali. - [x] Pembinaan non-pelanggaran tidak menambah hitungan kasus. - [x] Apresiasi/Prestasi tidak menambah hitungan kasus. - [x] Pembinaan klasikal tidak menampilkan identitas kasus yang menjadi latar belakang umum. ### 15.2 Pembinaan - [x] Scope class menyimpan semua roster aktif sebagai snapshot. - [x] Scope group menolak kurang dari dua siswa. - [x] Scope individual menolak lebih dari satu siswa. - [x] Siswa dari kelas/tahun lain ditolak. - [x] Session lama tidak berubah saat roster berubah. - [x] Arsip read-only. - [x] Soft deleted session tidak muncul pada daftar normal. ### 15.3 Apresiasi & Prestasi - [x] Apresiasi dapat disimpan tanpa level/result. - [x] Prestasi membutuhkan level/result. - [x] Bulk create gagal seluruhnya bila satu siswa tidak sah. - [x] Legacy positive menjadi Apresiasi internal. - [x] Publish hanya dapat dilakukan aktor berwenang pada periode aktif. - [x] Unpublish menyembunyikan record dari siswa. - [x] Siswa lain tidak dapat menebak/membuka ID recognition. - [x] Tidak ada poin/ranking/XP yang berubah. ### 15.4 DOCX - [x] Rekap Pembinaan kelas sesuai filter. - [x] Riwayat individual hanya memuat siswa terpilih. - [x] Rekap Recognition membedakan Apresiasi dan Prestasi. - [x] Export siswa hanya published. - [x] Data nihil valid. - [x] Unicode Indonesia dan multiline tidak rusak. - [x] File sementara dibersihkan. - [x] Nama file aman. - [x] Word dapat membuka sampel tanpa repair prompt. ### 15.5 Authorization dan periode - [x] Wali aktif hanya dapat mengakses kelas sah. - [x] Wali lama hanya dapat membaca arsip yang memang pernah menjadi tanggung jawabnya. - [x] Guru non-wali ditolak backend. - [x] Admin tercatat di audit ketika mutasi/export. - [x] Semester harus berada di tahun pelajaran yang dipilih. - [x] Tanggal record harus berada pada periode. ### 15.6 Regression - [x] Absensi mapel dan status T tetap berjalan. - [x] Absensi harian dan recap/export tetap berjalan. - [x] Lifecycle pelanggaran open/follow-up/resolve/reopen tetap berjalan. - [x] Biodata dan komunikasi orang tua tetap berjalan. - [x] Voting Kelas tetap berjalan. - [x] Laporan pelanggaran existing tetap dapat diunduh. --- ## 16. Verification commands Jalankan command yang relevan setelah setiap fase. Simpan jumlah test/assertion dan exit code pada checkpoint. ```powershell php artisan route:list --path=homeroom php artisan test --filter=HomeroomGuidance php artisan test --filter=StudentRecognition php artisan test --filter=HomeroomDashboard php artisan test --filter=StudentViolation php artisan test --filter=HomeroomReportExport vendor\bin\pint --test npm run typecheck npm run build git diff --check ``` Final gate Phase 7: ```powershell php artisan test php artisan route:list vendor\bin\pint --test npm run typecheck npm run build git diff --check git status --short --branch ``` Aturan database: - gunakan database testing/`RefreshDatabase` untuk migration test; - jangan menjalankan `migrate:fresh` pada database development/production berisi data tanpa persetujuan eksplisit; - sebelum deployment, hitung row legacy dan hasil backfill; - setelah deployment, verifikasi count, unique legacy mapping, dan visibility legacy internal. --- ## 17. Current repo map yang diverifikasi pada 24 Agustus 2026 - Branch `main` sinkron dengan `origin/main`; worktree bersih saat PRD disusun. - `routes/web.php`: route Homeroom berada dalam group guru; route siswa memakai `can:siswa`. - `app/Models/StudentHomeroomNote.php`: type existing `general`, `coaching`, `positive`. - `app/Http/Controllers/HomeroomNoteController.php`: redirect transisi GET dan guard `410 Gone` untuk mutation legacy. - `resources/js/pages/Homeroom/Guidance.tsx` dan `Recognitions.tsx`: dua modul pengganti form generik lama. - `resources/js/pages/Homeroom/StudentShow.tsx`: pintasan modul terstruktur dan timeline terpadu. - `app/Models/StudentViolation.php` dan `StudentViolationFollowUp.php`: lifecycle kasus existing. - `resources/js/pages/Homeroom/ViolationShow.tsx`: tindakan/follow-up/resolve/reopen sudah berada pada timeline kasus. - `app/Services/HomeroomStudentOverviewService.php`: menggabungkan violation, follow-up, homeroom note, dan komunikasi. - `app/Services/HomeroomAnalyticsService.php`: menghitung guidance, appreciation, dan achievement terstruktur. - `app/Services/HomeroomDocxService.php`: memakai template `documents/templates/homeroom-report.docx`, private temp file, sanitasi, dan streaming cleanup. - `app/Http/Controllers/HomeroomReportController.php`: DOCX pelanggaran individual/kelas dan filter opt-in note/komunikasi. - `resources/js/layouts/AuthenticatedLayout.tsx`: menu Pelanggaran, Pembinaan, serta Apresiasi & Prestasi terpisah. - `tests/Feature/HomeroomDashboardTest.php`: coverage note/timeline/analytics existing. - `tests/Feature/StudentViolationLifecycleTest.php`: coverage lifecycle kasus. - `tests/Feature/HomeroomReportExportTest.php`: coverage DOCX existing. - `PRD-HOMEROOM.md`: kontrak Homeroom Workspace lama; dokumen ini menjadi addendum domain baru dan tidak membatalkan compatibility contract yang masih relevan. --- ## 18. Keputusan produk final untuk implementasi 1. Nama menu generik **Catatan Wali Kelas** diganti menjadi **Pembinaan Wali Kelas**. 2. Catatan positif dipindahkan secara konsep ke **Apresiasi & Prestasi**. 3. Pembinaan mempunyai scope klasikal, kelompok, dan individual. 4. Pembinaan klasikal menyimpan snapshot peserta. 5. Penanganan pelanggaran tetap hanya pada kasus pelanggaran. 6. Apresiasi dan Prestasi memakai record per siswa; multi-select membuat beberapa record dalam transaction. 7. Data legacy dipertahankan dan dibackfill secara idempotent. 8. Data legacy tidak dipublikasikan otomatis. 9. Publication ke siswa bersifat eksplisit. 10. DOCX mencakup rekap kelas, riwayat individual, dan lembar satu penghargaan. 11. Tidak ada leaderboard, ranking, XP, atau poin penghargaan. 12. Bukti file privat ditunda; versi pertama memakai referensi teks/URL opsional. 13. Pembinaan Senin/Jumat tidak dijadwalkan otomatis agar sistem tidak mencatat kegiatan yang tidak terlaksana. 14. Arsip selalu read-only. --- ## 19. Pertanyaan yang tidak menghalangi Phase 0–3 Keputusan berikut dapat ditetapkan sebelum Phase 5/7 tanpa mengubah fondasi data: 1. Apakah tanda tangan DOCX cukup Wali Kelas + Mengetahui, atau perlu nama Kepala Sekolah otomatis. 2. Apakah versi lanjutan perlu menambahkan notifikasi database ketika penghargaan pertama kali dipublikasikan. 3. Apakah Lembar Penghargaan memakai satu desain umum atau desain berbeda untuk Apresiasi dan Prestasi. 4. Berapa lama referensi bukti/URL perlu dipertahankan setelah siswa lulus. 5. Apakah admin boleh mempublikasikan penghargaan atas nama wali kelas atau hanya melakukan koreksi. Default sementara: - signature menggunakan Wali Kelas dan kolom Mengetahui; - notifikasi ditunda sampai halaman portal siswa stabil; - satu template DOCX umum; - admin boleh memperbaiki/publish dengan audit lengkap. --- ## 20. Definition of complete Fitur dinyatakan selesai hanya jika: 1. Pengguna memahami perbedaan Pelanggaran, Pembinaan, Apresiasi, dan Prestasi dari menu/form. 2. Pembinaan klasikal/kelompok/individual tersimpan dengan participant historis yang benar. 3. Follow-up pelanggaran tidak terduplikasi menjadi pembinaan. 4. Apresiasi dan Prestasi mempunyai data terstruktur serta filter yang berguna. 5. Siswa hanya melihat recognition published miliknya. 6. Data note lama tetap dapat ditemukan tanpa double count. 7. DOCX kelas, individual, dan satu penghargaan valid serta aman. 8. Otorisasi kelas/periode/arsip dan audit lulus automated test. 9. Regression Homeroom, StudentViolation, biodata, absensi, report, dan Voting tetap hijau. 10. Typecheck, production build, formatting/diff check, browser QA mobile/desktop, dan verifikasi DOCX selesai. 11. Checklist fase dan checkpoint diperbarui berdasarkan bukti nyata. 12. Status source code, push, deployment, migration production, dan QA production dilaporkan sebagai hasil yang terpisah.