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

docs(04): complete Inventory, Expenses, and Financial Reports phase

Browse Source 
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
kevin-asprec
2026-03-05 15:57:57 +08:00
parent 0316bb211f
commit 517454b329
3 changed files with 140 additions and 37 deletions
Download Patch File Download Diff File Expand all files Collapse all files

60
.planning/REQUIREMENTS.md
View File

@@ -58,31 +58,31 @@
### Inventory & Asset Management
- [ ] **INV-01**: Staff can register hardware items (routers, ONUs, cables, connectors, splitters) with type, model, serial number
- [ ] **INV-02**: All stock movements are recorded as immutable events (received, issued, returned, disposed)
- [ ] **INV-03**: System tracks current stock levels derived from movement history (not mutable quantity)
- [ ] **INV-04**: Assets can be assigned to a subscriber (deployed at client location)
- [ ] **INV-05**: Assets can be assigned to a technician (carried for field work)
- [ ] **INV-06**: Staff can view asset history (where it's been, who had it)
- [x] **INV-01**: Staff can register hardware items (routers, ONUs, cables, connectors, splitters) with type, model, serial number
- [x] **INV-02**: All stock movements are recorded as immutable events (received, issued, returned, disposed)
- [x] **INV-03**: System tracks current stock levels derived from movement history (not mutable quantity)
- [x] **INV-04**: Assets can be assigned to a subscriber (deployed at client location)
- [x] **INV-05**: Assets can be assigned to a technician (carried for field work)
- [x] **INV-06**: Staff can view asset history (where it's been, who had it)
### Expense Tracking
- [ ] **EXP-01**: Staff can record expenses with amount, date, category, vendor, and description
- [ ] **EXP-02**: Admin can manage expense categories (bandwidth, rent, fuel, supplies, etc.)
- [ ] **EXP-03**: Staff can manage vendors (name, contact, services provided)
- [ ] **EXP-04**: System generates expense reports by category, vendor, and period
- [ ] **EXP-05**: All expenses create corresponding journal entries in accounting
- [x] **EXP-01**: Staff can record expenses with amount, date, category, vendor, and description
- [x] **EXP-02**: Admin can manage expense categories (bandwidth, rent, fuel, supplies, etc.)
- [x] **EXP-03**: Staff can manage vendors (name, contact, services provided)
- [x] **EXP-04**: System generates expense reports by category, vendor, and period
- [x] **EXP-05**: All expenses create corresponding journal entries in accounting
### Accounting
- [x] **ACCT-01**: System provides a standard Chart of Accounts pre-configured for ISP business
- [x] **ACCT-02**: All money movements (payments, expenses, collector remittances) auto-generate double-entry journal entries
- [x] **ACCT-03**: Staff can create manual journal entries for inter-account transfers (e.g., cash-on-hand → bank)
- [ ] **ACCT-04**: System generates Income Statement (Profit & Loss) for any date range
- [ ] **ACCT-05**: System generates Balance Sheet (assets, liabilities, equity) as of any date
- [ ] **ACCT-06**: System generates Trial Balance to verify books are balanced
- [x] **ACCT-04**: System generates Income Statement (Profit & Loss) for any date range
- [x] **ACCT-05**: System generates Balance Sheet (assets, liabilities, equity) as of any date
- [x] **ACCT-06**: System generates Trial Balance to verify books are balanced
- [x] **ACCT-07**: All journal entries are immutable — corrections done via reversing entries only
- [ ] **ACCT-08**: Full audit trail on every accounting entry (who created, when, reference to source transaction)
- [x] **ACCT-08**: Full audit trail on every accounting entry (who created, when, reference to source transaction)
- [x] **ACCT-09**: All account balances are derived from journal entry history (never stored as mutable values)
### Client Portal
@@ -192,21 +192,21 @@
| TECH-02 | Phase 3 | Complete |
| TECH-03 | Phase 3 | Complete |
| TECH-04 | Phase 3 | Complete |
| 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 |
| INV-01 | Phase 4 | Complete |
| INV-02 | Phase 4 | Complete |
| INV-03 | Phase 4 | Complete |
| INV-04 | Phase 4 | Complete |
| INV-05 | Phase 4 | Complete |
| INV-06 | Phase 4 | Complete |
| EXP-01 | Phase 4 | Complete |
| EXP-02 | Phase 4 | Complete |
| EXP-03 | Phase 4 | Complete |
| EXP-04 | Phase 4 | Complete |
| EXP-05 | Phase 4 | Complete |
| ACCT-04 | Phase 4 | Complete |
| ACCT-05 | Phase 4 | Complete |
| ACCT-06 | Phase 4 | Complete |
| ACCT-08 | Phase 4 | Complete |
| DASH-01 | Phase 5 | Pending |
| DASH-02 | Phase 5 | Pending |
| DASH-03 | Phase 5 | Pending |

14
.planning/ROADMAP.md
View File

@@ -15,7 +15,7 @@ Decimal phases appear between their surrounding integers in numeric order.
- [x] **Phase 1: Foundation** - Multi-tenant isolation, auth, Docker dev environment, and testing infrastructure
- [x] **Phase 2: Subscriber and Billing Core** - Subscriber management, billing engine, payment recording, and the double-entry accounting ledger
- [x] **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
- [x] **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
@@ -96,11 +96,11 @@ Plans:
**Plans**: 5 plans
Plans:
- [ ] 04-01-PLAN.md — Inventory event-ledger: hardware item registration, immutable stock movements, derived stock levels, JE posting for receiving (INV-01, INV-02, INV-03)
- [ ] 04-02-PLAN.md — Asset management: subscriber/technician asset assignment, return with condition, admin-only disposal with write-off JE, location history (INV-04, INV-05, INV-06)
- [ ] 04-03-PLAN.md — Expense tracking: expense recording with category/vendor, expense category seeding, vendor CRUD, expense-to-JE posting (EXP-01, EXP-02, EXP-03, EXP-05)
- [ ] 04-04-PLAN.md — Expense reports and audit trail: reports by category/vendor/period, JE audit trail with creator and source reference (EXP-04, ACCT-08)
- [ ] 04-05-PLAN.md — Financial report engine: Trial Balance, Income Statement, Balance Sheet from JE history, account drill-down (ACCT-04, ACCT-05, ACCT-06)
- [x] 04-01-PLAN.md — Inventory event-ledger: hardware item registration, immutable stock movements, derived stock levels, JE posting for receiving (INV-01, INV-02, INV-03)
- [x] 04-02-PLAN.md — Asset management: subscriber/technician asset assignment, return with condition, admin-only disposal with write-off JE, location history (INV-04, INV-05, INV-06)
- [x] 04-03-PLAN.md — Expense tracking: expense recording with category/vendor, expense category seeding, vendor CRUD, expense-to-JE posting (EXP-01, EXP-02, EXP-03, EXP-05)
- [x] 04-04-PLAN.md — Expense reports and audit trail: reports by category/vendor/period, JE audit trail with creator and source reference (EXP-04, ACCT-08)
- [x] 04-05-PLAN.md — Financial report engine: Trial Balance, Income Statement, Balance Sheet from JE history, account drill-down (ACCT-04, ACCT-05, ACCT-06)
---
@@ -135,5 +135,5 @@ Phases execute in numeric order: 1 → 2 → 3 → 4 → 5
| 1. Foundation | 5/5 | ✓ Complete | 2026-03-04 |
| 2. Subscriber and Billing Core | 5/5 | ✓ Complete | 2026-03-04 |
| 3. Operational Modules | 5/5 | ✓ Complete | 2026-03-05 |
| 4. Inventory, Expenses, and Financial Reports | 0/5 | Planned | - |
| 4. Inventory, Expenses, and Financial Reports | 5/5 | ✓ Complete | 2026-03-06 |
| 5. Visibility and Client Portal | 0/5 | Not started | - |

103
.planning/phases/04-inventory-expenses-and-financial-reports/04-VERIFICATION.md Normal file
View File

@@ -0,0 +1,103 @@
---
phase: 04-inventory-expenses-and-financial-reports
verified: 2026-03-05T12:00:00Z
status: passed
score: 5/5 must-haves verified
---
# Phase 4: Inventory, Expenses, and Financial Reports Verification Report
**Phase 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.
**Verified:** 2026-03-05T12:00:00Z
**Status:** passed
**Re-verification:** No -- initial verification
## Goal Achievement
### Observable Truths
| # | Truth | Status | Evidence |
|---|-------|--------|----------|
| 1 | Staff can register hardware and record movements as immutable events; stock levels derived from movement history | VERIFIED | InventoryService (429 lines) has registerItem, recordMovement with 5 movement types, getStockLevels derived via aggregation. StockMovement schema has no updatedAt (immutable). No mutable quantity column exists. 13 tests cover registration, movements, stock derivation. |
| 2 | Asset assigned to subscriber shows full location history | VERIFIED | AssetService (449 lines) has getAssetHistory returning chronological timeline with resolved subscriber/technician/warehouse names via batch Map lookup. API at GET /api/inventory/items/[id]/history wired to AssetService. 11 tests include full lifecycle test (RECEIVED to ISSUED to tech to RETURNED to ISSUED to sub to RETURNED to DISPOSED). |
| 3 | Expense records with amount/date/category/vendor auto-create double-entry JE with audit trail | VERIFIED | Expense model has amount (Decimal), expenseDate, categoryId, vendorId, createdById, journalEntryId fields. ExpenseService.postExpense creates balanced JE via JournalEntryService.createEntry with DR expense account (from category.accountCode) and CR cash/bank (from paymentMethod). AuditTrailService (169 lines) traces JE to creator, timestamp, and source referenceType/referenceId. 15 expense tests + 9 audit trail tests. |
| 4 | Income Statement for date range and Balance Sheet as of date, derived from JE lines | VERIFIED | FinancialReportService (557 lines) getIncomeStatement queries JE lines by REVENUE/EXPENSE account types within date range. getBalanceSheet queries JE lines for ASSET/LIABILITY/EQUITY up to asOfDate, computes Net Income inline. Both use journalEntryLine.groupBy with POSTED status filter. API routes wired to service. 16 tests verify correct amounts and date filtering. |
| 5 | Trial Balance with debits equal credits -- self-verifying | VERIFIED | FinancialReportService.getTrialBalance computes totalDebits and totalCredits from JE lines, returns isBalanced = equalsInCents(totalDebits, totalCredits). Tests explicitly assert isBalanced === true and totalDebits.equals(totalCredits). Empty tenant also verified balanced with zero totals. |
**Score:** 5/5 truths verified
### Required Artifacts
| Artifact | Expected | Status | Details |
|----------|----------|--------|---------|
| src/lib/services/inventory-service.ts | Inventory event ledger | VERIFIED | 429 lines, no stubs, imported by 3 API routes + asset-service |
| src/lib/services/asset-service.ts | Asset lifecycle | VERIFIED | 449 lines, no stubs, imported by 4 API routes |
| src/lib/services/expense-service.ts | Expense tracking + JE | VERIFIED | 537 lines, no stubs, imported by 3 API routes |
| src/lib/services/vendor-service.ts | Vendor CRUD | VERIFIED | 149 lines, imported by 2 API routes |
| src/lib/services/expense-report-service.ts | Expense aggregation | VERIFIED | 214 lines, imported by 2 API routes |
| src/lib/services/audit-trail-service.ts | JE audit trail | VERIFIED | 169 lines, imported by API route |
| src/lib/services/financial-report-service.ts | Financial reports | VERIFIED | 557 lines, all from JE lines, imported by 4 API routes |
| prisma/schema.prisma models | Data models | VERIFIED | InventoryItem, StockMovement (no updatedAt), Expense, Vendor, ExpenseCategory all present |
| 28 API route files | REST endpoints | VERIFIED | All exist (10-99 lines each), import and call services, use withPermission |
| 5 test files | Integration tests | VERIFIED | 2,626 total lines, 64 tests across inventory/asset/expense/audit/financial |
### Key Link Verification
| From | To | Via | Status | Details |
|------|----|-----|--------|---------|
| InventoryService.recordMovement | JournalEntryService.createEntry | Direct call for RECEIVED | WIRED | DR 1200, CR 2010 with totalCost |
| AssetService.disposeAsset | JournalEntryService.createEntry | Direct call for disposal | WIRED | DR 5030, CR 1200 write-off |
| ExpenseService.postExpense | JournalEntryService.createEntry | Direct call, ref=Expense | WIRED | DR category account, CR cash/bank |
| FinancialReportService | journalEntryLine.groupBy | Prisma queries on POSTED JEs | WIRED | All 3 reports derive from JE lines |
| AuditTrailService | journalEntry queries | Prisma with createdBy, lines | WIRED | Returns creator, timestamp, source ref |
| All API routes | Service methods | import + call | WIRED | All 28 routes properly wired |
### Requirements Coverage
| Requirement | Status | Blocking Issue |
|-------------|--------|----------------|
| INV-01: Register hardware items | SATISFIED | -- |
| INV-02: Immutable stock movements | SATISFIED | -- |
| INV-03: Derived stock levels | SATISFIED | -- |
| INV-04: Asset assign to subscriber | SATISFIED | -- |
| INV-05: Asset assign to technician | SATISFIED | -- |
| INV-06: Asset history | SATISFIED | -- |
| EXP-01: Record expenses | SATISFIED | -- |
| EXP-02: Manage expense categories | SATISFIED | -- |
| EXP-03: Manage vendors | SATISFIED | -- |
| EXP-04: Expense reports | SATISFIED | -- |
| EXP-05: Expenses create JEs | SATISFIED | -- |
| ACCT-04: Income Statement | SATISFIED | -- |
| ACCT-05: Balance Sheet | SATISFIED | -- |
| ACCT-06: Trial Balance | SATISFIED | -- |
| ACCT-08: Full audit trail | SATISFIED | -- |
### Anti-Patterns Found
No TODO, FIXME, placeholder, or stub patterns found in any phase 4 service or API route file.
### Human Verification Required
#### 1. Stock Level Derivation Accuracy
**Test:** Register batch items, perform mixed movements (RECEIVED, ISSUED, RETURNED, DISPOSED), then check /api/inventory/stock-levels
**Expected:** Stock levels match expected quantities at each location
**Why human:** Complex aggregation logic; manual spot-check against real DB confirms correctness
#### 2. Full Asset Lifecycle Timeline
**Test:** Create serialized item, assign to technician, return, assign to subscriber, return, dispose. View /api/inventory/items/{id}/history
**Expected:** Chronological timeline with resolved names
**Why human:** Name resolution depends on actual subscriber/user records
#### 3. Financial Reports Cross-Consistency
**Test:** Create various transactions, generate all 3 reports
**Expected:** Trial Balance debits = credits; Income Statement net income matches Balance Sheet net income line
**Why human:** Cross-report consistency needs human verification with known data
### Gaps Summary
No gaps found. All 5 observable truths verified at all three levels (existence, substantive implementation, wiring). All 15 requirements satisfied. No stub patterns found. 64 integration tests across 5 test files cover all critical behaviors.
---
_Verified: 2026-03-05T12:00:00Z_
_Verifier: Claude (gsd-verifier)_