diff --git a/.planning/STATE.md b/.planning/STATE.md index 7291c69..fd95a92 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -9,19 +9,19 @@ See: .planning/PROJECT.md (updated 2026-03-04) ## Current Position -Phase: 3 of 5 (Operational Modules) — COMPLETE -Plan: 5 of 5 in phase 3 (17/20 total complete) -Status: Phase 3 complete. 03-01 (Zones), 03-02 (Collections/Remittances), 03-03 (Ticketing), 03-04 (Job Orders), 03-05 (Technician Compensation) all complete. -Last activity: 2026-03-05 — Completed 03-05-PLAN.md (Technician Management — 27 tests, hybrid compensation, PER_JOB/SALARY/HYBRID models) +Phase: 4 of 5 (Inventory, Expenses, and Financial Reports) +Plan: 1 of 3 in phase 4 (18/20 total complete) +Status: In progress. 04-01 (Inventory Event-Ledger) complete. +Last activity: 2026-03-05 — Completed 04-01-PLAN.md (Inventory Event-Ledger — 13 tests, dual tracking, immutable movements, JE posting) -Progress: [█████████████████░░░] 85% (17/20 plans across all phases) +Progress: [██████████████████░░] 90% (18/20 plans across all phases) ## Performance Metrics **Velocity:** -- Total plans completed: 11 -- Average duration: 9.5 min -- Total execution time: 104 min +- Total plans completed: 12 +- Average duration: 10 min +- Total execution time: 120 min **By Phase:** @@ -30,10 +30,11 @@ Progress: [█████████████████░░░] 85% (17 | 01-foundation | 5/5 complete | 41 min | 8.2 min | | 02-subscriber-and-billing-core | 5/5 complete | 57 min | 11.4 min | | 03-operational-modules | 5/5 complete | ~65 min | ~13 min | +| 04-inventory-expenses-reports | 1/3 complete | 16 min | 16 min | **Recent Trend:** -- Last 10 plans: 01-05 (6 min), 02-01 (7 min), 02-03 (7 min), 02-02 (16 min), 02-04 (12 min), 02-05 (8 min), 03-01 (15 min), 03-02 (11 min), 03-04 (6 min), 03-05 (9 min) -- Trend: stable — 03-05 migration applied cleanly, all 27 tests passed on first run +- Last 10 plans: 02-01 (7 min), 02-03 (7 min), 02-02 (16 min), 02-04 (12 min), 02-05 (8 min), 03-01 (15 min), 03-02 (11 min), 03-04 (6 min), 03-05 (9 min), 04-01 (16 min) +- Trend: stable — 04-01 migration applied cleanly, all 13 tests passed on first run *Updated after each plan completion* @@ -119,6 +120,10 @@ Recent decisions affecting current work: - [03-05]: Missing job type rate defaults to 0 bonus — rateMap.get(jobType) ?? Decimal(0); not an error per design spec - [03-05]: SALARY model detail returns jobs with rate=0 — consistent API shape across all 3 models; all detail responses have a jobs array - [03-05]: Compensation cleanup order in tests: jobOrders -> tickets -> ticketCategories -> jobTypeRates -> technicianProfiles -> zoneAssignments -> subscribers -> zones -> servicePlans -> users -> tenant +- [04-01]: Only RECEIVED movements auto-post JEs (DR 1200, CR 2010) — ISSUED/RETURNED/DISPOSED/TRANSFERRED do not create JEs +- [04-01]: CASL subject is "Inventory" (existing type in types.ts) — OFFICE_STAFF gets can("manage", "Inventory") +- [04-01]: Stock levels derived in JS from movement aggregation — acceptable for ISP scale (same pattern as collector balances, outstanding reports) +- [04-01]: Inventory cleanup order in tests: stockMovements -> inventoryItems -> journalEntryLines -> null reversesEntryId -> journalEntries -> accountingPeriods -> accounts -> users -> tenant ### Pending Todos @@ -136,6 +141,6 @@ None. ## Session Continuity -Last session: 2026-03-05T00:17:08Z -Stopped at: Completed 03-05-PLAN.md (Technician Management — 27 tests, hybrid compensation, Phase 3 complete) +Last session: 2026-03-05T02:32:00Z +Stopped at: Completed 04-01-PLAN.md (Inventory Event-Ledger — 13 tests, dual tracking, immutable movements) Resume file: None diff --git a/.planning/phases/04-inventory-expenses-and-financial-reports/04-01-SUMMARY.md b/.planning/phases/04-inventory-expenses-and-financial-reports/04-01-SUMMARY.md new file mode 100644 index 0000000..df2f33f --- /dev/null +++ b/.planning/phases/04-inventory-expenses-and-financial-reports/04-01-SUMMARY.md @@ -0,0 +1,111 @@ +--- +phase: 04-inventory-expenses-and-financial-reports +plan: 01 +subsystem: inventory +tags: [inventory, stock-movements, event-ledger, journal-entries, dual-tracking] +dependency-graph: + requires: [02-01, 02-02] + provides: [InventoryItem-model, StockMovement-model, InventoryService, inventory-api-routes] + affects: [04-02] +tech-stack: + added: [] + patterns: [immutable-event-ledger, derived-stock-levels, dual-tracking-serialized-batch] +key-files: + created: + - prisma/migrations/20260305021700_add_inventory_models/migration.sql + - src/lib/services/inventory-service.ts + - src/app/api/inventory/items/route.ts + - src/app/api/inventory/items/[id]/route.ts + - src/app/api/inventory/items/[id]/movements/route.ts + - src/app/api/inventory/stock-levels/route.ts + - src/lib/__tests__/inventory-service.test.ts + modified: + - prisma/schema.prisma + - src/lib/casl/permissions.ts +decisions: + - id: inv-tracking-type + summary: "Dual tracking: SERIALIZED (serial number required, qty=1) vs BATCH (no serial, variable qty)" + - id: inv-je-received-only + summary: "Only RECEIVED movements auto-post JEs (DR 1200, CR 2010); ISSUED/RETURNED/DISPOSED/TRANSFERRED do not" + - id: inv-casl-subject + summary: "CASL subject is 'Inventory' (existing type), not 'InventoryItem' — OFFICE_STAFF gets manage Inventory" +metrics: + duration: "16 min" + completed: "2026-03-05" +--- + +# Phase 4 Plan 1: Inventory Event-Ledger Foundation Summary + +Immutable stock movement ledger with dual tracking (serialized by serial number, batch by quantity), derived stock level computation, and automatic JE posting for receiving movements. + +## What Was Built + +### Schema (Task 1) +- 4 new enums: `ItemTrackingType` (SERIALIZED/BATCH), `ItemCondition` (NEW/REFURBISHED/USED/DAMAGED), `MovementType` (RECEIVED/ISSUED/RETURNED/DISPOSED/TRANSFERRED), `LocationType` (WAREHOUSE/TECHNICIAN/SUBSCRIBER) +- `InventoryItem` model: dual tracking, serial number uniqueness per tenant (nullable unique), purchaseCost/purchaseDate/warrantyExpiry +- `StockMovement` model: immutable (no updatedAt), journalEntryId for RECEIVED, performedBy relation to User +- Indexes on tenantId, itemType, trackingType, inventoryItemId, movementType + +### InventoryService (Task 2) +- `registerItem`: creates items, validates SERIALIZED requires serial number, BATCH rejects serial number +- `recordMovement`: validates per-movement-type rules, enforces qty=1 for SERIALIZED, auto-posts JE for RECEIVED (DR 1200 Equipment Inventory, CR 2010 Accounts Payable) +- `getStockLevels`: derives stock from movement aggregation (RECEIVED/RETURNED add, ISSUED/TRANSFERRED remove+add, DISPOSED remove), filters zero-quantity entries +- `getItemMovements`: chronological history with performedBy details +- `listItems`: filterable by itemType, trackingType, isActive +- `getItem`: single item with recent movements + +### API Routes +- `POST /api/inventory/items` — register new item (ADMIN, OFFICE_STAFF) +- `GET /api/inventory/items` — list items with filters +- `GET /api/inventory/items/[id]` — item detail +- `POST /api/inventory/items/[id]/movements` — record movement +- `GET /api/inventory/items/[id]/movements` — movement history +- `GET /api/inventory/stock-levels` — derived stock levels + +### CASL Permissions +- OFFICE_STAFF: `can("manage", "Inventory")` added +- TECHNICIAN: existing `can("read", "Inventory")` preserved + +### Tests (13 passing) +- Registration: serialized with serial, batch without, reject serialized without serial, reject batch with serial +- Movements: RECEIVED with JE (DR 1200, CR 2010), ISSUED, RETURNED, DISPOSED, reject SERIALIZED qty>1 +- Stock derivation: batch receive 10 issue 3 = 7, serialized latest location +- History: chronological order +- List: itemType filter + +## Decisions Made + +| Decision | Rationale | +|----------|-----------| +| Only RECEIVED movements create JEs | Other movement types (ISSUED, RETURNED, etc.) are internal transfers that don't affect AP. Asset reclassification JEs for ISSUED/DISPOSED will be added in 04-02 if needed | +| CASL subject "Inventory" not "InventoryItem" | Reuses existing subject type from types.ts. OFFICE_STAFF gets full manage access | +| Stock levels computed in JS not SQL | Follows existing pattern (collector balances, outstanding reports). Acceptable for ISP scale | + +## Deviations from Plan + +### Auto-fixed Issues + +**1. [Rule 2 - Missing Critical] OFFICE_STAFF inventory CASL permission** +- **Found during:** Task 2 (API route creation) +- **Issue:** OFFICE_STAFF had no Inventory permissions in CASL, would fail withPermission() checks +- **Fix:** Added `can("manage", "Inventory")` to OFFICE_STAFF role +- **Files modified:** src/lib/casl/permissions.ts +- **Commit:** a742f70 + +**2. [Rule 3 - Blocking] CASL subject mismatch** +- **Found during:** Task 2 (API route creation) +- **Issue:** Plan specified "InventoryItem" as withPermission subject but types.ts only has "Inventory" +- **Fix:** Used "Inventory" subject in all API routes +- **Files modified:** All API route files +- **Commit:** a742f70 + +## Next Phase Readiness + +04-02 (Asset Lifecycle) can build on: +- InventoryItem and StockMovement models are stable +- InventoryService.recordMovement handles all 5 movement types +- Stock level derivation ready for assignment tracking (ISSUED to subscriber) +- JE posting pattern established (can extend for disposal write-offs) + +### Cleanup Order for Tests +stockMovements -> inventoryItems -> journalEntryLines -> null reversesEntryId -> journalEntries -> accountingPeriods -> accounts -> users -> tenant