NetForge/.planning/phases/05-visibility-and-client-portal/05-05-PLAN.md

phase, plan, type, wave, depends_on, files_modified, autonomous, must_haves

phase	plan	type	wave	depends_on	files_modified	autonomous	must_haves
05-visibility-and-client-portal	05	execute	3	05-01 05-02 05-03	src/lib/__tests__/integration/e2e-workflows.test.ts	true	truths artifacts key_links Subscriber registration through invoice generation through payment recording works as a single workflow Collector collection through remittance verification works end-to-end with correct JE postings Ticket creation through job order completion triggers auto-resolve All JEs produced during workflows are balanced (debits = credits) Data created by workflows appears correctly in dashboard metrics path provides min_lines src/lib/__tests__/integration/e2e-workflows.test.ts End-to-end workflow tests for critical business processes 250 from to via pattern src/lib/__tests__/integration/e2e-workflows.test.ts src/lib/services/*.ts orchestrates multiple services in sequence (SubscriberService|BillingService|PaymentService|CollectorService|RemittanceService|TicketService|JobOrderService|DashboardService)

Create end-to-end tests that exercise critical user workflows from start to finish, verifying that all services integrate correctly and produce accurate accounting entries.

Purpose: INFRA-04 — prove that the system works as a coherent whole, not just isolated units. Output: E2E workflow test suite covering the three critical business processes.

<execution_context> @C:\Users\KevinAsprec.claude/get-shit-done/workflows/execute-plan.md @C:\Users\KevinAsprec.claude/get-shit-done/templates/summary.md </execution_context>

@.planning/PROJECT.md @.planning/ROADMAP.md @.planning/STATE.md

@src/lib/services/subscriber-service.ts @src/lib/services/billing-service.ts @src/lib/services/payment-service.ts @src/lib/services/collector-service.ts @src/lib/services/remittance-service.ts @src/lib/services/ticket-service.ts @src/lib/services/job-order-service.ts @src/lib/services/dashboard-service.ts @src/lib/accounting/journal-entry-service.ts

Task 1: Billing workflow end-to-end test src/lib/__tests__/integration/e2e-workflows.test.ts Create the e2e test file with the first critical workflow.

Setup (shared across all workflows in this file):

• Create tenant (triggers COA seed, ticket category seed)
• Create admin user, office staff user, collector user, technician user
• Create service plan
• Create zone, assign collector to zone

Workflow 1: Subscriber Registration -> Invoice Generation -> Payment Recording

Test as a sequential story:

describe("E2E: Billing Workflow")

  test("1. Register a new subscriber")
    - Call createSubscriber with name, address, plan
    - Verify: subscriber created with ACTIVE status, accountNumber generated (SUB-NNNN)
    - Verify: subscriber has the correct plan assigned

  test("2. Generate invoice for subscriber")
    - Call generateInvoiceForSubscriber (from BillingService)
    - Verify: invoice created with correct totalAmount matching plan price
    - Verify: invoice has UNPAID status
    - Verify: JE posted (DR 1100 AR, CR 4010 Service Revenue) — verify via JournalEntryService.getTrialBalance or direct query

  test("3. Record full payment against invoice")
    - Call recordPayment with full invoice amount
    - Verify: invoice status = PAID, amountPaid = totalAmount
    - Verify: payment created with COMPLETED status
    - Verify: JE posted (DR 1010 Cash, CR 1100 AR)

  test("4. Record partial payment on second invoice")
    - Generate second invoice
    - Record partial payment (50% of amount)
    - Verify: invoice status = PARTIAL, amountPaid = partial amount
    - Verify: JE for partial amount is balanced

  test("5. Verify trial balance is balanced after all transactions")
    - Call getTrialBalance
    - Verify: totalDebits === totalCredits (books are self-verifying)

  test("6. Dashboard reflects billing activity")
    - Call getRevenueMetrics
    - Verify: revenueToday includes the payments made
    - Call getSubscriberMetrics
    - Verify: active count includes the registered subscriber

Use the existing service functions directly (not HTTP calls). This tests the service integration layer. npx vitest run src/lib/__tests__/integration/e2e-workflows.test.ts — billing workflow tests pass Billing workflow e2e test passes: subscriber -> invoice -> payment -> balanced books -> dashboard reflects

Task 2: Collection and ticket workflow end-to-end tests src/lib/__tests__/integration/e2e-workflows.test.ts Add two more workflow test suites to the same file.

Workflow 2: Collector Collection -> Remittance Verification

describe("E2E: Collection & Remittance Workflow")

  test("1. Collector records field collection")
    - Create subscriber with unpaid invoice
    - Call recordCollection (from CollectorService) as collector
    - Verify: collection created, invoice allocated via FIFO
    - Verify: JE posted (DR 1030 Cash in Transit, CR 1100 AR)

  test("2. Collector submits remittance")
    - Call createRemittance with the collection amount
    - Verify: remittance created with SUBMITTED status

  test("3. Office staff verifies remittance")
    - Call verifyRemittance with verified total = submitted total
    - Verify: remittance status = VERIFIED
    - Verify: JE posted (DR 1010 Cash on Hand, CR 1030 Cash in Transit)
    - Verify: variance = 0

  test("4. Dashboard reflects collection activity")
    - Call getCollectorSummary
    - Verify: collectionsToday > 0
    - Verify: unverifiedRemittances = 0 (all verified)

  test("5. Trial balance still balanced after collection workflow")
    - Verify totalDebits === totalCredits

Workflow 3: Ticket Creation -> Job Order -> Completion -> Auto-Resolve

describe("E2E: Ticket to Job Order Resolution")

  test("1. Staff creates ticket from client call")
    - Call createTicket with category, subject, description, source=STAFF
    - Verify: ticket created with OPEN status, TKT-NNNN number

  test("2. Convert ticket to job order")
    - Call createJobOrder linked to ticket
    - Assign to technician
    - Verify: job order created with PENDING status
    - Verify: ticket status auto-transitions to ASSIGNED

  test("3. Technician completes job order")
    - Call updateJobOrderStatus to IN_PROGRESS
    - Call updateJobOrderStatus to COMPLETED with outcomeNotes
    - Verify: job order status = COMPLETED

  test("4. Ticket auto-resolves when all jobs complete")
    - Verify: ticket status = RESOLVED (auto-resolved by checkTicketAutoResolve)
    - Verify: resolvedAt is set

  test("5. Staff closes resolved ticket")
    - Call transitionTicketStatus to CLOSED
    - Verify: ticket status = CLOSED
    - Verify: closedAt is set

Cleanup (afterAll): Use the most comprehensive cleanup order covering all subsystems: ticketComments -> jobOrders -> tickets -> ticketCategories -> collectionAllocations -> collections -> remittances -> paymentAllocations -> payments -> invoiceLines -> invoices -> journalEntryLines -> null reversesEntryId -> journalEntries -> stockMovements -> inventoryItems -> expenses -> vendors -> expenseCategories (custom) -> subscribers -> servicePlans -> tenantSettings -> accountingPeriods -> accounts -> zoneAssignments -> zones -> technicianProfiles -> jobTypeRates -> users -> tenant

Minimum total test count across all 3 workflows: 16+ tests. npx vitest run src/lib/__tests__/integration/e2e-workflows.test.ts — all workflow tests pass All 3 critical workflows pass e2e: billing, collection/remittance, ticket/job-order; trial balance balanced throughout; dashboard metrics accurate; 16+ tests pass; INFRA-04 satisfied

- `npx vitest run src/lib/__tests__/integration/e2e-workflows.test.ts` — all tests pass - Trial balance is balanced after each workflow (self-verifying books) - Dashboard metrics reflect workflow activity - All three critical paths exercised end-to-end

<success_criteria>

• Billing workflow: registration -> invoice -> payment -> balanced books
• Collection workflow: field collection -> remittance -> verification -> balanced books
• Ticket workflow: create -> job order -> completion -> auto-resolve -> close
• Trial balance balanced after every workflow
• Dashboard metrics reflect real data from workflows
• INFRA-04 requirement satisfied </success_criteria>

After completion, create `.planning/phases/05-visibility-and-client-portal/05-05-SUMMARY.md`