From e14b926da1c4bce28ac3c27c166937fed0a183ac Mon Sep 17 00:00:00 2001 From: kevin-asprec Date: Wed, 4 Mar 2026 22:06:07 +0800 Subject: [PATCH] docs(02): capture phase context Phase 02: Subscriber and Billing Core - Implementation decisions documented - Phase boundary established Co-Authored-By: Claude Opus 4.6 --- .../02-CONTEXT.md | 74 +++++++++++++++++++ 1 file changed, 74 insertions(+) create mode 100644 .planning/phases/02-subscriber-and-billing-core/02-CONTEXT.md diff --git a/.planning/phases/02-subscriber-and-billing-core/02-CONTEXT.md b/.planning/phases/02-subscriber-and-billing-core/02-CONTEXT.md new file mode 100644 index 0000000..b1fc22e --- /dev/null +++ b/.planning/phases/02-subscriber-and-billing-core/02-CONTEXT.md @@ -0,0 +1,74 @@ +# Phase 2: Subscriber and Billing Core - Context + +**Gathered:** 2026-03-04 +**Status:** Ready for planning + + +## Phase Boundary + +Subscriber management (registration, plan assignment, status lifecycle), billing engine (prepaid/postpaid invoice generation), payment recording (cash/bank, partial, overpayment), and the double-entry accounting ledger (Chart of Accounts, JournalEntryService, manual entries). No collector workflows, no ticketing, no reports beyond outstanding balance — those are later phases. + + + + +## Implementation Decisions + +### Subscriber Lifecycle +- Statuses: Active, Suspended, Cancelled +- Suspension triggers: both automatic (configurable days overdue per tenant) AND manual (staff can suspend/unsuspend anytime) +- Auto-suspend threshold is a per-tenant setting (each ISP configures their own overdue days) +- Reactivation requires full payment of outstanding balance — no reactivation with unpaid debt +- Cancellation is reversible — cancelled subscribers can be reactivated with their full history intact (not a new record) + +### Billing Models +- Prepaid = pay before the service period starts; postpaid = use service, get billed after +- Invoice generation is anniversary-based (each subscriber billed on their signup date, not a fixed monthly date) +- Prepaid invoices generated X days before the billing date to give subscribers time to pay +- Plan changes take effect on the next billing cycle — no proration needed +- No load-based/usage-based billing — this is flat monthly plans only + +### Payment Recording +- Payment fields: Claude's discretion on the right set (amount, method, reference, date, invoice allocation are expected) +- Overpayment creates a credit balance that auto-applies to the next invoice +- Partial payments supported — applied to oldest unpaid invoice first (FIFO) +- Payment voids/reversals allowed for Admin and Office Staff — implemented as reversing journal entries (no deletion) +- Idempotency keys on payment creation to prevent double-recording + +### Chart of Accounts & Ledger +- Pre-configured ISP-specific Chart of Accounts auto-provisioned at tenant signup — not customizable in v1 +- Journal entries visible to Admin only — staff sees only reports and summaries +- Manual journal entries (e.g., cash-on-hand to bank) use maker-checker workflow — one person creates, another approves +- Accounting periods enforced — Admin can close a month, no entries allowed in closed periods +- All journal entries are immutable — corrections via reversing entries only +- All balances derived from journal entry history — no mutable balance fields anywhere + +### Claude's Discretion +- Payment input fields (reasonable set expected) +- Pre-configured COA account list (standard ISP accounts: revenue, COGS, operating expenses, assets, liabilities, equity) +- Prepaid invoice lead time (how many days before billing date) +- Invoice numbering scheme +- Outstanding balance report layout and filters +- Service plan fields beyond name, speed, and monthly price + + + + +## Specific Ideas + +- Small ISPs often have one person doing everything — the maker-checker workflow should be optional or have a "self-approve" override for single-person operations +- FIFO payment allocation is how most Philippine ISPs work — collectors in the field just collect whatever the subscriber can pay and it goes to the oldest bill +- Credit balance is important because some subscribers prepay multiple months when they have cash on hand + + + + +## Deferred Ideas + +None — discussion stayed within phase scope + + + +--- + +*Phase: 02-subscriber-and-billing-core* +*Context gathered: 2026-03-04*