# Enrollment Collection V1 — HR Dashboard API

**Created:** 2026-06-03  
**Controller:** `App\Controllers\EnrollmentCollectionV1DashboardController`  
**Model:** `App\Models\EnrollmentCollectionV1DashboardModel`  
**Source queries:** `metabase_raw_queries.csv` → collection `Enrollment Collection V1`  
**Base app URL (local):** `https://localhost/PHP828APPS/ruc/nhance/index.php`  
**Total KPIs:** 10

---

## Overview

All Enrollment Collection V1 KPIs from **Enrollment Collection V1** are implemented as PHP model methods.  
SQL uses Metabase param `{{client_policy_id}}` → CodeIgniter bind `:client_policy_id:`.

| What | URL fragment | Use case |
|------|-------------|----------|
| **Single KPI** | `kpi/{slug or Metabase id}` | One card at a time |
| **All KPIs** | `all` | Full enrollment dashboard (10 KPIs) |
| **Debug / preview** | `debug` / `preview` | Admin / FE testing |

Query param: `client_policy` or `client_policy_id` (required for `kpi` / `all`).

---

## Route stacks

### 1. Admin — `authMVC`

Prefix: `util/enrollment-collection-v1`

| Method | Path | Purpose |
|--------|------|---------|
| GET | `util/enrollment-collection-v1/preview` | UI debug grid |
| GET | `util/enrollment-collection-v1/preview/{policy_id}` | Same, policy in URL |
| GET | `util/enrollment-collection-v1/debug` | Raw JSON (all KPIs) |
| GET | `util/enrollment-collection-v1/debug/{policy_id}` | Same, policy in URL |
| GET | `util/enrollment-collection-v1/all` | JSON — all 6 KPIs |
| GET | `util/enrollment-collection-v1/kpi/{slug\|id}` | JSON — single KPI |

### 2. Frontend / HR App — `authJWT`

Prefix: `employeeRest/enrollment-collection-v1`

Same paths as above under `employeeRest/` (Bearer + `X-App-Signature`).

---

## How to call

> **Important:** Admin routes live under the **`util/`** prefix (same as `util/claims-collection-v2`).  
> `enrollment-collection-v1/preview` without `util/` will return **404**.

```
GET /index.php/util/enrollment-collection-v1/preview?client_policy=4687
GET /index.php/util/enrollment-collection-v1/all?client_policy=4687
GET /index.php/util/enrollment-collection-v1/kpi/originally_enrolled?client_policy=4687
GET /index.php/util/enrollment-collection-v1/kpi/117?client_policy=4687
GET /index.php/util/enrollment-collection-v1/debug?client_policy=4687
```

Full local example:

```
https://localhost/PHP828APPS/ruc/nhance/index.php/util/enrollment-collection-v1/preview?client_policy=4687
```

---

## All 10 KPIs

| Metabase ID | Method slug | Label | Rows |
|-------------|-------------|-------|------|
| 115 | `originally_enrolled` | Originally Enrolled | single |
| 116 | `added_subsequently` | Added Subsequently | single |
| 117 | `gender_split` | Gender Split | multi |
| 119 | `enrollment_relationship` | Relationship | multi |
| 122 | `average_age_by_enrollment_month` | Average age by Enrolment month | multi |
| 123 | `original_base_premium` | Original Base Premium | single |
| 124 | `overall_active` | Overall Active | single |
| 125 | `enrollment_age_group` | Age Group | multi |
| 126 | `additions_premium` | Additions Premium | single |
| 127 | `net_premium` | Net Premium | single |

> Slug `enrollment_relationship` avoids clashing with Claims V2 `claim_amount_by_relationship` (ticket-level).

---

## Output columns

| Slug | Key row fields |
|------|----------------|
| `originally_enrolled` | `Originally Enrolled` |
| `added_subsequently` | `Subsequent Additions` |
| `gender_split` | `gender`, `member_count`, `percentage` |
| `enrollment_relationship` | `relationship`, `member_count`, `percentage` |
| `average_age_by_enrollment_month` | `enrollment_month`, `month_label`, `average_age`, `enrollments` |
| `original_base_premium` | `opening_premium` |
| `overall_active` | `Overall Active` |
| `enrollment_age_group` | `age_group`, `member_count`, `percentage` |
| `additions_premium` | `additions_premium` |
| `net_premium` | `net_premium` |

---

## Sample `all` response (excerpt)

```json
{
  "status": true,
  "policy_id": 4687,
  "data": {
    "originally_enrolled": {
      "id": 115,
      "label": "Originally Enrolled",
      "rows": [{ "Originally Enrolled": "320" }]
    },
    "gender_split": {
      "id": 117,
      "label": "Gender Split",
      "rows": [
        { "gender": "Male", "member_count": "180", "percentage": "56.25" }
      ]
    }
  }
}
```

---

## Files

| File | Purpose |
|------|---------|
| `app/Models/EnrollmentCollectionV1DashboardModel.php` | KPI SQL, `KPI_MAP`, `KPI_LABELS` |
| `app/Controllers/EnrollmentCollectionV1DashboardController.php` | `kpi()`, `all()`, `preview()`, `debug()` |
| `app/Views/enrollment_collection_v1_dashboard.php` | Preview UI |
| `app/Config/Routes.php` | `enrollment-collection-v1` groups (util + employeeRest) |
| `tests/smoke_enrollment_collection_v1.php` | `php tests/smoke_enrollment_collection_v1.php 4687` |
| `enrollment-dashboard.md` | This document |

---

## Related

- Claims dashboard: `hr-dashboard.md` → `claims-collection-v2` (36 KPIs)

---

## BE notes

- Run `php tests/smoke_enrollment_collection_v1.php {policy_id}` after model changes.
- Status filters in CSV use `'Active'` (capital A) for some KPIs; kept as in Metabase export.