diff --git a/.planning/STATE.md b/.planning/STATE.md index fd95a92..672b119 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -10,18 +10,18 @@ See: .planning/PROJECT.md (updated 2026-03-04) ## Current Position 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) +Plan: 3 of 5 in phase 4 (20/22 total complete) +Status: In progress. 04-01 and 04-03 complete. +Last activity: 2026-03-05 — Completed 04-03-PLAN.md (Expense Tracking — 15 tests, vendor management, approval workflow, JE posting) -Progress: [██████████████████░░] 90% (18/20 plans across all phases) +Progress: [████████████████████] 91% (20/22 plans across all phases) ## Performance Metrics **Velocity:** -- Total plans completed: 12 -- Average duration: 10 min -- Total execution time: 120 min +- Total plans completed: 13 +- Average duration: 11 min +- Total execution time: 137 min **By Phase:** @@ -30,11 +30,11 @@ Progress: [██████████████████░░] 90% (18 | 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 | +| 04-inventory-expenses-reports | 2/5 complete | 33 min | 16.5 min | **Recent Trend:** -- 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 +- Last 10 plans: 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), 04-03 (17 min) +- Trend: stable — 04-03 all 15 tests passed, migration via db push + resolve *Updated after each plan completion* @@ -124,6 +124,12 @@ Recent decisions affecting current work: - [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 +- [04-03]: ExpensePaymentMethod determines CR account: CASH->1010, BANK_TRANSFER/CHECK->1020 +- [04-03]: Default behavior is immediate post (no approval required); requireApproval flag enables DRAFT-only creation +- [04-03]: System expense categories (isSystemCategory=true) cannot be deleted; custom categories deletable if no expenses reference them +- [04-03]: Vendor added as CASL subject; OFFICE_STAFF gets manage Expense and manage Vendor +- [04-03]: ISP COA now has 31 accounts — added 5080 Fuel/Transportation, 5085 Rent Expense +- [04-03]: Expense cleanup order: expenses -> vendors -> expenseCategories (non-system) -> journalEntryLines -> null reversesEntryId -> journalEntries -> accountingPeriods -> accounts -> ticketCategories -> expenseCategories (system) -> users -> tenant ### Pending Todos @@ -141,6 +147,6 @@ None. ## Session Continuity -Last session: 2026-03-05T02:32:00Z -Stopped at: Completed 04-01-PLAN.md (Inventory Event-Ledger — 13 tests, dual tracking, immutable movements) +Last session: 2026-03-05T02:52:00Z +Stopped at: Completed 04-03-PLAN.md (Expense Tracking — 15 tests, vendor management, approval workflow, JE posting) Resume file: None diff --git a/.planning/phases/04-inventory-expenses-and-financial-reports/04-03-SUMMARY.md b/.planning/phases/04-inventory-expenses-and-financial-reports/04-03-SUMMARY.md new file mode 100644 index 0000000..1b3114c --- /dev/null +++ b/.planning/phases/04-inventory-expenses-and-financial-reports/04-03-SUMMARY.md @@ -0,0 +1,151 @@ +--- +phase: 04-inventory-expenses-and-financial-reports +plan: 03 +subsystem: expenses, accounting +tags: [expense-tracking, vendor-management, journal-entries, double-entry, approval-workflow, prisma] + +# Dependency graph +requires: + - phase: 02-subscriber-and-billing-core + provides: "JournalEntryService, Chart of Accounts, accounting period management" + - phase: 01-foundation + provides: "Tenant provisioning, CASL permissions, withTenantContext" +provides: + - "Vendor model and VendorService (CRUD)" + - "ExpenseCategory model with 9 pre-seeded ISP categories" + - "Expense model with ExpenseService (create, approve, post, void)" + - "Automatic JE posting on expense post (DR expense account, CR cash/bank)" + - "Optional approval workflow (DRAFT -> APPROVED -> POSTED)" + - "API routes for expenses, categories, and vendors" + - "COA accounts 5080 Fuel/Transportation, 5085 Rent Expense (31 total)" +affects: [04-05-financial-reports, 05-dashboard] + +# Tech tracking +tech-stack: + added: [] + patterns: + - "Expense JE pattern: DR category.accountCode, CR 1010/1020 based on paymentMethod" + - "Optional approval workflow via requireApproval flag" + - "ExpensePaymentMethod enum determines CR account (CASH->1010, BANK_TRANSFER/CHECK->1020)" + +key-files: + created: + - "src/lib/services/expense-service.ts" + - "src/lib/services/vendor-service.ts" + - "src/app/api/expenses/route.ts" + - "src/app/api/expenses/[id]/route.ts" + - "src/app/api/expenses/[id]/approve/route.ts" + - "src/app/api/expenses/categories/route.ts" + - "src/app/api/expenses/categories/[id]/route.ts" + - "src/app/api/vendors/route.ts" + - "src/app/api/vendors/[id]/route.ts" + - "src/lib/__tests__/expense-service.test.ts" + - "prisma/migrations/20260305_add_expense_vendor_models/migration.sql" + modified: + - "prisma/schema.prisma" + - "src/lib/tenant.ts" + - "src/lib/accounting/chart-of-accounts.ts" + - "src/lib/casl/types.ts" + - "src/lib/casl/permissions.ts" + +key-decisions: + - "ExpensePaymentMethod determines CR account: CASH->1010, BANK_TRANSFER/CHECK->1020" + - "Default behavior is immediate post (no approval required); requireApproval flag enables DRAFT-only creation" + - "System expense categories (isSystemCategory=true) cannot be deleted; custom categories can be deleted if no expenses reference them" + - "Vendor subject added to CASL types; OFFICE_STAFF gets manage permissions for Expense and Vendor" + - "COA now has 31 accounts (added 5080 Fuel/Transportation, 5085 Rent Expense)" + - "Expense cleanup order: expenses -> vendors -> expenseCategories (non-system) -> journalEntryLines -> null reversesEntryId -> journalEntries -> accountingPeriods -> accounts -> ticketCategories -> expenseCategories (system) -> users -> tenant" + +patterns-established: + - "Expense JE: DR category expense account (from accountCode), CR cash/bank account" + - "Optional approval workflow pattern: requireApproval flag on create, approveExpense triggers post" + - "Category-to-COA linking via accountCode field on ExpenseCategory" + +# Metrics +duration: 17min +completed: 2026-03-05 +--- + +# Phase 4 Plan 3: Expense Tracking Summary + +**Expense tracking with vendor management, 9 pre-seeded categories, optional approval workflow, and automatic double-entry JE posting on every expense** + +## Performance + +- **Duration:** 17 min +- **Started:** 2026-03-05T02:35:00Z +- **Completed:** 2026-03-05T02:52:00Z +- **Tasks:** 2 +- **Files modified:** 16 + +## Accomplishments +- Full expense lifecycle: create, approve, post, void with JE integration +- 9 default ISP expense categories seeded at tenant creation (bandwidth, equipment, salary, etc.) +- Vendor CRUD with unique name per tenant +- Every posted expense creates balanced JE (DR expense account from category, CR cash/bank) +- Optional approval workflow (DRAFT -> APPROVED -> POSTED when enabled) +- 15 integration tests covering all expense scenarios + +## Task Commits + +Each task was committed atomically: + +1. **Task 1: Schema + COA + category seeding** - `fe4d22f` (feat) +2. **Task 2: Services, API routes, migration, tests** - `b7bbc50` (feat) + +## Files Created/Modified +- `prisma/schema.prisma` - Added Vendor, ExpenseCategory, Expense models + enums +- `src/lib/tenant.ts` - Added expense category seeding in createTenant transaction +- `src/lib/accounting/chart-of-accounts.ts` - Added 5080, 5085 expense accounts (31 total) +- `src/lib/casl/types.ts` - Added Vendor subject +- `src/lib/casl/permissions.ts` - Added Expense/Vendor permissions for OFFICE_STAFF +- `src/lib/services/vendor-service.ts` - VendorService: create, update, list, get +- `src/lib/services/expense-service.ts` - ExpenseService: create, approve, post, void, list, categories CRUD +- `src/app/api/expenses/route.ts` - POST/GET expense endpoints +- `src/app/api/expenses/[id]/route.ts` - GET expense detail +- `src/app/api/expenses/[id]/approve/route.ts` - POST approve expense +- `src/app/api/expenses/categories/route.ts` - GET/POST expense categories +- `src/app/api/expenses/categories/[id]/route.ts` - PUT expense category +- `src/app/api/vendors/route.ts` - GET/POST vendor endpoints +- `src/app/api/vendors/[id]/route.ts` - GET/PUT vendor detail +- `src/lib/__tests__/expense-service.test.ts` - 15 integration tests +- `prisma/migrations/20260305_add_expense_vendor_models/migration.sql` - DB migration + +## Decisions Made +- ExpensePaymentMethod determines CR account: CASH -> 1010 Cash on Hand, BANK_TRANSFER/CHECK -> 1020 Cash in Bank +- Default behavior is immediate post (requireApproval=false); when enabled, expense stays DRAFT until approved +- System expense categories protected from deletion; custom categories deletable only if no expenses reference them +- Added Vendor as a new CASL subject (separate from Expense) for granular permissions +- COA expanded to 31 accounts with Fuel/Transportation (5080) and Rent Expense (5085) + +## Deviations from Plan + +### Auto-fixed Issues + +**1. [Rule 2 - Missing Critical] Added Vendor to CASL types and OFFICE_STAFF permissions** +- **Found during:** Task 1 (Schema + permissions) +- **Issue:** Plan specified API routes for vendors with ADMIN/OFFICE_STAFF access, but Vendor was not in AppSubjects and OFFICE_STAFF had no Expense/Vendor permissions +- **Fix:** Added "Vendor" to AppSubjects type, added can("manage", "Expense") and can("manage", "Vendor") for OFFICE_STAFF role +- **Files modified:** src/lib/casl/types.ts, src/lib/casl/permissions.ts +- **Verification:** API routes compile with correct permission checks +- **Committed in:** fe4d22f (Task 1 commit) + +--- + +**Total deviations:** 1 auto-fixed (1 missing critical) +**Impact on plan:** Essential for API route authorization. No scope creep. + +## Issues Encountered +- Docker exec commands were unresponsive; switched to `DATABASE_URL_LOCAL` with `prisma db push` for migration (same result, different approach) + +## User Setup Required +None - no external service configuration required. + +## Next Phase Readiness +- Expense tracking complete, all costs hit the double-entry ledger automatically +- Financial reports in 04-05 can now include expense data alongside revenue +- Ready for 04-04 (if exists) or 04-05 Financial Reports + +--- +*Phase: 04-inventory-expenses-and-financial-reports* +*Completed: 2026-03-05*