prn2026/docs/05-workflow-design.md

Workflow Design

Application Status Lifecycle

Final initial statuses:

draft
submitted
under_ppm_review
approved
rejected
assigned
cancelled
deleted_by_ktm

Application Status Meaning

Status	Meaning
draft	Created but not fully submitted. Used only if partial saves are implemented.
submitted	Applicant or actor submitted the application for review.
under_ppm_review	PPM has opened or started reviewing the application.
approved	Application approved for a position but not necessarily assigned to final Saluran/team.
rejected	Application rejected with reason.
assigned	Approved applicant has active staff assignment.
cancelled	Application cancelled by Admin or workflow rule.
deleted_by_ktm	KTM-created placeholder/application removed so applicant can self-register.

Public QR Application Flow

Phase 4 implementation behavior:

• /pohon/{pusat_mengundi_uuid} resolves by public UUID and shows the public application form when registration is open.
• If registration is closed, the same QR route shows a closed-registration page.
• Successful submissions redirect to /permohonan/{application_uuid}/berjaya.
• Uploaded IC documents and bank statements are stored on the private local disk under the application UUID path.
• Submitted applications immediately create application_documents, application_status_histories, and pending bank_verifications records.

1. Applicant scans QR code for a Pusat Mengundi.
2. System resolves /pohon/{pusat_mengundi_uuid}.
3. System checks election and registration period.
4. If registration is closed, show clear closed-registration message.
5. Applicant selects role: KTM, KP, KPDP, or PAPM.
6. If selected role is KP or KPDP, system shows approved KTM list for that Pusat Mengundi with available vacancy.
7. Applicant fills personal, contact, bank, and address details.
8. Applicant uploads IC document and bank statement.
9. System validates IC uniqueness for current election.
10. If an active KTM-created applicant exists for the same IC, system blocks self-registration and explains that KTM must delete the pre-created record first.
11. System stores documents privately.
12. Application status becomes submitted.
13. Bank verification starts as pending.
14. PPM reviews the application in Phase 5.

Registration Period Rules

During registration period:

• Public Pemohon can register through QR.
• KTM can register KP.
• PPM can review and assign.

After registration period:

• Public self-registration is closed.
• KTM cannot register new KP.
• PPM cannot register new applicants.
• Only Admin can register, edit, or assign staff.
• Admin changes after closing require catatan.
• System must show clear closed-registration messages.

Registration open calculation:

• registration_start_date <= today <= registration_end_date
• plus is_registration_open = true.
• if is_registration_open_override is not null, it explicitly opens or closes registration regardless of the normal date window.

Applicant Status Portal

Pemohon awam boleh semak status permohonan melalui /permohonan/{uuid}/status tanpa perlu log masuk.

• UUID awam permohonan digunakan sebagai pengecam — tiada login diperlukan.
• Pautan status dipaparkan pada halaman kejayaan permohonan dan boleh disalin.
• Maklumat yang dipaparkan: nama (disamarkan 3 aksara pertama), jawatan dipohon, pusat mengundi, status, sebab penolakan (jika ditolak), nombor rujukan UUID.
• Maklumat yang TIDAK dipaparkan: IC, akaun bank, nombor telefon, ID dalaman, saluran, nama KTM.
• UUID tidak dikenali → 200 dengan mesej generik ("status tidak dapat dipaparkan") — tidak mendedahkan sama ada UUID pernah wujud.
• Rekod deleted_by_ktm dan rekod soft-deleted juga mengembalikan mesej generik.

Status display mapping:

Status DB	Paparan
submitted	Menunggu Semakan
under_ppm_review	Sedang Disemak
approved	Diluluskan
assigned	Diluluskan & Ditempatkan
rejected	Ditolak (+ sebab penolakan)
cancelled	Dibatalkan

Admin Election Settings

Admin can manage the following settings per election via /admin/setup/settings/{election}:

• is_attendance_active — Toggle attendance recording on/off. Should only be activated on polling day. PPM cannot record attendance when this is false. Toggling is recorded in activity log with before/after values.
• is_registration_open_override — Three states: null (Auto — follows date window), true (Force Open — opens even outside date window), false (Force Closed — closes even inside date window). Use override only in exceptional circumstances. When override is active, a warning badge is shown on the settings page.

Changes to election settings require Admin role and are written to activity_log with log_name = 'admin_settings', recording who changed what and when.

Note: is_registration_open (the base toggle) is still set in the database during initial setup. The is_registration_open_override is the runtime control available via the Admin Settings UI.

KTM Vacancy Rule for Public KP/KPDP Selection

For public KP or KPDP applications:

• Candidate KTM options come from active staff_assignments with position KTM, same election, same Pusat Mengundi, and assigned Saluran Mengundi.
• Remaining vacancy is calculated from position_quotas for the KTM's Saluran Mengundi and requested role.
• Used vacancy counts active team assignments under that KTM plus reserved public applications in submitted, under_ppm_review, or approved status.
• If no vacancy remains, the KTM cannot be selected.

PPM Review Flow

Phase 5 implementation behavior:

• PPM application URLs use application public UUID.
• PPM list and detail views are scoped by active PPM staff_assignments.
• ApplicationPolicy blocks PPM access to applications outside assigned Pusat Mengundi.
• Approved applications are moved directly to assigned because Phase 5 approval also creates the active staff assignment.
• Private document download is available only through the authorized PPM review route.

1. PPM opens own dashboard.
2. System lists applications only for PPM's assigned Pusat Mengundi.
3. PPM reviews applicant detail and documents.
4. PPM may change applicant role before approval.
5. System records any role change in audit trail.
6. PPM approves only if IC document and bank statement exist.
7. If approved as KTM, PPM assigns KTM to a Saluran Mengundi.
8. If approved as KP or KPDP, PPM assigns applicant to an approved KTM under the same Pusat Mengundi.
9. If approved as PAPM, system assigns at Pusat Mengundi level.
10. System creates or updates staff_assignments.
11. System records assignment history and activity log.

KTM Flow

Phase 6 implementation behavior:

• KTM routes are under /ktm/applications.
• KTM scope is based on active staff_assignments with position KTM, status active, and a Saluran Mengundi.
• KTM can create only KP applicant records.
• KTM-created records are stored as source = created_by_ktm and status = submitted.
• Creating a KP applicant queues a Markdown email to the applicant.
• KTM approval creates an active KP staff_assignments row under the KTM assignment and changes application status to assigned.
• KTM can delete only unassigned records they created through the KTM flow, changing status to deleted_by_ktm before soft delete.

1. KTM logs in and opens own dashboard.
2. System identifies active KTM assignment and Saluran.
3. KTM views own KP list and remaining KP vacancy.
4. During registration period, KTM can register KP only.
5. KTM-created KP has source = created_by_ktm.
6. System sends email notification to applicant.
7. KTM can approve KP application only under own team while registration is open.
8. If applicant wants to self-register with the same IC, system blocks until KTM deletes the KTM-created record.
9. Deleting a KTM-created applicant changes status to deleted_by_ktm, records status history, and soft deletes the record.

Admin Manual Entry and Management Flow

Phase 7 implementation behavior:

• Admin management routes are under /admin/management.
• Admin can list all applications with filters for status, Pusat Mengundi, jawatan, and keyword.
• Admin can create manual application records with source = admin_manual.
• Manual Admin-created records create pending bank verification state but do not send KTM-created applicant email.
• Admin can edit application personal, role, bank, status, and placement-related fields.
• Admin can direct-assign an application to Pusat/Saluran/KTM team; this creates or updates staff_assignments, sets application status to assigned, and writes status/assignment history.
• Admin can edit existing staff_assignments; changes are mirrored back to the related application where applicable.
• Admin can key in and delete Police, KKM, and JKM representative records.
• If registration is closed, Admin changes require catatan; the system stores it in system_notes.

1. Admin opens global application/staff list.
2. Admin can create or edit application/staff records.
3. Admin can directly assign staff to Pusat Mengundi and Saluran Mengundi.
4. Admin can key in Police, KKM, and JKM records.
5. If registration period has ended, Admin must provide catatan for any register/edit/assign action.
6. System saves note in system_notes.
7. System records activity log and assignment/application history.

Admin Kewangan Flow

Phase 8 implementation behavior:

• Finance routes are under /kewangan/bank.
• Finance list shows applications in approved or assigned status.
• Filters support Pusat Mengundi, role, bank verification status, missing bank statement, missing bank account number, and keyword search.
• Admin Kewangan can update only bank_verifications.status and finance_note.
• Updating verification records sets verified_by_user_id and verified_at and writes activity log.
• Admin Kewangan cannot access Admin assignment management routes.
• Finance export creates an XLSX file in private storage using OpenSpout and inserts an export_logs row.

1. Admin Kewangan opens finance dashboard.
2. System lists approved staff and bank verification status.
3. Admin Kewangan filters by Pusat Mengundi, role, status, missing bank statement, or missing account number.
4. Admin Kewangan marks bank verification as pending, verified, rejected, or requires correction.
5. Admin Kewangan adds finance note.
6. System records bank verification activity log.
7. Admin Kewangan can export finance verification list.

Wheelchair Flow

Phase 9 implementation behavior:

• Wheelchair management routes are under /admin/management/wheelchairs.
• Admin can upsert one allocation record per election and Pusat Mengundi.
• Admin can record taken transactions with quantity, date/time, person taking, and notes.
• Admin can record returned transactions with quantity, date/time, return condition, and notes.
• System calculates total taken, total returned, outstanding quantity, and available quantity.
• Taken quantity is blocked when it exceeds available allocation.
• Returned quantity is blocked when it exceeds outstanding quantity.
• Allocation quantity is blocked when it is lower than outstanding quantity.
• Allocation changes and transactions are recorded in activity log.

1. Admin enters allocated wheelchair quantity per Pusat Mengundi.
2. Admin records taken quantity, date/time, and person taking.
3. Admin records returned quantity, date/time, condition, and notes.
4. System stores each movement in wheelchair_transactions.
5. System records activity log.

Attendance Flow

Phase 10 implementation behavior:

• PPM attendance routes are under /ppm/attendance.
• PPM can only access Pusat Mengundi assigned through active PPM staff_assignments.
• PPM can record attendance only when election_settings.is_attendance_active = true.
• Attendance is recorded per active staff_assignments row and uses statuses present, absent, or not_recorded.
• Present records store check-in time; absent and not-recorded records clear check-in time.
• Attendance updates write activity log with actor, staff assignment, status, and check-in time.
• Admin attendance routes are under /admin/attendance.
• Admin first view lists Pusat Mengundi with total staff, present, absent, and not recorded.
• Admin detail view shows staff name, role, Saluran, status, check-in time, notes, and recorded by.
• Admin detail export generates XLSX with OpenSpout and writes export_logs.

1. Attendance module becomes active based on election setting.
2. PPM opens attendance screen for own Pusat Mengundi.
3. System lists all assigned staff under that Pusat Mengundi.
4. PPM marks each staff as present or absent.
5. If present, check-in time is stored.
6. System stores recorded by and note.
7. Admin dashboard shows first-level list of Pusat Mengundi.
8. Admin clicks Pusat Mengundi to see staff-level attendance details.
9. Admin exports summary or detail attendance reports.

Attendance statuses:

present
absent
not_recorded

Bank Verification Status

pending
verified
rejected
requires_correction

Status meaning:

• pending: Not yet checked by finance.
• verified: Bank details accepted.
• rejected: Bank details are invalid or unusable.
• requires_correction: Applicant/staff record needs correction or additional document.

Audit Events

Must be audited:

• Application submission.
• Application approval/rejection.
• Role change.
• Assignment creation/change/cancellation.
• Document upload/change.
• Bank verification update.
• Admin edit after registration closes.
• Attendance update.
• Wheelchair transaction.
• Excel export.

Audit record should include:

• actor
• action
• subject
• previous value
• new value
• timestamp
• note/catatan if available