### Diploma Admissions

Package `soq-sg-diploma-admissions` - permissions 90140-90149 - implementation guide: [Diploma Admissions Module Guide](../engineering/modules/diploma-admissions/MODULE.md)

#### What this module does

Diploma Admissions manages the PEI admissions workflow before a learner is enrolled into a diploma programme: public application, staff screening, document review, interview/review notes, offer issue, applicant accept/decline, deposit/payment and enrolment. It is not a visa or accreditation decision system.

#### UI map: where to click

| UI area | Path | What operators do | Key buttons / controls |
|---|---|---|---|
| Applications list | `/admin/diploma-admissions/applications` | Search/filter applications and open details. | Filters, **Export**, application link |
| Board | `/admin/diploma-admissions/applications/board` | See pipeline by status. | Status columns, application cards |
| Funnel | `/admin/diploma-admissions/applications/funnel` | Review conversion counts. | **Export funnel** |
| Application detail | `/admin/diploma-admissions/applications/{id}` | Screen documents, assign owner, add notes/reviews/interviews, issue offers, enrol. | **Assign**, **Add note**, **Review document**, **Issue offer**, **Revoke offer**, **Manual enrol**, **Delete** |
| Programmes | `/admin/diploma-admissions/programmes` | Define diploma programme linked to course. | **New programme**, **Edit**, **Delete** |
| Intakes | `/admin/diploma-admissions/intakes` | Define open admission windows and capacity. | **New intake**, **Edit**, **Delete** |
| Settings | `/admin/diploma-admissions/settings` | Offer expiry, notifications, exemption caps and staff IDs. | **Save settings** |
| Exemption rules | `/admin/diploma-admissions/exemption-rules` | Manage module exemption rules. | **New rule**, **Edit**, **Delete** |
| Applicant panel | `/panel/diploma-applications` | Applicant checks status, uploads/responds, accepts or declines offer. | **Accept offer**, **Decline offer**, exemption request |

#### Permissions

| Permission | Purpose |
|---|---|
| `admin_sg_diploma_admissions` | Parent module access |
| `admin_sg_diploma_admissions_list` | Applications list, board and funnel |
| `admin_sg_diploma_admissions_view` | Application details and document downloads |
| `admin_sg_diploma_admissions_screen` | Transition/screen applications and review documents |
| `admin_sg_diploma_admissions_decide` | Approve / reject / waitlist decisions |
| `admin_sg_diploma_admissions_offer` | Issue and revoke offers |
| `admin_sg_diploma_admissions_enrol` | Record payment and enrol |
| `admin_sg_diploma_admissions_export` | Export applications and funnel data |
| `admin_sg_diploma_admissions_delete` | Delete applications |
| `admin_sg_diploma_admissions_settings` | Programmes, intakes and settings |
| `admin_sg_module_exemption_*` | Exemption rule/request/approval actions |

Run `php artisan soq:seed-diploma-admissions` to install sections, settings and notification templates.

#### Maker-Checker Approval Protocol (Sprint 4 Governance)

To comply with Singapore PEI governance and regulatory standards, admission decision-making enforces a strict **Maker-Checker** (Two-Person Rule):
1. **The Maker (Admissions Screener Officer - Staff):**
   - Conducts preliminary screening: reviews applicant qualification transcripts, validates identification documents (NRIC/FIN), and verifies prerequisite compliance.
   - Logs screening notes and submits an academic recommendation (`approve` / `reject`).
   - **Self-Approval Block:** The screener officer is strictly prevented by system policy from executing the final admission approval. Any attempt to self-approve triggers an immediate `403 Forbidden` (*"Maker-Checker violation: Screener officer cannot approve their own application"*).
2. **The Checker (Admissions Manager / Approver Officer):**
   - Independent manager-level officer who reviews the application file, screener findings, and recommendation.
   - Authorizes the official admission decision, transitioning the application to `approved_firm` or executing a rejection/waitlist action.
3. **Auditor Read-Only Mode (`staff_principal`):**
   - Compliance Auditors and external review bodies have complete read-only visibility into admission records, screening reviews, assessment trails, and document uploads.
   - All mutating and destructive actions (e.g. deleting applications, altering statuses, modifying applicant credentials) return `403 Forbidden` to ensure audit trail immutability.

#### Core statuses and operator meaning

| Stage | Meaning | Operator action |
|---|---|---|
| Submitted | Applicant sent application. | Check documents and assign owner. |
| Screening | Staff (Maker) is reviewing eligibility/documents. | Review documents, add note/review, make recommendation. |
| Approved Firm | Manager (Checker) approves application. | Independent verification completed; proceed to offer issuance. |
| Interview / Review | Internal assessment stage. | Record interview/review result. |
| Offered | Offer issued and waiting for applicant. | Monitor expiry and applicant response. |
| Accepted | Applicant accepted offer. | Confirm payment/deposit and enrol when ready. |
| Declined / Withdrawn / Rejected | Application closed negatively. | Keep audit trail; do not enrol. |
| Enrolled | Learner converted/enrolled. | Handover to academic operations. |

Exact labels follow the status values in the application detail screen.

#### Field guide: programmes

| Field | What to enter | Impact |
|---|---|---|
| Programme title/code | Public/admin name and internal code. | Appears in application/intake selection. |
| Linked course | Diploma course learners will be enrolled into. | Required for checkout/enrolment and module exemptions. |
| Status | Active/inactive. | Inactive programmes are not offered to applicants. |
| Description/requirements | Admission criteria and notes. | Helps staff and applicants understand requirements. |

#### Field guide: intakes

| Field | What to enter | Impact |
|---|---|---|
| Programme | Programme this intake belongs to. | Applications are grouped by programme/intake. |
| Start/end dates | Course/admission timeline. | Used for display and offer context. |
| Application open/close window | Dates applicants can apply. | Closed intakes cannot accept public applications. |
| Capacity | Seat limit or unlimited. | Occupied count appears in intakes list. |
| Status | Open/closed/draft style status. | Controls availability. |

#### Field guide: settings

| Setting | What it controls |
|---|---|
| Offer expiry days | How long an offer remains valid. |
| Reminder staff IDs | Who receives staff notifications. |
| Exemption cap (%) | Max fee waiver percentage without special reason. |
| Applicant exemption requests | Whether applicant panel shows self-service exemption request form. |
| Notification templates | Seeded by command; must exist for staff/applicant messages. |

#### First-time setup

1. Run `php artisan migrate`.
2. Run `php artisan soq:seed-diploma-admissions`.
3. Confirm admin/staff roles have the permissions they need.
4. Create or choose the course that represents the diploma programme.
5. Open `/admin/diploma-admissions/programmes` and click **New programme**.
6. Open `/admin/diploma-admissions/intakes` and click **New intake** for the programme.
7. Open `/admin/diploma-admissions/settings` and save offer expiry, staff IDs and exemption settings.
8. If module exemptions are used, create rules in `/admin/diploma-admissions/exemption-rules`.
9. Submit a test application from the public/applicant flow.
10. Process the application through offer, acceptance and enrolment in UAT before using live applicants.

#### Application processing SOP

1. Open `/admin/diploma-admissions/applications` and filter for new/submitted applications.
2. Open the application detail page.
3. Click **Assign** to set an owner if needed.
4. Review applicant profile and documents.
5. For each document, use **Review document** to approve/reject or record status.
6. Add internal notes with **Add note** for audit context.
7. Add review/interview records if the applicant requires academic assessment.
8. Move the application through the next transition button shown by the detail page.
9. When ready, click **Issue offer** and choose offer details/type.
10. Applicant accepts or declines from panel. Staff can revoke offer if needed.
11. After acceptance and payment/deposit policy is satisfied, click **Manual enrol** if automatic enrolment has not already happened.

#### UAT script

| Step | Action | Expected result |
|---|---|---|
| 1 | Create programme and open intake. | Intake list shows 0 / capacity applications. |
| 2 | Submit public application with documents. | Application appears in list and board. |
| 3 | Assign staff and review documents. | Detail page records owner and document review status. |
| 4 | Add note, review and interview. | Timeline/audit sections show records. |
| 5 | Issue offer. | Offer appears, PDF link available, applicant sees offer in panel. |
| 6 | Applicant accepts offer. | Status moves to accepted; decline path also tested separately. |
| 7 | Apply exemption if relevant. | Payable amount reflects approved waiver. |
| 8 | Enrol applicant. | Student/course enrolment is created and status becomes enrolled. |
| 9 | Export applications/funnel. | CSV/Excel output matches filters. |
| 10 | Let offer expire through cron in a test case. | `soq:diploma-process-offers` closes/flags expired offers according to settings. |

#### Daily operations

- Use **Applications list** for exact filtering and **Board** for pipeline stand-up review.
- Check document review backlog daily while applications are open.
- Use notes for audit-relevant decisions, not chat messages outside SOQ.
- Use Funnel weekly to see drop-off from submitted -> offered -> accepted -> enrolled.
- Check offer expiry reminders if applicants report missing deadlines.

#### Troubleshooting

| Symptom | Check |
|---|---|
| Programme not visible to applicants | Programme inactive, no open intake, application window closed, or linked course missing. |
| Intake count wrong | Applications may be filtered by status; refresh after create/delete. |
| Staff cannot issue offer | Role needs decide permission and application must be in an offerable state. |
| Applicant cannot accept | Offer expired/revoked, applicant account mismatch, or already accepted/declined. |
| Manual enrol fails | Linked course, sale/payment/deposit conditions, or existing enrolment conflict. |
| Notifications not sent | Seed notification templates and check production mail settings. |
| Exemption waiver missing | Exemption not approved or cap/reason issue. |

#### Boundaries and policy notes

- Do not invent accreditation, ICA/visa, or regulatory approval outcomes.
- Deferment, intake transfer, student ID generation and full SLA/audit pack are not part of the current built scope unless separately implemented.
- Admissions decisions should keep audit notes in SOQ so staff can explain why offer/enrolment was approved or rejected.