docs(02-05): complete payment system plan — Phase 2 complete
Tasks completed: 2/2 - Task 1: Payment model with FIFO allocation and void - Task 2: Payment APIs, outstanding report, and 29 passing tests Phase 2 (Subscriber and Billing Core) complete — 265/265 tests passing SUMMARY: .planning/phases/02-subscriber-and-billing-core/02-05-SUMMARY.md
This commit is contained in:
kevin-asprec
@@ -9,30 +9,30 @@ See: .planning/PROJECT.md (updated 2026-03-04)
|
||||
|
||||
## Current Position
|
||||
|
||||
Phase: 2 of 5 (Subscriber and Billing Core) — In progress
|
||||
Plan: 5 of 5 in phase 2 remaining (10/20 total complete)
|
||||
Status: In progress. 02-01 (COA), 02-02 (JournalEntryService), 02-03 (Subscriber), 02-04 (BillingEngine) complete. Ready for 02-05 (PaymentService).
|
||||
Last activity: 2026-03-04 — Completed 02-04-PLAN.md (BillingEngine, 38 tests)
|
||||
Phase: 2 of 5 (Subscriber and Billing Core) — COMPLETE
|
||||
Plan: 5 of 5 in phase 2 (11/20 total complete)
|
||||
Status: Phase 2 complete. 02-01 (COA), 02-02 (JournalEntryService), 02-03 (Subscriber), 02-04 (BillingEngine), 02-05 (PaymentService) all done.
|
||||
Last activity: 2026-03-04 — Completed 02-05-PLAN.md (PaymentService, 29 tests, 265 total)
|
||||
|
||||
Progress: [█████████░] 50% (10/20 plans across all phases)
|
||||
Progress: [███████████░] 55% (11/20 plans across all phases)
|
||||
|
||||
## Performance Metrics
|
||||
|
||||
**Velocity:**
|
||||
- Total plans completed: 8
|
||||
- Average duration: 9.5 min
|
||||
- Total execution time: 76 min
|
||||
- Total plans completed: 9
|
||||
- Average duration: 9.4 min
|
||||
- Total execution time: 84 min
|
||||
|
||||
**By Phase:**
|
||||
|
||||
| Phase | Plans | Total | Avg/Plan |
|
||||
|-------|-------|-------|----------|
|
||||
| 01-foundation | 5/5 complete | 41 min | 8.2 min |
|
||||
| 02-subscriber-and-billing-core | 4/5 complete | 49 min | 12.25 min |
|
||||
| 02-subscriber-and-billing-core | 5/5 complete | 57 min | 11.4 min |
|
||||
|
||||
**Recent Trend:**
|
||||
- Last 8 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)
|
||||
- Trend: stable (02-04 was complex — schema + 3 services + 4 API routes + 38 tests)
|
||||
- Last 9 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)
|
||||
- Trend: stable — 02-05 was complex but tests passed on second run
|
||||
|
||||
*Updated after each plan completion*
|
||||
|
||||
@@ -90,6 +90,11 @@ Recent decisions affecting current work:
|
||||
- [02-04]: generateInvoiceForSubscriber returns null (not error) for duplicates — idempotent by design; generateMonthlyInvoices tracks in skipped array
|
||||
- [02-04]: CreditService is standalone module — applyCredit() callable from BillingService (auto-apply) and PaymentService (02-05 overpayment)
|
||||
- [02-04]: Dynamic route handlers pattern: export function GET/POST(req, { params }) wrapping withPermission()(handler)(req) — required for Next.js 15 Promise params in [id] routes
|
||||
- [02-05]: PaymentAllocation as separate model — enables per-invoice allocation queries and void recalculation; each allocation row: paymentId + invoiceId + amount
|
||||
- [02-05]: FIFO by dueDate ASC — oldest due date allocated first (matches standard ISP billing practice)
|
||||
- [02-05]: Overpayment to subscriber.creditBalance atomically with JE — same pattern as invoice.amountPaid from 02-04
|
||||
- [02-05]: Outstanding report computed in JS after fetching — Prisma doesn't support computed fields in WHERE/ORDER BY; acceptable for ISP scale
|
||||
- [02-05]: Test invoiceCounter for periodStart uniqueness — monotonic counter generates unique periodStart per invoice, avoids @@unique([tenantId, subscriberId, periodStart]) in test helpers
|
||||
|
||||
### Pending Todos
|
||||
|
||||
@@ -103,9 +108,10 @@ None.
|
||||
- [01-05 note]: /admin/tenants/[id] detail page is a stub link ("View") — detail view not implemented yet (out of Phase 1 scope)
|
||||
- [02-02 note]: JournalEntry afterAll cleanup needs explicit order (lines → null reversesEntryId → entries → tenant) — document for any future test that involves journal entries
|
||||
- [02-04 note]: Invoice cleanup order in tests: invoiceLines → invoices → journalEntryLines → null reversesEntryId → journalEntries → subscribers → servicePlans → tenantSettings → accountingPeriods → accounts → users → tenant
|
||||
- [02-05 note]: Payment cleanup order in tests: paymentAllocations → payments → invoiceLines → invoices → journalEntryLines → null reversesEntryId → journalEntries → subscribers → servicePlans → tenantSettings → accountingPeriods → accounts → users → tenant
|
||||
|
||||
## Session Continuity
|
||||
|
||||
Last session: 2026-03-04T15:39:35Z
|
||||
Stopped at: Completed 02-04-PLAN.md (BillingEngine + 38 tests, Invoice/InvoiceLine models)
|
||||
Last session: 2026-03-04T15:52:55Z
|
||||
Stopped at: Completed 02-05-PLAN.md (PaymentService + 29 tests — Phase 2 complete)
|
||||
Resume file: None
|
||||
|
||||
162
.planning/phases/02-subscriber-and-billing-core/02-05-SUMMARY.md
Normal file
162
.planning/phases/02-subscriber-and-billing-core/02-05-SUMMARY.md
Normal file
@@ -0,0 +1,162 @@
|
||||
---
|
||||
phase: 02-subscriber-and-billing-core
|
||||
plan: "05"
|
||||
subsystem: payments
|
||||
tags: [prisma, postgresql, payment, fifo, journal-entry, double-entry, outstanding-report, idempotency]
|
||||
|
||||
# Dependency graph
|
||||
requires:
|
||||
- phase: 02-04
|
||||
provides: Invoice model with amountPaid convenience field, BillingService, CreditService
|
||||
- phase: 02-02
|
||||
provides: JournalEntryService as sole accounting gateway
|
||||
- phase: 02-01
|
||||
provides: ISP COA — accounts 1010/1020/1100/1150/4010
|
||||
|
||||
provides:
|
||||
- Payment model with idempotency key, FIFO allocation, void fields
|
||||
- PaymentAllocation model linking payments to invoices
|
||||
- PaymentService: recordPayment() FIFO allocation, voidPayment() with reversing JE, getSubscriberPaymentHistory()
|
||||
- OutstandingReportService: getOutstandingReport() with filters/pagination
|
||||
- REST API: POST/GET /api/payments, GET /api/payments/[id], POST /api/payments/[id]/void
|
||||
- REST API: GET /api/subscribers/[id]/payments, GET /api/subscribers/[id]/balance
|
||||
- REST API: GET /api/reports/outstanding
|
||||
- 29 integration tests for full payment lifecycle
|
||||
|
||||
affects:
|
||||
- 03-collections-and-routing (collectors receive/record payments)
|
||||
- 05-online-payment (payment gateway integration scaffolded here)
|
||||
- reporting (outstanding balances, payment history)
|
||||
|
||||
# Tech tracking
|
||||
tech-stack:
|
||||
added: []
|
||||
patterns:
|
||||
- FIFO allocation: oldest unpaid invoice (by dueDate ASC) allocated first
|
||||
- Overpayment creates subscriber.creditBalance (atomically with JE, same pattern as amountPaid)
|
||||
- Idempotency via @@unique([tenantId, idempotencyKey]) — safe to retry
|
||||
- Void via reversing JE (immutability — no deletes, corrections only)
|
||||
- PaymentAllocation model tracks allocation breakdown per payment per invoice
|
||||
|
||||
key-files:
|
||||
created:
|
||||
- prisma/migrations/20260304154606_add_payment_model/migration.sql
|
||||
- src/lib/services/payment-service.ts
|
||||
- src/lib/services/outstanding-report-service.ts
|
||||
- src/app/api/payments/route.ts
|
||||
- src/app/api/payments/[id]/route.ts
|
||||
- src/app/api/payments/[id]/void/route.ts
|
||||
- src/app/api/subscribers/[id]/payments/route.ts
|
||||
- src/app/api/subscribers/[id]/balance/route.ts
|
||||
- src/app/api/reports/outstanding/route.ts
|
||||
- src/lib/__tests__/payment.test.ts
|
||||
modified:
|
||||
- prisma/schema.prisma
|
||||
- src/lib/prisma-tenant.ts
|
||||
|
||||
key-decisions:
|
||||
- "PaymentAllocation is a separate model (not embedded) — enables per-invoice allocation queries and supports void recalculation"
|
||||
- "FIFO by dueDate ASC — earliest due date gets first allocation (matches ISP norms)"
|
||||
- "Overpayment goes to subscriber.creditBalance (same atomically-updated pattern as amountPaid)"
|
||||
- "Void recalculates invoice.amountPaid by subtracting allocation.amount — safe for multiple-payment scenarios"
|
||||
- "Outstanding report computes in-process (not raw SQL) — Prisma computed fields not supported; totalAmount-amountPaid computed in JS"
|
||||
- "Tests use unique invoiceCounter for periodStart — avoids @@unique([tenantId, subscriberId, periodStart]) constraint in test helpers"
|
||||
|
||||
patterns-established:
|
||||
- "Payment cleanup order in tests: paymentAllocations -> payments -> invoiceLines -> invoices -> journalEntryLines -> null reversesEntryId -> journalEntries -> subscribers -> servicePlans -> tenantSettings -> accountingPeriods -> accounts -> users -> tenant"
|
||||
- "withPermission() HOF pattern continued for all payment/report routes"
|
||||
|
||||
# Metrics
|
||||
duration: 8min
|
||||
completed: 2026-03-04
|
||||
---
|
||||
|
||||
# Phase 2 Plan 05: Payment System Summary
|
||||
|
||||
**FIFO cash/bank payment recording with idempotency, partial/full/overpayment tracking, reversing-JE voids, and outstanding balance report — completing the ISP revenue cycle**
|
||||
|
||||
## Performance
|
||||
|
||||
- **Duration:** 8 min
|
||||
- **Started:** 2026-03-04T15:44:52Z
|
||||
- **Completed:** 2026-03-04T15:52:55Z
|
||||
- **Tasks:** 2/2
|
||||
- **Files modified:** 12
|
||||
|
||||
## Accomplishments
|
||||
|
||||
- Payment model with FIFO allocation, idempotency key, void support, and journal entry links
|
||||
- PaymentService: recordPayment() with FIFO, voidPayment() with reversing JE, getSubscriberPaymentHistory()
|
||||
- OutstandingReportService showing who owes what — the core product value
|
||||
- 7 REST API routes for payment recording, history, balance, void, and outstanding report
|
||||
- 29 integration tests covering all payment scenarios (full/partial/overpayment, FIFO, idempotency, void, tenant isolation)
|
||||
- Full regression: 265/265 tests pass
|
||||
|
||||
## Task Commits
|
||||
|
||||
Each task was committed atomically:
|
||||
|
||||
1. **Task 1: Payment model + PaymentService with FIFO allocation** - `6b91e67` (feat)
|
||||
2. **Task 2: Payment APIs + outstanding report + tests** - `bbfc9d6` (feat)
|
||||
|
||||
**Plan metadata:** (created below)
|
||||
|
||||
## Files Created/Modified
|
||||
|
||||
- `prisma/schema.prisma` - Added PaymentMethod/PaymentStatus enums, Payment and PaymentAllocation models, relations
|
||||
- `src/lib/prisma-tenant.ts` - Added "payment" and "paymentAllocation" to TENANT_SCOPED_MODELS and withTenantContext()
|
||||
- `prisma/migrations/20260304154606_add_payment_model/migration.sql` - DB migration for Payment and PaymentAllocation tables
|
||||
- `src/lib/services/payment-service.ts` - recordPayment() FIFO, voidPayment() reversing JE, getSubscriberPaymentHistory()
|
||||
- `src/lib/services/outstanding-report-service.ts` - getOutstandingReport() with amount/date/status filters
|
||||
- `src/app/api/payments/route.ts` - POST record payment, GET list payments
|
||||
- `src/app/api/payments/[id]/route.ts` - GET single payment detail
|
||||
- `src/app/api/payments/[id]/void/route.ts` - POST void payment
|
||||
- `src/app/api/subscribers/[id]/payments/route.ts` - GET subscriber payment history
|
||||
- `src/app/api/subscribers/[id]/balance/route.ts` - GET subscriber outstanding balance
|
||||
- `src/app/api/reports/outstanding/route.ts` - GET outstanding balance report
|
||||
- `src/lib/__tests__/payment.test.ts` - 29 integration tests
|
||||
|
||||
## Decisions Made
|
||||
|
||||
- **PaymentAllocation as separate model:** Enables per-invoice allocation queries and void recalculation. Each allocation is a row: paymentId + invoiceId + amount.
|
||||
- **FIFO by dueDate ASC:** Oldest due date allocated first — matches standard ISP billing practice.
|
||||
- **Overpayment to subscriber.creditBalance:** Same pattern as invoice.amountPaid — always updated atomically in same transaction as journal entry. CreditService from 02-04 is callable for future credit-to-invoice application.
|
||||
- **Void recalculation via subtraction:** voidPayment() subtracts allocation.amount from invoice.amountPaid — safe even when multiple payments partially cover the same invoice.
|
||||
- **Outstanding report computed in JS:** Prisma does not support computed fields in WHERE/ORDER BY. totalAmount-amountPaid computed in process after fetching invoices. Acceptable for ISP scale (hundreds, not millions of records).
|
||||
- **Test invoiceCounter for periodStart uniqueness:** Invoice schema has @@unique([tenantId, subscriberId, periodStart]). Test helper uses a monotonic counter to generate unique periodStart per invoice, avoiding constraint violations when creating multiple invoices per subscriber in tests.
|
||||
|
||||
## Deviations from Plan
|
||||
|
||||
### Auto-fixed Issues
|
||||
|
||||
**1. [Rule 1 - Bug] Fixed unique periodStart constraint in test helper**
|
||||
- **Found during:** Task 2 (first test run — 6 tests failed with PrismaClientKnownRequestError)
|
||||
- **Issue:** Test `createInvoice()` helper used a fixed `periodStart: new Date(Date.UTC(2026, 1, 1))` for all invoices. Multiple invoices for the same subscriber violated `@@unique([tenantId, subscriberId, periodStart])`.
|
||||
- **Fix:** Added `invoiceCounter` variable; each `createInvoice()` call uses `new Date(Date.UTC(2020, 0, invoiceCounter))` as unique periodStart.
|
||||
- **Files modified:** `src/lib/__tests__/payment.test.ts`
|
||||
- **Verification:** All 29 tests pass after fix
|
||||
- **Committed in:** `bbfc9d6` (Task 2 commit)
|
||||
|
||||
---
|
||||
|
||||
**Total deviations:** 1 auto-fixed (Rule 1 - Bug in test helper)
|
||||
**Impact on plan:** Minimal. Test helper bug; no production code affected. Fix is a standard test-isolation technique.
|
||||
|
||||
## Issues Encountered
|
||||
|
||||
None beyond the test helper bug documented above.
|
||||
|
||||
## User Setup Required
|
||||
|
||||
None - no external service configuration required.
|
||||
|
||||
## Next Phase Readiness
|
||||
|
||||
- Phase 2 (Subscriber and Billing Core) is **complete**: COA, JournalEntryService, Subscriber, BillingEngine, PaymentService all done.
|
||||
- 265 total tests passing across all Phase 1 and Phase 2 plans.
|
||||
- Phase 3 (Collections and Routing) can begin: collector routes, payment collection, zone-based assignment.
|
||||
- Key context for Phase 3: collectors will use PaymentService.recordPayment() to record collected payments; subscriber.zone field is already on the schema.
|
||||
|
||||
---
|
||||
*Phase: 02-subscriber-and-billing-core*
|
||||
*Completed: 2026-03-04*
|
||||
Reference in New Issue
Block a user