# RBAC and Permission Matrix

## Roles

- Admin
- Admin Kewangan
- PPM
- KTM
- Pemohon

Permissions will be implemented with `spatie/laravel-permission`. Policies will still enforce record-level ownership, such as PPM only accessing assigned Pusat Mengundi and KTM only accessing own team.

## Permission Naming Pattern

Suggested naming:

```text
module.action
```

Examples:

- `admin.dashboard.view`
- `election.manage`
- `application.review`
- `assignment.manage`
- `finance.verify`
- `attendance.record`
- `export.generate`

## Matrix

| Capability | Admin | Admin Kewangan | PPM | KTM | Pemohon |
|---|---:|---:|---:|---:|---:|
| View own dashboard | Yes | Yes | Yes | Yes | Optional |
| Manage users | Yes | No | No | No | No |
| Manage roles and permissions | Yes | No | No | No | No |
| Manage election settings (toggle attendance, override registration) | Yes (UI) | No | No | No | No |
| Manage Bahagian Pilihanraya | Yes | No | No | No | No |
| Manage Daerah Mengundi | Yes | No | No | No | No |
| Manage Pusat Mengundi | Yes | No | No | No | No |
| Manage Saluran Mengundi | Yes | No | No | No | No |
| Manage Jawatan and quotas | Yes | No | No | No | No |
| Generate QR links | Yes | No | View own only | No | No |
| Submit public application | Manual only | No | No | No | Yes |
| View all applications | Yes | Finance data only | No | No | No |
| View own Pusat applications | Yes | No | Yes | No | No |
| View own KTM team KP applications | Yes | No | Yes if same Pusat | Yes | No |
| Create manual application | Yes | No | No after final rule; PPM reviews only | KP only | Public flow only |
| Create KP applicant | Yes | No | No | Yes, own team only | No |
| Approve/reject KTM application | Yes | No | Yes | No | No |
| Approve/reject KP application | Yes | No | Yes | Yes, own team only | No |
| Approve/reject KPDP application | Yes | No | Yes | No | No |
| Approve/reject PAPM application | Yes | No | Yes | No | No |
| Change applicant role before approval | Yes | No | Yes, own Pusat only | No | No |
| Assign PPM | Yes | No | No | No | No |
| Assign KTM to Saluran | Yes | No | Yes, own Pusat only | No | No |
| Assign KP/KPDP to KTM | Yes | No | Yes, own Pusat only | No | No |
| Assign self as KTM | Admin can assign if valid | No | No direct self-assignment | No | No |
| Manage Police escort | Yes | No | View own Pusat only | View own Saluran only | No |
| Manage KKM representative | Yes | No | View own Pusat only | No | No |
| Manage JKM representative | Yes | No | View own Pusat only | No | No |
| Manage wheelchair allocation | Yes | No | View or record if delegated later | No | No |
| Record wheelchair transaction | Yes | No | Optional only if delegated | No | No |
| Record attendance | Yes | No | Yes, own Pusat only | No | No |
| View attendance dashboard | Yes | No | Own Pusat only | Own Saluran/team only if needed | No |
| Verify bank account | View and override if needed | Yes | No | No | No |
| Change assignment or placement | Yes | No | Own Pusat only | No | No |
| Export full staff list | Yes | No | No | No | No |
| Export staff list by Pusat | Yes | No | Own Pusat only if enabled | No | No |
| Export missing document list | Yes | No | Own Pusat only if enabled | No | No |
| Export finance verification list | Yes | Yes | No | No | No |
| Export attendance list | Yes | No | Own Pusat only if enabled | No | No |
| View audit trail | Yes | Limited finance-related if needed | Own Pusat events if needed | Own actions if needed | No |
| Download ic_document | Yes (all) | No | Yes (own Pusat applications only) | No | No |
| Download bank_statement | Yes (all) | Yes (all) | Yes (own Pusat applications only) | No | No |

## Initial Permission List

Admin:

- `admin.dashboard.view`
- `users.manage`
- `roles.manage`
- `election.manage`
- `hierarchy.manage`
- `positions.manage`
- `quotas.manage`
- `qr.manage`
- `applications.view_all`
- `applications.create_manual`
- `applications.update`
- `applications.approve`
- `applications.reject`
- `assignments.manage_all`
- `representatives.manage`
- `wheelchairs.manage`
- `attendance.view_all`
- `attendance.record_all`
- `finance.view`
- `finance.verify`
- `exports.generate_all`
- `audit.view`
- `system_notes.create`

Admin Kewangan:

- `finance.dashboard.view`
- `finance.view`
- `finance.verify`
- `finance.export`
- `applications.view_finance_fields`

PPM:

- `ppm.dashboard.view`
- `applications.view_own_pusat`
- `applications.review_own_pusat`
- `applications.approve_own_pusat`
- `applications.reject_own_pusat`
- `applications.change_role_own_pusat`
- `assignments.manage_own_pusat`
- `representatives.view_own_pusat`
- `attendance.record_own_pusat`
- `attendance.view_own_pusat`
- `exports.generate_own_pusat`

KTM:

- `ktm.dashboard.view`
- `ktm.team.view`
- `ktm.kp.create`
- `ktm.kp.approve`
- `ktm.kp.delete_created`
- `applications.view_own_team`

Pemohon:

- `public_application.create`
- `public_application.view_own_status` if applicant portal is implemented later

## Record-Level Authorization Rules

### PPM Scope

- PPM can only view and manage applications where `applications.pusat_mengundi_id` is assigned to their active PPM staff assignment.
- PPM can only assign staff to Saluran under their assigned Pusat Mengundi.
- PPM can approve only applications with required IC and bank statement documents.
- Phase 5 implements this through `ApplicationPolicy` plus active PPM `staff_assignments` scope.
- PPM document download is limited to documents attached to applications inside their assigned Pusat Mengundi.
- Phase 10 allows PPM to record attendance only for active staff assignments under their own Pusat Mengundi and only when the attendance module is active.

### KTM Scope

- KTM can only view KP under their own KTM assignment.
- KTM can only register KP, not KTM, KPDP, PAPM, PPM, Police, KKM, or JKM.
- KTM can approve KP only where the KP belongs to their own team.
- KTM cannot assign himself/herself to Saluran.
- Phase 6 implements this through active KTM `staff_assignments` scope.
- KTM-created records are marked `source = created_by_ktm`.
- KTM can delete only their own unassigned `created_by_ktm` applicant records.

### Admin Kewangan Scope

- Admin Kewangan can view approved staff list and bank-related fields.
- Admin Kewangan can update `bank_verifications`.
- Admin Kewangan cannot update placement, position, Pusat Mengundi, or Saluran Mengundi.
- Phase 7 confirms Admin Kewangan is blocked from Admin management routes such as assignment edit/listing.
- Phase 8 implements `/kewangan/bank` for bank checking, status update, finance note, filters, and finance export.
- Admin can also access finance bank routes for oversight, but assignment changes remain outside the finance module.

### Admin Management Scope

- Admin can view global application and assignment lists.
- Admin can create manual application records.
- Admin can edit applicant/staff details and direct assignment records.
- Admin can key in Police, KKM, and JKM representatives.
- Admin can manage wheelchair allocation and taken/returned transactions.
- Admin can view attendance dashboard, attendance details by Pusat Mengundi, and generate attendance detail exports.
- If registration is closed for the election, Admin create/edit/assign/representative changes require `catatan`.
- Admin management changes write domain history/activity logs and `system_notes` for post-closing changes.

### Public Pemohon Scope

- Public users can access only QR application routes.
- Public application is allowed only during registration period.
- Public users cannot list other applicants or staff.