prn2026/docs/decision-log.md

# Decision Log

This log records architecture decisions, package choices, database design trade-offs, security decisions, and assumptions.

## 2026-05-28 - Phase 0 Workspace Baseline

Decision:

- Treat current workspace as a clean/new project because no Laravel files or git repository are present.

Reason:

- Inspection found an empty `C:\Users\User\Aplikasi\prn2026` workspace, no `.git`, and no project files.

Impact:

- Phase 1 should create a fresh Laravel application.
- No existing code removal is required.

## 2026-05-28 - Laravel Version Selection Approach

Decision:

- Use the latest stable Laravel version supported by Composer and PHP during Phase 1.

Reason:

- Local PHP CLI is 8.5.1 and Composer is 2.9.4, which should support modern Laravel versions.
- Actual package compatibility should be verified at install time.

Impact:

- Do not lock a specific Laravel major version in Phase 0.
- Record final installed Laravel version in this log during Phase 1.

## 2026-05-28 - Authentication Scaffolding Choice

Decision:

- Plan to use Laravel Breeze with Blade stack for authentication scaffolding.

Reason:

- It is simple, maintainable, first-party, and suitable for government-style internal systems.
- Blade aligns with the requested stack.

Impact:

- Phase 1 should install Breeze after Laravel scaffolding.
- Public Pemohon QR flow should be custom and should not rely on open public account registration unless later required.

## 2026-05-28 - Frontend Stack Choice

Decision:

- Use Bootstrap 5, Bootstrap Icons, Blade, Vite, and jQuery where suitable.

Reason:

- Bootstrap 5 provides responsive admin UI quickly and maintainably.
- Bootstrap Icons covers common UI icon needs.
- jQuery remains useful for simple progressive enhancements with plugins such as Select2/DataTables.

Impact:

- Avoid heavy SPA architecture.
- Keep Blade as the primary rendering model.

## 2026-05-28 - RBAC Package Choice

Decision:

- Use `spatie/laravel-permission`.

Reason:

- Mature Laravel package for roles and permissions.
- Supports middleware, Blade directives, and permission caching.

Impact:

- Role and permission seeders are required.
- Record-level rules still require Laravel policies and services.

## 2026-05-28 - Audit Package Choice

Decision:

- Use `spatie/laravel-activitylog` plus domain-specific history tables.

Reason:

- Activity log is useful for generic before/after auditing.
- Domain history tables are better for reporting application status and assignment changes.

Impact:

- Implement structured histories for application and assignment workflows.
- Use activity log for broad audit trail requirements.

## 2026-05-28 - Excel Package Choice

Decision:

- Use `maatwebsite/excel`.

Reason:

- It is the common Laravel package for XLSX exports/imports and supports export classes.

Impact:

- Exports will live in `app/Exports`.
- Export query/filter logic will live in services.
- Every export must create an `export_logs` row.

## 2026-05-28 - QR Code Package Choice

Decision:

- Plan to use a Laravel-compatible QR code package, with `simplesoftwareio/simple-qrcode` as the first candidate if compatible.

Reason:

- The system requires QR codes for Pusat Mengundi public registration links.

Impact:

- Confirm package compatibility during Phase 1 before installation.
- If incompatible, choose another maintained Laravel-compatible QR generator and document the change.

## 2026-05-28 - UI Helper Package Choices

Decision:

- Plan to use SweetAlert2, Select2 or Tom Select, Flatpickr, and either DataTables or Laravel server-side pagination depending on screen needs.

Reason:

- SweetAlert2 improves confirmations.
- Searchable select controls are useful for Pusat, Saluran, KTM, and role assignment forms.
- Flatpickr improves date/time input consistency.
- Server-side pagination is safer for large operational data; DataTables may be used selectively.

Impact:

- Final npm package list must be verified in Phase 1.
- Prefer server-rendered pages and pagination for maintainability.

## 2026-05-28 - Optional Debug and PDF Packages

Decision:

- Do not install Laravel Telescope in the initial Phase 1 production baseline.
- Do not install DOMPDF in Phase 1.

Reason:

- Telescope is useful for local development but should not be part of the production default unless explicitly configured and protected.
- DOMPDF is only needed later if printable PDF reports become a confirmed requirement.

Impact:

- Reconsider Telescope only for local development after core modules exist.
- Reconsider DOMPDF only when a concrete PDF report format is provided.

## 2026-05-28 - Static Analysis and Formatting

Decision:

- Use Laravel Pint.
- Use Larastan/PHPStan if compatible with the selected Laravel and PHP versions.

Reason:

- Pint provides consistent code style.
- Static analysis improves reliability, but compatibility with PHP 8.5 and current Laravel must be checked.

Impact:

- Phase 1 or Phase 11 should configure quality commands.

## 2026-05-28 - Testing Framework

Decision:

- Use Laravel's built-in PHPUnit baseline.
- Pest may be installed if compatible and beneficial after Laravel setup.

Reason:

- PHPUnit is always available in standard Laravel projects.
- Pest improves readability but should not block delivery if compatibility issues arise.

Impact:

- Tests should be written in a way that can be implemented with PHPUnit even if Pest is skipped.

## 2026-05-28 - Dual-Role Assignment Model

Decision:

- Model operational roles through `staff_assignments`, not a single role field on users or applications.

Reason:

- A PPM may also be KTM.
- Staff placement is tied to election, Pusat Mengundi, Saluran Mengundi, position, and team structure.

Impact:

- A person can have more than one active assignment when business rules allow it.
- Validation services must enforce invalid duplicates while allowing PPM + KTM.

## 2026-05-28 - Public Identifier Security

Decision:

- Use UUID or ULID public identifiers for public QR links.

Reason:

- Public URLs must not expose internal auto-increment IDs.

Impact:

- Pusat Mengundi requires a public UUID/ULID column.
- Public route binding should resolve by public identifier.

## 2026-05-28 - Sensitive Document Storage

Decision:

- Store IC documents and bank statements on private Laravel storage.

Reason:

- These are sensitive documents and must not be publicly accessible.

Impact:

- No public storage symlink for sensitive uploads.
- Downloads must go through authorized controller actions.

## 2026-05-28 - Registration Period Assumption

Assumption:

- Registration period is event-specific and stored in `election_settings`.
- `election_settings.is_registration_open` is stored and used together with the configured registration dates.

Reason:

- The system may need to support future elections with different dates.
- The original requirement explicitly asks for a setting indicating whether registration is open.

Impact:

- Registration checks must use the active election setting.
- Admin settings UI must make both the date window and open/closed state clear.

## 2026-05-28 - Generic Public Account Registration

Assumption:

- Generic public user registration should not be enabled by default.

Reason:

- Requirement says registration is only for public applicant flow if allowed.
- QR applicant flow can collect application records without creating login accounts.

Impact:

- Breeze registration may be disabled or restricted for internal user creation.
- Admin-created users handle internal roles.

## 2026-05-28 - MySQL Availability

Assumption:

- MySQL server will be provided even though `mysql` CLI is not currently in PATH.

Reason:

- The requirement specifies MySQL, but local CLI check failed.

Impact:

- Phase 1 must confirm DB connection through Laravel `.env` and migrations.

## 2026-05-28 - Phase 1 Laravel Version Installed

Decision:

- Installed `laravel/laravel` v13.8.0.
- Installed `laravel/framework` v13.12.0.

Reason:

- Composer resolved Laravel 13 as the latest stable skeleton/framework compatible with PHP 8.5.1.

Impact:

- Package compatibility was verified against Laravel 13 and PHP 8.5.1 during installation.

## 2026-05-28 - Phase 1 Authentication and Registration

Decision:

- Installed Laravel Breeze v2.4.2 for simple Blade authentication scaffolding.
- Disabled generic public `/register` routes.
- Retained public applicant registration for a later QR-specific module.

Reason:

- Internal users should be Admin-created.
- The original requirement allows public registration only for the applicant flow if enabled.

Impact:

- `/login`, password reset, logout, profile, and email verification routes exist.
- `/register` returns 404.
- Public applicant registration will be implemented under `/pohon/{pusat_mengundi_uuid}` in Phase 4.

## 2026-05-28 - Phase 1 Package Compatibility Results

Decision:

- Installed compatible Composer packages:
  - `spatie/laravel-permission` v7.4.1
  - `spatie/laravel-activitylog` v5.0.0
  - `simplesoftwareio/simple-qrcode` v4.2.0
  - `laravel/breeze` v2.4.2
  - `larastan/larastan` v3.9.6
  - `openspout/openspout` v5.7.1
- Laravel Pint was already installed by the Laravel 13 skeleton at v1.29.1.
- PHPUnit was installed by the Laravel 13 skeleton at v12.5.28.

Reason:

- Composer successfully resolved these versions with Laravel 13.12.0 and PHP 8.5.1.

Impact:

- RBAC, activity log, QR generation, auth scaffolding, static analysis, formatting, and spreadsheet export foundations are available.

## 2026-05-28 - Maatwebsite Excel Compatibility Exception

Decision:

- Did not install `maatwebsite/excel` in Phase 1.
- Installed `openspout/openspout` v5.7.1 as the compatible spreadsheet export foundation.

Reason:

- Composer rejected `maatwebsite/excel` for this environment.
- Latest resolvable `maatwebsite/excel` versions either do not support Laravel 13 or depend on `phpoffice/phpspreadsheet` versions constrained to PHP `<8.5.0`.
- The local environment is PHP 8.5.1.
- Faking Composer platform PHP was rejected because it would weaken production-readiness.

Impact:

- Export service design remains unchanged.
- Export implementation should use OpenSpout unless `maatwebsite/excel` releases a PHP 8.5 and Laravel 13 compatible version or the runtime target is changed to a compatible PHP version.
- This is a documented deviation from the preferred export package in the original requirement due to compatibility.

## 2026-05-28 - Phase 1 Frontend Package Results

Decision:

- Installed npm packages:
  - `bootstrap`
  - `@popperjs/core`
  - `bootstrap-icons`
  - `jquery`
  - `sweetalert2`
  - `tom-select`
  - `flatpickr`
  - `datatables.net-bs5`
  - `datatables.net-responsive-bs5`

Reason:

- These packages support the requested Bootstrap 5, jQuery-assisted, responsive admin UI.

Impact:

- Vite production build is available.
- Tailwind dependencies remain from Breeze scaffolding but are not used by the application layout.

## 2026-05-28 - Generated View Replacement

Decision:

- Replaced generated Laravel/Breeze Tailwind views with Bootstrap 5 Blade views.

Reason:

- The original requirement specifies Bootstrap 5.

Impact:

- Auth, guest, app, navigation, profile, welcome, and dashboard views now follow the Bootstrap-based government-style admin UI direction.

## 2026-05-28 - Phase 1 Local Database Choice

Decision:

- `.env.example` is configured for MySQL.
- Local `.env` remains on SQLite for Phase 1 verification.

Reason:

- The PHP `pdo_mysql` extension is available, but MySQL CLI/server credentials are not available in the current workspace.
- SQLite allows auth, RBAC migrations, seeding, and tests to be verified immediately.

Impact:

- Production and shared environments must configure MySQL in `.env`.
- Local development can switch to MySQL once credentials are provided.

Superseded by:

- `2026-05-28 - Phase 2 MySQL Connection Confirmed`.

## 2026-05-28 - Application Timezone

Decision:

- Set application timezone to `Asia/Kuala_Lumpur` through `APP_TIMEZONE`.

Reason:

- The system is for Malaysian election operations and polling-day attendance timestamps must use local time.

Impact:

- Date/time display, audit timestamps, and attendance check-in defaults will align with Malaysia time when using Laravel timezone helpers.

## 2026-05-28 - Phase 2 MySQL Connection Confirmed

Decision:

- Use MySQL for local Phase 2 migration and seeding verification.

Reason:

- Laravel successfully connected to MySQL 8.4.8 through PDO using `.env` database `prn2026`.
- This better matches the production database requirement than SQLite.

Impact:

- Phase 2 schema was verified against MySQL, including identifier length constraints.
- MySQL CLI remains unavailable in PATH, but Laravel/PDO connectivity is sufficient for migrations and tests requiring the configured app database.

## 2026-05-28 - Phase 2 Core Domain Migration Strategy

Decision:

- Implement Phase 2 domain schema in one ordered migration file.

Reason:

- The tables are tightly coupled by foreign keys and the phase is a single baseline domain cut.
- Keeping the initial domain schema in one migration makes fresh local setup easier at this stage.

Impact:

- Future schema changes should use separate additive migrations.
- Down migration disables foreign key checks to safely drop circular application/assignment references.

## 2026-05-28 - Phase 2 Index Name Strategy

Decision:

- Use explicit short names for long composite indexes.

Reason:

- MySQL rejected Laravel's generated index name for `position_quotas` because it exceeded the 64-character identifier limit.

Impact:

- Composite indexes use concise names such as `pq_election_saluran_position_idx` and `sa_election_saluran_position_idx`.

## 2026-05-28 - Phase 2 Seed Data Strategy

Decision:

- Seed a realistic but small sample election hierarchy and operational assignments.

Reason:

- Later UI phases need immediate data for dashboards, setup screens, and authorization checks.

Impact:

- Seed data includes one election, one Bahagian, one Daerah, one Pusat, three Saluran, quotas, sample users, and a PPM who also has a KTM assignment.

## 2026-05-29 - Phase 3 Admin Setup Scope Boundary

Decision:

- Complete Phase 3 as Admin setup for hierarchy CRUD, Jawatan CRUD, quota setup, PPM assignment, and QR generation.
- Keep KKM, JKM, and Police operational CRUD for Phase 7 Admin management.

Reason:

- The original phase sequence defines Phase 3 around election structure, PPM assignment, jawatan/quota setup, and QR links.
- KKM, JKM, and Police records need the broader Admin management controls, post-registration notes, and audit behavior planned in Phase 7.

Impact:

- The Phase 2 schema already contains representative tables.
- Phase 3 UI does not yet manage representative records.

## 2026-05-29 - Phase 3 QR Storage and Route Binding

Decision:

- Generate QR SVG files into private local storage under `qrcodes/pusat-mengundi/{public_uuid}.svg`.
- Serve the QR SVG through an Admin-protected controller route.
- Use `/pohon/{pusatMengundi:public_uuid}` as the public registration URL.

Reason:

- The public URL must not expose internal database IDs.
- Keeping generated QR assets outside the public web root avoids accidental direct exposure and keeps access paths explicit.

Impact:

- Admin can regenerate QR codes per Pusat Mengundi.
- Public QR routes currently show a placeholder until Phase 4 implements the full application form.

## 2026-05-29 - Phase 3 PPM Assignment Service

Decision:

- Implement PPM assignment through `PpmAssignmentService`.
- Store the assignment in `staff_assignments`, mark previous active PPM assignment for the same Pusat Mengundi as `replaced`, create a `staff_assignment_histories` row, and assign the RBAC role `PPM` to the user.

Reason:

- Dual-role support requires assignments to remain separate from RBAC roles.
- RBAC controls application access, while `staff_assignments` controls operational placement.

Impact:

- A user can be PPM and also hold another operational assignment such as KTM when later assignment rules allow it.
- PPM changes are auditable from the assignment history and activity log.

## 2026-05-29 - Phase 3 Quota Consistency Validation

Decision:

- Validate that a selected Saluran Mengundi belongs to the selected Pusat Mengundi when creating or updating a position quota.

Reason:

- Quotas must not accidentally attach a saluran from another Pusat Mengundi.

Impact:

- Position quotas can be set at pusat level by leaving saluran blank, or at saluran level with a matching pusat and saluran pair.

## 2026-05-29 - Phase 3 Public Layout

Decision:

- Add a lightweight public Blade layout for QR-facing pages.

Reason:

- Public QR routes should not render the authenticated internal navigation when accessed by unauthenticated applicants.

Impact:

- The Phase 3 QR placeholder is mobile-friendly and independent of internal Admin navigation.

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

Decision:

- Replace the Phase 3 QR placeholder route implementation with `PublicApplicationController`.
- Keep the public QR URL as `/pohon/{pusatMengundi:public_uuid}`.
- Use `/permohonan/{application:public_uuid}/berjaya` for the post-submission confirmation page.

Reason:

- Existing QR codes and registration URLs must remain valid.
- Public UUID route binding avoids exposing internal auto-increment IDs.

Impact:

- Public applicants can now submit real applications through the QR link.
- The old placeholder controller remains unused and can be removed in a later cleanup with a recorded reason.

## 2026-05-29 - Phase 4 Registration Period Service

Decision:

- Add `RegistrationPeriodService` to centralize open/closed registration checks.
- Treat `is_registration_open_override` as an explicit override when it is not null.

Reason:

- Public, KTM, PPM, and Admin workflows will all need consistent registration-period behavior in later phases.

Impact:

- Public GET and POST routes block submissions when registration is closed.
- Admin settings UI in a later phase should clearly show whether an override is active.

## 2026-05-29 - Phase 4 Public Upload Storage

Decision:

- Store public IC documents and bank statements on Laravel's private `local` disk under `applications/{application_public_uuid}`.
- Record metadata in `application_documents`.

Reason:

- IC documents and bank statements are sensitive and must not be served from public storage.

Impact:

- Later document download/view actions must go through authorized controllers.
- Public success pages do not expose document paths.

## 2026-05-29 - Phase 4 KTM Vacancy Calculation

Decision:

- Add `KtmVacancyService`.
- For public KP/KPDP applications, remaining vacancy is quota minus active team assignments minus reserved submitted/under-review/approved applications for the same KTM assignment and role.

Reason:

- Applicants should only choose a KTM when vacancy exists, and pending submissions should reserve capacity to prevent overbooking.

Impact:

- The public form shows only KTM options with remaining vacancy for KP/KPDP.
- POST validation rechecks vacancy to prevent stale form submission.

## 2026-05-29 - Phase 4 Duplicate IC Rule

Decision:

- Normalize IC numbers to digits and enforce one active application per election.
- If the duplicate active record has `source = created_by_ktm`, show a specific message instructing that KTM must delete that pre-created record first.

Reason:

- The original requirement explicitly distinguishes KTM-created records from public self-registration.

Impact:

- Public submissions are blocked for duplicate IC values.
- Cancelled or `deleted_by_ktm` records do not block future self-registration.

## 2026-05-29 - Phase 4 Bank Verification Initialization

Decision:

- Create a pending `bank_verifications` row immediately after public application submission.

Reason:

- This prepares records for the Admin Kewangan workflow and avoids missing finance state later.

Impact:

- Admin Kewangan module can later query pending bank checks without needing to backfill submitted public applications.

## 2026-05-29 - Phase 5 PPM Record-Level Authorization

Decision:

- Add `ApplicationPolicy` and `PpmScopeService`.
- Scope PPM access by active `staff_assignments` where position is `PPM`, status is `active`, and assignment is at Pusat Mengundi level.

Reason:

- Role middleware alone cannot enforce "PPM only manages own Pusat Mengundi".

Impact:

- PPM can list, view, approve, reject, and download documents only for applications under their assigned Pusat Mengundi.
- Admin remains able to pass policy checks for future shared application views.

## 2026-05-29 - Phase 5 Approval Creates Assignment

Decision:

- PPM approval creates or updates an active `staff_assignments` row and sets application status to `assigned`.
- Assignment history and application status history are written in the same transaction.

Reason:

- In this module, approval is coupled with the required placement selection for KTM, KP, KPDP, or PAPM.
- A separate `approved` holding state can still be used later if a workflow needs approval without placement.

Impact:

- Approved Phase 5 applications immediately appear as active staff assignments.
- Role changes before approval are recorded through application status metadata, assignment history, and activity log.

## 2026-05-29 - Phase 5 Vacancy Validation

Decision:

- Add `AssignmentVacancyService` for pusat-level and saluran-level placement checks.
- Reuse `KtmVacancyService` for KP/KPDP assignment to KTM, with an option to ignore the application being approved when counting reserved vacancy.

Reason:

- PPM assignment must prevent overfilling KTM, KP, KPDP, and PAPM quotas.
- Pending KP/KPDP public applications reserve vacancy, but the current application should not block its own approval.

Impact:

- PPM can assign KTM only to an available Saluran.
- PPM can assign KP/KPDP only to an active KTM under the same Pusat Mengundi with remaining vacancy.

## 2026-05-29 - Phase 5 Authorized Document Download

Decision:

- Add PPM document download route under authenticated PPM review routes.
- Verify the document belongs to the application before streaming it from private storage.

Reason:

- PPM needs to review uploaded IC and bank statement documents, but files must remain private.

Impact:

- Uploaded files are not exposed through public storage URLs.
- Document viewing for Admin/Admin Kewangan can be added later using the same private-storage pattern.

## 2026-05-29 - Phase 5 Attendance Boundary

Decision:

- Do not implement polling-day attendance in Phase 5.
- Keep attendance screens, summaries, and exports for Phase 10.

Reason:

- The phase sequence separates PPM review/assignment from attendance reporting/export design.
- Attendance has separate dashboard and export requirements that should be implemented together.

Impact:

- PPM dashboard still shows attendance as a future module.
- Phase 10 remains responsible for polling-day attendance.

## 2026-05-29 - Phase 6 KTM Scope Service

Decision:

- Add `KtmScopeService` to define KTM ownership from active `staff_assignments` with position `KTM`, a Saluran Mengundi, and status `active`.

Reason:

- A KTM may only manage KP records under their own assigned Saluran/team.

Impact:

- KTM listing, registration, approval, and deletion are constrained to the current user's active KTM assignments.
- KTM cannot manage another KTM's team.

## 2026-05-29 - Phase 6 KTM-Created Applicant Records

Decision:

- KTM registration creates `applications` rows with `source = created_by_ktm`, `status = submitted`, and requested position `KP`.
- The KTM form does not accept a selectable role; malicious extra role fields are ignored by the service.

Reason:

- KTM is only allowed to register KP, not KTM, KPDP, PAPM, PPM, Police, KKM, or JKM.
- The existing public duplicate-IC rule already blocks public self-registration while an active KTM-created record exists.

Impact:

- KTM-created applicants can be reviewed/approved by KTM under their own team.
- Public self-registration remains blocked until the KTM-created record is deleted or cancelled.

## 2026-05-29 - Phase 6 Email Notification

Decision:

- Add queued Markdown Mailable `KtmCreatedApplicantMail`.
- Queue the email when KTM creates a KP applicant.

Reason:

- The requirement asks that KTM-created applicants receive email notification with name, role, Pusat Mengundi, KTM name, and correction instructions.

Impact:

- Queue/mail configuration must be valid in production.
- Tests use Laravel mail fake to verify the mailable is queued.

## 2026-05-29 - Phase 6 KTM Approval and Deletion

Decision:

- KTM approval of KP creates active `staff_assignments` with `reports_to_assignment_id` pointing to the KTM assignment and status `assigned` on the application.
- KTM can delete only unassigned `created_by_ktm` records under their own assignment.

Reason:

- Approval is a placement action, and after registration closes only Admin should be allowed to register/edit/assign.
- Deletion is needed to unblock public self-registration for applicants pre-created by KTM.

Impact:

- KTM approval is blocked after registration closes.
- Deletion writes `deleted_by_ktm` status history and soft deletes the application.

## 2026-05-29 - Phase 7 Admin Management Route Boundary

Decision:

- Add Admin management routes under `/admin/management`, separate from `/admin/setup`.

Reason:

- Setup screens manage election structure and QR preparation, while Phase 7 manages operational application/staff corrections and representative records.

Impact:

- Admin dashboard now links to both setup and management.
- Admin Kewangan is blocked from management routes because placement changes are Admin-only.

## 2026-05-29 - Phase 7 Manual Entry Source

Decision:

- Admin manual applications use `source = admin_manual`.
- Direct Admin assignments use `source = admin_direct`, while edited assignments use `source = admin_update`.

Reason:

- Source flags distinguish public, KTM-created, PPM-approved, and Admin-maintained records for audit and later reporting.
- Admin-keyed records must not trigger KTM-created applicant bank/detail request email behavior.

Impact:

- Manual records create pending bank verification state but no email notification.
- Reports can filter records by operational source.

## 2026-05-29 - Phase 7 Post-Closing Catatan Enforcement

Decision:

- Centralize post-closing note enforcement in `AdminPostCloseNoteService`.
- Require `catatan` when the election registration period is closed for Admin application edit, manual entry, direct assignment, assignment edit, and representative changes.

Reason:

- The original requirement makes post-registration Admin changes allowable only with a note.

Impact:

- Missing catatan returns validation errors.
- Accepted post-closing changes create `system_notes` linked to the changed record.

## 2026-05-29 - Phase 7 Representative Management

Decision:

- Implement Police, KKM, and JKM manual entry in one representative management screen while keeping their existing separate database tables.

Reason:

- Operationally these records are maintained together by Admin, but the schema separates fields because Police can be saluran-specific and has rank/station fields.

Impact:

- PPM representative display can continue reading the existing separate tables.
- Future edit forms can extend the same service without schema changes.

## 2026-05-29 - Phase 8 Finance Scope

Decision:

- Implement finance verification under `/kewangan/bank`.
- Limit Admin Kewangan write access to `bank_verifications.status` and `finance_note`.

Reason:

- The finance role must verify bank details without changing placement or assignments.

Impact:

- Admin Kewangan can filter and update finance records.
- Admin Kewangan remains blocked from Admin management assignment routes.

## 2026-05-29 - Phase 8 Finance Export Implementation

Decision:

- Implement finance XLSX export with OpenSpout in `app/Exports/FinanceVerificationExport`.
- Keep export orchestration in `FinanceExportService` and query/filter logic in `FinanceVerificationQuery`.

Reason:

- The original preferred package `maatwebsite/excel` remains incompatible with this PHP 8.5/Laravel 13 environment.
- The project already documented OpenSpout as the compatible export foundation.

Impact:

- Export files are stored in private local storage under `exports/finance`.
- Every finance export writes an `export_logs` row with user, timestamp, report type, filters, file name, disk, and path.

## 2026-05-29 - Phase 8 Sensitive Finance Display

Decision:

- Add `App\Support\SensitiveData` masking helper and use it on finance screens for IC, phone, and bank account values.

Reason:

- Finance users need enough information to identify records, but full sensitive values should not be displayed unless necessary.

Impact:

- Finance list/detail screens mask IC, phone, and account numbers.
- Future modules can reuse the same helper for consistent sensitive data handling.

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

Decision:

- Implement wheelchair management under Admin Management at `/admin/management/wheelchairs`.

Reason:

- Wheelchair allocation and movement are operational Admin functions tied to Pusat Mengundi, not initial election hierarchy setup.

Impact:

- Admin can access wheelchair management from the Admin management module.
- Admin Kewangan and other roles cannot access wheelchair management routes.

## 2026-05-29 - Phase 9 Wheelchair Quantity Rules

Decision:

- Treat `wheelchair_allocations.allocated_quantity` as the maximum quantity available for a Pusat Mengundi.
- Treat `wheelchair_transactions` rows as immutable movement records.
- Calculate outstanding quantity as total taken minus total returned.

Reason:

- Separate movement records are more auditable than overwriting current state fields.

Impact:

- Taken transactions are blocked when quantity exceeds available allocation.
- Returned transactions are blocked when quantity exceeds outstanding quantity.
- Allocation cannot be reduced below outstanding quantity.
- Every allocation change and movement is written to activity log.

## 2026-05-29 - Phase 10 Attendance Activation

Decision:

- Block PPM attendance recording unless `election_settings.is_attendance_active` is true.

Reason:

- Attendance should only be used on polling day or when explicitly activated by Admin settings.

Impact:

- PPM can see attendance screens but cannot submit records while inactive.
- Tests explicitly activate the flag before successful recording.

## 2026-05-29 - Phase 10 Attendance Scope and Storage

Decision:

- Store attendance per active `staff_assignments` row.
- Scope PPM recording by active PPM assignment to Pusat Mengundi.

Reason:

- Staff assignments already represent final placement and support dual roles.
- Attendance belongs to a concrete operational assignment, not only a user.

Impact:

- A user with dual role can have separate attendance records per assignment.
- Admin summaries can group attendance by Pusat, role, and Saluran.

## 2026-05-29 - Phase 10 Attendance Export

Decision:

- Implement attendance detail export using OpenSpout and `AttendanceExportService`.

Reason:

- Report format may change later, so export formatting is isolated from controllers.
- OpenSpout remains the compatible XLSX writer for this environment.

Impact:

- Attendance detail exports are stored in private local storage under `exports/attendance`.
- Every export writes an `export_logs` row with report type and Pusat filter parameters.

## 2026-05-29 - Phase 11 Document Access Hardening

Decision:

- Add authorized document download routes for Admin and Admin Kewangan.
- Admin can download all application documents.
- Admin Kewangan can download only `bank_statement` documents.

Reason:

- PPM document download existed, but Admin and Finance document access also needs an explicit private-storage controller path.
- Finance users should not download IC documents because the finance workflow only requires bank evidence.

Impact:

- Sensitive files remain on private storage and are served only through authenticated, role-protected routes.
- Document download actions are recorded in activity log.

## 2026-05-29 - Phase 11 Final Hardening Scope

Decision:

- Treat Phase 11 as final quality gate, security review, targeted test-gap closure, and documentation hardening.

Reason:

- The main feature phases are complete; remaining work should reduce release risk without changing broad behavior.

Impact:

- Added document authorization tests and sensitive-data masking unit test.
- Deployment notes now include final quality gate commands and document-storage warnings.
## 2026-06-02 - Fasa 15-A: Export File Purge Strategy

Decision:

- Retention period default: 30 days. Configurable via `--days` option to allow shorter retention for audit events (e.g., polling day exports) or longer retention for post-event review.
- Purge is triggered by `created_at < now - days` on the `export_logs` table, not `generated_at`, because `created_at` is always set by Eloquent and cannot be null.
- Records with files already missing from disk are still marked `purged_at` to prevent repeated processing attempts.
- `purged_by_user_id` is nullable and not set by the scheduled command (system-initiated purge). It is reserved for future manual purge UI where an Admin might trigger purge on demand and should be attributed.
- The scheduled task uses `withoutOverlapping()` and `runInBackground()` so large purge runs don't block the scheduler.

Reason:

- Finance verification lists and attendance exports contain bank account numbers and personal data. Indefinite storage of these files increases breach risk.
- A 30-day default balances post-export review window (staff may need to re-download for a few weeks) against data minimisation.

Impact:

- `routes/console.php` now contains a `Schedule::command(...)` entry.
- `php artisan schedule:run` must be configured in the operating system cron (per existing deployment notes).
- `export_logs` table has `purged_at` and `purged_by_user_id` columns via migration `2026_06_02_000001_add_purged_at_to_export_logs.php`.

## 2026-06-02 - Fasa 14-A: Applicant Status Portal

Decision:

- Route uses a plain string parameter `{publicUuid}` instead of route model binding `{application:public_uuid}` to prevent Laravel from returning 404 for unknown UUIDs. The controller handles all lookup and returns 200 with a generic message for invalid or internal-only UUIDs.
- `deleted_by_ktm` applications and soft-deleted records return the same generic message as "not found", so the portal cannot be used to infer whether a UUID once existed.
- Name masking shows only the first 3 characters to confirm identity to the applicant without revealing the full name to observers.
- IC number, bank account, and phone are never displayed.
- Rejection reason is displayed when status is `rejected` — this is intentional as the applicant has a right to know why their application was rejected.

Reason:

- Without this feature, applicants could only find out their status by contacting the Admin or PPM, creating unnecessary support burden.
- UUID-as-identifier (not requiring login) balances accessibility with security — only the person who received the QR-generated UUID link can access the status.

Impact:

- Route: `GET /permohonan/{publicUuid}/status` → `public.applications.status`.
- No authentication middleware applied to this route.
- `SensitiveData::maskName()` added.

## 2026-06-02 - Fasa 12-E: Document Type Allowlists

Decision:

- Define document type allowlists as constants on the `ApplicationDocument` model (`ALLOWED_FOR_ADMIN`, `ALLOWED_FOR_PPM`, `ALLOWED_FOR_FINANCE`), making the single source of truth co-located with the model they describe.
- All download paths reference these constants; adding a new document type requires a deliberate update to the relevant allowlist.

Reason:

- Admin and PPM paths had no explicit type checks — silently allowed any document type. If a new sensitive type were added, those roles would automatically get access without a conscious decision.
- PPM path used 404 for ownership mismatch, which reveals document ID existence to unauthorised callers. Changed to 403.
- PPM path had no activity log — inconsistent with Admin and Finance paths.

Impact:

- `ApplicationDocument::ALLOWED_FOR_ADMIN = ['ic_document', 'bank_statement']` — Admin can download both types.
- `ApplicationDocument::ALLOWED_FOR_PPM = ['ic_document', 'bank_statement']` — PPM can download both types (needed to review before approval).
- `ApplicationDocument::ALLOWED_FOR_FINANCE = ['bank_statement']` — Finance can only download bank statements.
- Any new document type added to the system requires explicit inclusion in each allowlist before the relevant role can download it.

## 2026-06-02 - Fasa 13-A: Composite Database Indexes

Decision:

- Audit existing indexes before adding new ones. Verified that Phase 2 migration already contains `(election_id, ic_number)` and `(election_id, pusat_mengundi_id, status)` on `applications`, and `(election_id, pusat_mengundi_id, position_id)` and `(election_id, saluran_mengundi_id, position_id)` on `staff_assignments`.
- Added only genuinely missing indexes via a separate migration to avoid modifying the baseline Phase 2 migration.
- Did not add `(election_id, status)` on `bank_verifications` because that table does not have an `election_id` column.

Reason:

- `KtmVacancyService` is called on every public KP/KPDP application and on the form for KTM option display. Two queries inside it (`$assignedCount` and `$reservedCount`) had no composite coverage.
- The admin application list query does not filter by `election_id`, so `(election_id, status)` on `applications` primarily helps dashboard count queries and future per-election reporting.

Impact:

- Migration: `2026_06_02_000000_add_performance_indexes.php`.
- Index verification steps documented in `docs/08-deployment-notes.md`.
- No model or service code changes required.

## 2026-06-02 - Fasa 12-C: Middleware RequireAdminPostCloseNote

Decision:

- Add `RequireAdminPostCloseNote` middleware and apply it to the entire `admin/management` route group as a safety net on top of the existing service-layer enforcement.
- Keep all existing `$this->postCloseNoteService->requireIfClosed(...)` calls in services (they provide the correct election context for each record).
- Middleware resolves the election from: `election_id` in the request body (create routes), or the first active election (edit/delete routes where the election comes from the model, not the request).

Reason:

- The existing service-layer enforcement is correct but convention-based — a new controller that forgets to call `requireIfClosed()` would silently bypass the gate.
- Middleware provides an automatic belt-and-suspenders check that applies to ALL write operations in the route group regardless of which service is called.
- The middleware approach is safe because: (a) single active election is the normal operating state, and (b) the service still does the precise check with the correct election.

Impact:

- Alias: `admin.post_close_note` registered in `bootstrap/app.php`.
- Applied to `['auth', 'role:Admin', 'admin.post_close_note']` in `routes/web.php` for the management group.
- Read operations (GET) pass through without note check.
- Missing note returns redirect-back with validation errors on `note` field.

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

Decision:

- Add Admin Settings UI at `GET/PATCH /admin/setup/settings/{election}` for toggling `is_attendance_active` and `is_registration_open_override`.
- Place the Settings screen within the existing `admin/setup` route group and include it in the `_nav.blade.php` as a warning-toned button.
- Log all settings changes via `activity('admin_settings')` with before and after values.

Reason:

- Both `is_attendance_active` and `is_registration_open_override` were previously only editable via direct database access, which is unsafe in production.
- The risk of accidental misconfiguration (e.g., forgetting to activate attendance on polling day) is high without a UI.

Impact:

- `ElectionSettingsController`, `ElectionSettingsService`, and `UpdateElectionSettingsRequest` added.
- Route names: `admin.setup.settings.edit`, `admin.setup.settings.update`.
- Accessibility: Admin role only; all other roles are forbidden.
- `is_registration_open_override` exposes three logical states: null (auto), true (force open), false (force closed), mapped via HTML radio buttons with empty string for null.

## 2026-06-02 - Fasa 12-D: Pembetulan SampleElectionSeeder (CALON_TAMBAHAN)

Decision:

- Fixed `SampleElectionSeeder::seedQuotas()` to query position code `CALON_TAMBAHAN` instead of the old `CALON_SIMPANAN`.
- Fixed `tests/Feature/AdminSetupTest.php` to include required operational counts (`saluran_count`, etc.) when posting to `admin.setup.pusat.store`, and to use saluran number '3' (not '1') to avoid conflict with auto-generated salurans from `PusatOperationalSetupService`.

Reason:

- The 2026-05-31 phase renamed `CALON_SIMPANAN` → `CALON_TAMBAHAN` via migration. The seeder was not updated, causing `KeyError` when accessing `$positions['CALON_TAMBAHAN']`.
- The 2026-05-31 phase also made `saluran_count` required on POST for Pusat creation. The test was not updated to match, causing a conflict when it tried to manually create saluran number 1 that already existed.

Impact:

- `php artisan migrate:fresh --seed` now runs cleanly.
- All 90 tests pass.
- Pint and PHPStan pass.

## 2026-05-31 - Pendaftaran operasi semasa daftar Pusat Mengundi

- Nama Saluran tidak lagi diperlukan pada UI. Saluran dikenal pasti menggunakan nombor di bawah Pusat Mengundi.
- Borang daftar Pusat Mengundi menerima bilangan Saluran, KTM, Polis Iring, KP, PPM, KPDP, PAPM, JKM, KKM dan Calon Tambahan.
- Saluran bernombor `1..N` dijana secara automatik semasa Pusat Mengundi dicipta.
- Kuota `PPM`, `PAPM`, `JKM` dan `KKM` disimpan pada skop Pusat Mengundi.
- Kuota `KTM`, `POLIS`, `KP`, `KPDP` dan `CALON_TAMBAHAN` disimpan pada setiap Saluran. Ini mengekalkan model operasi satu pasukan bagi setiap Saluran.
- Istilah `CALON_SIMPANAN` ditukar kepada `CALON_TAMBAHAN` melalui migrasi data agar rekod sedia ada kekal boleh digunakan.
- Penciptaan Pusat, Saluran dan kuota dilaksanakan dalam transaksi pangkalan data supaya konfigurasi tidak tertinggal separuh jika setup gagal.