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/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*