phase 5: fixed expense logic simplified and compacted

docs/api-refactor-lightweight-plan.md

@@ -3,9 +3,14 @@
 ## Goal
 Reduce `api/src/server.ts` size and duplication with low-risk, incremental moves.
 
-Current state (2026-03-15):
-- `server.ts` has ~4.8k lines and 50 endpoint registrations.
-- Duplicate endpoint signatures also exist in `api/src/routes/*` but are not currently registered.
+Current state (2026-03-17):
+- `server.ts` still holds most business routes, but Phases 1-5 are complete.
+- Completed move logs:
+  - `docs/api-phase1-move-log.md`
+  - `docs/api-phase2-move-log.md`
+  - `docs/api-phase3-move-log.md`
+  - `docs/api-phase4-move-log.md`
+  - `docs/api-phase5-move-log.md`
 
 ## Refactor Guardrails
 1. Keep route behavior identical while moving code.
@@ -26,7 +31,7 @@ When moving a domain:
 4. Confirm no duplicate route registrations remain.
 
 ## Shared Helpers (Phase 0)
-Create these helpers first to keep endpoint moves lightweight:
+Create and/or finish these helpers to keep endpoint moves lightweight:
 
 1. `api/src/services/user-context.ts`
 - `getUserTimezone(...)`
@@ -49,15 +54,108 @@ Create these helpers first to keep endpoint moves lightweight:
 - Standard typed error object and response body builder.
 - Keeps endpoint error handling consistent.
 
-## Move Order (Incremental)
-1. Low-risk endpoints: `health`, `session`, `me`, `user/config`.
-2. `auth` + `account` endpoints.
-3. `variable-categories` endpoints.
-4. `transactions` endpoints.
-5. `fixed-plans` endpoints.
-6. `income`, `budget`, `payday` endpoints.
-7. `dashboard` + `crisis-status`.
-8. `admin` endpoints.
+## Progress Snapshot
+Completed:
+1. Phase 1: low-risk endpoints (`health`, `session`, `me`, `user/config`).
+2. Phase 2: `auth` + `account` endpoints.
+3. Phase 3: `variable-categories` endpoints.
+4. Phase 4: `transactions` endpoints.
+5. Phase 5: `fixed-plans` endpoints.
+
+Remaining:
+1. Phase 6: `income`, `budget`, `payday` endpoints.
+2. Phase 7: `dashboard` + `crisis-status`.
+3. Phase 8: `admin` + site access endpoints.
+4. Phase 9: final cleanup and helper consolidation.
+
+## Remaining Plan (Detailed)
+
+### Phase 5: Fixed Plans Domain
+Move these routes out of `server.ts` into `api/src/routes/fixed-plans.ts` (or split module if needed):
+1. `PATCH /fixed-plans/:id/early-funding`
+2. `POST /fixed-plans/:id/attempt-final-funding`
+3. `PATCH /fixed-plans/:id/mark-unpaid`
+4. `POST /fixed-plans/:id/fund-from-available`
+5. `POST /fixed-plans/:id/catch-up-funding`
+6. `POST /fixed-plans`
+7. `PATCH /fixed-plans/:id`
+8. `DELETE /fixed-plans/:id`
+9. `POST /fixed-plans/:id/true-up-actual`
+10. `GET /fixed-plans/due`
+11. `POST /fixed-plans/:id/pay-now`
+
+Primary risk:
+- Payment/funding workflows are tightly coupled with available budget math and rollover rules.
+
+Test focus:
+- `api/tests/fixed-plans*.test.ts`
+- `api/tests/payment-rollover.test.ts`
+
+### Phase 6: Income, Budget, Payday Domain
+Move these routes into a dedicated module (e.g., `api/src/routes/budget-income.ts`):
+1. `POST /income`
+2. `GET /income/history`
+3. `POST /income/preview`
+4. `POST /budget/allocate`
+5. `POST /budget/fund`
+6. `POST /budget/reconcile`
+7. `GET /payday/status`
+8. `POST /payday/dismiss`
+
+Primary risk:
+- Budget-session synchronization and allocator side effects.
+
+Test focus:
+- Income/budget allocation tests
+- Any tests asserting payday status/dismiss behavior
+
+### Phase 7: Dashboard Read Domain
+Move read endpoints into `api/src/routes/dashboard.ts`:
+1. `GET /dashboard`
+2. `GET /crisis-status`
+
+Primary risk:
+- Derived numbers diverging between dashboard and rebalance/session APIs.
+
+Test focus:
+- Dashboard API contract checks and UI smoke verification.
+
+### Phase 8: Admin and Site Access Domain
+Move operational endpoints into `api/src/routes/admin.ts` and/or `api/src/routes/site-access.ts`:
+1. `POST /admin/rollover`
+2. `GET /site-access/status`
+3. `POST /site-access/unlock`
+4. `POST /site-access/lock`
+
+Primary risk:
+- Lockout/maintenance flow regressions and accidental open access.
+
+Test focus:
+- Site access flow tests
+- Admin rollover auth/permission checks
+
+### Phase 9: Final Cleanup
+1. Remove dead helper duplicates from `server.ts` and route modules.
+2. Consolidate common helpers into `api/src/services/*`.
+3. Normalize error envelopes where safe (no contract change unless explicitly planned).
+4. Re-run full API/security suites and perform deployment smoke checks.
+
+## Reference Audit Requirement (Per Move)
+For every endpoint moved:
+1. Record original location in `server.ts`.
+2. Record new route module location.
+3. Record frontend references (`web/src/api/*`, hooks, pages).
+4. Record test references.
+5. Add a phase move log under `docs/api-phaseX-move-log.md`.
+
+## Verification Steps (Per Phase)
+1. Build:
+- `cd api && npm run build`
+2. Run focused tests for moved domain.
+3. Run security suites relevant to moved endpoints.
+4. Deploy.
+5. Run production endpoint smoke checks for the moved routes.
+6. Confirm logs show expected status codes (no unexplained 401/403/500 shifts).
 
 ## Definition of Done per Phase
 1. Endpoints compile and register once.