docs(03-02): complete Collector Collection and Remittance plan

Tasks completed: 2/2
- Task 1: Collection/Remittance schema, 1030 COA, migration, tenant scoping
- Task 2: Collector service, remittance service, report service, APIs, 26 tests

SUMMARY: .planning/phases/03-operational-modules/03-02-SUMMARY.md

.planning/STATE.md

@@ -10,18 +10,18 @@ See: .planning/PROJECT.md (updated 2026-03-04)
 ## Current Position
 
 Phase: 3 of 5 (Operational Modules) — In progress
-Plan: 3 of 5 in phase 3 (14/20 total complete)
+Plan: 4 of 5 in phase 3 (15/20 total complete)
-Status: Phase 3 in progress. 03-01 (Zones), 03-02 (skipped/not present), 03-03 (Ticketing) complete.
+Status: Phase 3 in progress. 03-01 (Zones), 03-02 (Collections/Remittances), 03-03 (Ticketing) complete.
-Last activity: 2026-03-05 — Completed 03-03-PLAN.md (Ticketing system, 28 tests)
+Last activity: 2026-03-05 — Completed 03-02-PLAN.md (Collections/Remittances — 26 tests, 1030 COA, zone enforcement)
 
-Progress: [█████████████░] 70% (14/20 plans across all phases)
+Progress: [███████████████░] 75% (15/20 plans across all phases)
 
 ## Performance Metrics
 
 **Velocity:**
-- Total plans completed: 9
+- Total plans completed: 10
-- Average duration: 9.4 min
+- Average duration: 9.5 min
-- Total execution time: 84 min
+- Total execution time: 95 min
 
 **By Phase:**
 
@@ -29,10 +29,11 @@ Progress: [█████████████░] 70% (14/20 plans across a
 |-------|-------|-------|----------|
 | 01-foundation | 5/5 complete | 41 min | 8.2 min |
 | 02-subscriber-and-billing-core | 5/5 complete | 57 min | 11.4 min |
+| 03-operational-modules | 3/5 in progress | ~50 min | ~17 min |
 
 **Recent Trend:**
-- Last 10 plans: 01-02 (8 min), 01-03 (9 min), 01-04 (7 min), 01-05 (6 min), 02-01 (7 min), 02-03 (7 min), 02-02 (16 min), 02-04 (12 min), 02-05 (8 min), 03-01 (15 min)
+- Last 10 plans: 01-03 (9 min), 01-04 (7 min), 01-05 (6 min), 02-01 (7 min), 02-03 (7 min), 02-02 (16 min), 02-04 (12 min), 02-05 (8 min), 03-01 (15 min), 03-02 (11 min)
-- Trend: stable — 03-01 had a migration workaround but tests passed on first run
+- Trend: stable — 03-02 migration applied cleanly, 26 tests passed on first run
 
 *Updated after each plan completion*
 
@@ -105,6 +106,11 @@ Recent decisions affecting current work:
 - [03-03]: Ticket cleanup order in tests: tickets -> ticketCategories -> subscribers -> ... (categories seeded by createTenant must be deleted on teardown)
 - [03-03]: transitionTicketStatus is the single gateway for status changes — updateTicket explicitly excludes status field
 - [03-03]: 6 default ISP categories seeded in createTenant $transaction (No Connection, Slow Speed, Billing Inquiry, New Installation, Equipment Issue, Other)
+- [03-02]: Collection JE uses 1030 Cash in Transit (not 1010) — cash is in collector's hands until remitted to office
+- [03-02]: Remittance JE uses verifiedTotal on both DR 1010 and CR 1030 sides — variance is recorded on remittance record, not in ledger
+- [03-02]: Variance is non-blocking — any discrepancy is an audit record; remittance proceeds to VERIFIED regardless
+- [03-02]: Collection cleanup order: collectionAllocations → collections → invoiceLines → invoices → journalEntryLines → null reversesEntryId → journalEntries → zoneAssignments → subscribers → zones → servicePlans → accountingPeriods → accounts → users → tenant
+- [03-02]: ISP COA now has 29 accounts — added 1030 Cash in Transit between 1020 Cash in Bank and 1100 AR
 
 ### Pending Todos
 
@@ -122,6 +128,6 @@ None.
 
 ## Session Continuity
 
-Last session: 2026-03-04T23:40:15Z
+Last session: 2026-03-04T23:54:44Z
-Stopped at: Completed 03-03-PLAN.md (Ticketing system — 28 tests, Ticket/TicketCategory models, guard-map lifecycle, 7 API routes)
+Stopped at: Completed 03-02-PLAN.md (Collections/Remittances — 26 tests, 1030 COA, zone enforcement, two-party verification)
 Resume file: None

.planning/phases/03-operational-modules/03-02-SUMMARY.md

@@ -0,0 +1,144 @@
+---
+phase: 03-operational-modules
+plan: "02"
+subsystem: payments
+tags: [prisma, postgresql, accounting, double-entry, collections, remittances, fifo, zone-enforcement]
+
+# Dependency graph
+requires:
+  - phase: 02-subscriber-and-billing-core
+    provides: Invoice model, AR account (1100), JournalEntryService, PaymentService FIFO pattern
+  - phase: 03-01
+    provides: Zone model, ZoneAssignment, getCollectorSubscribers zone scoping pattern
+provides:
+  - Collection model with FIFO invoice allocation and zone enforcement
+  - CollectionAllocation model linking collections to invoices
+  - Remittance model with two-party verification and variance tracking
+  - Account 1030 Cash in Transit in ISP COA
+  - CollectorService: recordCollection, voidCollection, getCollectionHistory
+  - RemittanceService: createRemittance, verifyRemittance, listRemittances
+  - CollectionReportService: getDailyCollectionSummary, getCollectorCollectionDetail
+  - 6 API routes for collections, remittances, and collection reports
+  - 26 integration tests (13 collector + 13 remittance)
+affects:
+  - 03-04 (inventory or financial reporting phases that use collection totals)
+  - 03-05 (any future financial dashboard reading 1030/1010 account balances)
+  - Phase 5 reporting (collection→remittance chain feeds cash flow reports)
+
+# Tech tracking
+tech-stack:
+  added: []
+  patterns:
+    - "Two-phase cash tracking: 1030 (collector holds) → 1010 (office receives)"
+    - "FIFO collection allocation: same pattern as PaymentService but DR 1030 (not 1010)"
+    - "Variance-tolerant verification: non-blocking discrepancy recording"
+    - "Zone enforcement throws on violation: same security boundary pattern as 03-01"
+
+key-files:
+  created:
+    - prisma/migrations/20260304234448_add_collections_remittances/migration.sql
+    - src/lib/services/collector-service.ts
+    - src/lib/services/remittance-service.ts
+    - src/lib/services/collection-report-service.ts
+    - src/app/api/collections/route.ts
+    - src/app/api/collections/[id]/route.ts
+    - src/app/api/collections/[id]/void/route.ts
+    - src/app/api/remittances/route.ts
+    - src/app/api/remittances/[id]/verify/route.ts
+    - src/app/api/reports/collections/route.ts
+    - src/lib/__tests__/collector-service.test.ts
+    - src/lib/__tests__/remittance-service.test.ts
+  modified:
+    - prisma/schema.prisma
+    - src/lib/prisma-tenant.ts
+    - src/lib/accounting/chart-of-accounts.ts
+
+key-decisions:
+  - "Collection JE uses 1030 Cash in Transit (not 1010 Cash on Hand) — cash is in collector's hands, not yet at office"
+  - "Remittance verification JE: DR 1010 verifiedTotal, CR 1030 verifiedTotal — JE balanced using verifiedTotal on both sides; variance recorded on remittance record only (not in ledger)"
+  - "Variance is non-blocking by design — any discrepancy is an audit record, not a system blocker"
+  - "Collector balances derived from transactions — no stored balance field on collector or remittance"
+  - "Zone enforcement throws (not empty return) on violation — matches 03-01 security boundary decision"
+  - "Collection cleanup order: collectionAllocations → collections → invoiceLines → invoices → journalEntryLines → null reversesEntryId → journalEntries → zoneAssignments → subscribers → zones → servicePlans → accountingPeriods → accounts → users → tenant"
+  - "withPermission HOF used for API routes (same pattern as ticket/zone routes — no direct getServerSession)"
+
+patterns-established:
+  - "Cash flow chain: Subscriber pays Collector (1030 DR/1100 CR) → Collector remits to office (1010 DR/1030 CR)"
+  - "Two-party verification: collector declares total (PENDING), office verifies with counted total (VERIFIED)"
+  - "FIFO allocation for collections mirrors PaymentService FIFO — same pattern, different debit account"
+
+# Metrics
+duration: 11min
+completed: 2026-03-05
+---
+
+# Phase 3 Plan 02: Collector Field Collection and Remittance System Summary
+
+**Field cash collection system with FIFO allocation, zone enforcement, two-party remittance verification, and double-entry accounting chain: Collection DR 1030/CR 1100, Remittance DR 1010/CR 1030**
+
+## Performance
+
+- **Duration:** 11 min
+- **Started:** 2026-03-04T23:43:21Z
+- **Completed:** 2026-03-04T23:54:44Z
+- **Tasks:** 2 completed
+- **Files modified:** 14
+
+## Accomplishments
+- Collection model with FIFO invoice allocation, zone enforcement, void/reversing JE
+- Remittance model with two-party verification, variance recording (non-blocking), verification JE
+- Account 1030 Cash in Transit added to ISP COA — completes the cash chain (1010/1020/1030)
+- 26 integration tests: FIFO ordering, zone enforcement throws, JE account code verification, void reversals, variance tests, double-verify rejection
+- 6 API routes following withPermission HOF pattern
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task 1: Collection/Remittance schema, 1030 account, migration, tenant scoping** - `0967fc2` (feat)
+2. **Task 2: Collector service, remittance service, report service, APIs, and tests** - `a72aaa9` (feat)
+
+## Files Created/Modified
+- `prisma/schema.prisma` - Added CollectionStatus, RemittanceStatus enums; Collection, CollectionAllocation, Remittance models
+- `prisma/migrations/20260304234448_add_collections_remittances/migration.sql` - Applied migration
+- `src/lib/accounting/chart-of-accounts.ts` - Added 1030 Cash in Transit between 1020 and 1100
+- `src/lib/prisma-tenant.ts` - Added collection, collectionAllocation, remittance to TENANT_SCOPED_MODELS with 12-operation extension blocks
+- `src/lib/services/collector-service.ts` - recordCollection (zone enforcement + FIFO + DR 1030/CR 1100 JE), voidCollection, getCollectionHistory
+- `src/lib/services/remittance-service.ts` - createRemittance, verifyRemittance (DR 1010/CR 1030, non-blocking variance), listRemittances
+- `src/lib/services/collection-report-service.ts` - getDailyCollectionSummary, getCollectorCollectionDetail
+- `src/app/api/collections/route.ts` - POST/GET /api/collections
+- `src/app/api/collections/[id]/route.ts` - GET /api/collections/[id]
+- `src/app/api/collections/[id]/void/route.ts` - POST /api/collections/[id]/void
+- `src/app/api/remittances/route.ts` - POST/GET /api/remittances
+- `src/app/api/remittances/[id]/verify/route.ts` - POST /api/remittances/[id]/verify
+- `src/app/api/reports/collections/route.ts` - GET /api/reports/collections
+- `src/lib/__tests__/collector-service.test.ts` - 13 integration tests
+- `src/lib/__tests__/remittance-service.test.ts` - 13 integration tests
+
+## Decisions Made
+- Collection JE uses 1030 (not 1010) — cash is in collector's hands until remitted
+- Remittance JE uses verifiedTotal on both DR 1010 and CR 1030 sides to keep it balanced; variance is an audit field on the remittance record, not a ledger entry
+- Variance is non-blocking by design — ISP operations require flexibility in cash handling
+- Collector balances derived from transaction log — no stored balance field
+- Zone enforcement throws on violation (matches 03-01 security boundary decision)
+
+## Deviations from Plan
+
+None — plan executed exactly as written.
+
+## Issues Encountered
+None — tests passed on first run, migration applied cleanly.
+
+## User Setup Required
+None — no external service configuration required.
+
+## Next Phase Readiness
+- Cash collection and remittance chain complete (1030 → 1010 in double-entry ledger)
+- Daily collection summary report available for management
+- Collector zone enforcement active and tested
+- Ready for Phase 3 remaining plans (inventory or financial dashboard)
+- Cleanup order documented in STATE.md for future test isolation
+
+---
+*Phase: 03-operational-modules*
+*Completed: 2026-03-05*