# Proposed Database Design

## Phase 2 Implementation Status

Status: Implemented on 2026-05-28.

Implemented in migration:

- `user_profiles`
- `elections`
- `election_settings`
- `bahagian_pilihanrayas`
- `daerah_mengundis`
- `pusat_mengundis`
- `saluran_mengundis`
- `positions`
- `position_quotas`
- `applications`
- `application_documents`
- `application_status_histories`
- `staff_assignments`
- `staff_assignment_histories`
- `police_escorts`
- `kkm_representatives`
- `jkm_representatives`
- `wheelchair_allocations`
- `wheelchair_transactions`
- `attendances`
- `bank_verifications`
- `export_logs`
- `system_notes`

Implemented models and relationships are available under `app/Models`.

Implementation notes:

- Public-facing identifiers use UUID columns.
- MySQL index names are explicitly shortened where Laravel's generated names would exceed MySQL's identifier limit.
- Complex business constraints such as "four KP per KTM" are intentionally enforced by future services rather than only by database constraints.
- A PPM plus KTM dual-role assignment is represented through two active rows in `staff_assignments`.

## Export Log Purge Columns (Fasa 15 — 2026-06-02)

Added via migration `2026_06_02_000001_add_purged_at_to_export_logs.php`.

| Column | Type | Purpose |
|---|---|---|
| `purged_at` | nullable timestamp | Set when the export file is deleted by `exports:purge` command |
| `purged_by_user_id` | nullable FK → users | Reserved for future manual purge UI attribution |

Records with `purged_at IS NOT NULL` are skipped on subsequent purge runs.

## Performance Indexes (Fasa 13 — 2026-06-02)

Added via migration `2026_06_02_000000_add_performance_indexes.php`.

### `applications` table

| Index name | Columns | Purpose |
|---|---|---|
| `app_election_status_idx` | `(election_id, status)` | Dashboard count queries and admin list filtered by election |
| `app_ktm_position_idx` | `(selected_ktm_assignment_id, requested_position_id)` | `KtmVacancyService` reserved-application count (called per KP/KPDP vacancy check) |

### `staff_assignments` table

| Index name | Columns | Purpose |
|---|---|---|
| `sa_reports_to_pos_status_idx` | `(reports_to_assignment_id, position_id, status)` | `KtmVacancyService` active-assignment count under a KTM (called per vacancy check) |

### Existing indexes (Phase 2)

| Table | Columns | Name |
|---|---|---|
| `applications` | `(election_id, ic_number)` | auto |
| `applications` | `(election_id, pusat_mengundi_id, status)` | auto |
| `staff_assignments` | `(election_id, pusat_mengundi_id, position_id)` | `sa_election_pusat_position_idx` |
| `staff_assignments` | `(election_id, saluran_mengundi_id, position_id)` | `sa_election_saluran_position_idx` |
| `attendances` | `(election_id, pusat_mengundi_id, status)` | `att_election_pusat_status_idx` |
| `attendances` | `(election_id, staff_assignment_id)` | `att_election_staff_unique` (unique) |

### Why `bank_verifications` was not indexed with `election_id`

`bank_verifications` does not have a direct `election_id` column — it joins through `application_id` (unique FK). All finance queries that need election filtering use `whereHas('application', ...)` subqueries. The existing `status` index and unique `application_id` index are sufficient for the current query patterns.

## Design Goals

- Support one election or multiple election events over time.
- Keep public identifiers separate from internal database IDs.
- Support dual-role assignment, especially PPM also acting as KTM.
- Keep sensitive documents private and access-controlled.
- Preserve auditability through history tables and activity log.
- Support exports, finance verification, attendance, wheelchair tracking, and post-closing notes.

## Naming Conventions

- Table names use Laravel plural snake_case where practical.
- Existing Malay domain terms are retained for clarity.
- Public UUID/ULID columns use names such as `public_uuid`.
- Status fields use lowercase snake_case values.
- Foreign keys use `foreignId()->constrained()` where possible.

## Core Identity Tables

### users

Laravel default user authentication table with additions as needed.

Key fields:

- `id`
- `name`
- `email`
- `password`
- `email_verified_at`
- `remember_token`
- timestamps
- soft deletes if operationally useful

Notes:

- Roles are assigned through `spatie/laravel-permission`.
- Not every public applicant must become a login user unless later required.

### user_profiles

Stores extended identity details for staff/admin users.

Key fields:

- `id`
- `user_id`
- `ic_number`
- `phone_number`
- `address`
- `bank_name`
- `bank_account_number`
- timestamps

Notes:

- Sensitive fields should be masked in views where full values are not required.
- IC uniqueness at profile level should be evaluated with election-specific application rules.

## Election and Settings

### elections

Represents each election event.

Key fields:

- `id`
- `public_uuid`
- `name`
- `code`
- `status`
- `starts_at`
- `polling_date`
- timestamps
- soft deletes

Suggested statuses:

- `draft`
- `active`
- `closed`
- `archived`

### election_settings

Stores event-specific operational settings.

Key fields:

- `id`
- `election_id`
- `registration_start_date`
- `registration_end_date`
- `polling_date`
- `is_registration_open`
- `is_registration_open_override` nullable
- `is_attendance_active`
- timestamps

Notes:

- Registration open state is computed from dates and `is_registration_open`.
- `is_registration_open_override` can be used later if the system needs to distinguish manual override from normal date-based availability.
- Attendance can be toggled separately for rehearsal or polling day.

## Election Hierarchy

### bahagian_pilihanrayas

Key fields:

- `id`
- `election_id`
- `code`
- `name`
- timestamps
- soft deletes

Relationships:

- belongs to election.
- has many daerah mengundi.

### daerah_mengundis

Key fields:

- `id`
- `election_id`
- `bahagian_pilihanraya_id`
- `code`
- `name`
- timestamps
- soft deletes

Relationships:

- belongs to election.
- belongs to bahagian pilihanraya.
- has many pusat mengundi.

### pusat_mengundis

Key fields:

- `id`
- `election_id`
- `daerah_mengundi_id`
- `public_uuid`
- `code`
- `name`
- `address`
- `registration_url`
- `qr_code_path`
- timestamps
- soft deletes

Relationships:

- belongs to election.
- belongs to daerah mengundi.
- has many saluran mengundi.
- has many position quotas.
- has many staff assignments.
- has one wheelchair allocation.

Notes:

- `public_uuid` is used by `/pohon/{pusat_mengundi_uuid}`.
- `registration_url` can be generated dynamically; storing it is optional. If stored, it must be refreshed if domain changes.

### saluran_mengundis

Key fields:

- `id`
- `election_id`
- `pusat_mengundi_id`
- `number`
- `name`
- `voter_count`
- timestamps
- soft deletes

Relationships:

- belongs to election.
- belongs to pusat mengundi.
- has many staff assignments.

## Roles and Permissions

Managed by `spatie/laravel-permission`:

- `roles`
- `permissions`
- `model_has_roles`
- `model_has_permissions`
- `role_has_permissions`

Application roles:

- Admin
- Admin Kewangan
- PPM
- KTM
- Pemohon

## Positions and Quotas

### positions

Stores operational staff positions.

Key fields:

- `id`
- `code`
- `name`
- `scope`
- `is_public_applyable`
- `is_assignable`
- `allows_dual_role`
- timestamps
- soft deletes

Suggested position codes:

- `PPM`
- `KTM`
- `KP`
- `KPDP`
- `PAPM`
- `POLIS`
- `KKM`
- `JKM`
- `CALON_SIMPANAN`

Suggested scopes:

- `pusat`
- `saluran`
- `external`

### position_quotas

Defines vacancy requirements by election, pusat, saluran, and role.

Key fields:

- `id`
- `election_id`
- `pusat_mengundi_id`
- `saluran_mengundi_id` nullable
- `position_id`
- `quota`
- timestamps
- soft deletes

Notes:

- PPM, PAPM, KKM, JKM, and wheelchair-related staffing are usually Pusat scope.
- KTM, KP, KPDP, Police escort, and calon simpanan are usually Saluran scope.
- Use nullable `saluran_mengundi_id` for Pusat-level quota.

## Applications

### applications

Represents public, KTM-created, or Admin-keyed applicant/staff application record.

Key fields:

- `id`
- `election_id`
- `pusat_mengundi_id`
- `selected_ktm_assignment_id` nullable
- `user_id` nullable
- `public_uuid`
- `source`
- `status`
- `name`
- `ic_number`
- `phone_number`
- `email`
- `address`
- `requested_position_id`
- `approved_position_id` nullable
- `bank_name`
- `bank_account_number`
- `created_by_user_id` nullable
- `approved_by_user_id` nullable
- `approved_at` nullable
- `rejected_by_user_id` nullable
- `rejected_at` nullable
- `rejection_reason` nullable
- timestamps
- soft deletes

Suggested source values:

- `public`
- `created_by_ktm`
- `admin_manual`

Suggested status values are documented in `docs/05-workflow-design.md`.

Rules:

- IC uniqueness is enforced per election among active/non-cancelled records.
- Public self-registration is blocked if an active `created_by_ktm` record exists for the same election and IC.
- Admin may manually enter records after registration closes with required note.
- Phase 4 public submissions create `source = public`, `status = submitted`, and a public UUID reference.
- For KP and KPDP public applications, `selected_ktm_assignment_id` stores the selected active KTM assignment if vacancy remains.

### application_documents

Stores private uploaded documents.

Key fields:

- `id`
- `application_id`
- `document_type`
- `disk`
- `path`
- `original_name`
- `mime_type`
- `size`
- `uploaded_by_user_id` nullable
- timestamps
- soft deletes

Document types:

- `ic_document`
- `bank_statement`
- `other`

Rules:

- IC and bank statement documents are required before PPM approval.
- Documents are stored on private disk.
- Phase 4 public uploads store `ic_document` and `bank_statement` under private local storage using the application public UUID path.

### application_status_histories

Tracks application lifecycle status changes.

Key fields:

- `id`
- `application_id`
- `from_status` nullable
- `to_status`
- `changed_by_user_id` nullable
- `note` nullable
- `metadata` JSON nullable
- timestamps

## Staff Assignments

### staff_assignments

Canonical table for approved staff placement.

Key fields:

- `id`
- `election_id`
- `application_id` nullable
- `user_id` nullable
- `position_id`
- `pusat_mengundi_id`
- `saluran_mengundi_id` nullable
- `reports_to_assignment_id` nullable
- `status`
- `assigned_by_user_id`
- `assigned_at`
- `source`
- timestamps
- soft deletes

Suggested statuses:

- `active`
- `pending`
- `cancelled`
- `replaced`

Notes:

- Allows one person to hold multiple assignments, including PPM and KTM.
- `reports_to_assignment_id` can link KP/KPDP to the approved KTM assignment.
- A KTM assignment to Saluran is created by PPM or Admin, not chosen by KTM.
- Unique constraints should prevent duplicate active position assignment to the same role/scope where business rules require.

### staff_assignment_histories

Tracks assignment changes.

Key fields:

- `id`
- `staff_assignment_id`
- `from_position_id` nullable
- `to_position_id` nullable
- `from_pusat_mengundi_id` nullable
- `to_pusat_mengundi_id` nullable
- `from_saluran_mengundi_id` nullable
- `to_saluran_mengundi_id` nullable
- `from_reports_to_assignment_id` nullable
- `to_reports_to_assignment_id` nullable
- `changed_by_user_id`
- `note` nullable
- timestamps

## Representatives and External Operational Data

### police_escorts

Key fields:

- `id`
- `election_id`
- `pusat_mengundi_id`
- `saluran_mengundi_id` nullable
- `name`
- `ic_number` nullable
- `phone_number` nullable
- `rank` nullable
- `station` nullable
- `notes` nullable
- timestamps
- soft deletes

### kkm_representatives

Key fields:

- `id`
- `election_id`
- `pusat_mengundi_id`
- `name`
- `ic_number` nullable
- `phone_number` nullable
- `agency` nullable
- `notes` nullable
- timestamps
- soft deletes

### jkm_representatives

Key fields:

- `id`
- `election_id`
- `pusat_mengundi_id`
- `name`
- `ic_number` nullable
- `phone_number` nullable
- `agency` nullable
- `notes` nullable
- timestamps
- soft deletes

## Wheelchair Management

### wheelchair_allocations

Key fields:

- `id`
- `election_id`
- `pusat_mengundi_id`
- `allocated_quantity`
- `notes` nullable
- timestamps

### wheelchair_transactions

Key fields:

- `id`
- `wheelchair_allocation_id`
- `transaction_type`
- `quantity`
- `taken_at` nullable
- `taken_by_name` nullable
- `returned_at` nullable
- `return_condition` nullable
- `recorded_by_user_id`
- `notes` nullable
- timestamps

Suggested transaction types:

- `taken`
- `returned`
- `adjustment`

Return condition values:

- `baik`
- `rosak`

## Attendance

### attendances

Key fields:

- `id`
- `election_id`
- `staff_assignment_id`
- `pusat_mengundi_id`
- `saluran_mengundi_id` nullable
- `position_id`
- `status`
- `check_in_time` nullable
- `recorded_by_user_id`
- `note` nullable
- timestamps

Attendance statuses:

- `present`
- `absent`
- `not_recorded`

Notes:

- Store denormalized pusat/saluran/position references for simpler reporting.
- A unique key should prevent multiple active attendance rows for the same election and staff assignment.

## Finance

### bank_verifications

Key fields:

- `id`
- `application_id`
- `status`
- `verified_by_user_id` nullable
- `verified_at` nullable
- `finance_note` nullable
- timestamps

Statuses:

- `pending`
- `verified`
- `rejected`
- `requires_correction`

Notes:

- Admin Kewangan can update this table only.
- Assignment and placement edits are outside Admin Kewangan scope.
- Phase 4 public submissions create an initial `pending` bank verification row.

## Exports and Notes

### export_logs

Key fields:

- `id`
- `election_id` nullable
- `generated_by_user_id`
- `generated_at`
- `report_type`
- `filter_parameters` JSON nullable
- `file_name`
- `disk` nullable
- `path` nullable
- timestamps

Report types:

- `full_staff_list`
- `staff_list_by_pusat`
- `staff_list_by_role`
- `missing_document_list`
- `finance_verification_list`
- `attendance_summary`
- `attendance_detail_by_pusat`

### system_notes

Stores structured operational notes, especially post-registration changes.

Key fields:

- `id`
- `election_id`
- `noteable_type`
- `noteable_id`
- `note_type`
- `note`
- `created_by_user_id`
- timestamps

Suggested note types:

- `post_registration_change`
- `admin_correction`
- `finance_note`
- `general`

## Audit Log

### activity_log

Managed by `spatie/laravel-activitylog`.

Required logged details:

- actor
- subject
- event name
- previous values
- new values
- timestamp
- note or reason where available

## Key Constraints and Indexes

Planned indexes:

- `elections.public_uuid`
- `pusat_mengundis.public_uuid`
- `applications.public_uuid`
- `applications.election_id, ic_number`
- `applications.election_id, pusat_mengundi_id, status`
- `staff_assignments.election_id, pusat_mengundi_id, position_id`
- `staff_assignments.election_id, saluran_mengundi_id, position_id`
- `bank_verifications.status`
- `attendances.election_id, pusat_mengundi_id, status`
- `export_logs.generated_by_user_id, generated_at`

Planned uniqueness:

- Unique active public UUIDs.
- One active PPM per Pusat Mengundi.
- One active KTM per Saluran Mengundi.
- One active KPDP per KTM or Saluran based on final rule implementation.
- Four active KP per KTM/team enforced by quota service, not only DB constraint.
- Application IC uniqueness per election for active public/admin records, with special handling for deleted/cancelled KTM-created records.

## Documented Trade-Offs

- `staff_assignments` is used instead of a single role column because the system must support dual-role assignment.
- Domain-specific history tables are retained in addition to generic activity log because workflows need reportable status/assignment timelines.
- Representative tables are separate from applications because Police, KKM, and JKM records may not follow the public applicant workflow.
- Attendance denormalizes role and location references to make election-day reporting faster and more stable.
## Kemas kini operasi Pusat Mengundi - 2026-05-31

- `saluran_mengundis.name` dikekalkan sebagai nullable untuk keserasian rekod lama, tetapi tidak lagi diminta pada UI.
- Semasa Pusat Mengundi baharu didaftarkan, Saluran bernombor `1..N` dijana secara automatik.
- `position_quotas` menyimpan `PPM`, `PAPM`, `JKM` dan `KKM` pada skop Pusat serta `KTM`, `POLIS`, `KP`, `KPDP` dan `CALON_TAMBAHAN` pada skop Saluran.
- Kod jawatan `CALON_SIMPANAN` dimigrasikan kepada `CALON_TAMBAHAN`.