alrahma_sunday_school/docs/enrollment_eligibility_plan.md

# Enrollment Eligibility and Admin Exception Plan

## 1. Goal

Tighten re-enrollment eligibility for existing Al Rahma Sunday School students without changing the separate new-student registration flow. Parents should only be able to submit re-enrollment for students already linked to their account and already transitioned or eligible for transition into the selected school year.

This plan matches the current project enrollment architecture:

- CodeIgniter 4 controllers and views under `app/Controllers/View` and `app/Views`.
- School years are referenced by `school_years.name` strings such as `2026-2027`, not by target-year IDs.
- Parent re-enrollment currently uses `/parent/enroll_classes_handler` and `app/Views/parent/enroll_classes.php`.
- New-student registration remains `/parent/register_student` and is out of scope except that re-enrollment must not create new students.
- Eligibility and placement already live mainly in `App\Services\EnrollmentTransitionService`, `App\Support\Enrollment\DeliberationDecision`, and `App\Support\Enrollment\EnrollmentEligibility`.
- Existing operational tables include `enrollments`, `student_class`, `student_decisions`, `school_years`, `enrollment_flags`, `enrollment_age_rules`, `enrollment_transition_audits`, and `invoices`.

## 2. Existing Rules To Preserve

Do not replace the current transition model with a parallel eligibility service. Extend the existing service and return shape.

Current enrollment decisions are based on `student_decisions.decision` or `student_decisions.deliberation_decision_standard`, normalized by `DeliberationDecision`:

| Decision | Current behavior |
|---|---|
| `PASSED` | Parent re-enrollment is allowed when the student can be placed in the next grade. If no next grade exists, the student is blocked with an exit/completion flag. |
| `REPEAT_CLASS` | Parent re-enrollment is allowed into the same class when available; otherwise administration must assign the class. |
| `MAKE_UP_EXAM` | Parent re-enrollment is allowed, but placement is temporary in the same grade until the make-up exam result is resolved. |
| `EXPELLED` | Parent re-enrollment is blocked and administrative review is flagged. |
| `WITHDRAWN` | Parent re-enrollment is blocked and withdrawal review is flagged. Decision values containing the correct spelling `withdraw` are normalized to `WITHDRAWN`. |
| `DEFERRED_DECISION` or pending/missing decision | Parent re-enrollment is blocked until administration records or reviews the decision. |

Also preserve these existing controls:

- Registration window checks from `school_years.registration_opens_at` / `registration_starts_on` and `registration_deadline_at` / `registration_ends_on`.
- Late-registration behavior from `school_years.late_registration_blocked`.
- Adult-student blocking for parent-submitted registration when the student is 18 or older on September 1 of the target school year.
- Age-rule checks from `enrollment_age_rules`.
- Placement statuses such as `automatic_distribution_pending`, `same_class_assigned`, `temporary_same_grade`, `manual_class_required`, `temporary_manual_class_required`, and `exit_required`.
- Follow-up flags in `enrollment_flags`.
- Audit history in `enrollment_transition_audits`.

## 3. New Eligibility Requirements

Add these policy checks to the existing transition evaluation and parent submission path.

### 3.1 Non-overridable checks

These must pass for every parent-submitted enrollment, including an administrative exception:

1. Parent session is authenticated and belongs to an active primary parent account.
2. Student row exists in `students`.
3. Student is linked to the parent through the current project link model. Today the direct link is `students.parent_id`; if `family_students` / `family_guardians` are adopted for this flow, centralize that lookup and use it everywhere.
4. Target school year name exists in `school_years.name`.
5. Source school year can be resolved by the existing previous-year helpers.
6. Student belongs to the source year through `student_class`, `enrollments`, or `student_decisions`.
7. Student does not already have an active target-year enrollment that should block duplicate submission.
8. Parent request values are reloaded from the database. Browser-provided decision, eligibility, class, or exception values are ignored.
9. Parent re-enrollment never creates, attaches, or relinks a student. Keep that work in the existing parent/admin student-management flow.

### 3.2 Standard eligibility checks

After the non-overridable checks pass, standard parent eligibility is:

```text
academic_ok =
  deliberation_decision in (PASSED, REPEAT_CLASS, MAKE_UP_EXAM)
  AND placement_status is not exit_required

status_ok =
  deliberation_decision not in (EXPELLED, WITHDRAWN, DEFERRED_DECISION)
  AND latest relevant enrollment status is not denied or withdrawn

window_ok =
  registration window is open for parent submissions

age_ok =
  student is not an adult student for parent-submitted enrollment
  AND configured blocking age rules pass

family_name_ok =
  all active linked siblings for the parent have the same normalized last name

financial_ok =
  previous-year balance policy does not block submission

standard_parent_enrollment_allowed =
  academic_ok AND status_ok AND window_ok AND age_ok AND family_name_ok AND financial_ok
```

Missing or unrecognized academic data should remain blocking/review-required as the current service does today. Make-up exam is not a blocker; it is eligible with a warning and a `PENDING_MAKE_UP_EXAM_PROMOTION` follow-up.

## 4. Sibling Last-Name Rule

Implement sibling last-name matching as a family-level rule in the existing enrollment evaluation.

Required behavior:

- Evaluate all active students linked to the parent for the target re-enrollment flow.
- A parent with one linked student passes this rule.
- If every linked student has the same normalized last name, set the rule result to pass for every student.
- If any linked student has a different, missing, or unusable last name, block every linked student for that parent with the same machine-readable reason.
- Normalize by trimming, collapsing spaces, comparing case-insensitively, and ignoring common punctuation variants. Preserve original names for display and audit.
- Do not hide this rule in SQL-only filtering. Return it as a visible reason code such as `SIBLING_LAST_NAME_MISMATCH`.

This rule should be overrideable by administration, but only after the linked-student relationship is already valid.

## 5. Financial Rule

Use the existing invoice source, not a new finance ledger abstraction unless finance is refactored separately.

Current project behavior:

- `ParentController::familyFinancialSummary()` computes carry-over balance with `invoices.balance` for the previous school year.
- Blocking behavior is configured by `school_years.carry_over_balance_behavior`.
- Existing supported policy values include `information_only`, `payment_plan_required`, `submission_allowed_confirmation_blocked`, `submission_blocked_until_payment`, and `admin_approval_required`.

Required behavior:

- Recalculate the parent balance from `invoices` when the enrollment page is shown and again inside the submit handler.
- Treat a previous-year balance as blocking only when `carry_over_balance_behavior` is `submission_blocked_until_payment` or `admin_approval_required`.
- Keep `payment_plan_required` and `submission_allowed_confirmation_blocked` non-blocking for submission unless school policy changes those meanings.
- Record the balance, source school year, target school year, and policy behavior in the eligibility/audit snapshot.

## 6. Decision Output

Extend the current `EnrollmentTransitionService::evaluate()` response instead of introducing a separate response contract.

Add stable fields like:

```php
[
    'decision' => 'ELIGIBLE',
    'parent_enrollment_allowed' => true,
    'rule_codes' => [],
    'blocking_rule_codes' => [],
    'warning_rule_codes' => [],
    'review_rule_codes' => [],
    'admin_exception' => null,
    'financial_summary' => [],
]
```

Recommended decision values:

| Decision | Meaning |
|---|---|
| `ELIGIBLE` | Parent may submit re-enrollment. |
| `ELIGIBLE_WITH_WARNING` | Parent may submit, but the student needs a follow-up such as make-up exam promotion or manual placement. |
| `INELIGIBLE` | Confirmed blocker exists. |
| `REVIEW_REQUIRED` | Staff must correct or verify data. |
| `EXCEPTION_ELIGIBLE` | Standard rules fail, but a valid admin exception permits submission. |
| `ALREADY_ENROLLED` | Existing target-year enrollment blocks duplicate submission. |

Suggested rule codes:

- `PASSED`, `REPEAT_CLASS`, `MAKE_UP_EXAM`
- `NO_FINAL_DECISION`, `UNRECOGNIZED_DECISION`
- `EXPELLED`, `WITHDRAWN`, `DEFERRED_DECISION`
- `EXIT_REQUIRED`
- `REGISTRATION_NOT_OPEN`, `REGISTRATION_CLOSED`
- `ADULT_STUDENT_PARENT_BLOCKED`
- `AGE_RULE_BLOCKED`
- `SIBLING_LAST_NAME_MISMATCH`
- `OUTSTANDING_BALANCE_BLOCKED`, `FINANCE_APPROVAL_REQUIRED`
- `STUDENT_NOT_LINKED`, `SOURCE_YEAR_NOT_FOUND`, `TARGET_YEAR_NOT_FOUND`
- `ALREADY_ENROLLED`

Keep human-readable parent messages in `EnrollmentEligibility` or a nearby presenter helper so controllers and views do not hard-code policy text.

## 7. Admin Exception Design

Use the project's existing terminology: an exception is an administrative allowance for a specific enrollment case. Avoid a broad `parent.can_enroll = true` flag.

### 7.1 Table

Add an `enrollment_exceptions` table or explicitly rename the concept if the team prefers `enrollment_overrides`. The table should fit current school-year string usage:

| Field | Purpose |
|---|---|
| `id` | Primary key |
| `parent_id` | Parent receiving the exception |
| `student_id` | Existing linked student covered by the exception |
| `school_year` | Target year name |
| `source_school_year` | Source year name |
| `status` | `active`, `used`, `revoked`, or `expired` |
| `reason_code` | Structured exception category |
| `reason_note` | Required admin explanation |
| `bypassed_rule_codes_json` | Snapshot of standard rules bypassed |
| `created_by` | Admin user ID |
| `approved_by` | Optional second approver |
| `starts_at` / `expires_at` | Bounded validity period |
| `used_at` / `enrollment_id` | Consumption tracking |
| `revoked_at` / `revoked_by` / `revocation_reason` | Revocation tracking |
| `created_at` / `updated_at` | Record history |

Add an index or unique constraint that prevents more than one active exception for the same `parent_id`, `student_id`, and `school_year`.

### 7.2 What an exception may bypass

An exception may bypass only standard eligibility rules:

- `NO_FINAL_DECISION` or `UNRECOGNIZED_DECISION`
- `EXPELLED`, `WITHDRAWN`, or `DEFERRED_DECISION`, if school policy permits the selected reason code
- `AGE_RULE_BLOCKED`, when the configured age rule permits exceptions
- `SIBLING_LAST_NAME_MISMATCH`
- `OUTSTANDING_BALANCE_BLOCKED` or `FINANCE_APPROVAL_REQUIRED`
- Late registration closure, only if `school_years.administrative_exceptions_permitted` allows it
- Manual placement or capacity exception follow-ups

An exception must not bypass identity, parent-student linkage, target-year existence, source-year existence, duplicate enrollment protection, CSRF/server validation, or the rule that parent re-enrollment cannot create new students.

### 7.3 Permissions and UI

Use a narrow permission, for example `enrollment.exception.manage`, and add it through the existing roles/permissions system. Do not give it to every admin role by default.

Admin UI should be added to the existing Enrollment Administration dashboard or parent/family card flow:

1. Choose school year.
2. Choose parent.
3. View linked students and live evaluation results.
4. Select one or more students.
5. Review failed rule codes and messages.
6. Enter reason code, note, and expiry.
7. Require second approval for high-risk cases if policy requires it.
8. Save, revoke, and view history.

Do not add exception controls to the parent UI. Parents should only see that enrollment is allowed, blocked, under review, or requires contacting administration.

## 8. Backend Integration Points

Implement later work in these places:

- `App\Services\EnrollmentTransitionService`
  - Add family-level linked-student evaluation.
  - Add sibling last-name rule.
  - Add financial blocking rule or accept a finance collaborator if the team wants to keep the service narrower.
  - Add exception lookup/application.
  - Return stable rule codes.
- `App\Support\Enrollment\EnrollmentEligibility`
  - Keep parent-safe message generation here or split into a small presenter class.
- `App\Controllers\View\ParentController`
  - Keep `/parent/register_student` as new-student registration.
  - In the re-enrollment page and `/parent/enroll_classes_handler`, re-evaluate from database state before accepting submitted student IDs.
  - Ignore disabled checkbox assumptions from the browser.
- `App\Controllers\View\EnrollmentAdminController`
  - Add exception preview/create/revoke/history beside existing flags, follow-ups, audits, launch approval, and email preview.
- `App\Controllers\View\AdministratorController`
  - Keep Enrollment/Withdrawal status management, but do not let status changes serve as an unaudited substitute for exceptions.
- Migrations/models
  - Add an exception table/model.
  - Add any missing unique/index protection for target-year duplicate enrollments where feasible with the current schema.
  - Keep audit writes compatible with `enrollment_transition_audits`.

## 9. Submission Safety

Inside the parent re-enrollment submit handler:

1. Start a database transaction.
2. Resolve parent ID from session.
3. Resolve selected target school year and source school year.
4. Load submitted student IDs, then reload each student from the database.
5. Verify parent-student linkage.
6. Re-run `EnrollmentTransitionService::evaluate()` for each submitted student.
7. Recalculate financial blockers for the parent.
8. Validate any active exception by `parent_id`, `student_id`, and `school_year`.
9. Reject students whose final decision is not eligible or exception-eligible.
10. Create or update the target-year `enrollments` row with the current eligibility snapshot.
11. Mark one-use exceptions as used.
12. Write `enrollment_transition_audits` entries for accepted, rejected, and exception-applied outcomes.
13. Commit.

Add database protection against duplicate target-year enrollments. If historical duplicates prevent a strict unique index immediately, first add a cleanup/reporting step and then add the constraint.

## 10. Parent Experience

In `app/Views/parent/enroll_classes.php`, show existing linked students only.

Recommended states:

| State | Meaning |
|---|---|
| Enroll | Eligible or exception-eligible. |
| Eligible with follow-up | Eligible, but requires make-up exam, manual placement, capacity review, or similar flag. |
| Already submitted | Existing target-year enrollment is in review, payment pending, enrolled, waitlist, or another non-duplicate state. |
| Action needed | Financial or data correction is required. |
| Under review | Staff must resolve academic/status/placement data. |
| Contact administration | Parent cannot resolve the blocker in self-service. |

Do not expose internal exception notes or sensitive finance details. Do not show internal labels such as expelled unless school policy explicitly approves the wording; use parent-safe messages already present in `EnrollmentEligibility`.

## 11. Audit and Reporting

Continue using `enrollment_transition_audits` for enrollment decisions. Extend the payloads rather than creating a disconnected audit stream.

Audit records should include:

- actor user ID
- parent ID when available
- student ID
- source and target school-year names
- decision and rule-code snapshot
- financial snapshot used for the decision
- exception ID when applied
- original and new enrollment values
- request timestamp

Reports needed:

- active exceptions by school year
- expiring unused exceptions
- enrollments submitted through exception
- blockers by rule code
- repeated parent submission failures
- financial blockers pending finance/admin approval

## 12. Test Matrix

Add focused tests around the current classes and controller submission behavior:

| Case | Expected result |
|---|---|
| `PASSED` with clean status and placement | Eligible |
| `REPEAT_CLASS` with same target section | Eligible, same class assigned |
| `REPEAT_CLASS` without target section | Eligible with manual-class follow-up |
| `MAKE_UP_EXAM` | Eligible with warning and make-up follow-up |
| `EXPELLED` | Blocked/review-required |
| `WITHDRAWN`, including historical misspellings | Blocked/review-required |
| `DEFERRED_DECISION` | Blocked/review-required |
| Pending or missing final decision | Blocked/review-required |
| Passed highest grade with no next class | Blocked with exit/completion follow-up |
| Registration not open | Blocked for parent |
| Registration closed and late blocking enabled | Blocked for parent |
| Adult student on September 1 | Parent submission blocked |
| Blocking age rule | Blocked unless valid exception applies |
| One linked sibling last name differs | Every linked sibling blocked |
| Linked sibling has missing last name | Every linked sibling blocked |
| One linked student only | Last-name rule passes |
| Previous-year balance with information-only policy | Not blocked |
| Previous-year balance with submission-blocked policy | Blocked |
| Previous-year balance with admin-approval policy | Blocked unless valid exception applies |
| Submitted student does not belong to parent | Denied even with exception |
| Nonexistent student ID | Denied |
| Expired/revoked/wrong-year/wrong-student exception | Denied |
| Valid scoped exception | Exception eligible and audited |
| Browser tampers with disabled checkbox or decision fields | Server ignores browser state |
| Concurrent duplicate submissions | Only one target-year enrollment is accepted |

Keep existing unit tests for `DeliberationDecision` and `EnrollmentEligibility`, and add service-level tests for `EnrollmentTransitionService` with mocked builders where practical. Add integration tests for the submit path if the test database can reliably seed `students`, `student_class`, `student_decisions`, `school_years`, `enrollments`, `invoices`, and exception rows.

## 13. Rollout Plan

1. Confirm policy decisions: sibling rule, financial behavior, exception authority, parent-facing messages, and high-risk approvals.
2. Inventory data quality: duplicate target-year enrollments, missing decisions, misspelled withdrawal values, missing last names, missing parent links, and open invoice balances.
3. Add rule-code output to `EnrollmentTransitionService` without enforcing new blockers yet.
4. Add read-only reporting for who would be blocked by sibling/finance rules.
5. Add exception schema, model, permissions, audit payloads, and admin UI.
6. Enforce server-side parent submission checks behind a feature flag or school-year setting.
7. Monitor blockers, exceptions, failed submissions, duplicate attempts, and finance approval volume during the first enrollment window.
8. Remove any old duplicated eligibility checks only after the central evaluation is stable.

## 14. Decisions Required Before Coding

These are policy decisions and should not be guessed in code:

1. Does the sibling last-name rule apply to every `students.parent_id` match, or only active/current linked students after `family_students` is fully adopted?
2. What exact statuses count as active linked students for the sibling rule?
3. Which parent-facing message is approved for sibling mismatch?
4. Which financial behavior values should block submission versus only block confirmation?
5. What balance tolerance, if any, is allowed?
6. Can finance/admin approve a balance exception, and does it need second approval above a threshold?
7. Can expulsion, withdrawal, deferred decision, or adult-student rules be overridden, and by whom?
8. How long can an exception remain active, and is it single-use?
9. Should duplicate enrollment protection block every existing target-year row, or only statuses such as `admission under review`, `review & decision`, `payment pending`, `enrolled`, and `waitlist`?

## 15. Definition of Done

- Parent re-enrollment uses one authoritative server-side evaluation path.
- Parent submission can enroll only existing linked students.
- New-student registration remains separate and unaffected.
- Academic, placement, registration-window, adult-student, age-rule, sibling-name, financial, and exception checks are all represented as stable rule codes.
- Make-up exam remains eligible with a temporary placement follow-up.
- Sibling last-name mismatch blocks every linked student unless a valid scoped exception applies.
- Financial blocking follows `school_years.carry_over_balance_behavior` and current invoice balances.
- Administrative exceptions are scoped by parent, student, and school-year name.
- Exceptions cannot bypass identity, linkage, school-year validity, source-year validity, or duplicate protection.
- Every accepted, blocked, and exception-applied submission is auditable.
- Duplicate target-year submissions are prevented.
- The test matrix above passes.