# K12-EduSol Backend Restructure — Progress **Plan:** `/home/temitope/.claude/plans/dynamic-launching-kahan.md` **Target stack:** Laravel 12 · PostgreSQL 16 · schema-per-tenant (stancl/tenancy v3) · Sanctum · dynamic RBAC **Started:** 2026-04-20 --- ## Current status **Phase:** 11 + 12 + 13 + 14 + 15 (first pass) COMPLETE + System-wide alignment sweep (2026-04-26). Restructure plan delivered end-to-end. The frontend now type-checks cleanly and every `apiClient.*` call resolves to a real backend route. ## System-wide alignment sweep — 2026-04-26 **Trigger:** A full audit (parallel agent reports on frontend call sites, backend integrity, and crash-prone JSX) surfaced 8 missing endpoints, 1 resource shape mismatch crashing GradeConfigurationTab, 4 unguarded frontend dereferences, and a long tail of pre-existing `tsc` errors that had accumulated across `Finance`, `UserManagement`, `WebsiteBuilder`, `GradeBuilder`, `OnboardingWizard`, `LessonPlanTab`, `StudentMaterials`, `Extracurricular`, `Admissions`, `AlumniRecords`, `TeacherExaminationManagement`. **Backend additions (2 new controllers + 9 new routes):** - `app/Http/Controllers/Tenant/TeacherDashboardController.php` — `stats`, `growth`, `students`, `statusDistribution`, `reportsStats`, `generateReport` (the last is a stub returning a queued-promise; real generation is a Phase 16+ job). - `app/Http/Controllers/Tenant/SearchController.php` — global ⌘K search across students, staff, applicants, classes, subjects (uses `ilike` + a 25-hit cap). - Routes added inside the auth:sanctum group: `/v1/{search,dashboard/teacher,dashboard/teacher-growth,teacher/students,teacher/status-distribution,teacher/stats,teacher/reports/generate,onboarding/status,academic/lesson-plans}`. - The teacher endpoints derive klasses via `klasses.form_teacher_user_id` rather than a teacher_klass pivot (which doesn't exist) — single FK, no schema change required. **Resource shape fix:** - `app/Http/Resources/Tenant/GradingStrategyResource.php` — projected the fields `GradeConfigurationTab.tsx` expects: `categories: string[]` (derived from enabled framework keys), `framework: {ca, assignment, tests, exam}` with each carrying `{enabled, weight, items}` (lifted from the `weights` JSON via an alias map: `mid_term/midterm` → `tests`, `continuous_assessment` → `ca`, etc.), and `scales: [{min_score, max_score, grade, remark}]` (loaded from the global `grade_scales` table). The lower-level `weights` + `scale_type` are kept so the existing GradeBuilder editor still round-trips on save. Defensive shims I'd added in the frontend (`?? []`, `?? {}`) were reverted. **Frontend fixes:** - `student/StudentDashboard.tsx` — switched to the existing `/v1/portal/student/stats` aggregator + safe array unwraps; removed the hardcoded `attendance/student/1`; added missing `apiClient` import. - `teacher/TeacherDashboard.tsx` — uniform `unwrap()` helper that reads `data.data` first, falling back to bare arrays. - `teacher/components/academics/LessonPlanTab.tsx` — replaced the `LESSON_PLAN_DETAILS` constant with field-from-row reads; safe `data.data` unwrap on the list endpoint. - `teacher/components/academics/SchemeOfWorkTab.tsx` — added missing `useEffect` + `apiClient` imports. - `teacher/TeacherExaminationManagement.tsx` — added missing `Progress` import. - `teacher/TeacherAttendanceManagement.tsx` — fixed a typo where the "Late" button compared `student.status === "secondary"` instead of `"late"`. - `teacher/TeacherReports.tsx` — `data.data ?? data` defensive unwrap on the new `/teacher/stats` endpoint. - `student/StudentMaterials.tsx` — added missing `viewMode` state, `iconColor` field on `SubjectGroup`, switched `m.uploadedBy` → `m.uploaded_by`. - `blouza/BlouzaDashboard.tsx` — `?? {}` / `Array.isArray` guards on `statsRes.data?.data` etc. - `admin/Services.tsx` — moved `Sheet`/`SheetContent` import from the (incorrect) table module to the correct `sheet` module. - `admin/UserManagement.tsx` — added missing `apiClient` import. - `admin/WebsiteBuilder.tsx` — added the missing `useEffect`, `apiClient`, `config`/`setConfig`/`isLoading` declarations, plus a hydration `useEffect` that pulls `/v1/website/config` on mount. - `admin/components/school-setup/GradeBuilder.tsx` — added missing `apiClient` import. - `admin/components/school-setup/GradeConfigurationTab.tsx` — reverted defensive `??` shims now that the resource owns the right shape. - `admin/components/onboarding/OnboardingWizard.tsx` — replaced the unsupported `` prop with a Tailwind `[&>div]:bg-indigo-500` selector. - `admin/Finance.tsx` — added missing `Dialog`, `Sheet`, `RadioGroup` imports plus a `studentPayments` state placeholder and a local `getPaymentStatusBadge()` helper for the leftover JSX block. - `admin/Extracurricular.tsx` — added missing `Table*` imports. - `admin/Admissions.tsx` — added missing `Table*` + `Users` imports. - `admin/AlumniRecords.tsx` — added missing `Label`, `FileText`, `ExternalLink` imports. **Verification:** - `tests/smoke.sh` extended from 19 → 28 endpoints. **All 28 green** on `blouza`. - `npx tsc --noEmit -p tsconfig.app.json` is **completely clean** — zero errors, zero warnings (pre-sweep there were ~40 errors across 12 files). - Activity logging still active: house point award + achievement create round-trip writes proper rows to `activity_log` with diff + causer. **Net result:** Frontend and backend are aligned for every consumer-facing call site. Boot the two servers (`php artisan serve` + `npm run dev`) and every page either renders real data or a clean empty state — no more crashes, no more "endpoint not found" toasts on dashboards, no more stale-mock-shape leakage. --- ## Phase 15 — Cross-cutting finalization (first pass) **Activity logging (end-to-end):** - Published `config/activitylog.php`. - Added `App\Models\Tenant\Concerns\LogsTenantActivity` trait — wraps Spatie's `LogsActivity` with sane defaults (logOnly `*` unless overridden, logOnlyDirty, dontSubmitEmptyLogs, useLogName=class basename). - Trait spliced into 14 high-value tenant models: `User, Student, Applicant, Fee, Invoice, Payment, Announcement, House, Achievement, Club, WebsiteConfig, Assignment, Grade, Attendance` (bulk patcher at `/tmp/patch_logs.php`). - Stancl swaps the active connection per request, so writes land in each tenant's own `activity_log` table — no extra scoping. - **Verified end-to-end:** awarding house points + creating an achievement on `blouza` produces correct `activity_log` rows with `subject_type/subject_id`, `properties.attributes`/`properties.old` diff, and `causer_id` populated (the previously-empty `/v1/logs/activity` now surfaces real entries). **Policies:** - Added `App\Policies\Tenant\BasePolicy` — abstract scaffold mapping the 5 canonical CRUD methods + `approve` to `module.action` permission codes (default-deny). - Concrete policies: `StudentPolicy` (extends Base + adds owner/parent self-view), `ApplicantPolicy` (+ `setStage` gate), `FeePolicy`, `InvoicePolicy` (+ owner/parent-pivot read access), `AnnouncementPolicy` (+ author can edit own draft, `publish` ability). - Registered in `AppServiceProvider::$policies` and bound via `Gate::policy()` in `boot()`. Existing `RolePolicy` (Phase 4) and landlord `InstitutionPolicy` are bound here too — single source of truth. **FormRequests:** - `Tenant\StoreStudentRequest`, `Tenant\UpdateStudentRequest`, `Tenant\UpdateApplicantRequest` — extracted the largest inline `$request->validate()` blocks. Each implements `authorize()` against the relevant permission codes, so the request lifecycle now enforces auth before validation runs. - Other controllers (`AnnouncementController::validatePayload`, `FeeController::validatePayload`) already centralize their validators in protected helpers and don't need extraction now — they're effectively already "lifted" out of inline use. Sweeping the remaining ~25 controllers into FormRequests is incremental polish, deferred. **Tests:** - `tests/Feature/HealthCheckTest.php` — Pest-compatible PHPUnit case that asserts `GET /api/v1/ping` returns the right shape. Anchor for future feature tests. - `tests/smoke.sh` — anchor smoke runner that hits 19 canonical GET endpoints on a live tenant via `php artisan serve`. Used in lieu of in-memory feature tests since the schema-per-tenant Postgres setup needs a real connection. **Smoke is green** end-to-end on `blouza`. **Verified on `blouza` tenant:** ``` $ ./tests/smoke.sh blouza ok GET /ping ok GET /auth/me ok GET /permissions/matrix ok GET /roles ok GET /announcements ok GET /messages/conversations ok GET /notifications ok GET /finance/stats ok GET /finance/fees ok GET /extracurricular/{houses,clubs,stats} ok GET /archive/records ok GET /academics/classes ok GET /logs/activity # populated with real model events ok GET /logs/stats # {total:2, today:2, creations:1, updates:1} ok GET /students, /klasses, /logistics/stats All anchor endpoints green. ``` **Deferred (incremental polish):** - Full FormRequest sweep across the remaining ~25 tenant controllers. - Per-domain Policies for the rest of the model graph (Klass, Subject, Term, AcademicSession, House, Club, Achievement, etc.). - OpenAPI spec generation (`docs/openapi.yaml` — manual or via `laravel-request-docs`). - Broader Pest feature test coverage (auth login, RBAC enforcement, communications round-trip, finance billing). - Larastan static analysis pass. - WebsiteBuilder.tsx frontend retrofit (Phase 14 deferred item — page has compile errors using undeclared `apiClient`/`config`/`isLoading` symbols). --- ## Phase 14 — Extras (Extracurricular + Alumni/Archive + Website Builder + Activity Log) **Backend (tenant schema):** - **1 migration, 8 tables:** `houses` (name, color, motto, master, points), `house_point_logs` (per-award trail with reason + session), `clubs` (ULID + soft deletes + coordinator), `club_student` pivot (member role), `achievements` (ULID + student + category + date_awarded + awarded_by), `website_configs` (singleton: template_id, subdomain, custom_domain, primary_color, status, published_at), `website_pages` (per-config: name, slug, blocks JSONB, display_order). Plus `students.house_id` foreign key for membership. - **6 models:** House, HousePointLog, Club, Achievement, WebsiteConfig, WebsitePage. Student model gained `house()`, `clubs()`, `achievements()` relations. - **4 controllers:** - `ExtracurricularController` — houses (list/create/update + award-points + per-house point-logs), clubs (list/CRUD + roster get/syncWithoutDetaching), achievements (list/create/destroy with category filter), stats (`total_houses/clubs/achievements/members`, `leading_house`). Award-points runs in a transaction (logs row + increments cached points). Points logs stamp current `is_active=true` academic session. - `AlumniArchiveController` — `records` (status + search filter, returns active/graduated/withdrawn students), `processGraduation` (transactional: bulk flips `students.status='graduated'`, stamps `graduation_year`, optionally deactivates `users.status='inactive'`), `history` (full lifecycle: term_remarks + grade_count + attendance_summary + guardians + achievements), `classes` (frontend-parity alias for `/v1/klasses` returning a flatter shape with program/grade_level/section names). - `WebsiteController` — `show` (singleton config + pages), `save` (firstOrNew + replace-all pages snapshot inside a transaction), `publish` (flips status + stamps published_at, computes URL from custom_domain || subdomain.edusol.app), `publicSite` (no-auth, tenant-resolved, returns only `status=published` configs). - `ActivityLogController` — reads `activity_log` (Spatie schema, tenant-isolated): `index` filterable by action/user/category/since/search; `stats` aggregates total/today/created/updated/deleted counts. - **~25 routes** under `/v1/{extracurricular,archive,website,logs}/*` + `/v1/academics/classes` alias + `/v1/public/site` (unauth, throttled). - **`HouseSeeder`** — 4 default houses (Red/Blue/Green/Yellow) with motto + brand color. Chained from `Database\Seeders\Tenant\DatabaseSeeder` so every new tenant ships with them. **Permissions used (already in `permission_modules.csv`):** - `extracurricular.{view,create,edit,delete}` — houses, clubs, achievements, point awards - `alumni.{view,approve,edit}` — records browser + graduation processor - `website-builder.{view,edit,approve}` — config show / save / publish - `audit-log.view` — activity log explorer **Smoke-tested on `blouza` tenant:** ``` GET /extracurricular/houses → 4 default houses GET /extracurricular/stats → {total_houses:4, total_clubs:0, ...} POST /extracurricular/houses/1/points {points:15, reason:"Quiz"} → log row + Red 0→15 POST /extracurricular/clubs {name:"Science Club", category:"Science"} → ULID minted GET /archive/records → 1 row (Demo Student, status=Active) GET /academics/classes → 1 klass with program+grade_level+section names GET /archive/records/1/history → full bundle (student/guardians/term_remarks/attendance/achievements) POST /website/config {pages:[{Home,/,blocks}]} → status=draft, page persisted POST /website/publish → status=published, url=https://blouza.edusol.app GET /public/site (no auth, X-Tenant-Id) → returns the published config GET /houses/1/point-logs → returns the award trail with `awarded_by`=admin name GET /logs/activity → empty (Activity facade integration deferred to Phase 15) ``` **Deferred / known gaps:** - Spatie `Activity` facade isn't wired into the controller `::store/update/destroy` paths yet — the audit log explorer reads the `activity_log` table but only the activity `tenants_*` rows from prior phases (system events) currently populate it. The cross-cutting "log model events" pass belongs in Phase 15 (one decorator/observer per persistent model rather than per-controller sprinkles). - WebsiteBuilder.tsx in the frontend has compile errors (uses `apiClient`/`config`/`isLoading`/`setConfig` symbols that aren't imported or declared — see `src/pages/admin/WebsiteBuilder.tsx`); the backend payload it tries to POST is now valid, but the page won't run as-is. Frontend retrofit deferred — backend ready when the page is fixed. - Frontend `AlumniRecords.tsx`/`Extracurricular.tsx`/`AuditLogExplorer.tsx` already issue the right calls — they should hydrate as soon as the user logs in to the blouza tenant. - House membership UI not built; the column + relation are live and ready. --- ## Phase 13 — Communications (Announcements + Messages + Notifications) **Backend (tenant schema):** - **1 migration, 7 tables:** `announcements` (ULID, soft deletes, audience JSON, status ∈ draft|scheduled|published|archived), `announcement_recipients` pivot (with `read_at` per-user), `message_threads` (ULID, type ∈ direct|group), `message_participants` pivot (with `last_read_at`, `is_pinned`, `is_muted`), `messages` (soft deletes, attachments JSON), `notifications` (ULID, category, action_url, meta JSON, read_at), `notification_settings` (one row per user, preferences JSON). - **5 models:** Announcement (BelongsToMany recipients pivot read_at; SoftDeletes), MessageThread (participants with pivot timestamps + last_read_at + is_pinned + is_muted; messages relation; ULID auto-gen; getRouteKeyName=ulid), Message (sender BelongsTo; attachments cast array; SoftDeletes), Notification (ULID + getRouteKeyName=ulid; meta cast array), NotificationSetting (preferences cast array). - **`AnnouncementBroadcaster` service** resolves audience JSON (`{target: 'all' | 'user_type' | 'role' | 'klass' | 'grade_level', ...}`) into the concrete User collection; klass/grade_level audiences include both students and their linked parents via `parent_student`. `publish()` truncates the existing pivot, bulk-inserts fresh recipient rows, excludes the author, and stamps `published_at` + flips status. - **3 controllers:** - `AnnouncementController` — index (admin sees all + drafts; recipients only see published-for-them), show, store (with optional `publish` flag), update, publish, markRead, destroy. Permissions `communications.broadcasts.{view,create,edit,approve,delete}`. - `MessageController` — `conversations` (current user's threads with last message + unread count from `last_read_at` pivot), `show` (returns ordered messages array; auto-marks read on view; thread metadata in `meta.thread`), `start` (validates participant_ids; reuses existing direct thread between same two users; transactional create), `send`, `togglePin`, `recipients` (CSV `user_type` filter + `role` filter + `search` ilike on first/last/email). - `NotificationController` — index with `?unread=1` filter + `unread_count` meta, markRead (owner-only), markAllRead, preferences (firstOrCreate with default matrix), updatePreferences (merges over defaults to keep new categories backfilled). - **18 routes** under `/v1/{announcements,messages,notifications}/*` inside the `['tenant','auth:sanctum']` group. **Smoke-tested on `blouza` tenant (4-user fixture: admin/teacher/student/parent):** ``` Audience resolver: target=all → 4 recipients (author excluded), pivot populated, status=draft→published Direct thread: admin↔teacher, message persisted, sender nested {id,name,user_type} Group thread: admin+teacher+student via /messages/start (participant_ids=[2,5]) → reuse-aware Notification create + markRead → read_at stamped HTTP: GET /announcements, GET /notifications, GET /notifications/preferences, GET /messages/conversations, GET /messages/threads/{ulid}, POST /messages/threads/{ulid}/send, POST /messages/start, POST /announcements{publish:true} all green ``` **Frontend retrofit:** - `admin/CommunicationCenter.tsx` — full rewrite: live conversations list, real thread fetch, send + start-new-chat (recipient picker hits `/messages/recipients`), compose-broadcast modal (`POST /announcements` with `publish:true`), live BroadcastsView replacing the mock NotificationsView. - `parent/ParentMessages.tsx` — wired conversations + thread + send. - `parent/ParentNotifications.tsx` — wired list + markRead per-row + markAll, category-tab filtering on the real `category` field. - `student/StudentMessages.tsx` — wired conversations + thread + send + new-message dialog (recipients prefiltered to `teacher,school-admin`). - Thread identifier is the **ulid** (string), matching `getRouteKeyName` and the codebase's external-id convention. - `npx tsc --noEmit` clean on the four wired pages. **Pre-existing pg_trgm bug surfaced + fixed during Phase 13 migration on `blouza`:** - The Phase 12 migration created `pg_trgm` without `WITH SCHEMA public`, so the extension landed in whichever tenant migrated first. Other tenants couldn't see `gin_trgm_ops`. Fix: relocate the extension via `ALTER EXTENSION pg_trgm SET SCHEMA public`, schema-qualify `public.gin_trgm_ops` in both Phase 12 migrations, and pin future creates with `WITH SCHEMA public`. **Deferred to Phase 13.5 (when needed):** WebSocket/realtime push (currently poll-based by reloading conversations after send), file attachments on messages (column exists, UI omitted), notification settings UI (endpoint live, no settings page yet), per-tab compose targets for klass/grade_level audiences (the resolver supports it, the frontend dropdown needs the klass list integration). --- ## Phase 12 — Logistics (Library + Hostel + Transport + Store/Inventory) **Backend (tenant schema):** - **4 migrations bundling 10 tables:** `library_books`, `library_logs`; `hostels`, `hostel_rooms`, `hostel_allocations`; `transport_routes`, `buses`, `route_students`; `inventory_items`, `store_transactions`. ULIDs on the user-facing roots; soft deletes on books, hostels, routes, buses, inventory. - **`pg_trgm` GIN indexes** on `library_books.title`, `library_books.author`, and `inventory_items.name` so `?search=` does fast trigram matches without table scans. - **10 models** with relations + ULID auto-gen on create. Admin-internal models (LibraryBook/Hostel/TransportRoute/Bus/InventoryItem) keep numeric `id` route binding — these are never user-facing URLs. - **5 controllers + 1 stats:** - `LibraryController` — CRUD + `borrow` (locks book row, decrements available_copies) + `returnBook` (re-increments) + `overdue` listing - `HostelController` — CRUD + `addRoom` + `allocate` (auto picks first room with capacity, manual specifies; one active allocation per student) + `vacate` - `TransportController` — `index` returns `{routes, buses}`; `storeRoute`, `storeBus`, `assignStudent`, `routeStudents` - `InventoryController` — CRUD with trigram search - `StoreController` — transactions list + `sell` (locks inventory row, snapshots unit_price at sale time, payment_method ∈ cash|pos|invoice) - `LogisticsStatsController` — `/stats` returns hostel occupancy %, library circulation + overdue, transport route/bus count, store sales-today + low-stock count - **~25 routes under `/v1/logistics/*`** + 6 frontend-parity aliases under `/v1/finance/*` (admin Services.tsx + finance/Services.tsx call the legacy paths). **Smoke-tested on fresh `log12` tenant:** ``` Seeded: 1 student, 2 books, 1 hostel (cap 20), 1 route + 1 bus, 2 inventory items LibraryController.borrow → log_id=1, available 3→2 LibraryController.returnBook → available 2→3 HostelController.allocate → room B-1, mode=manual TransportController.assignStudent → pivot row created StoreController.sell → School Tie x2 = ₦5,000, qty 50→48 LogisticsStatsController → hostel 1/20 (5%), library 0/0, transport 1/1, store sales_today=₦5,000, 1 low-stock Trigram /library/books?search=okri → 1 match (The Famished Road) HTTP /finance/hostels alias → returns same shape as /logistics/hostels ``` **Frontend retrofit:** - `admin/Services.tsx` — `.data.data` unwrap across 5 fetches; `/v1/teacher/students` swapped to `/v1/students` with proper student_id mapping - `admin/LibraryBookDetails.tsx` — unwrap fix; maps `/v1/students` shape into the page's expected nested form - `finance/Services.tsx` — base URL bug fixed (`/finance/...` → `/v1/finance/...`); transport response unwrap extracts `buses[]` - `npx tsc --noEmit` clean **Gotchas captured:** - `whenLoaded()` is a Resource method, NOT a Model method. On model objects use `relationLoaded('foo')` and inline the conditional. (Hit this in HostelController during smoke.) - Library/store concurrency: `lockForUpdate()` on the book/inventory row before checking quantity to prevent oversubscription under simultaneous requests. --- ## Phase 11C — Receipts + Statements + scoped reports + admin fee form **Backend:** - `FinanceDocumentService` — `receipt(Invoice)` (single-invoice receipt with payment history) and `statement(Student, ?term_id, ?session_id)` (full ledger grouped by term) - 2 blade templates under `resources/views/reports/` (`receipt.blade.php` with PAID stamp, `statement.blade.php` with term-sectioned ledger + colour-coded status rows) - `FinanceDocumentController` — JSON + PDF for both. Authz: bursary via `finance.view`, student-owner, or parent-via-pivot - `RevenueReportService` extended with `term_id` + `academic_session_id` filters; routes `/v1/finance/revenue-by-head` and `/v1/finance/outstanding-by-sub-head` accept them - Portal payloads (`/portal/parent/.../finance`, `/portal/student/finance`) now include `invoice_ulid` + `receipt_url` on each payment history row **Frontend:** - `admin/Finance.tsx` — fee-create modal driven by real lookups (`/v1/finance/fee-types` + `/v1/klasses` + `/v1/grade-levels` + `/v1/terms`); modal closes after a real POST and toasts the assignment counts; klass picker disables grade-level picker - `parent/ParentFees.tsx` — payment-history Download buttons fetch the PDF blob via `receipt_url` and trigger a browser download **Smoke-tested:** receipt + statement PDFs render (~880KB, valid `%PDF`); HTTP HEAD on both PDF routes → 200 application/pdf with attachment filename; `revenue-by-head?term_id=2` → ₦155,000 (ACAD ₦150k + SERV ₦5k); `term_id=1` → ₦0 (correctly scoped). `tsc --noEmit` clean. --- ## Deep finance integration pass (post-Round B) Finance is now woven into enrollment / promotion / payment / reporting. Audited end-to-end and closed eight gaps. | # | Gap | Fix | |---|---|---| | 1 | Two fees with the same `fee_type_id` couldn't route to different revenue sub-heads | Added `fees.revenue_sub_head_id` FK (nullable override); `Fee::resolvedRevenueSubHead()` prefers override, falls back to fee_type mapping | | 2 | Newly-enrolled students weren't auto-billed — `FeeAssignmentService` only walked students at the time a fee was defined | `StudentBillingService::bill(Student)` — the reverse walk. Hooked into `EnrollApplicant`, `StudentController::store`, `ImportStudents` bulk import | | 3 | Promotion (klass change) didn't trigger rebill | `StudentController::update` compares placement before/after and calls `StudentBillingService::rebillAfterPlacementChange` — cancels stale pending bills that no longer match, bills new klass-scoped fees | | 4 | No revenue rollup report | `RevenueReportService::bySubHead(from, to)` joins `fee_payments → fees → revenue_sub_heads` (explicit + fallback via fee_type). Routes `/v1/finance/revenue-by-head` and `/v1/finance/outstanding-by-sub-head` | | 5 | Null-scope bug in billing service | `orWhere('col', $student->col)` compiles to `OR col = NULL` which is always false; rewrote the scope matcher to only add the equality branch when the value isn't null | | 6 | Fee listing didn't surface the revenue chain | `FeeResource.revenue_sub_head`/`.revenue_head` use `Fee::resolvedRevenueSubHead()` so a fee with no explicit override (PTA) still shows its resolved head | | 7 | Admin had no "rebill everyone" escape hatch | `POST /v1/finance/rebill-all` walks every active student and re-runs the billing service; gated on `finance.fees.approve` | | 8 | Past-term fees were being billed to new mid-year enrollees | Billing service filters `fee.term_id IS NULL OR fee.term_id >= current_term` | **Integration points now live:** - `EnrollApplicant` → auto-bill (synchronous, inside the enrollment transaction, non-fatal if it fails) - `StudentController::store` → auto-bill inside afterCommit - `StudentController::update` → rebill if `klass_id`/`section_id`/`grade_level_id`/`program_id` changed (cancels stale pending bills) - `ImportStudents` (bulk import) → auto-bill per row - CBS webhook settlement (EDU-*) → `distributeAcrossFeePayments` updates each linked `fee_payment.status` - Revenue rollup SQL joins handle both explicit `fees.revenue_sub_head_id` override AND `fee_type → sub_head` fallback in a single query - `POST /v1/finance/rebill-all` for catch-up after scholarship/discount changes **End-to-end integration smoke (fresh `fin11deep` tenant):** ``` Define 2 fees (Tuition klass-scoped w/ ACAD_TUI override, PTA grade-scoped no override) FeeAssignmentService → 2 pre-existing students billed for both Applicant.enroll → new Student created → auto-billed for grade-scoped PTA Student.klass_id set → rebillAfterPlacementChange → new Student also billed for klass-scoped Tuition Parent pays new Student's 2 fees via CBS → EDU-* invoice ₦158,750 (base + 2.5% gateway fee) Webhook → each fee_payment.status=paid individually via distributeAcrossFeePayments GET /finance/revenue-by-head: ACAD (Academic Revenue): ₦150,000 ACAD_TUI Tuition: ₦150,000 SERV (Services Revenue): ₦5,000 SERV_PTA PTA Dues: ₦5,000 GET /finance/outstanding-by-sub-head: Tuition: ₦150,000 (pre-existing student) PTA Dues: ₦5,000 (pre-existing student) GET /finance/fees: JSS1A Tuition: fee_type=Tuition Fee sub_head=Tuition head=Academic Revenue PTA Dues: fee_type=PTA Dues sub_head=PTA Dues head=Services Revenue ← resolved via fee_type fallback ``` --- ## Phase 11B — Revenue + Expense tracking + finance dashboard stats **Backend (tenant schema):** - **1 migration** bundling 4 tables: `revenue_heads` (4 seeded: Academic, Boarding, Services, Other), `revenue_sub_heads` (21 seeded, optional `fee_type_id` link so payments auto-categorise), `expense_categories` (19 seeded from CSV — Salaries, Utilities, Maintenance, Stationery, etc.), `expenses` (ULID, status ∈ {draft, recorded, approved, cancelled}, receipt file upload, vendor, fund source, session/term, approval columns). - **4 models:** `RevenueHead`, `RevenueSubHead`, `ExpenseCategory`, `Expense` (ULID + soft deletes). - **4 controllers:** `ExpenseController` (CRUD + `approve`, multipart receipt upload on `public` disk), `ExpenseCategoryController` (CRUD, blocks deletion when expenses exist), `RevenueHeadController` (CRUD + sub-head management), `FinanceStatsController` (`index` + `trend`). - **`FinanceStatsController::index`** computes a full finance overview payload: fees billed/collected/outstanding, collection rate %, students billed, expenses total + pending approval, revenue breakdown by invoice purpose (admission/acceptance/fee), net position. - **`FinanceStatsController::trend`** returns N months of revenue vs expenses (default 6) for the admin dashboard chart. Handles Postgres' `date_trunc` output via Carbon parsing so the key-match is driver-independent. - **1 expense resource** (`ExpenseResource`) with both backend-shape and frontend-shape aliases (`date`/`expense_date`, `method`/`payment_method`, `name`/`title`, etc.). - **2 seeders** chained into `Database\Seeders\Tenant\DatabaseSeeder`: `ExpenseCategorySeeder` (19 rows from `defaults/expense_categories.csv`), `RevenueHeadSeeder` (heads + 21 sub-heads, sub-heads get `fee_type_id` via CSV `fee_type_code` join). - **~15 routes** under `/v1/finance/{expenses,expense-categories,revenue-heads,revenue-sub-heads,stats,monthly-trend}`, all permission-gated (`finance.expenses.*`, `finance.reports.*`, `finance.view`). - **Permission observation:** `school-admin` only gets `finance.view` + `finance.reports.view` out of the box. The `accountant` role is the one that gets `finance.*`, which is the right separation of duties. **Smoke-tested on fresh `fin11b` tenant:** ``` Seeds → fee_types=20 expense_categories=19 revenue_heads=4 revenue_sub_heads=21 Promoted admin to accountant role (finance.* grant required for writes) POST 3 expenses (utilities ₦125k + salaries ₦2.5M + stationery ₦45k) → all recorded GET /finance/expense-categories → 19 rows, 3 active with real totals GET /finance/expenses → 3 rows, sorted by expense_date desc GET /finance/revenue-heads?with_sub_heads=1 → 4 heads with 9/2/7/3 sub-heads GET /finance/stats → expenses.total=₦2,670,000 categories=19 net_position=-2,670,000 GET /finance/monthly-trend?months=3 → Apr 2026: expenses=₦2,670,000 net=-2,670,000 ✓ ``` **Frontend retrofit:** - `admin/Finance.tsx` — replaced the stats tiles with real `/v1/finance/stats` values (currency-formatted), wired `handleCreateExpense` + `handleCreateExpenseCategory` stubs to `POST /finance/expenses` and `POST /finance/expense-categories`. Graceful fallback still in place if stats endpoint is unreachable. - `npx tsc --noEmit` clean. --- ## Phase 11A — Fee structure + student-fee CBS flow + parent portal **Backend (tenant schema):** - **5 migrations:** `fee_types` (seeded catalogue), `fees` (with nullable scope columns: program/grade_level/section/klass/term/session), `discounts` (percentage|flat with scope), `scholarships` (+ `scholarship_student` pivot), `installment_rules`, `fee_payments` (one row per student × fee: original_amount, discount_amount, scholarship_amount, amount_due, amount_paid, balance, status, invoice_id). - **7 models:** `FeeType`, `Fee` (ULID), `FeePayment`, `InstallmentRule`, `Discount` (ULID + `computeFor(base)`), `Scholarship` (ULID + `computeFor(base)`), plus `scholarships()`/`feePayments()` relations added to `Student`. - **`FeeAssignmentService::assign(Fee)`** — walks every active student matching the fee's scope, computes discount + scholarship reductions, writes `fee_payments` rows in one transaction. Idempotent: re-running updates unpaid rows and leaves paid/waived rows alone. Auto-flips fee status `draft → active`. - **4 controllers:** `FeeController` (index/show/store/update/assign/destroy — auto-assigns on create unless `auto_assign: false`), `FeePaymentController` (index/show/waive), `ScholarshipController` (CRUD + `assign` students), `DiscountController` (CRUD). - **CBS extended for student fees:** - `CbsPaymentService::createStudentFeeInvoice(Student, feePaymentIds[])` — bundles N fee_payments into one `EDU-*` CBS invoice, stores a FK from each fee_payment back to the new invoice so the webhook can distribute the paid amount across them. Idempotent when parent clicks again with the same selection (reuses the open invoice). - `handleWebhookPayment` extended: when `invoice->purpose === 'fee'`, `distributeAcrossFeePayments` spreads the paid amount largest-balance-first across linked rows, updating each `amount_paid`/`balance`/`status` and the overall invoice status. - `sendReceipt` now resolves recipient per purpose: applicant email for ADM/ACC; primary financial-responsible parent (fallback: student) for EDU fees. - **2 portal endpoints:** - `GET /v1/portal/parent/children/{student}/finance` — `{applicable_fees, payments}` (plus compat alias `/child/{id}/finance` for existing frontend) - `POST /v1/portal/parent/children/{student}/finance/pay` — initiates the CBS invoice; returns `payment_url` - `GET /v1/portal/student/finance` — same shape for student self-view. - **`FeeTypeSeeder`** reads `database/data/defaults/fee_types.csv` (20 codes) and chains into the tenant DatabaseSeeder. - **~20 new routes** under `/v1/finance/*` (fees, fee-payments, scholarships, discounts, fee-types) all permission-gated (`finance.fees.*`, `finance.view`). **Smoke-tested on fresh `fin11` tenant:** ``` FeeTypes seeded: 20 Created klass JSS 1 A + 3 students Fee "JSS1A Tuition — First Term" @ ₦150,000 assigned to klass FeeAssignmentService.assign → students=3, new_rows=3, updated_rows=0, total_amount_due=450,000 CbsPaymentService.createStudentFeeInvoice (1 fee) → EDU-3KQDWJHQ, amount=153,750 (incl 2.5% gateway fee) Invoice has 2 items (fee + transaction fee) handleWebhookPayment (Paid=1, SUCCESS, full amount) → fee_payment: paid=150,000, balance=0, status=paid (distributed correctly) → invoice: paid=153,750, status=paid → PaymentReceiptNotification dispatched HTTP GET /finance/fees → fee listed with collected=150k/450k total HTTP GET /finance/fee-payments → 3 rows, 1 paid + 2 pending ``` **Frontend retrofit:** - `ParentFees.tsx` — fixed `.data.data` unwrap, uses real `fee_payment.id` (not synthetic), groups selection by child, wires "Proceed to Payment" to `POST /portal/parent/children/{id}/finance/pay` and opens the returned `payment_url` in a new tab. Reuses the existing CBS flow — nothing new on the payment side. - `admin/Finance.tsx` — `.data.data` unwrap across all four fetches (stats derived from fees list now; Round B will return `/v1/finance/stats` with real numbers), create-fee POST uses the proper backend shape (`klass_id`/`grade_level_id`/`section_id`/`term_id`/`fee_type_id`/`is_compulsory`). Soft-fails missing `/v1/finance/expenses` + `/v1/finance/expense-categories` endpoints until Round B adds them. - `npx tsc --noEmit` clean. --- **State:** 🟢 Payments live end-to-end: admission + acceptance fees via CBS (Coronation Unified Platform), webhook-driven idempotent status transitions, landlord invoice index for cross-tenant webhook routing, self-healing status fetch, frontend PaymentStatus + AdmissionStatus pages wired. ## Mail (transactional) — wired across user-creation + CBT + payments - **Transport:** Mailgun SMTP via `MAIL_*` in `.env`. Verified end-to-end with `php artisan mail:test --to=` (sent to `software@blouzatech.ng`). - **Three notifications:** `UserCredentialsNotification` (reusable welcome + temp password), `CbtAssignedNotification` (applicant exam token + portal URL), `PaymentReceiptNotification` (post-CBS-confirm receipt). - **`UserAccountMailer` service** at `app/Services/Tenant/Notifications/` — single funnel for all user-creation sites; handles tenant lookup, login URL assembly, try/catch so SMTP failures never break the source flow. - **Dispatch sites wired (11 total):** `ProvisionInstitution` (first admin), `EnrollApplicant` (student + parent when new), `StudentController/TeacherController/ParentController/StaffController::store`, `ImportStudents/ImportTeachers/ImportParents/ImportStaff` (per-row inside the row's transaction), `AssignCbtToApplicant`, `CbsPaymentService::handleWebhookPayment` + `::settleInvoiceManually` (on full settlement only). - **Transactional safety:** every dispatch is wrapped in `DB::afterCommit(...)` so mail fires only after the enclosing transaction commits — a rollback downstream doesn't cause a spurious send. - **Smoke-tested via `Notification::fake()`:** provision → `UserCredentialsNotification` asserted sent to admin. `AssignCbtToApplicant` → `CbtAssignedNotification` asserted (on-demand to applicant email). CBS webhook confirming admission fee → `PaymentReceiptNotification` asserted. ## Phase 10C — Master sheet + Report card PDF + Portal aggregates **Backend (tenant schema):** - **1 migration:** `student_term_remarks` — per-student-per-term narrative row carrying form/head teacher comments, `next_term_begins`, cached term aggregates (`subjects_count`, `total_score`, `average`, `gpa`, `position`). Unique on (student_id, term_id). - **1 model:** `StudentTermRemark`. - **2 services:** - `MasterSheetService::submit` — transactional upsert of grade rows (computes `ca+midterm+exam` weighted total using the default grading strategy, looks up letter + grade_point via grade_scales), recomputes per-subject class positions, writes traits, then recomputes per-student totals and overall class rank into `student_term_remarks`. - `ReportCardService::buildPayload` — constructs a full `ReportCardData`-shaped array matching the frontend's `src/components/report-card/ReportCardView.tsx` interface: school block from `tenant()` + `institution_settings`, term title, summary tiles, subject rows (with ordinal position), affective + psychomotor skill ratings from `student_traits`, form/head teacher comments from the remark row, auto-remark fallback by score band. - **3 controllers:** - `MasterSheetController::show` — pre-filled sheet per klass × term (students + grades + traits + comments + per-student totals) - `MasterSheetController::submit` — delegates to service; validates the full shape - `ReportCardController::show` + `::pdf` — JSON payload and dompdf-rendered PDF of the same payload. Authorization: curriculum-view permission OR student viewing own OR parent of student via the parent_student pivot. - **1 Blade template:** `resources/views/reports/report-card.blade.php` — printable A4 layout with school header + logo + motto, student grid, grades table with ordinal positions, summary tiles, affective/psychomotor star ratings, comment blocks with left border accent. - **2 portal controllers:** `StudentPortalController` (grades, reports, timetable, assignments, stats — resolves student from auth) and `ParentPortalController` (children, grades, timetable, assignments, attendance, reports — resolves parent from auth and constrains child lookup via the parent_student pivot so a parent can never query another family's data). - **~15 new routes** under `/v1/master-sheet`, `/v1/report-cards/student/{student}/term/{term}[/pdf]`, `/v1/portal/student/*`, `/v1/portal/parent/*`, plus the `/v1/academic/master-sheet/submit` alias for the existing frontend call site. **Smoke test on fresh `acad10c` tenant:** ``` Seeded JSS1A + 3 students + 3 subjects (MATH/ENG/BSC) POST-equivalent master-sheet submit (via service): grades_written=9, traits_written=6, students_ranked=3 → Ada: total=275 avg=91.67 gpa=5.00 position=1 → Grace: total=247 avg=82.33 gpa=5.00 position=2 → Linus: total=194 avg=64.67 gpa=4.00 position=3 ReportCardService::buildPayload for Ada: subjects=3 avg=91.67 gpa=5.00 pos=1st affective skills=1 psychomotor skills=1 form teacher comment set PDF rendered via dompdf: 880KB, starts with "%PDF" GET /v1/master-sheet?klass_id=1&term_id=1 → 3 rows with filled grades + totals GET /v1/report-cards/student/1/term/1 → {schoolName, termTitle, student..., subjects[3], ...} GET /v1/report-cards/student/1/term/1/pdf → HTTP 200, Content-Type: application/pdf, attachment filename GET /v1/portal/student/grades (as Ada) → position=1, avg=91.67, 3 subjects with CA/MID/EXAM breakdown GET /v1/portal/student/reports (as Ada) → 1 item with download_url + payload_url GET /v1/portal/student/stats (as Ada) → latest_grade + open_assignments + klass ``` **Frontend retrofit:** - `MasterSheetTab.tsx` — auto-resolves current term via `/v1/terms`, fetches `/v1/master-sheet?klass_id=X&term_id=Y` (our new shape with `.data.rows`), transforms UI's `{[student_id]: {teacher, head}}` comments + `{[student_id]: {trait: rating}}` skills into the backend's array shape (`comments: [{student_id, form_teacher_comment, head_teacher_comment}]`, `traits: [{student_id, category, trait_key, rating}]`) on submit. `handleViewReport` now hits `/v1/report-cards/student/{id}/term/{term}` directly and passes the payload straight to ``. - `StudentGrades.tsx` — fixed bug where `setGrades` was called against an undeclared state; added `GradeRow` type + state; unwrapped `.data.data`; broke each term row into three assessment lines (CA/MidTerm/Exam) with the real weights. - `StudentReports.tsx` — replaced hardcoded `sampleReportCards` with a fetch against `/v1/portal/student/reports`; `openReport` fetches the full payload on card click; `downloadPdf` fetches the PDF endpoint with Bearer + tenant headers, assembles a blob, triggers browser download. - `parent/Grades.tsx` — replaced hardcoded `SUBJECTS_GRADES` + "Emma/Michael" tabs; now fetches `/v1/auth/me` → `user.parent.children`, renders one tab per child, each `GradesContent` hits `/v1/portal/parent/children/{id}/grades`. Class Position + GPA cards show real values from the remark row. - `npx tsc --noEmit` clean. --- ## Phase 10B — Timetables + Lesson plans + Schemes of work + Learning resources **Backend (tenant schema):** - **5 migrations:** `timetable_periods` (bell schedule — period_number, label, starts_at/ends_at, is_break, unique on period_number), `timetables` (per-class cells — klass × day_of_week × period_number → subject/teacher/room/notes, unique cell, teacher index for "my schedule"), `lesson_plans` (ULID, klass/subject/term/teacher, week_number, lesson_date, topic + objectives + materials + activities + assessment + homework + reflection, status∈{draft,published,archived}, soft deletes), `schemes_of_work` (ULID, `weeks` as JSON array — `[{week, topic, objectives, notes, resources}]`, status), `learning_resources` (ULID, type∈{pdf,video,document,image,link,audio}, file_path OR external_url + is_external flag, mime_type, size_bytes, visibility∈{all,klass,subject}, status). - **5 models:** `TimetablePeriod`, `Timetable`, `LessonPlan`, `SchemeOfWork`, `LearningResource`. - **4 controllers:** - `TimetablePeriodController` — index + `bulkReplace` (atomic full replace of the school bell schedule) - `TimetableController` — `forClass` (returns `{klass, periods, entries}` combined payload), `replace` (bulk cell replace, skips empty cells), `upsertCell` (single-cell edit), `destroyCell`, `forTeacher` (`/v1/timetable/teacher/me` — authenticated teacher's own cells) - `LessonPlanController` — full CRUD with teacher ownership guard; teachers scoped to their own by default, admins with curriculum/lesson-plans edit permissions can see all - `SchemeOfWorkController` — same shape - `LearningResourceController` — CRUD + multipart file upload (stored on `public` disk under `learning-resources/`), external URL fallback, student-visibility filter (students see visibility=all + their klass + their enrolled subjects) - **5 resources** with frontend-parity aliases — timetable entries expose `day`/`day_of_week` + `time_slot` (computed from period start/end) so the existing grid rendering works without changes. - **22 new routes** under `/v1/timetable-periods`, `/v1/timetable/class/{klass}`, `/v1/timetable/teacher/me`, `/v1/lesson-plans`, `/v1/schemes-of-work`, `/v1/resources`. Permission-gated (`classes.timetable.*`, `academics.lesson-plans.*`, `academics.scheme-of-work.*`, `academics.curriculum.*`). - **Frontend-parity alias:** `GET /v1/logistics/timetable/{klass}` routes to the same `forClass` handler (existing `TeacherClassTimetableManagement.tsx` called that shape). **Smoke test on fresh `acad10b` tenant:** ``` POST /v1/timetable-periods → 4 periods seeded (P1, P2, Break, P3) with computed time_slots PUT /v1/timetable/class/1 → 4 cells populated (Mon P1/P2, Tue P1, Wed P4 — all Math/Admin) GET /v1/timetable/class/1 → {klass, periods[4], entries[4]} GET /v1/logistics/timetable/1 → alias returns identical shape GET /v1/timetable/teacher/me → 4 cells belonging to user 1 POST /v1/lesson-plans → "Fractions introduction" ULID 01KPZFFEF... POST /v1/schemes-of-work → term scheme with 3-week breakdown POST /v1/resources (multipart) → Khan Academy video link, visibility=klass GET /v1/resources → 1 row returned with type=video, is_external=true ``` **Frontend retrofit:** - `TeacherClassTimetableManagement.tsx` — replaced `/v1/classes` + `/v1/users?role=Teacher` with `/v1/klasses` + `/v1/teachers`; unwrapped `.data.data`; removed hardcoded `timeSlots` (now driven by fetched `timetable-periods`); added `DAY_CODE_TO_LABEL` mapping so the grid keeps rendering by "Monday"/"Tuesday" while the backend stores `mon`/`tue`; replaced mock `teacher_id === 1` personal-schedule filter with a real fetch against `/v1/timetable/teacher/me`. - `StudentMaterials.tsx` — added missing `useEffect` + `apiClient` imports; unwrapped `.data.data`; kept the existing group-by-subject rendering intact. - `npx tsc --noEmit` clean. --- ## Phase 10A — Assignments + Submissions + Grading **Backend (tenant schema):** - **5 migrations:** `assignments` (ULID, klass/subject/term/session/teacher refs, type∈{classwork,homework,test,quiz,project}, submission_channel∈{smart,manual,file_upload}, date_sent/due_date, shuffle + late + auto_grade flags, soft deletes), `assignment_questions` (mcq/multi/true-false/short-answer/essay/file + options + correct_answer JSON + marks + display_order), `submissions` (ULID, auto_score/manual_score/total_score/percentage/grade_letter, status∈{pending,in_progress,submitted,graded,late}, is_late flag, graded_by/graded_at, unique(assignment_id, student_id)), `submission_answers` (per-question answer + is_correct + marks_earned + feedback, unique per submission+question), `grades` (term-end aggregate — ca/midterm/exam scores, total/percentage, letter/grade_point/position, remark, unique(student, subject, term) — powers report cards in 10C). - **5 models:** `Assignment`, `AssignmentQuestion`, `Submission`, `SubmissionAnswer`, `Grade`. - **`AssignmentAutoGrader`** service — per-type comparators (exact for mcq/true-false, set equality for multiple-response, case-insensitive + accepted-variants for short-answer; essay/file → manual). Mirrors CbtAutoGrader so Phase 15 can merge them. - **2 controllers:** `AssignmentController` (index/show/store/update/publish/destroy + ownership guard — teachers scoped to their own by default, admins pass by permission), `SubmissionController` (studentIndex, submit with auto-grade pass, list per-assignment for teacher, bulkGrade, show). - **3 resources:** `AssignmentResource` (with `->withQuestions()` / `->withSubmissions()` / `->hidingAnswerKey()` toggles and frontend-parity aliases — `level`/`subject`/`term`/`session`/`preparedBy`/`dateSent`/`dueDate`/`students`), `AssignmentQuestionResource` (answer-key scrubbing via explicit `if` block — same pattern as Phase 8 CBT), `SubmissionResource`. - **11 routes** under `/v1/teacher/assignments/*` (index/show/store/update/publish/destroy/submissions/grade) and `/v1/assignments` + `/v1/assignments/{id}/submit` + `/v1/submissions/{id}` for student flow. All permission-gated (`academics.curriculum.*`). **Smoke test on fresh `acad10` tenant:** ``` POST /v1/teacher/assignments (3 MCQ questions) → ULID 01KPYCR... total_marks=3 status=draft POST /v1/teacher/assignments/{ulid}/publish → status=published (Seeded 2 students via bulk-import; patched into klass 1) SubmissionController + AssignmentAutoGrader applied → Ada 3/3 (100%), Bode 1/3 (33%) GET /v1/teacher/assignments → level=JSS 1 A, submitted=2, total=2 GET /v1/teacher/assignments/{ulid} → questions + students rows with percentage + Graded status PATCH /v1/teacher/assignments/{ulid}/grade → bulk override; Ada 3, Bode 2 → {updated: 2} ``` **Frontend retrofit:** - `TeacherAssignmentManagement.tsx` — unwrapped `.data.data`, added klass/subject/term fetch on mount (replaces hardcoded `CLASSES`/`SUBJECTS`), added Term selector, mapped UI type labels (MCQ/TrueFalse/MultipleResponse/etc) to backend kebab-case enum, packed correct-answer from `{text,isCorrect}` option shape into the backend's `options:[str]` + `correct_answer` shape. Bulk-grade score now parsed as float. Detail endpoint mirrors `students` to `submissions` so existing bulk-edit code paths work. - `StudentAssignments.tsx` — added missing imports (`useEffect` + `apiClient`), unwrapped `.data.data`, dropped hardcoded `student_id` and sends just `{responses}`; lets the backend resolve the student from `auth:sanctum`. - `npx tsc --noEmit` clean. **Rounds B + C pending:** timetables, lesson plans, schemes of work, learning resources, master sheet entry, report card PDF, portal aggregates (student/parent views). --- ## CBS payment gateway — steps a, b, c **Architecture:** - **Platform-wide CBS merchant** — all tenants transact through one Blouza merchant (credentials in `.env`). MDA id/name is per-tenant-overridable but defaults to Blouza's. - **Landlord `payment_invoices_index`** — `(institution_id, invoice_number, status)`. Every tenant Invoice create also drops a row here so CBS's global webhook URL can route the notification back to the owning tenant schema. - **Landlord `CbsWebhookController`** — `POST /cbs/webhook` reads the index, `Tenancy::initialize($institution)`, then delegates to tenant `CbsPaymentService::handleWebhookPayment`. `GET /cbs/callback` redirects the browser to `{FRONTEND_URL}/payment-status?status=...&reference=...&tenant=...`. - **Tenant `Invoice` + `Payment`** — Invoice carries ULID + `purpose ∈ {admission, acceptance, fee}` + CBS hosted URL. Payment enforces idempotency via a composite unique index on `(payment_ref, request_reference)`. - **CBS prefixes preserved from reference:** `ADM-` admission fee, `ACC-` acceptance fee, `EDU-` reserved for Phase 11 student-fee invoices. **Backend files added:** - `config/cbs.php` — env-driven merchant + split % + callback config - `app/Integrations/Cbs/Cbs.php` — HTTP client with HMAC-SHA256 basic auth, 23h token cache (file-backed to sidestep Stancl's taggable-store requirement), retry-once on 401 - `app/Services/Tenant/Payment/CbsPaymentService.php` — `createAdmissionInvoice()`, `createAcceptanceInvoice()`, `handleWebhookPayment()`, `fetchPayment()` (self-heal), `settleInvoiceManually()`. Reuses unpaid invoices per (applicant, purpose) so refreshes don't spam CBS. - `app/Http/Controllers/Landlord/CbsWebhookController.php` — the cross-tenant router - `app/Http/Controllers/Tenant/ApplicantPaymentController.php` — public endpoints (`generate*Fee`, `*FeeStatus`) that resolve applicant by `app_id`/`ulid` - `app/Models/Landlord/PaymentInvoiceIndex.php`, `app/Models/Tenant/{Invoice,Payment}.php` - 3 tenant migrations (`invoices`, `payments` with composite idempotency unique, `applicants` + `admission_forms` payment columns), 1 landlord migration (`payment_invoices_index`) - `routes/cbs.php` — application-root `/cbs/webhook` + `/cbs/callback` registered via `bootstrap/app.php` - 4 new public routes under `/api/v1/public/admission/applicants/{appId}/{application,acceptance}-fee` (GET + POST each) **Smoke test against a mocked CBS (`Http::fake`):** ``` createAdmissionInvoice → invoice ADM-PQ2OICJQ, total=5125 (5000 + 2.5% fee), payment_url set landlord index write → status=pending, institution_id set webhook apply (Paid=1, SUCCESS) → invoice paid, applicant.application_fee_status=paid idempotency replay → short-circuits, payments count stays 1 createAcceptanceInvoice → stage check enforced (offered/enrolled), invoice ACC-* acceptance webhook apply → applicant.acceptance_fee_status=paid landlord index after → both invoices marked paid cross-tenant ``` **Frontend files added:** - `src/pages/public/PaymentStatus.tsx` — CBS return landing page; reads `?status=&reference=&tenant=` query params - `src/pages/public/AdmissionStatus.tsx` — applicant portal; APP-ID lookup → shows stage + Pay Application Fee + (when stage=offered) Pay Acceptance Fee; opens hosted payment URL in new tab; refreshes status post-return - 3 new routes in `App.tsx`: `/admission/status`, `/admission/status/:appId`, `/payment-status` - `npx tsc --noEmit` clean. **Redis + cache driver:** - Local Redis is installed but password-protected. Scaffolded `REDIS_*` env vars and a verification command: `php artisan cache:verify [--tenant=]`. Verifies PING, landlord Cache::put/get, and Stancl tenant-tagged Cache::put/get. - Until Redis auth is supplied, `CACHE_STORE=file` is the default. CBS token caching uses `storage_path('framework/cache/cbs_token.json')` directly (bypasses Stancl's CacheTenancyBootstrapper which wraps the default store in a taggable proxy that the file driver can't satisfy). - To enable Redis: `sudo grep requirepass /etc/redis/redis.conf` → set `REDIS_PASSWORD=` in `.env` → `php artisan cache:verify --tenant=paytest` → flip `CACHE_STORE=redis` once green. --- **Phase 9 state (unchanged):** 🟢 Attendance live: teacher flow (roster → mark → save → lock), student flow (calendar + stats), parent flow (per-child tabs with real children), student-subject enrollment, student traits (affective/psychomotor/behavioural). `/auth/me` now surfaces `user.student/teacher/parent.children` so the frontend can identify the logged-in entity without extra calls. ## Phase 9 summary — Attendance + student traits + student-subject enrollment **Backend (tenant schema):** - **3 migrations:** `attendance` (unique `student_id+klass_id+date`, plus indexes on klass/date and date/status), `attendance_locks` (per class+date, stamps counts on lock), `student_subject` (enrollment pivot per session), `student_traits` (affective/psychomotor/behavioural rating + remark per term). - **4 tenant models:** `Attendance`, `AttendanceLock`, `StudentSubject`, `StudentTrait`. Extended `Student` with `subjects()`, `attendance()`, `traits()` relations. Extended `User` with `student()`, `teacher()`, `parentGuardian()` so `/auth/me` can surface the right profile per user type. - **3 controllers:** `AttendanceController` (roster/status/store/lock + student & class history views), `StudentSubjectController` (index/sync per-student + `enrollKlass` bulk-seed), `StudentTraitController` (grouped index + bulk upsert). - **`AttendanceResource`** — date-only format, ISO timestamps, minimal payload. - **Store behaviour:** `status=unmarked` deletes the row (so teachers can undo a mark); any other status does an `updateOrCreate`. Returns per-session counts. - **Lock behaviour:** computes final counts at lock-time and stamps them on `attendance_locks`. Subsequent stores are rejected with `423 Locked`. - **10 routes** wired in `routes/api.php` — teacher flow under `/teacher/attendance/*`, admin/parent flow under `/attendance/class/{klass}` and `/attendance/student/{student}`, curriculum management under `/students/{student}/{subjects,traits}` and `/klasses/{klass}/enroll-subjects`, all permission-gated (`attendance.*`, `user-mgmt.students.*`, `academics.curriculum.*`). **Verification on fresh Phase9 tenant (Blouza-provisioned, 3 JSS1A students Ada/Grace/Linus):** ``` GET /teacher/attendance/students?class_id=1 → 3 rows, all unmarked GET /teacher/attendance/status?class_id=1&date=today → {locked: false} POST /teacher/attendance (3 records: present/late/absent) → counts {1,1,1,0,3} GET /teacher/attendance/students (post-mark) → all 3 reflect status + times + remarks PATCH /teacher/attendance/lock → {locked: true, locked_at: ...} POST /teacher/attendance (retry post-lock) → HTTP 423 ✓ GET /attendance/student/1 → Ada's history + stats PUT /students/1/subjects ({11,15,3}) → 3 rows enrolled for session 1 PUT /students/1/traits (2 traits, term 1) → grouped {affective:[1], psychomotor:[1]} POST /klasses/1/enroll-subjects ({11,15,3}) → enrolled: 6 (3 students × 3 subjects - 3 already-linked for Ada) ``` **Frontend retrofit:** - **`TeacherAttendanceManagement.tsx`** — dropped mock `class_id=1`. On mount, fetches `/v1/klasses`, sets first klass as default, exposes a class picker in the header. Unwraps `.data.data` on roster + status. Save/Lock use `selectedKlassId`; errors surface backend `message`. Klass change triggers re-fetch. - **`StudentAttendance.tsx`** — imports `apiClient` + `useEffect` + `toast` (weren't imported before). Pulls `student.id` from `/auth/me`, then hits `/v1/attendance/student/{id}`. Maps records + stats into the calendar view + summary cards. - **`parent/Attendance.tsx`** — removed hardcoded `ATTENDANCE_DATA` mock + hardcoded "Emma Johnson"/"Michael Johnson" tabs. Fetches `user.parent.children` from `/auth/me`, renders one tab per child, each `` hits `/v1/attendance/student/{childId}` independently. Graceful empty state when no children are linked. - **`/auth/me` extension** — `UserResource` now includes `student`, `teacher`, `parent.children` blocks (only when those relations are loaded). Both `login` and `me` eager-load them. Verified via tinker that Ada's record returns `{student: {id:1, admission_number:'2026-001', klass_id:1}}`. - `npx tsc --noEmit` clean. ## Phase 8 summary — Computer-Based Testing (CBT) **Backend (tenant schema):** - **3 migrations:** `cbt_questions`, `cbt_tests` + `cbt_test_questions` pivot, `cbt_attempts` + `cbt_attempt_answers` (polymorphic taker — Student or Applicant). - **`App\Enums\CbtQuestionType`** — mcq / multi / true-false / short-answer / essay, with `isAutoGradeable()`. - **4 tenant models:** `CbtQuestion`, `CbtTest`, `CbtAttempt` (polymorphic), `CbtAttemptAnswer`. All user-facing entities auto-generate ULIDs on create; `getRouteKeyName()` uses ULID. - **`CbtAutoGrader` service** — per-type comparators (exact for MCQ/TF, set-match for multi-response, case-insensitive + accepted-variants for short-answer; essay → manual). `gradeAttempt()` iterates answer rows, writes per-question is_correct + marks_earned, returns subtotal. - **2 actions:** `StartAttempt` (enforces max_attempts, resumes in-progress, pre-creates skeleton answer rows for round-trip), `SubmitAttempt` (upserts answers, auto-grades, computes total/percentage/grade_letter via `GradeScale::letterFor()`, passed flag, writes `entrance_exam_score` back onto Applicant when test purpose=admission). - **4 controllers:** `CbtQuestionController` (vault CRUD), `CbtTestController` (CRUD + `POST /publish` + question attach/sync), `CbtTakeController` (authenticated student: available → start → show → submit), `CbtPublicTakeController` (unauthenticated applicant flow keyed by `cbt_token` minted in Phase 7). - **3 API Resources** — `CbtQuestion`/`CbtTest`/`CbtAttempt`. Both question and test resources ship a `->hidingAnswerKey()` / `->showingAnswerKey()` toggle so public takers never see `correct_answer` or `explanation` even though the vault has them. - **Answer-key leak fix:** `$this->when()` returns a `MissingValue` sentinel that only Laravel's own response pipeline filters — when `CbtTestResource` calls `CbtQuestionResource::toArray()` manually, the sentinel leaks through. Rewrote `CbtQuestionResource::toArray()` to build the payload with an explicit `if (! $this->hideAnswerKey)` block. - **`CbtQuestionSeeder`** reads `database/data/setup-templates/cbt_questions_template.csv` (17 K-12 MCQs across MATH/ENG/BSC/PHY/CHM/BIO/GOV/ECO/SOS/CIV/LIT), wires in programs + grade-levels by code, stores correct answer as the option string (not the letter). - **~18 routes** — admin side permission-gated (`cbt.create/edit/delete/approve`), student side uses `auth:sanctum` + own-attempt ownership check, public side throttle `20/min`. - **Bug fix during smoke test:** `CbtTestController::store` was passing the `question_ids` input into `CbtTest::create()` (which tried to insert an array as a column → "Array to string conversion"). Unset before create. **Verification on fresh Blouza tenant (temp password: KDqL5c2rCU3M):** ``` GET /cbt/vault → 17 questions POST /cbt/tests (3 questions) → test ulid, total_marks=3 POST /admission/applicants/{id}/assign-exam → cbt_token=MS50XEIYF4 GET /public/cbt/{token} → intro OK; answer_key_hidden=TRUE ✓ POST /public/cbt/{token}/start → attempt ulid POST /public/cbt/{token}/attempts/{id}/submit (2 correct, 1 wrong) → status=graded, score=2/3, percentage=66.67%, letter=B, passed=True GET /admission/applicants/{id} → entrance_exam_score=66.67 (auto-written) GET /public/cbt/BOGUSTOKEN → 404 "Invalid CBT token." ``` **Frontend (`TeacherExaminationManagement.tsx`):** - `fetchVault` unwraps `response.data?.data`. - `handleSubmitAssessment` maps UI's Title-Case `type` to the backend's kebab-case enum, renames `text`→`content`, passes `correct_answer`, wraps single tag into array, adds `topic`. - Surfaces backend validation errors from `error.response.data.message`. - `npx tsc --noEmit` clean. ## Phase 7 summary — Admission pipeline ## Post-Phase-7 cross-cutting audit — applied fixes Three parallel Explore agents audited backend, frontend, and integration seams after Phase 7. Triaged findings (dropped false positives and Phase 8+ out-of-scope items), applied the real ones: **Backend authorization — defense-in-depth on write routes (24 routes changed):** - Added `permission:` middleware to every write route that previously only had controller-level `$this->guard()` guards. Authorization is now visible in `route:list` and rejects unauthorized requests before the controller runs. Covered: `POST/PUT/DELETE /students|teachers|parents|staff|admin/users|bulk-import/*`, `POST /school-setup/{logo,login-bg,progress/{step}}`, `POST/PUT/DELETE /admission/{forms,applicants/{id}/*}`. **`PublicAdmissionController::assertTenant()`** — asserts `tenancy()->initialized` at the top of `showForm`, `apply`, and `status`. Defense against silent middleware bypass; verified that a bare request without `X-Tenant-Id` now gets `HTTP 400 { message: "Tenant not identified..." }` instead of silently writing to the wrong schema. **`ProvisionInstitution` orphan-rollback** — wrapped the "create first admin user" step in try/catch. On failure, the entire institution is `forceDelete()`d (which drops the tenant schema via Stancl's `TenantDeleted` hook), and a `RuntimeException` surfaces the underlying error. Prevents stranded tenants after a partial provision. **`ParentController::update`** — added for parity with Student/Teacher/Staff controllers. Accepts first/last/phone, occupation/employer/address, status, and `children_admission_numbers` for re-syncing the pivot. **Delete response shape** — ParentController::destroy now returns `{data: null, message: "..."}`. Phase 15 cleanup will normalize the remaining delete methods uniformly. **`config/cors.php`** — added `X-Tenant-Id` and `X-Tenant` to `allowed_headers`. Strict CORS browsers now explicitly allow the tenant header. **`bootstrap/app.php`** — removed the redundant `prependToPriorityList` call. `AppServiceProvider::boot()`'s reflection-based prepend (runs after Stancl's provider) is the single source of truth for middleware priority. **Frontend cleanup:** - `RoleManagement.tsx` — deleted 95 lines of `_unusedInitialRoles` mock data that wasn't read anywhere. - `UserManagement.tsx` — replaced the 160+ lines of hardcoded mock `students`, `financeStaff`, `parents` arrays with empty `[]` initializers. The page now renders an empty state until `fetchUsers()` populates from the backend. **Smoke-tested post-audit** — tenant login works, POST /students → 201 with permission check, PUT /parents/{id} → 200 (new endpoint), public apply with header → 201, public apply without header → 400 (tenancy assert), frontend `npx tsc --noEmit` clean. **Acknowledged but deferred (out of Phase 7 scope):** - Services.tsx (Phase 12 logistics page) response-shape unwrap - WebsiteBuilder.tsx (Phase 14) - AdminDashboard.tsx aggregate stats (Phase 10+ once academic data is populated) - SchoolSetup.tsx `MOCK_ADMIN_STAFF` replacement (needs the Phase 10 timetable period endpoints) - Full FormRequest extraction across controllers (Phase 15 cross-cutting pass) - Splitting GradeConfigController into per-resource controllers (polish) - Normalising remaining `{message: ...}` delete responses (Phase 15 pass) ## Phase 7 summary — Admission pipeline **Backend (tenant schema):** - **5 migrations:** `admission_stages` (ref), `admission_forms` + `admission_criteria` + `screening_requirements`, `applicants`, `applicant_documents`, `applicant_status_histories`. - **7 models:** `AdmissionStage`, `AdmissionForm`, `AdmissionCriterion`, `ScreeningRequirement`, `Applicant` (auto-generates `app_id` and `ulid` on create; routes keyed on `ulid`), `ApplicantDocument`, `ApplicantStatusHistory`. - **Enum `App\Enums\ApplicantStage`** — codes: `applied`, `screening`, `entrance-exam`, `interaction`, `offered`, `enrolled`, with `allowedNext()` forward-transition map. - **3 actions** under `app/Actions/Tenant/Admission/`: `MoveApplicantToStage` (validates code, writes audit row, updates stage), `AssignCbtToApplicant` (generates unique 10-char token, stamps exam metadata, transitions to `entrance-exam`), `EnrollApplicant` (creates User + Student + ParentGuardian + pivot link, auto-generates `ADM-YYYY-NNNNN` admission number, returns temp password, transitions to `enrolled`). - **4 controllers** — `ApplicantController` (index with `by_stage` summary, show, update, setStage, assignCbt, enroll, destroy), `AdmissionFormController` (CRUD), `PublicAdmissionController` (unauth: showForm, apply, status), `AdmissionReferenceController` (stages + document types). - **4 API Resources** — `ApplicantResource` (with nested status_history + documents + frontend-friendly `currentStage` label), `ApplicantDocumentResource`, `AdmissionFormResource`, `AdmissionStageResource`. - **`AdmissionStageSeeder`** — reads `defaults/admission_stages.csv`, 6 stages with display order + colours. - **~15 routes** — admin-side gated by `admissions.*` permission codes; public-side throttled `10/min`, tenant-scoped via `X-Tenant-Id` or subdomain. **End-to-end smoke (fresh Blouza tenant):** - `GET /admission/stages` → 6 rows; `/admission/document-types` → 8 rows. - Public `POST /public/admission/apply` → creates applicant `APP-0C4C6C`, stage=applied, returns tracking URL. - Admin `GET /admission/applicants` → 1 applicant with `by_stage: {applied: 1}` meta. - Stage transitions: applied → screening → (assign CBT token `LUXYXLCXPQ` + exam date/venue) → entrance-exam → update exam_score=82.5 → interaction → offered — all 200. - Enroll → creates Student `ADM-2026-00001` + User + ParentGuardian (with test.parent@example.com) + pivot, returns temp password, applicant stage=enrolled. - Status history trace: 6 rows preserved (new → applied → screening → entrance-exam → interaction → offered → enrolled) with remarks for each. - Public `GET /public/admission/status/APP-0C4C6C` → returns current stage + CBT token + enrolment flag (no PII beyond what was submitted). - `/students` and `/parents` both show count=1 (the newly-enrolled applicant + their parent). **Frontend retrofit (`Admissions.tsx`):** - `CRM_STAGES` replaced with `{code, label}` tuples so the `