NetForge/.planning/phases/02-subscriber-and-billing-core/02-VERIFICATION.md

phase, verified, status, score, gaps

phase	verified	status	score	gaps
02-subscriber-and-billing-core	2026-03-04T16:00:01Z	gaps_found	4/5 must-haves verified	truth status reason artifacts missing Office staff can record a full or partial cash or bank payment against an invoice; the invoice status updates to partial or paid in real time failed Invoices are generated with status DRAFT (schema default). The payment service (recordPayment) only queries invoices with status IN (SENT, PARTIAL, OVERDUE). A freshly generated invoice cannot receive a cash or bank payment without first transitioning to SENT. No auto-SENT transition exists in billing-service.ts and no invoice issue/send endpoint exists. path issue src/lib/services/billing-service.ts generateInvoiceForSubscriber creates invoice without setting status, falls back to schema default DRAFT. path issue src/lib/services/payment-service.ts recordPayment fetches unpaid invoices with status IN (SENT, PARTIAL, OVERDUE). DRAFT invoices are excluded from the payment allocator. path issue src/app/api/invoices No status-transition endpoint exists to move a DRAFT invoice to SENT. Add status: InvoiceStatus.SENT and issuedAt: new Date() in the invoice.create call inside generateInvoiceForSubscriber in billing-service.ts

Phase 2: Subscriber and Billing Core Verification Report

Phase Goal: Staff can register subscribers, configure service plans, generate monthly invoices on schedule, record cash and bank payments against invoices, and every financial event posts a balanced double-entry journal entry to the ledger automatically. Verified: 2026-03-04T16:00:01Z Status: gaps_found Re-verification: No -- initial verification

Goal Achievement

Observable Truths

#	Truth	Status	Evidence
1	Staff can register a subscriber with name, address, contact, plan assignment and see them in filtered search immediately	VERIFIED	subscriber-service.ts createSubscriber (354 lines) validates required fields, auto-generates SUB-NNNN account numbers, validates active ServicePlan. searchSubscribers supports status/plan/name filters with pagination. POST /api/subscribers and GET /api/subscribers both wired. 41 integration tests confirm.
2	System auto-generates invoices for all active subscribers on billing cycle date -- prepaid and postpaid follow their state machine	VERIFIED	billing-service.ts generateMonthlyInvoices fetches all ACTIVE subscribers, applies shouldBillToday (POSTPAID: exact billingDay match; PREPAID: billingDay minus leadDays with month wrapping). Idempotency via unique(tenantId, subscriberId, periodStart). POST /api/billing/generate is the triggerable endpoint. 38 tests covering both billing types.
3	Office staff can record a full or partial cash or bank payment against an invoice; invoice status updates to partial or paid in real time	FAILED	payment-service.ts recordPayment is fully implemented with FIFO, partial/full/overpayment handling, and correct status transitions. However, invoices generated by the billing engine are created with status DRAFT (Prisma schema default). The payment service queries status IN (SENT, PARTIAL, OVERDUE) -- DRAFT invoices are excluded. A freshly generated invoice cannot receive payments.
4	Every payment and invoice generation event produces a balanced journal entry (debits = credits) with no manual accounting step	VERIFIED	JournalEntryService.createEntry (600 lines) enforces debit=credit in integer cents before writing. Billing calls createEntry (DR AR 1100 / CR Revenue 4010) per invoice. Payment calls createEntry (DR Cash/Bank 1010/1020 / CR AR 1100) per payment. Void calls reverseEntry. Source=SYSTEM auto-posts all entries. 36 JE tests plus billing and payment tests confirm balanced entries.
5	Staff can generate overdue/outstanding report filtered by date range, status, and amount -- outstanding balances derived from the journal, no stored balance fields	VERIFIED	outstanding-report-service.ts getOutstandingReport filters by startDate/endDate/status/minAmount/maxAmount with pagination. Outstanding = totalAmount minus amountPaid computed in JS. amountPaid is always updated atomically in the same DB transaction as its corresponding JE. No standalone ledger balance columns exist on any model. GET /api/reports/outstanding wired.

Score: 4/5 truths verified

Required Artifacts

Artifact	Expected	Status	Details
prisma/schema.prisma	All models (Account, JournalEntry, Subscriber, Invoice, Payment)	VERIFIED	13 models present. 7 migrations applied.
src/lib/accounting/chart-of-accounts.ts	28-account ISP COA	VERIFIED	279 lines. ISP_CHART_OF_ACCOUNTS with 5 parent headers plus 23 leaf accounts.
src/lib/accounting/journal-entry-service.ts	Sole ledger gateway, debit=credit enforcement	VERIFIED	600 lines. createEntry, approveEntry, reverseEntry, getAccountBalance, getTrialBalance all implemented.
src/lib/services/subscriber-service.ts	createSubscriber, searchSubscribers	VERIFIED	354 lines. Full CRUD plus status lifecycle plus paginated search.
src/lib/services/billing-service.ts	generateMonthlyInvoices, prepaid/postpaid logic, JE per invoice	VERIFIED	371 lines. shouldBillToday with month wrapping. JE via JournalEntryService. Invoice status gap noted separately.
src/lib/services/payment-service.ts	recordPayment FIFO, voidPayment with reversal	VERIFIED	509 lines. FIFO allocation, full/partial/overpayment, JE per payment, reversing JE on void.
src/lib/services/outstanding-report-service.ts	Report with filters, outstanding derived from journal	VERIFIED	198 lines. All filters implemented. Outstanding computed from amountPaid (atomically journal-linked).
src/app/api/subscribers/route.ts	GET search plus POST register	VERIFIED	133 lines. Both handlers wired to subscriber-service with CASL guards.
src/app/api/billing/generate/route.ts	POST trigger billing cycle	VERIFIED	71 lines. Calls generateMonthlyInvoices. Returns generated/skipped/errors.
src/app/api/payments/route.ts	POST record payment plus GET list	VERIFIED	149 lines. Full validation. Calls recordPayment.
src/app/api/reports/outstanding/route.ts	GET with filters	VERIFIED	64 lines. All query params passed through to getOutstandingReport.
src/lib/tests/billing.test.ts	38 integration tests	VERIFIED	1059 lines. 38 test cases covering POSTPAID, PREPAID, credit auto-apply, overdue, void, tenant isolation.
src/lib/tests/payment.test.ts	29 integration tests	VERIFIED	1101 lines. 29 test cases. Test helper creates invoices as SENT directly -- does not expose the DRAFT status gap.

Key Link Verification

From	To	Via	Status	Details
billing-service.ts	journal-entry-service.ts	JournalEntryService.createEntry	WIRED	Line 232: createEntry with DR AR 1100 / CR Revenue 4010
payment-service.ts	journal-entry-service.ts	JournalEntryService.createEntry	WIRED	Line 264: createEntry with DR Cash/Bank / CR AR
payment-service.ts	journal-entry-service.ts	JournalEntryService.reverseEntry	WIRED	Line 382: void calls reverseEntry
credit-service.ts	journal-entry-service.ts	JournalEntryService.createEntry	WIRED	Line 111: createEntry with DR Sub Credits 1150 / CR AR 1100
billing-service.ts	Invoice (status=SENT)	Status set in invoice create	NOT WIRED	Invoice created without explicit status, defaults to DRAFT. Payment service cannot see DRAFT invoices.
subscribers/route.ts	subscriber-service.ts	import + call	WIRED	Lines 4-7 import; called at lines 48 and 117
payments/route.ts	payment-service.ts	import + call	WIRED	Line 4 import; called at line 66
reports/outstanding/route.ts	outstanding-report-service.ts	import + call	WIRED	Line 4 import; called at line 52

Requirements Coverage

Requirement	Status	Blocking Issue
SUB-01: Staff can register subscriber	SATISFIED	createSubscriber plus POST /api/subscribers working
SUB-02: Subscriber status lifecycle	SATISFIED	changeSubscriberStatus with validated transition matrix
SUB-03: Search and filter subscribers	SATISFIED	searchSubscribers with status/plan/name/page filters
SUB-04: Plan assignment at registration	SATISFIED	servicePlanId required and validated on createSubscriber
BILL-01: Auto-generate monthly invoices for all active subscribers	SATISFIED	generateMonthlyInvoices runs billing cycle; API endpoint triggerable
BILL-02: Prepaid/postpaid subscriber billing types	SATISFIED	shouldBillToday handles both billing types with month wrapping
BILL-03: Office staff records cash or bank payment against invoice	BLOCKED	Invoice status DRAFT gap -- generated invoices cannot receive payments
BILL-04: Track outstanding balances in real time	SATISFIED	Outstanding report plus subscriber balance endpoint both implemented
BILL-05: Partial payment support	SATISFIED	FIFO allocation tracks partial/full payment; PARTIAL status applied
BILL-06: Payment void with audit trail	SATISFIED	voidPayment creates reversing JE; payment marked VOIDED
ACCT-01: COA auto-provisioned at tenant signup	SATISFIED	seedChartOfAccounts called inside createTenant transaction
ACCT-02: Double-entry journal enforcement	SATISFIED	JournalEntryService.createEntry enforces debit=credit in integer cents
ACCT-03: Immutable entries, corrections via reversals	SATISFIED	No updateEntry/deleteEntry methods; only reverseEntry
ACCT-07: Maker-checker workflow	SATISFIED	MANUAL entries create DRAFT; approveEntry required; SYSTEM auto-POSTED
ACCT-09: No stored balance fields	SATISFIED	Account balances derived from journal aggregates; amountPaid is transactional convenience field updated atomically with JEs

Anti-Patterns Found

File	Pattern	Severity	Impact
src/lib/services/billing-service.ts	No explicit status field in invoice.create data block -- defaults to DRAFT	Blocker	Invoices created as DRAFT cannot be paid via payment service

The return null at billing-service.ts line 182 is intentional idempotency behavior, not a stub.

Human Verification Required

None. All gaps are structural and verifiable programmatically.

Gaps Summary

One blocker prevents full goal achievement: the invoice DRAFT-to-SENT transition gap.

The billing engine (generateInvoiceForSubscriber) creates invoices without setting an explicit status, so they fall back to the Prisma schema default of DRAFT. The payment service (recordPayment) queries unpaid invoices with status IN (SENT, PARTIAL, OVERDUE) -- DRAFT is excluded. This means the end-to-end ISP revenue cycle is broken: a subscriber can be registered, an invoice can be generated, but that invoice cannot receive a cash or bank payment through the normal payment recording flow.

The fix is a two-field addition in src/lib/services/billing-service.ts inside the invoice.create data block:

status: InvoiceStatus.SENT, issuedAt: new Date(),

Billing-engine-generated invoices represent bills that have been issued to the subscriber, so auto-SENT is semantically correct. The payment tests already verify the full payment flow against SENT invoices -- passing that test coverage to the billing engine output closes the gap completely.

Note: the billing test coverage does not expose this gap because the payment test helper (createInvoice()) manually sets the invoice status to SENT. The billing tests verify invoice generation correctly but do not test the downstream payment step against a billing-engine-generated invoice.

All other must-haves -- subscriber registration, prepaid/postpaid invoice generation, balanced double-entry journal entries, and the outstanding report -- are fully implemented and structurally sound.

---

Verified: 2026-03-04T16:00:01Z Verifier: Claude (gsd-verifier)