kibin/NetForge
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(02-05): complete payment system plan — Phase 2 complete

Browse Source 
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
2026-03-04 23:54:42 +08:00
parent bbfc9d6fb4
commit 816ac5360f
2 changed files with 181 additions and 13 deletions
Download Patch File Download Diff File Expand all files Collapse all files

32
.planning/STATE.md
View File

@@ -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