From 816ac5360f66f8ba770a6c64c982c1791d6a527a Mon Sep 17 00:00:00 2001 From: kevin-asprec Date: Wed, 4 Mar 2026 23:54:42 +0800 Subject: [PATCH] =?UTF-8?q?docs(02-05):=20complete=20payment=20system=20pl?= =?UTF-8?q?an=20=E2=80=94=20Phase=202=20complete?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- .planning/STATE.md | 32 ++-- .../02-05-SUMMARY.md | 162 ++++++++++++++++++ 2 files changed, 181 insertions(+), 13 deletions(-) create mode 100644 .planning/phases/02-subscriber-and-billing-core/02-05-SUMMARY.md diff --git a/.planning/STATE.md b/.planning/STATE.md index 632c7c2..01b7b10 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -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 diff --git a/.planning/phases/02-subscriber-and-billing-core/02-05-SUMMARY.md b/.planning/phases/02-subscriber-and-billing-core/02-05-SUMMARY.md new file mode 100644 index 0000000..55f5d99 --- /dev/null +++ b/.planning/phases/02-subscriber-and-billing-core/02-05-SUMMARY.md @@ -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*