diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md index 54ed621..db62822 100644 --- a/.planning/REQUIREMENTS.md +++ b/.planning/REQUIREMENTS.md @@ -152,13 +152,80 @@ | Requirement | Phase | Status | |-------------|-------|--------| -| (populated during roadmap creation) | | | +| TENANT-01 | Phase 1 | Pending | +| TENANT-02 | Phase 1 | Pending | +| TENANT-03 | Phase 1 | Pending | +| AUTH-01 | Phase 1 | Pending | +| AUTH-02 | Phase 1 | Pending | +| AUTH-03 | Phase 1 | Pending | +| AUTH-04 | Phase 1 | Pending | +| INFRA-01 | Phase 1 | Pending | +| INFRA-02 | Phase 1 | Pending | +| SUB-01 | Phase 2 | Pending | +| SUB-02 | Phase 2 | Pending | +| SUB-03 | Phase 2 | Pending | +| SUB-04 | Phase 2 | Pending | +| SUB-05 | Phase 2 | Pending | +| BILL-01 | Phase 2 | Pending | +| BILL-02 | Phase 2 | Pending | +| BILL-03 | Phase 2 | Pending | +| BILL-04 | Phase 2 | Pending | +| BILL-05 | Phase 2 | Pending | +| BILL-06 | Phase 2 | Pending | +| ACCT-01 | Phase 2 | Pending | +| ACCT-02 | Phase 2 | Pending | +| ACCT-03 | Phase 2 | Pending | +| ACCT-07 | Phase 2 | Pending | +| ACCT-09 | Phase 2 | Pending | +| COLL-01 | Phase 3 | Pending | +| COLL-02 | Phase 3 | Pending | +| COLL-03 | Phase 3 | Pending | +| COLL-04 | Phase 3 | Pending | +| COLL-05 | Phase 3 | Pending | +| COLL-06 | Phase 3 | Pending | +| TICK-01 | Phase 3 | Pending | +| TICK-02 | Phase 3 | Pending | +| TICK-03 | Phase 3 | Pending | +| TICK-04 | Phase 3 | Pending | +| TICK-05 | Phase 3 | Pending | +| TECH-01 | Phase 3 | Pending | +| TECH-02 | Phase 3 | Pending | +| TECH-03 | Phase 3 | Pending | +| TECH-04 | Phase 3 | Pending | +| INV-01 | Phase 4 | Pending | +| INV-02 | Phase 4 | Pending | +| INV-03 | Phase 4 | Pending | +| INV-04 | Phase 4 | Pending | +| INV-05 | Phase 4 | Pending | +| INV-06 | Phase 4 | Pending | +| EXP-01 | Phase 4 | Pending | +| EXP-02 | Phase 4 | Pending | +| EXP-03 | Phase 4 | Pending | +| EXP-04 | Phase 4 | Pending | +| EXP-05 | Phase 4 | Pending | +| ACCT-04 | Phase 4 | Pending | +| ACCT-05 | Phase 4 | Pending | +| ACCT-06 | Phase 4 | Pending | +| ACCT-08 | Phase 4 | Pending | +| DASH-01 | Phase 5 | Pending | +| DASH-02 | Phase 5 | Pending | +| DASH-03 | Phase 5 | Pending | +| DASH-04 | Phase 5 | Pending | +| PORT-01 | Phase 5 | Pending | +| PORT-02 | Phase 5 | Pending | +| PORT-03 | Phase 5 | Pending | +| PORT-04 | Phase 5 | Pending | +| PORT-05 | Phase 5 | Pending | +| INFRA-03 | Phase 5 | Pending | +| INFRA-04 | Phase 5 | Pending | **Coverage:** -- v1 requirements: 53 total -- Mapped to phases: 0 (pending roadmap) -- Unmapped: 53 ⚠️ +- v1 requirements: 66 total (note: original count of 53 excluded PORT, DASH, and INFRA categories which are v1 scope) +- Mapped to phases: 66 +- Unmapped: 0 ✓ + +**Coverage note on PORT-05:** PORT-05 (online payment gateway integration) is listed in v1 requirements but is noted as out of scope in PROJECT.md ("Automated billing integration with payment gateways — v1 tracks payments, gateway integration later"). It is included in Phase 5 as a UI scaffold only — the interface is built but the actual payment gateway connection is deferred to v2. --- *Requirements defined: 2026-03-04* -*Last updated: 2026-03-04 after initial definition* +*Last updated: 2026-03-04 after roadmap creation — traceability populated* diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md new file mode 100644 index 0000000..8fa6f6a --- /dev/null +++ b/.planning/ROADMAP.md @@ -0,0 +1,139 @@ +# Roadmap: NetForge + +## Overview + +NetForge is built in five phases that follow strict dependency order: the accounting and tenant foundation must exist before any money can move; subscriber and billing core must exist before collectors can reconcile; operational modules (collector workflow, ticketing, inventory, expenses) complete the data that financial reports derive from; and visibility features (dashboard, client portal) are the read layer on top of everything. Every phase delivers a coherent, independently verifiable capability. No phase is optional — skipping any one creates a gap that the next phase cannot fill. + +## Phases + +**Phase Numbering:** +- Integer phases (1, 2, 3): Planned milestone work +- Decimal phases (2.1, 2.2): Urgent insertions (marked with INSERTED) + +Decimal phases appear between their surrounding integers in numeric order. + +- [ ] **Phase 1: Foundation** - Multi-tenant isolation, auth, Docker dev environment, and testing infrastructure +- [ ] **Phase 2: Subscriber and Billing Core** - Subscriber management, billing engine, payment recording, and the double-entry accounting ledger +- [ ] **Phase 3: Operational Modules** - Collector workflow, ticketing system, job orders, and technician management +- [ ] **Phase 4: Inventory, Expenses, and Financial Reports** - Inventory event-ledger, asset management, expense tracking, and accounting financial statements +- [ ] **Phase 5: Visibility and Client Portal** - Dashboard metrics, client self-service portal, integration tests, and end-to-end tests + +## Phase Details + +### Phase 1: Foundation +**Goal**: The development environment is containerized, tenant isolation is enforced at both application and database layers, all five roles can authenticate, and the test harness proves zero cross-tenant data leakage. +**Depends on**: Nothing (first phase) +**Requirements**: TENANT-01, TENANT-02, TENANT-03, AUTH-01, AUTH-02, AUTH-03, AUTH-04, INFRA-01, INFRA-02 +**Success Criteria** (what must be TRUE): + 1. Running `docker compose up` starts the full local stack (PostgreSQL, Redis, Next.js app) with no manual setup steps + 2. An admin can log in with email and password and stay logged in across browser refresh; logging out ends the session + 3. A user with the Technician role cannot access billing or subscriber management routes — a 403 is returned at the API layer, not just hidden in the UI + 4. A new ISP tenant can be created; a query issued by Tenant A returns zero rows from Tenant B's data — verified by automated test + 5. Platform super-admin can log in on a separate auth context and view all tenants without being scoped to any single tenant +**Plans**: TBD + +Plans: +- [ ] 01-01: Docker environment, PostgreSQL with RLS, Redis, project scaffolding (Next.js 15 + TypeScript + Prisma) +- [ ] 01-02: Auth module — Auth.js credential login, JWT with tenant_id + role, session persistence, logout +- [ ] 01-03: Tenant provisioning — signup flow, tenant resolver, Prisma middleware tenant injection, PostgreSQL RLS policies +- [ ] 01-04: RBAC with CASL — permission matrix for all five roles, API-layer enforcement, unauthorized access tests +- [ ] 01-05: Super-admin auth context — separate login, tenant management UI (create, suspend, view), unit test harness for core business logic + +--- + +### Phase 2: Subscriber and Billing Core +**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. +**Depends on**: Phase 1 +**Requirements**: SUB-01, SUB-02, SUB-03, SUB-04, SUB-05, BILL-01, BILL-02, BILL-03, BILL-04, BILL-05, BILL-06, ACCT-01, ACCT-02, ACCT-03, ACCT-07, ACCT-09 +**Success Criteria** (what must be TRUE): + 1. Staff can register a new subscriber with name, address, contact info, and plan assignment, and the subscriber appears in filtered search results immediately + 2. The system auto-generates invoices for all active subscribers on the billing cycle date — prepaid and postpaid subscribers receive invoices following their respective state machine logic + 3. 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 + 4. Every payment and invoice generation event produces a balanced journal entry in the ledger (debits = credits) with no manual accounting step required + 5. Staff can generate an overdue/outstanding report filtered by date range, status, and amount showing correct outstanding balances derived from the journal — no stored balance fields exist +**Plans**: TBD + +Plans: +- [ ] 02-01: Chart of Accounts — pre-configured ISP COA auto-provisioned at tenant signup, ACCT-01 and ACCT-09 (balance derivation from ledger, no mutable balance fields) +- [ ] 02-02: Journal Entry Service — JournalEntryService as sole gateway to ledger, debit=credit enforcement, immutable entries, reversing entry pattern (ACCT-02, ACCT-03, ACCT-07) +- [ ] 02-03: Subscriber management — registration, plan assignment, status lifecycle (active/suspended/cancelled), subscriber search and filtering (SUB-01, SUB-02, SUB-03, SUB-04) +- [ ] 02-04: Billing engine — prepaid and postpaid as distinct state machines, monthly invoice auto-generation via BullMQ scheduled job, due date calculation, overdue detection (BILL-01, BILL-02) +- [ ] 02-05: Payment tracker — cash/bank payment recording, partial payment support, invoice status update, outstanding balance reports, idempotency keys on payment creation, subscriber payment history ledger (BILL-03, BILL-04, BILL-05, BILL-06, SUB-05) + +--- + +### Phase 3: Operational Modules +**Goal**: Collectors can log field cash collections and remit to management with a verified audit trail; staff can create support tickets from client calls and convert them to job orders; technicians can update their own assigned work; and the system calculates technician compensation per job or monthly salary. +**Depends on**: Phase 2 +**Requirements**: COLL-01, COLL-02, COLL-03, COLL-04, COLL-05, COLL-06, TICK-01, TICK-02, TICK-03, TICK-04, TICK-05, TECH-01, TECH-02, TECH-03, TECH-04 +**Success Criteria** (what must be TRUE): + 1. A collector can log a cash payment against a subscriber invoice in the field; the system tracks total collected vs total remitted per collector derived from the transaction log — no stored balance field + 2. A collector can remit collected cash to management; an office staff member verifies the remittance; the verification creates the corresponding double-entry journal entry (cash in transit → office cash) + 3. Staff can create a support ticket from a client call, convert it to a job order, assign it to a technician, and the technician can mark it complete with outcome notes — all status transitions are synchronized between ticket and job order + 4. The system generates a daily collection summary report per collector showing payments collected, remitted, and any variance + 5. Admin can configure per-job compensation rates by job type; the system generates a compensation summary per technician per period correctly for both per-job and monthly-salary models +**Plans**: TBD + +Plans: +- [ ] 03-01: Collector zone management — zone/territory setup, subscriber-to-collector assignment, collector role scoping (COLL-03, AUTH-03) +- [ ] 03-02: Collector field collection and remittance — payment logging by collector, two-party remittance verification, journal entry on verified remittance, daily summary report (COLL-01, COLL-02, COLL-04, COLL-05, COLL-06) +- [ ] 03-03: Ticketing system — ticket creation from staff or client call, priority and category, ticket lifecycle (open → assigned → resolved → closed), client portal ticket submission (TICK-01, TICK-05) +- [ ] 03-04: Job order workflow — ticket-to-job-order conversion, technician assignment, status tracking (pending → in progress → completed), outcome notes, ticket status synchronization (TICK-02, TICK-03, TICK-04) +- [ ] 03-05: Technician management — profiles, compensation model configuration (per-job rates by type, monthly salary), CompensationService, period compensation summary (TECH-01, TECH-02, TECH-03, TECH-04) + +--- + +### Phase 4: Inventory, Expenses, and Financial Reports +**Goal**: Staff can track all network hardware through its full lifecycle as an immutable movement ledger; expenses are recorded and post to the ledger automatically; and the accounting module can produce a verified Trial Balance, Income Statement, and Balance Sheet from journal entry history alone. +**Depends on**: Phase 3 +**Requirements**: INV-01, INV-02, INV-03, INV-04, INV-05, INV-06, EXP-01, EXP-02, EXP-03, EXP-04, EXP-05, ACCT-04, ACCT-05, ACCT-06, ACCT-08 +**Success Criteria** (what must be TRUE): + 1. Staff can register a hardware item and record its movement through warehouse, technician, and subscriber locations as immutable events; current stock levels are derived from the movement history — no mutable quantity column + 2. An asset assigned to a subscriber shows the full location history (where it has been and who had it) + 3. Staff can record an expense with amount, date, category, and vendor; the expense automatically creates a double-entry journal entry with a full audit trail showing who created it, when, and what source transaction it references + 4. Admin can generate an Income Statement for any date range and a Balance Sheet as of any date, both derived entirely from journal entry lines + 5. A Trial Balance can be generated and the totals of all debit balances equal all credit balances — the books are self-verifying +**Plans**: TBD + +Plans: +- [ ] 04-01: Inventory event-ledger — hardware item registration, immutable stock movement records (received, issued, returned, disposed), derived stock level computation (INV-01, INV-02, INV-03) +- [ ] 04-02: Asset management — subscriber asset assignment, technician asset assignment, asset location history, lifecycle tracking (INV-04, INV-05, INV-06) +- [ ] 04-03: Expense tracking — expense recording with category and vendor, expense category management, vendor management, expense-to-journal-entry posting (EXP-01, EXP-02, EXP-03, EXP-05) +- [ ] 04-04: Expense reports and audit trail — expense reports by category, vendor, and period; full audit trail on all journal entries (who, when, source reference) (EXP-04, ACCT-08) +- [ ] 04-05: Financial report engine — Income Statement, Balance Sheet, Trial Balance derived from journal entry history; read-only report queries with proper date range filtering (ACCT-04, ACCT-05, ACCT-06) + +--- + +### Phase 5: Visibility and Client Portal +**Goal**: The ISP owner can see the complete financial and operational picture on a single dashboard; subscribers can log in to view their bills, payment history, and plan details, and submit tickets; and the full system is covered by integration and end-to-end tests on critical workflows. +**Depends on**: Phase 4 +**Requirements**: DASH-01, DASH-02, DASH-03, DASH-04, PORT-01, PORT-02, PORT-03, PORT-04, PORT-05, INFRA-03, INFRA-04 +**Success Criteria** (what must be TRUE): + 1. Dashboard shows revenue collected today and this month, overdue subscriber count, total outstanding amount, subscriber status breakdown (active/suspended/cancelled), and a cash flow summary — all updating when underlying data changes + 2. A subscriber can log in to the client portal and view their current bill, outstanding balance, payment history, and current plan details — scoped strictly to their own account at both the API and data layers + 3. A subscriber can submit a support ticket through the client portal and see it reflected in staff's ticket queue + 4. All API endpoints have integration tests that assert correct responses for authorized and unauthorized roles, verifying API-layer RBAC is not bypassed + 5. Critical user workflows (subscriber registration → invoice generation → payment recording, collector collection → remittance verification, ticket creation → job order completion) pass end-to-end tests +**Plans**: TBD + +Plans: +- [ ] 05-01: Dashboard service — revenue collected, overdue counts, subscriber status counts, cash flow summary; pre-aggregated metrics with indexed queries (DASH-01, DASH-02, DASH-03, DASH-04) +- [ ] 05-02: Client portal — subscriber login, bill and balance view, payment history, plan details and account status (PORT-01, PORT-02, PORT-04) +- [ ] 05-03: Client portal ticket submission and online payment scaffold — ticket submission from portal, PORT-05 online payment interface (payment gateway integration deferred to v2 per project scope; scaffold only) (PORT-03, PORT-05) +- [ ] 05-04: Integration tests — API endpoint tests for all roles, unauthorized access assertions, two-tenant cross-contamination tests (INFRA-03) +- [ ] 05-05: End-to-end tests — critical workflow automation: subscriber registration, billing cycle, payment recording, collector remittance, ticket-to-job-order resolution (INFRA-04) + +--- + +## Progress + +**Execution Order:** +Phases execute in numeric order: 1 → 2 → 3 → 4 → 5 + +| Phase | Plans Complete | Status | Completed | +|-------|----------------|--------|-----------| +| 1. Foundation | 0/5 | Not started | - | +| 2. Subscriber and Billing Core | 0/5 | Not started | - | +| 3. Operational Modules | 0/5 | Not started | - | +| 4. Inventory, Expenses, and Financial Reports | 0/5 | Not started | - | +| 5. Visibility and Client Portal | 0/5 | Not started | - | diff --git a/.planning/STATE.md b/.planning/STATE.md new file mode 100644 index 0000000..c6fb1f2 --- /dev/null +++ b/.planning/STATE.md @@ -0,0 +1,63 @@ +# Project State + +## Project Reference + +See: .planning/PROJECT.md (updated 2026-03-04) + +**Core value:** ISP owners can see exactly where their money is — who owes what, what's been collected, what's been spent, and what the business actually looks like financially — in real time. +**Current focus:** Phase 1 - Foundation + +## Current Position + +Phase: 1 of 5 (Foundation) +Plan: 0 of 5 in current phase +Status: Ready to plan +Last activity: 2026-03-04 — Roadmap created, STATE.md initialized + +Progress: [░░░░░░░░░░] 0% + +## Performance Metrics + +**Velocity:** +- Total plans completed: 0 +- Average duration: - +- Total execution time: 0 hours + +**By Phase:** + +| Phase | Plans | Total | Avg/Plan | +|-------|-------|-------|----------| +| - | - | - | - | + +**Recent Trend:** +- Last 5 plans: none yet +- Trend: - + +*Updated after each plan completion* + +## Accumulated Context + +### Decisions + +Decisions are logged in PROJECT.md Key Decisions table. +Recent decisions affecting current work: + +- [Roadmap]: Accounting COA and JournalEntryService built in Phase 2 before first invoice — cannot be retrofitted +- [Roadmap]: Inventory modeled as event-ledger (immutable movements) from Phase 4 — mutable quantity columns explicitly rejected +- [Roadmap]: Collector balances derived from transaction log, never stored as mutable fields +- [Roadmap]: PORT-05 (online payment) scaffolded in Phase 5 but payment gateway integration deferred to v2 per project out-of-scope decision + +### Pending Todos + +None yet. + +### Blockers/Concerns + +- [Phase 1 research flag]: MikroTik RouterOS Node.js client library maintenance status is LOW confidence — verify `node-routeros` vs `mikronode` before implementing router integration (MikroTik integration is v2, but adapter interface should be planned) +- [Phase 3 research flag]: Semaphore SMS API pricing/stability for 2026 is MEDIUM confidence — verify before any SMS work (SMS is v2, but abstraction layer design is relevant) + +## Session Continuity + +Last session: 2026-03-04 +Stopped at: Roadmap created. ROADMAP.md, STATE.md written. REQUIREMENTS.md traceability updated. Ready to plan Phase 1. +Resume file: None