Pilot Documentation Plan — W05 Daily Student Attendance

Rencana pilot dokumentasi untuk presensi siswa per sesi/jam pelajaran: guru atau wali kelas mencatat kehadiran, penyimpanan menyelesaikan sheet, operator sekolah memonitor atau mengoreksi sesuai kewenangan, lalu siswa/orang tua melihat hasil.

Last verified: 2026-08-08

Mode: server development, static code audit only

Workspace root: /home/scola/odoo

Frontend HEAD: 0275f7061e6e892b1f860eeb825c6f6a21851888 (develop)

Backend HEAD: 44425cc81d8d281ec76e9336c30b3e109a7fc473

Runtime verification: belum dilakukan; tidak ada data runtime yang ditulis dan tidak ada source aplikasi yang diubah

Traceability companion: pilot-attendance-traceability.md

1. Kesimpulan kesiapan

Pilot ini belum siap masuk tahap penulisan artikel final, tetapi sudah cukup terpetakan untuk backlog dan workshop keputusan. Jalur utama guru, operator, siswa, dan orang tua tersedia di codebase. Namun dokumentasi final berisiko mengajarkan jaminan yang belum benar-benar ditegakkan.

Enam syarat utama sebelum penulisan final:

1. BLK-A19 — Perbaiki atau buktikan secara runtime bahwa guru standar dapat membuat line pada penyimpanan pertama. Controller meng-elevate pembuatan sheet, tetapi tidak pembuatan line; ACL Scola Teacher sendiri tidak memberi create line.
2. BLK-A20 — Tegakkan roster lengkap dan larang student ID di luar batch/session pada endpoint guru maupun admin.
3. BLK-B04 — Selaraskan tombol dan route operator dengan role check backend, terutama principal dan wakasek kesiswaan yang tampak dapat mengedit di UI tetapi ditolak controller.
4. BLK-A21 — Putuskan dan tegakkan semantik penyelesaian/koreksi: saat ini Simpan langsung menjadi done, tanpa draft terpisah, alasan koreksi, batas waktu, approval, atau audit event khusus.
5. BLK-A22 — Putuskan model status Sakit/Dispensasi. Status excused saat ini dibaca sebagai Izin oleh agregator utama sehingga status tidak round-trip secara kanonis.
6. BLK-A23 — Tetapkan policy viewer/retention dan validasi server untuk file bukti; raw proof saat ini tidak memiliki validasi ukuran/tipe backend dan ikut berada dalam payload detail portal.

Evidence utama: ../custom_addons_scola/gcgscola/scola_attendance/controllers/attendance_api_mixin.py:4196, ../custom_addons_scola/gcgscola/scola_attendance/controllers/attendance_api_mixin.py:4305, ../custom_addons_scola/gcgscola/scola_attendance/security/ir.model.access.csv:4, ../custom_addons_scola/gcgscola/scola_attendance/security/ir.model.access.csv:8, ../custom_addons_scola/gcgscola/scola_core/security/scola_security.xml:88, src/views/AttendanceManagement/Admin/AttendanceSheetList.vue:192.

2. Penegasan scope pilot

2.1 In scope

• Presensi siswa berdasarkan sesi/jam pelajaran pada op.session.
• Guru atau wali kelas membuka sesi miliknya pada hari sekolah aktif.
• Pengisian status Hadir, Izin, Alpa, dan Telat; Sakit/Dispensasi hanya dibahas sebagai gap klasifikasi yang belum final.
• Penyimpanan pertama dan edit ulang sheet yang sudah tersimpan.
• Monitoring sesi yang belum/sudah diisi oleh operator sekolah.
• Pengisian pengganti atau koreksi melalui workspace admin, hanya setelah kewenangan dan auditnya diputuskan.
• Tampilan pribadi siswa serta tampilan anak yang tertaut pada akun orang tua.
• Relasi langsung ke izin siswa, rekap, rapor, dan promosi sebagai downstream/dependency.

2.2 Out of scope

• Employee attendance.
• RFID ingestion.
• Face recognition.
• Geofencing.
• Kedatangan/kepulangan gerbang dan pickup attendance.
• Advanced analytics, principal insight, dan analitik risiko.

Fitur di atas hanya boleh muncul sebagai dependency atau artikel lanjutan. Redirect guru PAUD/TK ke /attendance/daily adalah boundary produk, bukan bagian langkah pilot (src/router/teacherRouteFragments/attendance.js:6, src/views/AttendanceManagement/Faculty/Attendance.vue:275).

2.3 Koreksi terhadap W05 reconnaissance

Recon W05 menyebut submit/close/cancel dan kemungkinan notifikasi orang tua (docs/recon/workflow-candidates.md:22). Untuk scope per-sesi yang diverifikasi ulang:

• tidak ada aksi close/cancel terpisah pada UI guru;
• saveFacultySessionAttendanceSheet memanggil satu endpoint save (src/services/attendance/studentAttendance.service.js:435);
• endpoint menulis sheet.state = 'done' pada penyimpanan (../custom_addons_scola/gcgscola/scola_attendance/controllers/attendance_api_mixin.py:4332);
• edit ulang mengubah line yang sama lalu tetap done (src/views/AttendanceManagement/Faculty/AttendanceSheet.vue:667, ../custom_addons_scola/gcgscola/scola_attendance/controllers/attendance_api_mixin.py:4307);
• tidak ada pemanggilan notification/mail/bus eksplisit pada save per-sesi; notifikasi yang ditemukan di domain attendance berkaitan dengan jalur gerbang, bukan save per-sesi.

Tidak ditemukan commit yang menyentuh route/view/service attendance frontend setelah snapshot recon; commit attendance frontend terakhir pada jalur yang diaudit adalah 61abcb7/dcddf83. Backend attendance terakhir sebelum snapshot adalah a672512 pada 2026-08-04. Audit ini tetap memakai isi file pada HEAD di atas, bukan mengandalkan snapshot recon.

3. Actors dan batas kewenangan kandidat

Actor	Candidate responsibility	Bukti code	Status untuk pilot
Guru	Melihat sesi miliknya hari ini, mengisi, menyimpan, dan mengedit ulang sheet miliknya	route capability students.attendance.edit di src/router/teacherRouteFragments/attendance.js:27; backend role dan ownership check di ../custom_addons_scola/gcgscola/scola_attendance/controllers/attendance_api_mixin.py:4056, ../custom_addons_scola/gcgscola/scola_attendance/controllers/attendance_api_mixin.py:4160, ../custom_addons_scola/gcgscola/scola_attendance/controllers/attendance_api_mixin.py:4196	Kandidat utama, tetapi first-save wajib dibuktikan/fixed
Wali kelas	Memakai alur guru ketika juga menjadi faculty sesi; laporan wali adalah artikel terkait, bukan workspace input berbeda	homeroom mewarisi teacher capability di ../custom_addons_scola/gcgscola/scola_core/services/auth_capabilities.py:484; backend menerima homeroom di ../custom_addons_scola/gcgscola/scola_attendance/controllers/attendance_api_mixin.py:4057	Kandidat utama; hubungan wali kelas vs guru mapel perlu dijelaskan
Admin / school admin / head admin / admin staff	Memonitor seluruh sesi unit; membuat/memperbarui sheet melalui jalur admin	role check _admin_access_error di ../custom_addons_scola/gcgscola/scola_attendance/controllers/attendance_api_mixin.py:146; admin UI di src/views/AttendanceManagement/Admin/AttendanceSheetList.vue:192 dan src/views/AttendanceManagement/Admin/AttendanceSheetNew.vue:369	Kandidat operator setelah ownership koreksi disahkan
Principal	Monitoring sheet/detail unit	route view di src/router/principalRoutes.js:196; backend read allow di ../custom_addons_scola/gcgscola/scola_attendance/controllers/attendance_api_mixin.py:170	Read-only kandidat; UI edit drift harus ditutup
Wakasek kesiswaan	Monitoring sheet/detail unit	route view di src/router/vicePrincipalRoutes.js:214; backend read allow di ../custom_addons_scola/gcgscola/scola_attendance/controllers/attendance_api_mixin.py:170	Read-only kandidat; ACL model yang lebih luas tidak boleh dianggap kontrak produk
Siswa	Melihat attendance milik profil siswa terkait user	route di src/router/studentRouteFragments/core.js:25; identity lookup dan role check di ../custom_addons_scola/gcgscola/scola_attendance/controllers/attendance_api_mixin.py:2942	Kandidat reader
Orang tua	Memilih anak yang benar-benar tertaut lalu melihat rekap/detail	route di src/router/parentRouteFragments/core.js:35; child resolution di ../custom_addons_scola/gcgscola/scola_attendance/controllers/attendance_api_mixin.py:2835, ../custom_addons_scola/gcgscola/scola_attendance/controllers/attendance_api_mixin.py:2971	Kandidat reader; privasi bukti harus dibereskan

Catatan allowlist: current _admin_access_error menerima canonical admin, admin_staff, school_admin, head_admin, legacy aliases admin staff, staff, administrator, super admin, serta groups admin terkait (../custom_addons_scola/gcgscola/scola_attendance/controllers/attendance_api_mixin.py:146-166). Legacy aliases tersebut tidak otomatis menjadi actor pilot; supported operator set tetap memerlukan keputusan ATT-D01/ATT-D04.

Catatan: capability frontend bukan security boundary. Prefix API admin hanya digate students.attendance.view, sedangkan mutation authorization terjadi lagi di controller (../custom_addons_scola/gcgscola/scola_platform_support/api_route_access.py:137, ../custom_addons_scola/gcgscola/scola_attendance/controllers/attendance_api_mixin.py:146). Panduan tidak boleh menyimpulkan hak edit hanya dari menu atau capability.

4. Entry point dan route map yang sudah dideduplikasi

Surface kanonis	Route	Shared component / alias	Tujuan pilot
Daftar sesi guru	/faculty/attendance	—	Memilih sesi yang dijadwalkan hari ini
Sheet guru	/faculty/attendance/sheet/:id	legacy redirect /faculty/attendance/attendance-sheet/:id	Mengisi dan menyimpan attendance
Hub operator	/attendance/home	/admin-staff/students/attendance memakai component yang sama	Masuk ke alur per-sesi bila per_lesson_enabled
Monitoring sheet operator	/attendance/sheets	/principal/students/attendance/sheets dan /vice-principal/student-affairs/attendance memakai AttendanceSheetList.vue	Memantau done/pending dan membuka detail
Detail sheet	/attendance/session/:sheetId	alias role-specific principal/VP memakai AttendanceBySession.vue	Membaca line dan ekspor
Create/update operator	/attendance/sheets/create	/attendance/lines/create redirect; jangan dokumentasikan redirect sebagai halaman terpisah	Isi pengganti atau muat sheet existing berdasarkan session+date
Portal siswa	/student/attendance	—	Detail harian dan ringkasan mingguan
Portal orang tua	/parent/attendance	—	Pilih anak, rekap bulanan/mingguan, detail hari

Evidence route: src/router/teacherRouteFragments/attendance.js:25, src/router/attendanceRoutes.js:31, src/router/attendanceRoutes.js:123, src/router/attendanceRoutes.js:151, src/router/principalRoutes.js:206, src/router/vicePrincipalRoutes.js:214, src/router/studentRouteFragments/core.js:25, src/router/parentRouteFragments/core.js:35.

5. Candidate end-to-end flow

5.1 Happy path yang didukung struktur kode

1. Admin akademik menyiapkan unit/company, tahun ajaran, rombel, enrollment siswa, faculty, subject, classroom, dan sesi bertanggal.
2. Admin attendance mengaktifkan per_lesson_enabled untuk company pemilik sesi.
3. Guru/wali yang menjadi faculty sesi membuka /faculty/attendance.
4. API hanya mengambil op.session milik faculty untuk tanggal lokal sekolah hari ini.
5. Guru memilih kartu sesi; sistem memuat roster batch, existing lines, dan izin/permit yang relevan.
6. Guru meninjau default, mengubah status yang diperlukan, dan mengisi catatan/bukti bila memilih Izin.
7. Guru menekan Simpan. Implementasi saat ini membuat/memperbarui sheet dan line, lalu langsung menulis state done.
8. Operator membuka /attendance/sheets untuk melihat sheet atau daftar sesi pending, lalu membuka detail.
9. Jika koreksi diperlukan, operator saat ini harus membuka workspace /attendance/sheets/create, memilih session dan tanggal yang sama, memuat draft existing, mengubah line, lalu menyimpan ulang.
10. Siswa/orang tua melakukan fetch pada route portal untuk melihat data terbaru. Tidak ada bukti push notification per-sesi pada save path.

Langkah 6–9 belum boleh menjadi instruksi final sampai default all-present, semantik complete, kewenangan koreksi, dan audit disahkan.

5.2 State transition aktual

Tidak ada sheet
    -> GET session-sheet: virtual roster, seluruh siswa default Hadir
    -> POST session-sheet/save: sheet dibuat draft, line ditulis, lalu sheet langsung done

Sheet done
    -> UI menampilkan mode read-only
    -> Edit Kehadiran
    -> POST session-sheet/save
    -> line diperbarui dan sheet tetap done

Combined session menyimpan setiap canonical session di dalam savepoint; status gabungan adalah pending, partial, atau complete berdasarkan jumlah child sheet done (../custom_addons_scola/gcgscola/scola_attendance/controllers/attendance_api_mixin.py:3999, ../custom_addons_scola/gcgscola/scola_attendance/controllers/attendance_api_mixin.py:4196). Tidak ada transition canceled/closed pada alur per-sesi ini.

6. Inventory halaman pilot

6.1 Guru — daftar sesi

Component: src/views/AttendanceManagement/Faculty/Attendance.vue

• Data: tanggal/hari lokal, batch, subject, classroom, jam, unit, combined badge, completion badge, ringkasan.
• Filter: Semua, Belum Diisi, Selesai, dan unit bila lebih dari satu.
• Actions: buka sheet, buka rekap mapel, atau masuk alur gate jika mode terkait aktif.
• Validation/gate: per_lesson_enabled; bila hanya gate aktif route mengganti ke /attendance/daily.
• Exception: profile faculty tidak ditemukan, tidak ada sesi hari ini, mode nonaktif, atau API error.

Evidence: src/views/AttendanceManagement/Faculty/Attendance.vue:69, src/views/AttendanceManagement/Faculty/Attendance.vue:105, src/views/AttendanceManagement/Faculty/Attendance.vue:227, src/views/AttendanceManagement/Faculty/Attendance.vue:269, src/views/AttendanceManagement/Faculty/Attendance.vue:326.

6.2 Guru — sheet per sesi

Component: src/views/AttendanceManagement/Faculty/AttendanceSheet.vue

• Read-only context: batch, subject, jam, tanggal hari ini, total siswa, summary.
• Filters: pencarian nama; filter rombel hanya untuk combined session.
• Per-student fields: nama, NSN/NISN display, rombel gabungan, status, remark, proof file, approved-permit indicator.
• Status selection nyata: Hadir, Izin, Alpa, Telat (src/i18n/attendanceStatus.js:33).
• Izin modal: jenis alasan Sakit/Dispensasi/Izin lain, detail alasan, upload image/PDF, dan opsi tanpa bukti.
• Actions: tandai semua hadir/kosongkan, ubah per siswa, simpan, edit ulang, lihat/unduh bukti.
• Default: roster baru diprefill Hadir oleh backend.
• Validation frontend: tidak ada kewajiban memilih exactly one status setelah pengguna mengosongkan; tidak ada validasi size/type file selain accept browser.

Evidence: src/views/AttendanceManagement/Faculty/AttendanceSheet.vue:45, src/views/AttendanceManagement/Faculty/AttendanceSheet.vue:83, src/views/AttendanceManagement/Faculty/AttendanceSheet.vue:167, src/views/AttendanceManagement/Faculty/AttendanceSheet.vue:190, src/views/AttendanceManagement/Faculty/AttendanceSheet.vue:244, src/views/AttendanceManagement/Faculty/AttendanceSheet.vue:526, src/views/AttendanceManagement/Faculty/AttendanceSheet.vue:592, ../custom_addons_scola/gcgscola/scola_attendance/controllers/attendance_api_mixin.py:2034.

6.3 Operator — list/pending/detail

Components: AttendanceSheetList.vue, AttendanceBySession.vue

• List filters: pending date, search, attendance date.
• List actions: refresh, create manual, fill/continue pending session, open detail.
• Columns: attendance date, batch, register, session.
• Detail: date, student, four boolean status columns; export PDF/Excel.
• Detail tidak menyediakan tombol koreksi.
• Mismatch saat ini: column mapping memperlakukan remark sebagai Sakit dan late sebagai Terlambat, tetapi statusOptions yang dikomentari memetakan late ke Izin. Jangan mendokumentasikan legend detail sebagai klasifikasi yang sudah final.

Evidence: src/views/AttendanceManagement/Admin/AttendanceSheetList.vue:18, src/views/AttendanceManagement/Admin/AttendanceSheetList.vue:92, src/views/AttendanceManagement/Admin/AttendanceSheetList.vue:194, src/views/AttendanceManagement/Admin/AttendanceSheetList.vue:290, src/views/AttendanceManagement/Admin/AttendanceBySession.vue:46, src/views/AttendanceManagement/Admin/AttendanceBySession.vue:217, src/views/AttendanceManagement/Admin/AttendanceBySession.vue:226.

6.4 Operator — create/update substitute

Component: AttendanceSheetNew.vue

• Fields: register, session, attendance date, per-student Hadir/Telat/Izin/Alpa checkboxes, remark.
• Substitute mode mengunci tanggal dari query dan memuat metadata session.
• Exactly-one status ditegakkan hanya oleh handler UI saat satu checkbox dicentang; semua dapat dikosongkan.
• Backend mencari existing sheet berdasarkan session+date sehingga save ulang bertindak sebagai update.
• Backend tidak menerima alasan koreksi, approver, version, atau expected prior state.
• Tidak ada direct link dari detail ke workspace koreksi.

Evidence: src/views/AttendanceManagement/Admin/AttendanceSheetNew.vue:14, src/views/AttendanceManagement/Admin/AttendanceSheetNew.vue:31, src/views/AttendanceManagement/Admin/AttendanceSheetNew.vue:57, src/views/AttendanceManagement/Admin/AttendanceSheetNew.vue:103, src/views/AttendanceManagement/Admin/AttendanceSheetNew.vue:293, src/views/AttendanceManagement/Admin/AttendanceSheetNew.vue:332, src/views/AttendanceManagement/Admin/AttendanceSheetNew.vue:369.

6.5 Siswa

Component: src/views/AttendanceManagement/Student/Attendance.vue

• Mode: harian atau mingguan.
• Fields/filter: tanggal, tanggal acuan minggu, scope mode bila dual mode.
• Harian: summary dan detail session subject/time/status/remark/bukti.
• Mingguan: grid H/I/S/A/T dan klik hari kembali ke detail harian.
• Hanya profile student yang terkait user backend yang dapat dibaca.

Evidence: src/views/AttendanceManagement/Student/Attendance.vue:91, src/views/AttendanceManagement/Student/Attendance.vue:157, src/views/AttendanceManagement/Student/Attendance.vue:213, src/views/AttendanceManagement/Student/Attendance.vue:291, ../custom_addons_scola/gcgscola/scola_attendance/controllers/attendance_api_mixin.py:2942.

6.6 Orang tua

Component: src/views/AttendanceManagement/Parent/Attendance.vue

• Fields/filter: anak tertaut, mingguan/bulanan, tanggal acuan/bulan, tahun, scope mode.
• Summary: Hadir, Izin, Sakit, Alpa, Terlambat.
• Grid dapat diklik untuk membuka detail hari dan daftar session.
• Backend membatasi student_id pada children dari portal identity.
• Komponen juga berisi data gate/pickup, tetapi itu di luar artikel pilot.

Evidence: src/views/AttendanceManagement/Parent/Attendance.vue:93, src/views/AttendanceManagement/Parent/Attendance.vue:198, src/views/AttendanceManagement/Parent/Attendance.vue:238, src/views/AttendanceManagement/Parent/Attendance.vue:366, src/views/AttendanceManagement/Parent/Attendance.vue:498, src/views/AttendanceManagement/Parent/Attendance.vue:506, ../custom_addons_scola/gcgscola/scola_attendance/controllers/attendance_api_mixin.py:2835.

7. API dependency map

Actor/page	Service	Endpoint	Backend implementation	Purpose
Semua surface attendance	src/services/attendance/studentAttendance.service.js:51	POST /api/v1/attendance/student/settings	../custom_addons_scola/gcgscola/scola_attendance/controllers/attendance_daily_api.py:8, mode service/company payload	Menentukan per-lesson/gate/dual-mode
Daftar guru	src/services/attendance/studentAttendance.service.js:396	POST /api/v1/attendance/faculty/today-sessions	../custom_addons_scola/gcgscola/scola_attendance/controllers/attendance_faculty_api.py:8, mixin ../custom_addons_scola/gcgscola/scola_attendance/controllers/attendance_api_mixin.py:4056	Sesi faculty untuk tanggal lokal hari ini
Sheet guru	src/services/attendance/studentAttendance.service.js:424	POST /api/v1/attendance/faculty/session-sheet	../custom_addons_scola/gcgscola/scola_attendance/controllers/attendance_faculty_api.py:12, mixin ../custom_addons_scola/gcgscola/scola_attendance/controllers/attendance_api_mixin.py:4160	Session context, roster, existing lines, permit
Save guru	src/services/attendance/studentAttendance.service.js:435	POST /api/v1/attendance/faculty/session-sheet/save	../custom_addons_scola/gcgscola/scola_attendance/controllers/attendance_faculty_api.py:20, mixin ../custom_addons_scola/gcgscola/scola_attendance/controllers/attendance_api_mixin.py:4196	Create/update line dan set sheet done
List operator	src/services/attendance/adminAttendance.service.js:64	POST /api/v1/attendance/admin/sheets	../custom_addons_scola/gcgscola/scola_attendance/controllers/attendance_admin_api.py:65, mixin ../custom_addons_scola/gcgscola/scola_attendance/controllers/attendance_api_mixin.py:3430	Daftar sheet per-lesson unit
Pending operator	src/services/attendance/adminAttendance.service.js:48	POST /api/v1/attendance/admin/pending-sessions	../custom_addons_scola/gcgscola/scola_attendance/controllers/attendance_admin_api.py:38, mixin ../custom_addons_scola/gcgscola/scola_attendance/controllers/attendance_api_mixin.py:3189	Sesi unit yang belum done
Draft operator	src/services/attendance/adminAttendance.service.js:70	POST /api/v1/attendance/admin/sheet/draft	../custom_addons_scola/gcgscola/scola_attendance/controllers/attendance_admin_api.py:46, mixin ../custom_addons_scola/gcgscola/scola_attendance/controllers/attendance_api_mixin.py:3282	Roster/existing line untuk session+date
Save operator	src/services/attendance/adminAttendance.service.js:119	POST /api/v1/attendance/admin/sheet/create	../custom_addons_scola/gcgscola/scola_attendance/controllers/attendance_admin_api.py:55, mixin ../custom_addons_scola/gcgscola/scola_attendance/controllers/attendance_api_mixin.py:3335	Create/update sheet lalu set done
Detail operator	src/services/attendance/adminAttendance.service.js:83	POST /api/v1/attendance/admin/sheet-lines	../custom_addons_scola/gcgscola/scola_attendance/controllers/attendance_admin_api.py:69, mixin ../custom_addons_scola/gcgscola/scola_attendance/controllers/attendance_api_mixin.py:3464	Line read-only per sheet
Siswa harian	src/services/attendance/studentAttendance.service.js:311	POST /api/v1/attendance/student/daily	../custom_addons_scola/gcgscola/scola_attendance/controllers/attendance_portal_api.py:8, mixin ../custom_addons_scola/gcgscola/scola_attendance/controllers/attendance_api_mixin.py:2942	Detail session milik siswa
Siswa mingguan	src/services/attendance/studentAttendance.service.js:368	POST /api/v1/attendance/student/period-report	../custom_addons_scola/gcgscola/scola_attendance/controllers/attendance_portal_api.py:12, mixin ../custom_addons_scola/gcgscola/scola_attendance/controllers/attendance_api_mixin.py:2957	Grid/summary periode
Daftar anak	src/services/attendance/studentAttendance.service.js:316	POST /api/v1/attendance/parent/children	../custom_addons_scola/gcgscola/scola_attendance/controllers/attendance_portal_api.py:20, mixin ../custom_addons_scola/gcgscola/scola_attendance/controllers/attendance_api_mixin.py:2971	Anak terkait akun parent
Orang tua harian	src/services/attendance/studentAttendance.service.js:321	POST /api/v1/attendance/parent/daily	../custom_addons_scola/gcgscola/scola_attendance/controllers/attendance_portal_api.py:24, mixin ../custom_addons_scola/gcgscola/scola_attendance/controllers/attendance_api_mixin.py:2989	Detail hari anak terpilih
Orang tua periode	src/services/attendance/studentAttendance.service.js:353, src/services/attendance/studentAttendance.service.js:381	POST /api/v1/attendance/parent/monthly, POST /api/v1/attendance/parent/period-report	../custom_addons_scola/gcgscola/scola_attendance/controllers/attendance_portal_api.py:28, ../custom_addons_scola/gcgscola/scola_attendance/controllers/attendance_portal_api.py:37; mixin ../custom_addons_scola/gcgscola/scola_attendance/controllers/attendance_api_mixin.py:3007, ../custom_addons_scola/gcgscola/scola_attendance/controllers/attendance_api_mixin.py:3024	Grid dan summary

8. Prerequisites

8.1 Data prerequisite

• Active school/company scope dan timezone sekolah.
• per_lesson_enabled = true pada company pemilik sesi.
• Faculty profile tertaut dengan user guru.
• Session pada tanggal lokal hari ini, assigned ke faculty yang login.
• Session memiliki batch/rombel; subject/classroom/time memperkaya tampilan.
• Siswa berada pada session.batch_id.student_ids.
• Course pada session/batch diperlukan untuk auto-register yang stabil pada jalur operator.
• Parent profile tertaut ke anak; student user tertaut ke student profile.
• Izin/permit full-day yang sudah submitted/reviewed dapat muncul sebagai indikator; hanya approval final seharusnya mengubah default attendance.

Evidence: ../custom_addons_scola/gcgscola/scola_attendance/controllers/attendance_api_mixin.py:1912, ../custom_addons_scola/gcgscola/scola_attendance/controllers/attendance_api_mixin.py:1961, ../custom_addons_scola/gcgscola/scola_attendance/controllers/attendance_api_mixin.py:2034, ../custom_addons_scola/gcgscola/scola_attendance/controllers/attendance_api_mixin.py:4056, ../custom_addons_scola/gcgscola/scola_attendance/controllers/attendance_api_mixin.py:4160, ../custom_addons_scola/gcgscola/scola_attendance/controllers/attendance_api_mixin.py:3166.

8.2 Access prerequisite

• Frontend route guru: students.attendance.edit.
• Backend: role teacher, homeroom, atau guru, plus ownership session by faculty.
• Operator mutation backend: _admin_access_error; principal/VP hanya read menurut controller.
• Portal siswa/orang tua: role check dan identity linkage, bukan ID bebas dari frontend.
• Global attendance rules membatasi register/sheet/line ke allowed company IDs (../custom_addons_scola/gcgscola/scola_attendance/security/attendance_security.xml:10).

9. Validasi dan business rule yang terlihat

Rule	Enforcement sekarang	Dokumentasi pilot
Session wajib	Backend menolak session_id kosong	Boleh dijelaskan setelah runtime check
Guru hanya session miliknya	Backend membandingkan session.faculty_id dengan faculty user	Boleh dijelaskan
Mode per-lesson aktif	Backend memeriksa company pemilik session	Boleh dijelaskan
Existing attendance_sheet_id harus sesuai session	ID tidak sesuai diabaikan lalu dicari berdasarkan session+today	Jelaskan sebagai idempotent lookup hanya setelah test
New roster default Hadir	Backend mengisi semua batch students Hadir	Wajib keputusan bisnis dan warning; jangan disamarkan
Exactly-one status	UI setter mengosongkan flag lain, tetapi semua flag dapat menjadi false	Jangan menjanjikan validasi penuh
Full roster wajib	Combined session memvalidasi complete roster; regular session tidak	Blocked by defect untuk regular session
Student harus anggota batch	Combined session memvalidasi; regular faculty/admin save tidak	Blocked by defect
Izin approved prefill	Permit map menggunakan full-day types dan state submitted/approved; override ke excused final hanya untuk approved	Perlu artikel dependency dan business glossary
File proof	Browser accept=image/*,.pdf; backend menerima base64 tanpa size/type check	Jangan ajarkan upload sampai policy/fix
Save berarti complete	Backend selalu menulis state=done	Hanya dokumentasikan setelah owner menyetujui semantik
Edit setelah done	UI dan backend memperbolehkan	Perlu window/reason/audit decision
Period date	Backend menolak missing/invalid/reversed dates	Boleh dijelaskan pada portal/troubleshooting
Parent child scope	Backend memilih hanya child dari portal identity	Boleh dijelaskan setelah negative runtime test

10. Downstream effect dan notification

10.1 Downstream yang terkonfirmasi dari kode

• op.attendance.line menjadi data detail portal siswa/orang tua (../custom_addons_scola/gcgscola/scola_attendance/controllers/attendance_api_mixin.py:2754, ../custom_addons_scola/gcgscola/scola_attendance/controllers/attendance_api_mixin.py:2855).
• Rekap rapor membaca line per term dan menghitung hadir/telat/izin/sakit/alpa (../custom_addons_scola/gcgscola/scola_report_card/models/student_report.py:188).
• Promotion menghitung attendance percentage dari seluruh attendance line dalam tahun ajaran (../custom_addons_scola/gcgscola/scola_report_card/models/student_promotion.py:276).
• Approval permit dapat memperbarui line session/daily yang sudah ada (../custom_addons_scola/gcgscola/scola_student_activity/models/student_permit.py:437).
• Principal/admin report dan rekap subject/homeroom membaca line yang sama; advanced analytics tetap artikel lanjutan.

Risiko: report card/promotion saat ini menghitung line, bukan hari unik. Dalam mode per-session atau dual mode, arti “hari hadir” dan eligibility perlu keputusan bisnis sebelum didokumentasikan sebagai metrik resmi.

10.2 Notification behavior

• Save per-sesi tidak memanggil notification service, mail, atau bus secara eksplisit pada controller/model yang diaudit.
• Student/parent melihat perubahan ketika halaman melakukan fetch/reload.
• Notifikasi arrival/departure gerbang bukan bagian pilot.
• Jangan menulis “orang tua langsung menerima notifikasi” sampai runtime automation dan kanal resmi dibuktikan.

11. Exception dan recovery paths

Kondisi	Perilaku code/UI saat ini	Kebutuhan artikel troubleshooting
Mode per-lesson nonaktif	Guru diarahkan ke daily jika gate aktif; backend mengembalikan validation error	Jelaskan boundary mode, link ke artikel mode attendance
Faculty profile tidak ada	API faculty_not_found	Eskalasi ke admin user/faculty linkage
Tidak ada session hari ini	Empty state, bukan pilihan tanggal lain	Cek jadwal/session dan timezone; jangan menyuruh guru “ubah tanggal”
Session bukan milik guru	Backend session_not_found	Cek assignment faculty, jangan minta bypass
Roster kosong	Sheet tidak dapat memberi data berguna; admin save button disabled	Cek enrollment ke batch
First-save ACL gagal	Potensi AccessError bagi teacher tanpa group OpenEduCat attendance user	BLK-A19; blocker sebelum artikel final; test provisioning baru
Combined roster duplicate	Backend menolak dan rollback savepoint	Admin perbaiki membership antarrombel
Koneksi gagal saat per-session save	Service per-session tidak memakai offline outbox; UI menampilkan error	Jangan menjanjikan offline save; pertahankan halaman dan retry setelah koneksi pulih
Parent tanpa child	Error/empty state	Perbaiki parent-student linkage
Status portal belum berubah	Portal perlu fetch ulang; tidak ada push per-sesi yang dibuktikan	Reload, cek sheet done, cek scope Per Jam
Koreksi diperlukan	Existing sheet dapat dimuat ulang via admin form atau Edit guru	Owner, alasan, cutoff, dan audit belum ditetapkan

12. Privacy dan sensitive-data concerns

1. Nama, NSN/NISN, status kehadiran, alasan ketidakhadiran, dan izin merupakan data siswa.
2. Bukti izin dapat berisi data kesehatan. Guru dapat membuka URL evidence permit; student daily payload memuat proof_file, dan parent daily memakai serializer yang sama sebelum hanya menonaktifkan write flags (../custom_addons_scola/gcgscola/scola_attendance/controllers/attendance_api_mixin.py:2754, ../custom_addons_scola/gcgscola/scola_attendance/controllers/attendance_api_mixin.py:2816, ../custom_addons_scola/gcgscola/scola_attendance/controllers/attendance_api_mixin.py:2826).
3. Parent UI tidak merender proof session melalui AttendanceDayDetailPanel, tetapi payload API tetap dapat mengandung file raw. Data minimization belum ditegakkan.
4. Upload proof tidak memiliki batas ukuran/type backend pada save per-sesi.
5. Admin export PDF/Excel memasukkan nama/status siswa dan dibuat client-side; retention/download warning belum tersedia.
6. Company scope global ada untuk line/sheet/register, tetapi endpoint save regular belum memvalidasi bahwa setiap student ID milik batch/session yang sama. Ini harus dianggap integrity/isolation blocker.

Kebijakan yang dibutuhkan: siapa boleh melihat proof/reason, retensi, download, masking NSN, audit akses, ukuran/tipe file, dan apakah proof guru masih diperlukan bila permit resmi sudah tersedia.

13. Unresolved business decisions

ID	Pertanyaan keputusan	Recommended default untuk workshop
ATT-D01	Apakah guru mata pelajaran atau hanya wali kelas dapat input per-session?	Guru pemilik session; wali kelas hanya jika menjadi faculty session atau memakai jalur substitute resmi
ATT-D02	Apakah roster baru boleh default semua Hadir?	Tidak; default “Belum ditandai” sampai guru melakukan review eksplisit
ATT-D03	Apakah Simpan sama dengan Complete?	Pisahkan Save Draft dan Complete, atau minimal confirmation sebelum done
ATT-D04	Siapa boleh koreksi setelah complete?	Guru pemilik selama cutoff singkat; setelah cutoff admin/head admin dengan alasan wajib
ATT-D05	Apakah koreksi perlu approval?	Tidak untuk cutoff guru; ya atau audit review untuk admin setelah cutoff
ATT-D06	Apa glossary final Hadir, Telat, Izin, Sakit, Dispensasi, Alpa, Belum ditandai?	Status kanonis berbeda; Sakit/Dispensasi jangan hanya remark Izin
ATT-D07	Bagaimana satu hari diringkas dari banyak session dan dual mode?	Aturan harian eksplisit per sekolah; jangan hitung line sebagai hari tanpa agregasi
ATT-D08	Apakah save per-session mengirim notifikasi?	Default tidak; portal pull/reload. Tambahkan notifikasi hanya setelah channel/quiet-hour policy
ATT-D09	Siapa boleh melihat/upload/download bukti?	Permit owner dan approver terbatas; guru melihat status/reason minimal, bukan raw medical file secara default
ATT-D10	Principal dan wakasek kesiswaan read-only atau editor?	Read-only; correction tetap separation of duties operator
ATT-D11	Bagaimana session pengganti ditugaskan dan diaudit?	Admin/head admin memilih substitute dengan reason dan actor audit
ATT-D12	Apakah edit unlimited diperbolehkan?	Tidak; tetapkan cutoff berdasarkan tanggal/session dan recovery escalation
ATT-D13	Apakah alumni boleh melihat attendance lama karena role map memberi capability?	Tidak untuk pilot; perlu product/privacy decision terpisah
ATT-D14	Apa sumber nomor siswa yang boleh tampil: NSN, NIS, atau NISN?	Pakai label dan field kanonis yang disahkan DPO/product; minimalkan pada portal parent
ATT-D15	Siapa memiliki approval dan koreksi permit bridge yang dapat memprefill attendance?	Workflow permit tetap menjadi source approval; attendance hanya mengonsumsi status/evidence minimum, dengan actor dan linkage diaudit
ATT-D16	Apa recovery resmi bila save per-session timeout/offline?	Jangan menjanjikan offline outbox; pertahankan input, verifikasi hasil server, lalu retry dengan contract idempotent atau eskalasi
ATT-D17	Mode/jenjang dan baseline tanggal apa yang didukung pilot?	Pilot hanya per-session pada jenjang/mode yang route-nya mengizinkan; daftar guru today-only menurut tanggal sekolah; PAUD/gate flow menjadi related article

Blocker gate pilot memakai ID register final: BLK-A19 first-save teacher, BLK-A20 exact roster/completeness, BLK-B04 principal/VP CTA drift, BLK-A21 completion/correction, BLK-A22 Sakit/Izin, BLK-A23 proof privacy, dan BLK-B05 existing-guide drift.

14. Existing documentation reuse assessment

Existing file	Dapat dipakai	Harus diperbaiki sebelum reuse
docs/domains/absensi/README.md	Module/model/API map, mode boundary, downstream	Status “Done” bukan bukti runtime tenant; pisahkan gate vs per-session
docs/domains/absensi/attendance-modes-matrix.md	per_lesson_enabled, dual-mode scope, route mapping	Jangan membawa gate/pickup ke pilot body
docs/domains/absensi/attendance-navigation-audit.md	Label/menu canonical dan role entry point	Verifikasi menu served runtime; teacher label sekarang “Presensi Mapel”
docs/user-guide/quick-start/input-absensi-harian.md	Struktur singkat dan link related	Teacher tidak memilih tanggal/class di list; status Sakit tidak direct; admin field adalah session/register/date; “orang tua melihat” perlu fetch verification
docs/user-guide/troubleshooting/absensi.md	Struktur symptom/cause/action	Instruksi guru “ubah tanggal” tidak cocok dengan today-only session page; pisahkan per-session vs gate
docs/user-guide/per-role/teacher.md dan homeroom.md	Entry menu dan audience	Ganti istilah umum Absensi menjadi Presensi Mapel untuk alur ini
docs/user-guide/per-role/student.md dan parent.md	Route reader dan multi-child selection	Tambahkan scope Per Jam dan privacy-safe detail setelah API hardening
docs/user-guide/school-admin/kehadiran/hub-kehadiran-dan-rekap.md	Hub card concept	Jangan menyebut admin dapat edit tanpa role/correction policy
docs/domains/absensi/IMPLEMENTATION_GUIDE.md	High-level per-session dependency	Skenario 1.3 overclaims direct Sakit, tombol “Isi Kehadiran”, proof flow, dan auto-bridge; bukan source user copy
docs/qa/paud-attendance-manual-uat.md	Negative cases dual-mode dan view lintas role	Scope utamanya gate/PAUD; jadikan future/dependency, bukan pilot script
tests/e2e/critical/teacher_attendance_flow.spec.ts	Baseline save/edit assertions	Helper membuat seed melalui raw RPC; tambah fresh-role ACL, roster, tenant, admin correction, dan cross-role propagation
tests/e2e/critical/parent_attendance_flow.spec.ts	Baseline parent monthly page	Hanya membuktikan page/API monthly terbuka; belum membuktikan hasil save guru yang sama

15. Artefak pilot yang akan ditulis setelah Definition of Ready

15.1 Workflow guide

Working title: “Mencatat dan Menyelesaikan Presensi Siswa per Sesi”

Isi minimal:

• kapan memakai Per Jam dan kapan artikel lain dipakai;
• prerequisites dan ownership;
• pilih session hari ini;
• review seluruh roster, set status, dan complete;
• meaning setiap state/status;
• correction path resmi;
• cara memastikan hasil terlihat operator/siswa/orang tua;
• privacy warning dan escalation.

Acceptance: setiap langkah punya trace ID, tidak ada route alias legacy, dan tidak menyebut cancel/notifikasi yang tidak dibuktikan.

15.2 Role-specific quick guide

Empat kartu singkat:

• Guru/wali kelas: input dan review sebelum complete.
• Admin/head admin/admin staff: monitor pending, substitute, correction sesuai cutoff.
• Principal/wakasek: monitor read-only.
• Student/parent: pilih periode/scope dan baca hasil.

Setiap kartu harus menyebut “menu dapat berbeda menurut mode/unit” tanpa menganggap menu sebagai bukti permission.

15.3 Contextual page help

Page	Help payload kandidat
/faculty/attendance	Definisi Pending/Sebagian/Selesai, today-only, alasan session tidak tampil
/faculty/attendance/sheet/:id	Arti default, status, complete/edit, izin, privacy; blocker sampai semantics final
/attendance/sheets	Pending date, siapa yang boleh fill, perbedaan monitor vs edit
/attendance/sheets/create	Substitute/correction ownership, existing session+date, mandatory reason setelah fix
/attendance/session/:sheetId	Read-only detail, legend status, export warning
/student/attendance	Harian/mingguan, scope Per Jam, empty state
/parent/attendance	Child selector, monthly/weekly, scope Per Jam, freshness dan escalation

15.4 Field and action reference

Satu reference terstruktur untuk:

• session/date/batch/subject/time/classroom;
• student name dan identifier yang disetujui;
• status dan state glossary;
• remark/reason/proof;
• search, unit, batch, date, period, scope filters;
• Mark All Present, Save Draft/Complete, Edit, Refresh, Fill Session, Export;
• siapa yang dapat menjalankan setiap action dan apa downstream-nya.

15.5 Troubleshooting article

Pisahkan symptom berdasarkan actor:

• session tidak muncul;
• roster kosong atau salah;
• mode dialihkan ke gate;
• save pertama AccessError;
• status Sakit/Izin berbeda;
• perubahan belum terlihat portal;
• koreksi ditolak/cutoff;
• wrong child/no child;
• export/proof privacy;
• koneksi terputus — per-session tidak memiliki offline outbox.

15.6 Related-page links

• Setup jadwal/session dan enrollment rombel.
• Mode attendance configuration.
• Student permit/leave approval.
• Homeroom/subject attendance report.
• Parent/student attendance view.
• Report card attendance summary.
• Future: gate arrival/departure, RFID, face, pickup, advanced analytics.

15.7 Documentation acceptance test

Test ini dirancang sekarang tetapi baru dijalankan setelah defect/decision closure:

1. Provision user baru hanya dengan role Scola Teacher; pastikan first-save berhasil tanpa group legacy manual.
2. Buat session hari ini dengan dua siswa; pastikan guru lain dan tenant lain tidak dapat membaca/menulis.
3. Pastikan roster default sesuai keputusan ATT-D02 dan complete menolak roster incomplete/unmarked.
4. Save satu student masing-masing status kanonis, fetch kembali, lalu cocokkan guru, admin detail, student daily/period, parent daily/monthly.
5. Verifikasi Sakit dan Dispensasi konsisten di UI, API, rekap, rapor, dan promotion input.
6. Verifikasi state draft/complete dan correction cutoff/reason/audit sesuai ATT-D03–D05/D12.
7. Verifikasi principal/VP tidak melihat CTA mutation dan endpoint mutation ditolak.
8. Verifikasi admin roles yang disetujui dapat mengoreksi hanya company/unit sendiri.
9. Kirim missing/duplicate/out-of-batch/cross-company student IDs langsung ke API; semuanya harus ditolak atomik.
10. Verifikasi parent hanya dapat memilih child tertaut dan tidak menerima proof/reason melebihi policy.
11. Verifikasi tidak ada notifikasi per-session bila ATT-D08 default dipilih; bila notifikasi diaktifkan, uji exactly-once, audience, dan correction behavior.
12. Jalankan langkah artikel dari clean browser untuk teacher, homeroom, operator, student, dan parent; setiap visible label/action harus identik dengan artikel.

Evidence test yang dapat diperluas: tests/e2e/critical/teacher_attendance_flow.spec.ts:29, tests/e2e/critical/parent_attendance_flow.spec.ts:8, tests/unit/services/studentAttendance.service.spec.js:220, tests/unit/services/adminAttendance.service.spec.js:208, ../custom_addons_scola/gcgscola/scola_attendance/tests/test_attendance_structure_unit.py:376.

16. Definition of Ready sebelum penulisan dimulai

• [ ] ATT-D01 sampai ATT-D17 diputuskan dan dicatat oleh owner terkait.
• [ ] BLK-A19: first-save guru lulus dengan user fresh-provisioned tanpa group tambahan tak terdokumentasi.
• [ ] BLK-A20: faculty/admin save menolak roster incomplete, duplicate, out-of-batch, dan cross-company secara atomik.
• [ ] BLK-B04: role/capability/menu/controller parity lulus untuk operator, principal, dan VP kesiswaan.
• [ ] BLK-A21: draft/complete/correction/audit state machine telah diterapkan atau limitation resmi disetujui.
• [ ] BLK-A22: status glossary konsisten sampai agregasi portal/rapor/promotion.
• [ ] BLK-A23: proof file memiliki authorization, data minimization, type/size, retention, dan audit policy.
• [ ] Cross-role E2E membuktikan satu save guru yang sama tampil benar pada admin, student, dan parent.
• [ ] Runtime tenant baseline mencatat mode, company, timezone, module versions, dan role groups efektif.
• [ ] BLK-B05: existing quick-start/troubleshooting yang bertentangan ditandai untuk revisi bersamaan; jangan dibiarkan sebagai dua kontrak berbeda.
• [ ] Semua future documentation statements memiliki trace status selain Blocked by defect, Requires runtime verification, atau Requires business confirmation untuk langkah wajib.

17. Future related articles, bukan bagian pilot

• Kedatangan/kepulangan harian manual.
• Offline outbox untuk gate attendance.
• RFID ingestion dan device recovery.
• Face recognition dan liveness.
• Geofence/location policy.
• Pickup/transport attendance.
• Principal insight, attendance risk, dan advanced analytics.
• Employee attendance.

18. Dokumen dan source yang dibaca

Recon: seluruh file Markdown di docs/recon/, dengan fokus W05, route inventory, role matrix, page relationships, dan open questions. Existing docs: domain attendance, mode matrix, navigation audit, implementation guide, quick-start, role guides, troubleshooting, admin hub, configuration guide, dan PAUD UAT. Current source: route/menu/capability registry, semua page/service di tabel pilot, attendance controllers/models/security, portal identity, permit bridge, report-card/promotion downstream, serta FE/BE tests yang terkait.