docs(05): create phase plan

Phase 05: Visibility and Client Portal - 5 plans in 3 waves - 2 parallel (wave 1), 1 sequential (wave 2), 2 parallel (wave 3) - Ready for execution Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-05 17:14:54 +08:00
parent 5276f3bbf4
commit ea58620c7d
6 changed files with 929 additions and 6 deletions
--- a/.planning/phases/05-visibility-and-client-portal/05-05-PLAN.md
+++ b/.planning/phases/05-visibility-and-client-portal/05-05-PLAN.md
@@ -0,0 +1,212 @@
+---
+phase: 05-visibility-and-client-portal
+plan: 05
+type: execute
+wave: 3
+depends_on: ["05-01", "05-02", "05-03"]
+files_modified:
+  - src/lib/__tests__/integration/e2e-workflows.test.ts
+autonomous: true
+
+must_haves:
+  truths:
+    - "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"
+  artifacts:
+    - path: "src/lib/__tests__/integration/e2e-workflows.test.ts"
+      provides: "End-to-end workflow tests for critical business processes"
+      min_lines: 250
+  key_links:
+    - from: "src/lib/__tests__/integration/e2e-workflows.test.ts"
+      to: "src/lib/services/*.ts"
+      via: "orchestrates multiple services in sequence"
+      pattern: "(SubscriberService|BillingService|PaymentService|CollectorService|RemittanceService|TicketService|JobOrderService|DashboardService)"
+---
+
+<objective>
+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.
+</objective>
+
+<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>
+
+<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
+</context>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Billing workflow end-to-end test</name>
+  <files>src/lib/__tests__/integration/e2e-workflows.test.ts</files>
+  <action>
+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.
+  </action>
+  <verify>`npx vitest run src/lib/__tests__/integration/e2e-workflows.test.ts` — billing workflow tests pass</verify>
+  <done>Billing workflow e2e test passes: subscriber -> invoice -> payment -> balanced books -> dashboard reflects</done>
+</task>
+
+<task type="auto">
+  <name>Task 2: Collection and ticket workflow end-to-end tests</name>
+  <files>src/lib/__tests__/integration/e2e-workflows.test.ts</files>
+  <action>
+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.
+  </action>
+  <verify>`npx vitest run src/lib/__tests__/integration/e2e-workflows.test.ts` — all workflow tests pass</verify>
+  <done>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</done>
+</task>
+
+</tasks>
+
+<verification>
+- `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
+</verification>
+
+<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>
+
+<output>
+After completion, create `.planning/phases/05-visibility-and-client-portal/05-05-SUMMARY.md`
+</output>