113 lines
8.6 KiB
Markdown
113 lines
8.6 KiB
Markdown
---
|
|
phase: 05-visibility-and-client-portal
|
|
verified: 2026-03-05T17:50:00Z
|
|
status: passed
|
|
score: 5/5 must-haves verified
|
|
---
|
|
|
|
# Phase 5: Visibility and Client Portal Verification Report
|
|
|
|
**Phase Goal:** The ISP owner can see the complete financial and operational picture on a single dashboard; subscribers can log in to view their bills, payment history, and plan details, and submit tickets; and the full system is covered by integration and end-to-end tests on critical workflows.
|
|
**Verified:** 2026-03-05T17:50:00Z
|
|
**Status:** PASSED
|
|
**Re-verification:** No -- initial verification
|
|
|
|
## Goal Achievement
|
|
|
|
### Observable Truths
|
|
|
|
| # | Truth | Status | Evidence |
|
|
|---|-------|--------|----------|
|
|
| 1 | Dashboard shows revenue today/month, overdue count, outstanding amount, subscriber breakdown, cash flow summary | VERIFIED | DashboardService (424 lines) with 6 methods: getRevenueMetrics, getOverdueMetrics, getSubscriberMetrics, getCashFlowSummary, getCollectorSummary, getDashboardSummary. GET /api/dashboard returns composite. 6 integration tests pass. |
|
|
| 2 | Subscriber can log in to portal and view bill, balance, payment history, plan details -- scoped to own account | VERIFIED | Portal credentials provider in auth-options.ts with subscriberId in JWT. PortalService (123 lines) with getPortalAccount, getPortalInvoices, getPortalPayments. withPortalAuth middleware enforces subscriberId scope. 5 integration tests pass including cross-subscriber isolation test. |
|
|
| 3 | Subscriber can submit a support ticket and it appears in staff ticket queue | VERIFIED | PortalTicketService (283 lines) delegates to createTicket() with source=SUBSCRIBER. Shadow User pattern bridges FK constraint. Test explicitly verifies staff listTickets includes portal-created ticket. 6 integration tests pass. |
|
|
| 4 | All API endpoints have integration tests asserting RBAC enforcement for authorized/unauthorized roles | VERIFIED | api-rbac.test.ts (851 lines, 43 tests): Authentication 401/403, all 5 roles tested against CASL subjects, withPermission HOF enforcement, two-tenant data isolation with real DB records. All 43 tests pass. |
|
|
| 5 | Critical workflows pass end-to-end tests (billing, collection/remittance, ticket/job-order) | VERIFIED | e2e-workflows.test.ts (685 lines, 16 tests): Billing (register -> invoice -> payment -> trial balance -> dashboard), Collection (field collection -> remittance -> verification -> balanced JEs -> dashboard), Ticket (create -> job order -> completion -> auto-resolve -> close). Trial balance verified balanced after each workflow. All 16 tests pass. |
|
|
|
|
**Score:** 5/5 truths verified
|
|
|
|
### Required Artifacts
|
|
|
|
| Artifact | Expected | Status | Details |
|
|
|----------|----------|--------|--------|
|
|
| src/lib/services/dashboard-service.ts | Dashboard metric aggregation | VERIFIED | 424 lines, 6 methods, Prisma aggregate/groupBy, Promise.all parallel |
|
|
| src/app/api/dashboard/route.ts | Dashboard API endpoint | VERIFIED | 49 lines, withPermission read Report, date params |
|
|
| src/lib/__tests__/dashboard-service.test.ts | Dashboard tests | VERIFIED | 445 lines, 6 tests passing |
|
|
| src/lib/services/portal-service.ts | Subscriber-scoped data retrieval | VERIFIED | 123 lines, 3 methods with pagination |
|
|
| src/lib/middleware/portal-auth.ts | Portal auth middleware | VERIFIED | 64 lines, withPortalAuth HOF, 401/403 enforcement |
|
|
| src/app/api/portal/account/route.ts | Portal account endpoint | VERIFIED | 20 lines, withPortalAuth, calls getPortalAccount |
|
|
| src/app/api/portal/invoices/route.ts | Portal invoices endpoint | VERIFIED | 20 lines, withPortalAuth, calls getPortalInvoices |
|
|
| src/app/api/portal/payments/route.ts | Portal payments endpoint | VERIFIED | 20 lines, withPortalAuth, calls getPortalPayments |
|
|
| src/lib/__tests__/portal-service.test.ts | Portal service tests | VERIFIED | 352 lines, 5 tests passing |
|
|
| src/lib/services/portal-ticket-service.ts | Portal ticket creation + threads | VERIFIED | 283 lines, 5 functions, shadow User pattern |
|
|
| src/app/api/portal/tickets/route.ts | Portal ticket list/create | VERIFIED | 46 lines, GET + POST |
|
|
| src/app/api/portal/tickets/[id]/route.ts | Portal ticket detail | VERIFIED | 21 lines, GET with thread |
|
|
| src/app/api/portal/tickets/[id]/comments/route.ts | Ticket comments | VERIFIED | 61 lines, GET + POST |
|
|
| src/app/api/portal/payments/coming-soon/route.ts | Payment scaffold | VERIFIED | 42 lines, outstanding balance + instructions (gateway deferred to v2) |
|
|
| src/lib/__tests__/portal-ticket-service.test.ts | Portal ticket tests | VERIFIED | 340 lines, 6 tests passing |
|
|
| src/lib/__tests__/integration/api-rbac.test.ts | RBAC integration tests | VERIFIED | 851 lines, 43 tests passing |
|
|
| src/lib/__tests__/integration/e2e-workflows.test.ts | E2E workflow tests | VERIFIED | 685 lines, 16 tests passing |
|
|
|
|
### Key Link Verification
|
|
|
|
| From | To | Via | Status | Details |
|
|
|------|----|-----|--------|--------|
|
|
| Dashboard API route | DashboardService | import + getDashboardSummary call | WIRED | Route calls service, returns JSON response |
|
|
| DashboardService | Prisma Payment/Invoice/Subscriber/JE | aggregate/groupBy queries | WIRED | Real DB queries with proper filters |
|
|
| Portal auth | NextAuth JWT | subscriberId in token + session | WIRED | Dual CredentialsProvider, subscriberId persisted |
|
|
| Portal API routes | withPortalAuth | HOF wrapper | WIRED | All portal routes use withPortalAuth, subscriberId passed to service |
|
|
| Portal API routes | PortalService | import + function calls | WIRED | Account/invoices/payments endpoints call service functions |
|
|
| PortalService | Prisma queries | findFirst/findMany with subscriberId filter | WIRED | All queries scoped to subscriberId |
|
|
| Portal ticket | Staff ticket queue | createTicket() delegation with source=SUBSCRIBER | WIRED | Test verifies staff listTickets includes portal ticket |
|
|
| Portal ticket | User FK | ensurePortalUser shadow User | WIRED | Lazy creates User with CLIENT role for FK bridge |
|
|
| E2E tests | All services | Direct service function imports | WIRED | 12 service imports covering billing, collection, ticketing |
|
|
| RBAC tests | CASL + withPermission | Mock getCurrentUser + ability checks | WIRED | All 5 roles tested, HOF enforcement verified |
|
|
|
|
### Requirements Coverage
|
|
|
|
| Requirement | Status | Notes |
|
|
|-------------|--------|-------|
|
|
| DASH-01 | SATISFIED | Revenue today/month via getRevenueMetrics |
|
|
| DASH-02 | SATISFIED | Overdue count + outstanding via getOverdueMetrics |
|
|
| DASH-03 | SATISFIED | Active/suspended/cancelled via getSubscriberMetrics |
|
|
| DASH-04 | SATISFIED | Cash flow (money in vs out) via getCashFlowSummary |
|
|
| PORT-01 | SATISFIED | Portal login via account number + password, bill/balance view |
|
|
| PORT-02 | SATISFIED | Payment history via getPortalPayments with pagination |
|
|
| PORT-03 | SATISFIED | Ticket submission via createPortalTicket with staff visibility |
|
|
| PORT-04 | SATISFIED | Plan details in getPortalAccount (name, speed, price, billingType) |
|
|
| PORT-05 | SATISFIED (scaffold) | Payment coming-soon endpoint with balance + instructions; gateway deferred to v2 per PROJECT.md |
|
|
| INFRA-03 | SATISFIED | 43 RBAC integration tests across 5 roles + tenant isolation |
|
|
| INFRA-04 | SATISFIED | 16 e2e tests across 3 critical workflows with balanced trial balance verification |
|
|
|
|
### Anti-Patterns Found
|
|
|
|
| File | Line | Pattern | Severity | Impact |
|
|
|------|------|---------|----------|--------|
|
|
| portal-service.ts | 32 | return null | Info | Legitimate null check for subscriber not found |
|
|
| portal-ticket-service.ts | 208, 213 | return null | Info | Legitimate null checks for ticket not found / subscriber scoping |
|
|
| coming-soon/route.ts | 40 | Online payments coming soon | Info | Intentional scaffold per PORT-05 v2 deferral |
|
|
|
|
No blockers or warnings found.
|
|
|
|
### Human Verification Required
|
|
|
|
#### 1. Portal Login Flow
|
|
**Test:** Navigate to portal login page, enter subscriber account number and password, verify session persists
|
|
**Expected:** Subscriber sees their account overview with plan details, balance, billing day
|
|
**Why human:** Auth flow requires browser session, NextAuth redirect handling
|
|
|
|
#### 2. Dashboard Visual Layout
|
|
**Test:** Log in as admin, navigate to dashboard page
|
|
**Expected:** All 5 metric sections render with real data, no layout breaks
|
|
**Why human:** Phase 5 built the API layer only -- dashboard UI consumption needs frontend verification
|
|
|
|
#### 3. Portal Ticket Submission UX
|
|
**Test:** As a subscriber, submit a ticket through the portal UI, then log in as staff and check ticket queue
|
|
**Expected:** Ticket appears in staff queue with SUBSCRIBER source label
|
|
**Why human:** End-to-end browser flow crossing two auth contexts
|
|
|
|
---
|
|
|
|
_Verified: 2026-03-05T17:50:00Z_
|
|
_Verifier: Claude (gsd-verifier)_
|