update api and add more features

2026-06-04 02:24:41 -04:00
parent fa6c9519a0
commit 4e33882ac7
131 changed files with 34596 additions and 340 deletions
@@ -0,0 +1,96 @@
+# `ParentController` plan
+
+## Scope
+- **Controller**: `app/Http/Controllers/Api/Parents/ParentController.php`
+- **Purpose**: parent portal endpoints for attendance, invoices, enrollments, registration, emergency contacts, profile, and event participation.
+- **Primary dependencies**:
+  - `App\Services\Parents\ParentAttendanceService`
+  - `App\Services\Parents\ParentInvoiceService`
+  - `App\Services\Parents\ParentEnrollmentService`
+  - `App\Services\Parents\ParentRegistrationService`
+  - `App\Services\Parents\ParentEmergencyContactService`
+  - `App\Services\Parents\ParentProfileService`
+  - `App\Services\Parents\ParentEventParticipationService`
+
+## Routes
+All routes are under `v1` + `parents` group:
+- Base prefix: `GET/POST/PATCH/DELETE /api/v1/parents/...`
+- Group middleware: `parent.access`
+
+Endpoints:
+- `GET /api/v1/parents/attendance` → `attendance`
+- `GET /api/v1/parents/invoices` → `invoices`
+- `GET /api/v1/parents/enrollments` → `enrollments`
+- `POST /api/v1/parents/enrollments` → `updateEnrollments`
+- `GET /api/v1/parents/registration` → `registration`
+- `POST /api/v1/parents/registration` → `storeRegistration`
+- `PATCH /api/v1/parents/students/{studentId}` → `updateStudent`
+- `DELETE /api/v1/parents/students/{studentId}` → `deleteStudent`
+- `GET /api/v1/parents/emergency-contacts` → `emergencyContacts`
+- `POST /api/v1/parents/emergency-contacts` → `storeEmergencyContact`
+- `PATCH /api/v1/parents/emergency-contacts/{contactId}` → `updateEmergencyContact`
+- `GET /api/v1/parents/profile` → `profile`
+- `PATCH /api/v1/parents/profile` → `updateProfile`
+- `GET /api/v1/parents/events` → `events`
+- `POST /api/v1/parents/events/participation` → `updateParticipation`
+
+## Authentication & authorization
+- Uses `parent.access` middleware which resolves “secondary”/“authorized” users to a primary parent id and stores it in the request attribute `primary_parent_id`.
+- Controller helper `parentIdOrUnauthorized()`:
+  - Prefer `request()->attributes->get('primary_parent_id')`
+  - Fallback to `auth()->id()`
+  - On failure returns JSON `{ ok:false, message:"Unauthorized." }` with `401`
+
+## Requests/validation
+Validated via `FormRequest` classes per endpoint:
+- `attendance`: `ParentAttendanceRequest` (optional `school_year`)
+- `invoices`: `ParentInvoiceRequest` (optional `school_year`)
+- `enrollments`: `ParentEnrollmentRequest` (optional `school_year`)
+- `updateEnrollments`: `ParentEnrollmentActionRequest` (`enroll[]`, `withdraw[]`)
+- `storeRegistration`: `ParentRegistrationRequest` (`students[]`, `emergency_contacts[]`)
+- `updateStudent`: `ParentStudentUpdateRequest`
+- `store/update emergency contact`: `ParentEmergencyContactRequest`
+- `updateProfile`: `ParentProfileUpdateRequest`
+- `updateParticipation`: `ParentEventParticipationRequest` (`participation[]`)
+
+## Response shapes (legacy `{ ok: ... }`)
+This controller largely returns a legacy parent-portal shape rather than the Base API envelope.
+
+- `attendance`:
+  - `{ ok:true, attendance:[...], schoolYears:[...], selectedYear }`
+  - `attendance` uses `ParentAttendanceResource::collection(...)`
+- `invoices`:
+  - `{ ok:true, invoices:[...] }` (`InvoiceResource::collection(...)`)
+- `enrollments`:
+  - `{ ok:true, students:[...], schoolYears:[...], selectedYear, withdrawalDeadline, lastDayOfRegistration, schoolStartDate }`
+- `updateEnrollments`:
+  - `{ ok:true, enrolled:[...], withdrawn:[...] }`
+- `registration`:
+  - `{ ok:true, parent, existingKids:[...], emergencies:[...], maxChilds, maxEmergency, lastDayOfRegistration, registrationAgeDeadline }`
+- `storeRegistration`:
+  - `{ ok:true, created_student_ids:[...], skipped:[...] }` with status `201` if created_count>0 else `200`
+- `updateStudent` / `deleteStudent` / `updateParticipation`:
+  - `{ ok:true }`
+- `emergencyContacts`:
+  - `{ ok:true, contacts:[...] }`
+- `store/update emergency contact`:
+  - `{ ok:true, contact:{...} }` (store returns `201`)
+- `profile` / `updateProfile`:
+  - `{ ok:true, profile:{...} }`
+- `events`:
+  - `{ ok:true, activeEvents, charges, yourStudents }`
+
+## Error handling expectations
+- Unauthorized: `{ ok:false, message:"Unauthorized." }` with `401` (from `parentIdOrUnauthorized()`).
+- Service-layer exceptions are generally allowed to bubble unless handled in the service; controller does minimal try/catch.
+
+## Test plan (feature)
+- Auth/parent.access:
+  - Without auth → 401 `{ ok:false }`.
+  - With secondary/authorized user → resolved to primary parent id and returns correct data.
+- Each endpoint:
+  - Valid request returns `ok:true` and expected keys.
+  - Validation errors are returned by FormRequest (422).
+- Registration:
+  - Returns 201 when at least one student is created, 200 when all entries skipped.
+