diff --git a/.planning/STATE.md b/.planning/STATE.md index 8c7e782..7f62a0e 100644 --- a/.planning/STATE.md +++ b/.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) -Status: Phase 3 in progress. 03-01 (Zones), 03-02 (skipped/not present), 03-03 (Ticketing) complete. -Last activity: 2026-03-05 — Completed 03-03-PLAN.md (Ticketing system, 28 tests) +Plan: 4 of 5 in phase 3 (15/20 total complete) +Status: Phase 3 in progress. 03-01 (Zones), 03-02 (Collections/Remittances), 03-03 (Ticketing) complete. +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 -- Average duration: 9.4 min -- Total execution time: 84 min +- Total plans completed: 10 +- Average duration: 9.5 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) -- Trend: stable — 03-01 had a migration workaround but tests passed on first run +- 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-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 -Stopped at: Completed 03-03-PLAN.md (Ticketing system — 28 tests, Ticket/TicketCategory models, guard-map lifecycle, 7 API routes) +Last session: 2026-03-04T23:54:44Z +Stopped at: Completed 03-02-PLAN.md (Collections/Remittances — 26 tests, 1030 COA, zone enforcement, two-party verification) Resume file: None diff --git a/.planning/phases/03-operational-modules/03-02-SUMMARY.md b/.planning/phases/03-operational-modules/03-02-SUMMARY.md new file mode 100644 index 0000000..24140c6 --- /dev/null +++ b/.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*