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

docs: create roadmap (5 phases) and research

Browse Source 
Phases:
1. Foundation: tenant isolation, auth, Docker, RBAC
2. Subscriber & Billing Core: subscribers, invoicing, payments, accounting ledger
3. Operational Modules: collectors, ticketing, job orders, technicians
4. Inventory, Expenses & Reports: event-ledger inventory, expenses, financial statements
5. Visibility & Client Portal: dashboard, client self-service, integration & e2e tests

All 66 v1 requirements mapped to phases.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
kevin-asprec
2026-03-04 17:45:09 +08:00
parent 21541fd8d5
commit 1bdb4eafae
3 changed files with 274 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files

77
.planning/REQUIREMENTS.md
View File

@@ -152,13 +152,80 @@
| Requirement | Phase | Status | | 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:** **Coverage:**
- v1 requirements: 53 total - v1 requirements: 66 total (note: original count of 53 excluded PORT, DASH, and INFRA categories which are v1 scope)
- Mapped to phases: 0 (pending roadmap) - Mapped to phases: 66
- Unmapped: 53 ⚠️ - 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* *Requirements defined: 2026-03-04*
*Last updated: 2026-03-04 after initial definition* *Last updated: 2026-03-04 after roadmap creation — traceability populated*

139
.planning/ROADMAP.md Normal file
View File

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

63
.planning/STATE.md Normal file
View File

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