prn2026/docs/changelog.md

# Changelog

All notable user-facing changes to this project will be documented in this file.

## 2026-05-28 - Phase 0 Planning Records

Added:

- Initial project planning documentation.
- Proposed architecture.
- Proposed database design.
- RBAC matrix.
- Workflow design.
- UI/UX plan.
- Testing plan.
- Deployment notes.
- Decision and progress logs.

Notes:

- No application features have been implemented yet.
- No user-facing web interface exists yet.

## 2026-05-28 - Phase 0 Documentation Review

Changed:

- Clarified registration-open setting in database and workflow planning.
- Clarified Phase 1 package baseline.
- Recorded local-only Telescope and later-only DOMPDF decisions.

## 2026-05-28 - Phase 1 Laravel Base Application

Added:

- Laravel 13 application base.
- Login, logout, password reset, email verification, and profile routes from Breeze.
- Bootstrap 5 authenticated and guest layouts.
- Role-based dashboards for Admin, Admin Kewangan, PPM, KTM, and Pemohon.
- RBAC roles and permissions seeder.
- Default local Admin seed account.
- Spatie permission and activity log foundations.
- QR code package foundation.
- Spreadsheet export foundation using OpenSpout.

Changed:

- Disabled generic public account registration.
- Replaced generated Tailwind views with Bootstrap views.

Notes:

- `maatwebsite/excel` was not installed because Composer rejected it for the current PHP 8.5.1/Laravel 13 environment.

## 2026-05-28 - Phase 2 Core Database

Added:

- Core election-domain database schema.
- Domain models and relationships.
- Default position seeder.
- Sample election hierarchy seed data.
- Position quota seed data.
- Sample role users for Admin Kewangan, PPM, and KTM.
- Sample dual-role PPM plus KTM assignment.
- Sample wheelchair allocation.
- Core domain seeder test.

Changed:

- Confirmed local MySQL usage for migrations and seeders.
- Shortened long database index names for MySQL compatibility.

## 2026-05-29 - Phase 3 Admin Setup Module

Added:

- Admin setup overview page.
- CRUD screens for Bahagian Pilihanraya, Daerah Mengundi, Pusat Mengundi, Saluran Mengundi, and Jawatan.
- Position quota setup for pusat-level and saluran-level vacancies.
- PPM assignment from Pusat Mengundi detail screen.
- QR generation and refresh for each Pusat Mengundi.
- Public QR placeholder page at `/pohon/{pusat_mengundi_uuid}`.
- Admin dashboard link to Election setup.
- Feature tests for Admin setup access, hierarchy creation, QR generation, quota setup, PPM assignment, and public UUID QR route.

Changed:

- QR links now resolve using public UUID values instead of internal database IDs.
- Public QR pages use a public layout without authenticated navigation.

Notes:

- The full public applicant form remains scheduled for Phase 4.
- KKM, JKM, and Police operational management remains scheduled for the later Admin management phase.

## 2026-05-29 - Phase 4 Public Application Module

Added:

- Public application form at `/pohon/{pusat_mengundi_uuid}`.
- Application roles KTM, KP, KPDP, and PAPM.
- Dynamic KTM selection for KP/KPDP based on remaining vacancy.
- Required IC document and bank statement uploads.
- Private document storage for uploaded public application files.
- Registration period open/closed enforcement.
- Duplicate IC blocking for current election.
- Specific blocking message for active KTM-created records with the same IC.
- Application success page with public UUID reference.
- Pending bank verification creation for submitted applications.
- Feature and unit tests for public application rules, registration period, and vacancy calculation.

Changed:

- QR links now open the real public application flow instead of the Phase 3 placeholder.

Notes:

- PPM review and approval of submitted applications remains scheduled for Phase 5.

## 2026-05-29 - Phase 5 PPM Review and Assignment

Added:

- PPM application list scoped to assigned Pusat Mengundi.
- PPM application detail page with applicant, bank, document, selected KTM, agency representative, and status history sections.
- PPM approval flow with role change before approval.
- KTM assignment to available Saluran Mengundi.
- KP/KPDP assignment to active KTM with remaining vacancy.
- PAPM assignment at Pusat Mengundi level.
- PPM rejection flow with required reason.
- Private document download for PPM-owned applications.
- Record-level authorization policy for PPM application access.
- PPM dashboard metrics and link to review queue.
- Feature tests for PPM scoping, missing-document block, approval/assignment, role change, and rejection.

Changed:

- Application approval in PPM flow now creates active staff assignment and moves the application to `assigned`.
- Base controller now includes Laravel authorization support for policies.

Notes:

- Polling-day attendance remains scheduled for Phase 10.

## 2026-05-29 - Phase 6 KTM Flow

Added:

- KTM team page showing assigned Saluran, KP team members, and KP vacancy.
- KTM KP registration form.
- KTM-created KP records with `source = created_by_ktm`.
- Queued Markdown email notification for KTM-created applicants.
- KTM approval flow for KP applications under own team.
- KTM deletion flow for own unassigned KTM-created applicant records.
- Registration-period enforcement for KTM registration and approval.
- KTM dashboard metrics and links to team/KP registration pages.
- Feature tests for KTM team scope, KP-only registration, email notification, registration closing, approval, non-KP block, other-team block, and deletion.

Changed:

- KTM dashboard now shows assigned Saluran, active KP count, and KP vacancy from live data.

Notes:

- KTM cannot upload documents for applicants in this phase; document collection remains with public/admin flows.

## 2026-05-29 - Phase 7 Admin Management and Manual Entry

Added:

- Admin management dashboard at `/admin/management`.
- Global Admin application list with filters.
- Manual application entry by Admin.
- Admin application edit screen with direct assignment panel.
- Global staff assignment list and edit screen.
- Police, KKM, and JKM representative entry screen.
- Required post-registration `catatan` validation for Admin changes after registration closes.
- System note creation for post-closing Admin changes.
- Activity and history logging for Admin application and assignment changes.
- Feature tests for manual entry, post-closing notes, direct assignment, representative creation, and Admin Kewangan route blocking.

Changed:

- Admin dashboard now shows live counts for Pusat Mengundi, Saluran, applications, and pending review.
- Admin dashboard links to the new management module.

Notes:

- Admin manual records do not send applicant email requests.

## 2026-05-29 - Phase 8 Admin Kewangan

Added:

- Admin Kewangan bank verification module at `/kewangan/bank`.
- Finance list for approved/assigned staff.
- Filters for Pusat Mengundi, role, verification status, missing bank statement, missing account number, and keyword.
- Bank verification detail page.
- Status update for pending, verified, rejected, and requires correction.
- Finance note capture.
- Finance XLSX export with export log recording.
- Sensitive data masking for IC, phone, and bank account display.
- Feature tests for finance list, verification update, filters, export logs, and assignment access blocking.

Changed:

- Admin Kewangan dashboard now shows live finance counts and links to the finance module.

Notes:

- Finance export uses OpenSpout due to the documented `maatwebsite/excel` compatibility exception.

## 2026-05-29 - Phase 9 Wheelchair Management

Added:

- Admin wheelchair management module at `/admin/management/wheelchairs`.
- Wheelchair allocation setup per Pusat Mengundi.
- Taken transaction recording with quantity, time, person taking, and notes.
- Returned transaction recording with quantity, time, condition, and notes.
- Summary counts for allocated, taken, returned, outstanding, and available quantities.
- Transaction history table.
- Audit logging for allocation changes and wheelchair transactions.
- Feature tests for allocation, taken/returned transactions, quantity validation, and role access blocking.

Changed:

- Admin management dashboard and navigation now include Kerusi Roda.

Notes:

- Transaction rows are retained as movement history; current balance is calculated from transaction totals.

## 2026-05-29 - Phase 10 Attendance

Added:

- PPM attendance module at `/ppm/attendance`.
- PPM-scoped Pusat Mengundi attendance list.
- Bulk attendance recording for active staff assignments.
- Attendance statuses: present, absent, and not recorded.
- Check-in time, recorded by, and note fields.
- Attendance activation guard using `election_settings.is_attendance_active`.
- Admin attendance dashboard at `/admin/attendance`.
- Admin attendance detail view by Pusat Mengundi.
- Role-level attendance summary.
- Attendance detail XLSX export with export log recording.
- Feature and unit tests for PPM scoping, activation flag, Admin dashboard, export log, and summary calculation.

Changed:

- Admin dashboard now links to attendance.
- PPM dashboard now links to attendance and shows present count.

Notes:

- Attendance export uses OpenSpout due to the documented `maatwebsite/excel` compatibility exception.

## 2026-05-29 - Phase 11 Polish and Hardening

Added:

- Authorized Admin document download route for private application documents.
- Authorized Admin Kewangan bank statement download route.
- Activity logging for Admin and finance document downloads.
- Document access tests for Admin, Admin Kewangan, and unauthorized roles.
- Sensitive data masking unit test.
- Final deployment quality gate notes.

Changed:

- Admin application edit screen now shows uploaded documents with secure download links.
- Admin Kewangan bank detail screen now links to bank statement download when available.

Notes:

- Admin Kewangan cannot download IC documents through the finance document route.
## 2026-05-31

### Changed

- Borang daftar Pusat Mengundi kini menerima bilangan Saluran, KTM, Polis Iring, KP, PPM, KPDP, PAPM, JKM, KKM dan Calon Tambahan.
- Saluran dijana secara automatik mengikut nombor dan tidak lagi memerlukan nama.
- Istilah Calon Simpanan telah ditukar kepada Calon Tambahan.

## 2026-06-02 - Fasa 15-A: Purge Automatik Fail Eksport Sensitif

### Added

- Artisan command `exports:purge --days=30` — memadam fail XLSX eksport lama dari storage dan menandakan rekod `export_logs` dengan `purged_at`.
- Scheduled task harian pada `00:00` dalam `routes/console.php` untuk jalankan purge secara automatik (retention default: 30 hari).
- Kolum `purged_at` dan `purged_by_user_id` pada jadual `export_logs`.
- Activity log `export_file_purged` untuk setiap fail yang dipadamkan.
- 7 ujian baharu dalam `ExportPurgeCommandTest`.

### Changed

- `ExportLog` model kini mempunyai cast `purged_at` dan relationship `purgedBy()`.

## 2026-06-02 - Fasa 14-A: Portal Status Permohonan Pemohon Awam

### Added

- Halaman status permohonan di `/permohonan/{uuid}/status` — boleh dicapai tanpa log masuk menggunakan UUID awam sahaja.
- Memaparkan: nama disamarkan (3 aksara pertama), jawatan, pusat mengundi, status dengan badge berwarna, sebab penolakan jika ditolak.
- UUID tidak dikenali, rekod soft-deleted, dan rekod `deleted_by_ktm` mengembalikan 200 dengan mesej generik — tidak mendedahkan maklumat dalaman.
- `SensitiveData::maskName()` — helper masking nama (3 aksara pertama + `***`).
- Panel "Simpan pautan status" pada halaman kejayaan permohonan dengan butang salin URL.
- 9 ujian baharu dalam `PublicApplicationStatusTest`.

## 2026-06-02 - Fasa 12-E: Konsistensikan Semakan Jenis Dokumen Download

### Added

- `ApplicationDocument` model kini mempunyai type constants (`TYPE_IC_DOCUMENT`, `TYPE_BANK_STATEMENT`) dan per-role allowlists (`ALLOWED_FOR_ADMIN`, `ALLOWED_FOR_PPM`, `ALLOWED_FOR_FINANCE`) sebagai satu sumber kebenaran.
- Activity log untuk PPM document downloads: `document_downloaded_by_ppm`.
- 9 ujian baharu dalam `DocumentDownloadAuthorizationTest` meliputi semua tiga path dan kes sempadan.

### Fixed

- PPM path kini mempunyai semakan jenis dokumen eksplisit menggunakan `ALLOWED_FOR_PPM`.
- PPM path kini mengembalikan 403 (bukan 404) untuk ownership mismatch — tidak mendedahkan kewujudan ID dokumen.
- Admin path kini menggunakan `ALLOWED_FOR_ADMIN` secara eksplisit — jenis dokumen baharu perlu didaftarkan untuk Admin dapat akses.
- Finance path kini menggunakan `ALLOWED_FOR_FINANCE` constant (logik sama, kini konsisten).

## 2026-06-02 - Fasa 13-A: Composite Indexes Pangkalan Data

### Added

- Migration `2026_06_02_000000_add_performance_indexes.php` menambah 3 index baharu:
  - `applications.(election_id, status)` — dashboard count dan senarai admin bertapis election
  - `applications.(selected_ktm_assignment_id, requested_position_id)` — `KtmVacancyService` reserved-application count (dipanggil setiap semak kekosongan KP/KPDP)
  - `staff_assignments.(reports_to_assignment_id, position_id, status)` — `KtmVacancyService` active-assignment count di bawah KTM
- Dokumentasi lengkap semua index dalam `docs/03-database-design.md`.
- Arahan verifikasi index (`SHOW INDEX`, `EXPLAIN`) dalam `docs/08-deployment-notes.md`.

### Notes

- Dua index yang diancangkan dalam plan sudah wujud dalam migration Phase 2: `(election_id, ic_number)` dan `(election_id, pusat_mengundi_id, status)` pada `applications`.
- `bank_verifications` tiada kolum `election_id` — index berkaitan tidak ditambah.

## 2026-06-02 - Fasa 12-C: Perkukuh Enforcement Nota Catatan Post-Pendaftaran

### Added

- Middleware `RequireAdminPostCloseNote` — automatically enforces that a `note` field is present in all write operations (`POST`, `PATCH`, `PUT`, `DELETE`) on Admin management routes when election registration is closed. Middleware alias: `admin.post_close_note`.
- 5 ujian baharu meliputi semua mutation routes yang sebelum ini tidak mempunyai catatan enforcement tests: application create, assignment update, representative create, representative delete, dan ujian bahawa middleware tidak menyekat apabila pendaftaran terbuka.

### Changed

- Route group `admin/management` kini menggunakan middleware `['auth', 'role:Admin', 'admin.post_close_note']` — catatan dikuatkuasakan secara automatik pada semua write routes tanpa bergantung pada konvensyen pemanggilan service sahaja.

## 2026-06-02 - Fasa 12-B: Pembetulan Semakan IC Soft-Deleted

### Fixed

- Audit dan pengesahan bahawa semua query semakan IC duplikasi (`StorePublicApplicationRequest`, `KtmApplicationService`) menggunakan perlindungan dua lapis yang betul: SoftDeletes scope (mengecualikan `deleted_at IS NOT NULL`) dan `whereNotIn` (mengecualikan `cancelled` dan `deleted_by_ktm`).
- Tambah comment dalam kod untuk mendokumentasikan intent perlindungan ini secara eksplisit.

### Added (Tests)

- Ujian baharu `test_public_registration_is_unblocked_after_ktm_deletes_applicant`: mengesahkan pemohon awam boleh mendaftar semula selepas KTM delete rekod yang dicipta.
- Ujian baharu `test_cancelled_application_does_not_block_new_registration`: mengesahkan rekod `cancelled` tidak menyekat pendaftaran IC yang sama.

## 2026-06-02 - Fasa 12-A: Admin Settings UI

### Added

- Halaman Admin Settings di `/admin/setup/settings/{election}` untuk mengawal mod kehadiran dan override tempoh pendaftaran tanpa edit database.
- Toggle radio untuk `is_attendance_active`: Tidak aktif / Aktif.
- Toggle radio tiga-keadaan untuk `is_registration_open_override`: Auto (ikut tarikh) / Buka Paksa / Tutup Paksa.
- Pautan "Tetapan" dalam nav setup dan setup index actions.
- Amaran badge apabila override sedang aktif.
- Activity log untuk setiap perubahan tetapan (nilai sebelum dan selepas, siapa yang ubah).
- 9 ujian baharu untuk akses, kemaskini, dan activity log.

### Fixed

- `SampleElectionSeeder` kini query kod jawatan `CALON_TAMBAHAN` (bukan `CALON_SIMPANAN` lama) — `php artisan migrate:fresh --seed` kini berjalan tanpa ralat.
- `AdminSetupTest` dikemaskini untuk menghantar medan operasi yang diperlukan semasa cipta Pusat, dan menggunakan nombor saluran '3' untuk elak konflik dengan saluran auto-jana.

## 2026-06-02 - Perancangan Fasa 12–15

### Added

- Dokumen pelan penambahbaikan `docs/09-improvement-plan.md` merangkumi lapan isu yang dikenal pasti daripada semakan kod menyeluruh selepas Phase 11.
- Fasa 12–15 ditambah dalam `docs/01-development-plan.md` sebagai fasa penambahbaikan berprioritikan.

### Planned (belum dilaksanakan)

- Fasa 12: Pembetulan kritikal — Admin Settings UI untuk toggle kehadiran dan pendaftaran, pembetulan semakan IC soft-deleted, perkukuhan enforcement nota catatan, pembetulan seeder, dan konsistensi semakan jenis dokumen download.
- Fasa 13: Composite indexes pangkalan data untuk prestasi query berskala besar.
- Fasa 14: Portal status permohonan pemohon awam yang boleh dicapai via UUID tanpa login.
- Fasa 15: Purge automatik fail eksport sensitif dengan polisi simpanan boleh dikonfigurasi.