From ab1e94480e3c91e158860698ec0643012fcbba21 Mon Sep 17 00:00:00 2001 From: kevin-asprec Date: Thu, 5 Mar 2026 17:28:03 +0800 Subject: [PATCH] docs(05-02): complete Subscriber Portal Auth and API plan Tasks completed: 2/2 - Portal authentication via subscriber account number - PortalService, API routes, and integration tests (5 tests) SUMMARY: .planning/phases/05-visibility-and-client-portal/05-02-SUMMARY.md Co-Authored-By: Claude Opus 4.6 --- .planning/STATE.md | 29 +++-- .../05-02-SUMMARY.md | 109 ++++++++++++++++++ 2 files changed, 126 insertions(+), 12 deletions(-) create mode 100644 .planning/phases/05-visibility-and-client-portal/05-02-SUMMARY.md diff --git a/.planning/STATE.md b/.planning/STATE.md index 12274e7..68b7868 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -10,18 +10,18 @@ See: .planning/PROJECT.md (updated 2026-03-04) ## Current Position Phase: 5 of 5 (Visibility and Client Portal) -Plan: 1 of 5 in phase 5 (24/28 total complete) -Status: In progress. 05-01 complete (Dashboard Metrics API). -Last activity: 2026-03-05 — Completed 05-01-PLAN.md (Dashboard Metrics API — 6 tests, revenue/overdue/subscriber/cashflow/collector metrics) +Plan: 2 of 5 in phase 5 (25/28 total complete) +Status: In progress. 05-01 and 05-02 complete. +Last activity: 2026-03-05 — Completed 05-02-PLAN.md (Subscriber Portal Auth and API — 5 tests, portal credentials provider, subscriber-scoped endpoints) -Progress: [████████████████████████░░░░] 86% (24/28 plans across all phases) +Progress: [█████████████████████████░░░] 89% (25/28 plans across all phases) ## Performance Metrics **Velocity:** -- Total plans completed: 17 -- Average duration: 10.3 min -- Total execution time: 178 min +- Total plans completed: 18 +- Average duration: 10.1 min +- Total execution time: 182 min **By Phase:** @@ -31,11 +31,11 @@ Progress: [███████████████████████ | 02-subscriber-and-billing-core | 5/5 complete | 57 min | 11.4 min | | 03-operational-modules | 5/5 complete | ~65 min | ~13 min | | 04-inventory-expenses-reports | 5/5 complete | 71 min | 14.2 min | -| 05-visibility-and-client-portal | 1/5 complete | 3 min | 3 min | +| 05-visibility-and-client-portal | 2/5 complete | 7 min | 3.5 min | **Recent Trend:** -- Last 10 plans: 03-02 (11 min), 03-04 (6 min), 03-05 (9 min), 04-01 (16 min), 04-03 (17 min), 04-05 (10 min), 04-02 (8 min), 04-04 (20 min), 05-01 (3 min) -- Trend: 05-01 fastest plan yet — pure service + API + tests, no schema changes +- Last 10 plans: 03-04 (6 min), 03-05 (9 min), 04-01 (16 min), 04-03 (17 min), 04-05 (10 min), 04-02 (8 min), 04-04 (20 min), 05-01 (3 min), 05-02 (4 min) +- Trend: Phase 5 plans executing fast — service + API + tests pattern, minimal schema changes *Updated after each plan completion* @@ -147,6 +147,11 @@ Recent decisions affecting current work: - [05-01]: Cash flow uses same approach as FinancialReportService — POSTED JE lines on revenue (4xxx) and expense (5xxx) accounts with normal balance logic - [05-01]: getDashboardSummary runs all 5 metric methods in parallel via Promise.all - [05-01]: Dashboard cleanup order: expenses -> vendors -> expenseCategories (custom) -> collectionAllocations -> collections -> remittances -> paymentAllocations -> payments -> invoiceLines -> invoices -> journalEntryLines -> null reversesEntryId -> journalEntries -> zoneAssignments -> subscribers -> zones -> servicePlans -> accountingPeriods -> accounts -> ticketCategories -> expenseCategories (system) -> users -> tenant +- [05-02]: Dual NextAuth credentials providers (staff id=credentials, portal id=portal-credentials) on same instance — additive, no change to staff auth +- [05-02]: Subscriber.passwordHash is nullable — only subscribers with a set password can log in to portal +- [05-02]: subscriberId persisted in JWT token and session — distinguishes portal users from staff users without DB lookup +- [05-02]: withPortalAuth HOF validates subscriberId in session; 401 if no session, 403 if not portal user +- [05-02]: Portal cleanup order: payments -> paymentAllocations -> invoiceLines -> invoices -> journalEntryLines -> null reversesEntryId -> journalEntries -> subscribers -> servicePlans -> tenantSettings -> accountingPeriods -> accounts -> users -> tenant ### Pending Todos @@ -164,6 +169,6 @@ None. ## Session Continuity -Last session: 2026-03-05T09:23:00Z -Stopped at: Completed 05-01-PLAN.md (Dashboard Metrics API — 6 tests, all passing). +Last session: 2026-03-05T09:25:00Z +Stopped at: Completed 05-02-PLAN.md (Subscriber Portal Auth and API — 5 tests, portal credentials, subscriber-scoped endpoints). Resume file: None diff --git a/.planning/phases/05-visibility-and-client-portal/05-02-SUMMARY.md b/.planning/phases/05-visibility-and-client-portal/05-02-SUMMARY.md new file mode 100644 index 0000000..a1912d0 --- /dev/null +++ b/.planning/phases/05-visibility-and-client-portal/05-02-SUMMARY.md @@ -0,0 +1,109 @@ +--- +phase: 05-visibility-and-client-portal +plan: 02 +subsystem: portal +tags: [portal, auth, subscriber, nextauth, credentials, invoices, payments, account] + +# Dependency graph +requires: + - phase: 01-foundation + provides: NextAuth v4 with JWT strategy, withTenantContext, middleware auth exclusions + - phase: 02-subscriber-and-billing-core + provides: Subscriber, Invoice, Payment, ServicePlan models +provides: + - Portal credentials provider (accountNumber + password login) + - PortalService with subscriber-scoped data retrieval + - Portal API routes (account, invoices, payments) + - withPortalAuth middleware for portal endpoint authorization +affects: [05-03 (portal UI consumes these APIs), 05-05 (e2e tests)] + +# Tech tracking +tech-stack: + added: [] + patterns: + - "Dual NextAuth credentials provider (staff + portal) on same instance" + - "subscriberId in JWT/session for portal user identification" + - "withPortalAuth HOF for portal-only endpoint authorization" + +key-files: + created: + - src/lib/services/portal-service.ts + - src/lib/middleware/portal-auth.ts + - src/app/api/portal/account/route.ts + - src/app/api/portal/invoices/route.ts + - src/app/api/portal/payments/route.ts + - src/lib/__tests__/portal-service.test.ts + modified: + - prisma/schema.prisma + - src/lib/auth-options.ts + - src/types/next-auth.d.ts + - src/middleware.ts + +# Decisions +decisions: + - id: "portal-dual-provider" + description: "Two CredentialsProviders on same NextAuth instance (id: credentials, id: portal-credentials) -- additive, no change to staff auth" + - id: "portal-password-nullable" + description: "Subscriber.passwordHash is nullable -- only subscribers with a set password can log in to portal" + - id: "portal-subscriberId-jwt" + description: "subscriberId persisted in JWT token and session -- distinguishes portal users from staff users without DB lookup" + +# Metrics +metrics: + duration: "4 min" + completed: "2026-03-05" + tasks: 2 + tests: 5 +--- + +# Phase 05 Plan 02: Subscriber Portal Authentication and API Summary + +**Portal auth via account number + password with subscriber-scoped read-only API endpoints, 5 tests passing** + +## What Was Done + +### Task 1: Portal Authentication +- Added `passwordHash` (nullable String) to Subscriber model in Prisma schema +- Added second CredentialsProvider (`portal-credentials`) to NextAuth config accepting accountNumber + password + tenantId +- Provider looks up subscriber by @@unique([tenantId, accountNumber]) with non-null passwordHash +- JWT callback persists `subscriberId` into token; session callback exposes it on session.user +- Extended next-auth type definitions (Session, User, JWT) with optional `subscriberId` +- Updated middleware matcher to exclude `/portal/login` and `/api/portal/auth` from auth requirement + +### Task 2: PortalService and API Routes +- Created `PortalService` with three subscriber-scoped methods: + - `getPortalAccount(db, subscriberId)` -- returns profile, plan details, credit balance, billing day + - `getPortalInvoices(db, subscriberId, options)` -- paginated invoices with line items, ordered by periodStart DESC + - `getPortalPayments(db, subscriberId, options)` -- paginated payments, ordered by createdAt DESC +- Created `withPortalAuth` middleware HOF that validates subscriberId in session (401 if no session, 403 if not portal user) +- Created three portal API routes: + - `GET /api/portal/account` -- subscriber profile + plan + - `GET /api/portal/invoices` -- paginated invoices (query: page, limit) + - `GET /api/portal/payments` -- paginated payments (query: page, limit) + +### Integration Tests (5/5 passing) +1. `getPortalAccount returns subscriber with plan details` -- verifies all fields including plan name, speed, price, billingType +2. `getPortalInvoices returns paginated invoices` -- creates 3 invoices, verifies page 1 limit 2 returns 2 with total 3 +3. `getPortalPayments returns paginated payment history` -- creates 2 payments, verifies list and subscriber scoping +4. `getPortalAccount scoped to subscriberId only` -- creates 2 subscribers, verifies each sees only own data +5. `getPortalInvoices includes invoice line items` -- verifies lines array populated with description and lineTotal + +## Deviations from Plan + +None -- plan executed exactly as written. + +## Commits + +| Hash | Message | +|------|---------| +| 539564d | feat(05-02): portal authentication via subscriber account number | +| 7222dbe | feat(05-02): portal service, API routes, and integration tests | + +## Requirements Satisfied + +- **PORT-01**: Subscriber can log in with account number and password +- **PORT-02**: Subscriber can view current bill and outstanding balance (via invoices endpoint + account creditBalance) +- **PORT-04**: Subscriber can view full payment history (via payments endpoint) +- Account overview includes plan details, balance, and billing day +- Invoice and payment history are paginated +- Portal API endpoints scoped to logged-in subscriber only