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

docs(02-04): complete billing engine plan

Browse Source 
Tasks completed: 2/2
- Task 1: Invoice model + BillingService + InvoiceService + CreditService
- Task 2: Billing API routes + comprehensive tests (38 passing)

SUMMARY: .planning/phases/02-subscriber-and-billing-core/02-04-SUMMARY.md
This commit is contained in:
kevin-asprec
2026-03-04 23:41:50 +08:00
parent 902587683f
commit df4a467a38
2 changed files with 172 additions and 12 deletions
Download Patch File Download Diff File Expand all files Collapse all files

30
.planning/STATE.md
View File

@@ -10,29 +10,29 @@ See: .planning/PROJECT.md (updated 2026-03-04)
## Current Position
Phase: 2 of 5 (Subscriber and Billing Core) — In progress
Plan: 4 of 5 in phase 2 complete (9/20 total)
Status: In progress. 02-01 (COA), 02-02 (JournalEntryService), 02-03 (Subscriber) complete. Now ready for 02-04 (BillingEngine).
Last activity: 2026-03-04 — Completed 02-02-PLAN.md (JournalEntryService, 36 new tests, 198 total)
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)
Progress: [████████░░] 45% (9/20 plans across all phases)
Progress: [█████████░] 50% (10/20 plans across all phases)
## Performance Metrics
**Velocity:**
- Total plans completed: 7
- Average duration: 8.7 min
- Total execution time: 64 min
- Total plans completed: 8
- Average duration: 9.5 min
- Total execution time: 76 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 | 37 min | 9.25 min |
| 02-subscriber-and-billing-core | 4/5 complete | 49 min | 12.25 min |
**Recent Trend:**
- Last 7 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)
- Trend: slightly elevated (02-02 was complex — schema + service + API + 36 tests)
- 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)
*Updated after each plan completion*
@@ -85,6 +85,11 @@ Recent decisions affecting current work:
- [02-03]: billingDay capped at 28 — subscribers signing up on days 29-31 get billingDay=28 to avoid month-length invoice generation issues
- [02-03]: CANCELLED -> ACTIVE transition is reversible by design — ISPs frequently reinstate cancelled accounts per CONTEXT.md
- [02-03]: as any cast in service create() calls — Prisma static type requires tenantId but withTenantContext() extension injects at runtime; cast is intentional
- [02-04]: Invoice.amountPaid is transactional convenience field, NOT standalone stored balance — always updated atomically with JEs (same pattern as creditBalance from 02-03)
- [02-04]: shouldBillToday PREPAID month-wrapping: actualLeadDay = lastDayOfCurrentMonth + (billingDay - leadDays) — uses current month's last day, not previous month's
- [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
### Pending Todos
@@ -97,9 +102,10 @@ None.
- [01-04 note]: CASL condition types for string subjects use any cast — upgrade to class-based subjects when Phase 2 Prisma models (Subscriber, Invoice, etc.) are defined
- [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
## Session Continuity
Last session: 2026-03-04T15:23:19Z
Stopped at: Completed 02-02-PLAN.md (JournalEntryService + 36 new tests, 198 total)
Last session: 2026-03-04T15:39:35Z
Stopped at: Completed 02-04-PLAN.md (BillingEngine + 38 tests, Invoice/InvoiceLine models)
Resume file: None