docs: create refactoring progress tracker and phase 1 implementation plan

REFACTORING_PROGRESS.md

@@ -0,0 +1,244 @@
+# AI-Friendly Refactoring Progress Tracker
+
+**Branch:** `refactor/ai-friendly`  
+**Started:** 2026-04-18  
+**Status:** IN PROGRESS — Phase 1 Starting
+
+---
+
+## Phase Completion Summary
+
+| Phase | Status | Completion | Last Updated | Commits |
+|-------|--------|------------|--------------|---------|
+| **Phase 1: Backend Tests** | ⏳ STARTING | 0% | 2026-04-18 | 0 |
+| **Phase 2: Frontend Tests** | ⏳ PENDING | 0% | — | — |
+| **Phase 3: E2E Tests** | ⏳ PENDING | 0% | — | — |
+| **Phase 4: Backend Refactor** | ⏳ PENDING | 0% | — | — |
+| **Phase 5: Component Refactor** | ⏳ PENDING | 0% | — | — |
+| **Phase 6: Page Refactor** | ⏳ PENDING | 0% | — | — |
+
+---
+
+## Phase 1: Backend Tests (Pytest)
+
+**Target:** 85%+ coverage for `backend/routers/`, `backend/models.py`, `backend/auth.py`, `backend/ai/`
+
+**Test Files to Create:**
+- [ ] `backend/tests/conftest.py` (shared fixtures)
+- [ ] `backend/tests/test_users.py` (auth, CRUD, LDAP)
+- [ ] `backend/tests/test_items.py` (item ops)
+- [ ] `backend/tests/test_operations.py` (check-in/out)
+- [ ] `backend/tests/test_categories.py` (category mgmt)
+- [ ] `backend/tests/test_ai_extraction.py` (AI pipeline)
+- [ ] `backend/tests/test_offline_sync.py` (UUID idempotency)
+
+**Completion Criteria:**
+- ✅ All 7 test files created
+- ✅ `pytest backend/tests/ --cov=backend` shows **85%+ coverage**
+- ✅ All tests PASS (0 failures, 0 errors)
+- ✅ Coverage report: `pytest backend/tests/ --cov=backend --cov-report=html`
+- ✅ Git tag: `phase-1-complete` created
+- ✅ SESSION_STATE.md updated with Phase 1 status
+
+**Next Steps (If Interrupted):**
+Read REFACTORING_PROGRESS.md and SESSION_STATE.md. Resume from next unchecked task.
+
+---
+
+## Phase 2: Frontend Tests (Vitest)
+
+**Target:** 80%+ coverage for components, hooks, utilities
+
+**Test Files to Create:**
+- [ ] `frontend/tests/components/Scanner.test.tsx`
+- [ ] `frontend/tests/components/AIOnboarding.test.tsx`
+- [ ] `frontend/tests/components/AdminOverlay.test.tsx`
+- [ ] `frontend/tests/components/IdentityCheckOverlay.test.tsx`
+- [ ] `frontend/tests/hooks/useAdmin.test.ts`
+- [ ] `frontend/tests/lib/api.test.ts`
+- [ ] `frontend/tests/lib/labels.test.ts`
+- [ ] `frontend/tests/integration/scanner-workflow.test.tsx`
+- [ ] `frontend/tests/integration/inventory-workflow.test.tsx`
+
+**Completion Criteria:**
+- ✅ All 9 test files created
+- ✅ `npm test -- --coverage` shows **80%+ coverage**
+- ✅ All tests PASS (0 failures, 0 errors)
+- ✅ Git tag: `phase-2-complete` created
+- ✅ SESSION_STATE.md updated with Phase 2 status
+
+---
+
+## Phase 3: E2E Tests (Playwright)
+
+**Target:** 5+ critical workflows automated
+
+**E2E Workflows:**
+- [ ] Login workflow (LDAP + local)
+- [ ] Scan item → match inventory
+- [ ] Create new item (AI extraction)
+- [ ] Admin settings change
+- [ ] Offline sync (simulate network loss)
+
+**Test File:**
+- [ ] `frontend/e2e/critical-workflows.spec.ts`
+
+**Completion Criteria:**
+- ✅ 5+ workflows automated
+- ✅ `npx playwright test` — all passing
+- ✅ Runtime <30 min
+- ✅ Git tag: `phase-3-complete` created
+- ✅ SESSION_STATE.md updated with Phase 3 status
+
+---
+
+## Phase 4: Backend Refactoring
+
+**Target:** Split 3 routers into smaller, focused modules
+
+**Routers to Refactor:**
+1. `backend/routers/users.py` (443 lines) → Split into:
+   - `backend/routers/users.py` (endpoints, <150 lines)
+   - `backend/services/user_service.py` (CRUD logic)
+   - `backend/validators/user_validator.py` (input validation)
+
+2. `backend/routers/operations.py` (298 lines) → Split into:
+   - `backend/routers/operations.py` (endpoints, <150 lines)
+   - `backend/services/operation_service.py` (business logic)
+
+3. `backend/routers/items.py` (240 lines) → Split into:
+   - `backend/routers/items.py` (endpoints, <150 lines)
+   - `backend/services/item_service.py` (business logic)
+
+**Completion Criteria:**
+- ✅ All 3 routers split into service modules
+- ✅ `pytest backend/tests/ --cov=backend` — 85%+ coverage, all tests PASS
+- ✅ Zero files >300 lines
+- ✅ All functions <10 complexity
+- ✅ Git tag: `phase-4-complete` created
+- ✅ SESSION_STATE.md updated with Phase 4 status
+
+**Note:** No behavior changes. Tests validate before/after refactor.
+
+---
+
+## Phase 5: Component Refactoring
+
+**Target:** Split 3 large components into sub-components + hooks
+
+**Components to Refactor:**
+1. `frontend/components/AIOnboarding.tsx` (641 lines) → Split into:
+   - `frontend/components/AIOnboarding.tsx` (orchestrator, <150 lines)
+   - `frontend/components/AIOnboarding/StepValidator.tsx`
+   - `frontend/components/AIOnboarding/ImageCapture.tsx`
+   - `frontend/hooks/useAIExtraction.ts` (AI logic)
+
+2. `frontend/components/Scanner.tsx` (367 lines) → Split into:
+   - `frontend/components/Scanner.tsx` (container, <200 lines)
+   - `frontend/components/Scanner/Viewport.tsx`
+   - `frontend/components/Scanner/Controls.tsx`
+   - `frontend/hooks/useScannerZoom.ts`
+
+3. `frontend/components/AdminOverlay.tsx` (253 lines) → Split into:
+   - `frontend/components/AdminOverlay.tsx` (orchestrator, <180 lines)
+   - `frontend/components/AdminOverlay/FormFields.tsx`
+   - `frontend/components/AdminOverlay/SubmitButton.tsx`
+
+**Completion Criteria:**
+- ✅ All 3 components decomposed into sub-components + hooks
+- ✅ `npm test -- --coverage` — 80%+ coverage, all tests PASS
+- ✅ Manual browser test: All components render, buttons clickable
+- ✅ Git tag: `phase-5-complete` created
+- ✅ SESSION_STATE.md updated with Phase 5 status
+
+---
+
+## Phase 6: Page Refactoring
+
+**Target:** Extract page logic into hooks, reduce file sizes
+
+**Pages to Refactor:**
+1. `frontend/app/page.tsx` (979 lines) → Split into:
+   - `frontend/app/page.tsx` (layout only, <100 lines)
+   - `frontend/components/InventoryDashboard.tsx` (dashboard logic)
+   - `frontend/hooks/useDashboardData.ts` (data fetching + state)
+
+2. `frontend/app/inventory/page.tsx` (857 lines) → Split into:
+   - `frontend/app/inventory/page.tsx` (layout only, <100 lines)
+   - `frontend/components/InventoryManager.tsx`
+   - `frontend/hooks/useInventoryManager.ts`
+
+3. `frontend/app/logs/page.tsx` (341 lines) → Split into:
+   - `frontend/app/logs/page.tsx` (layout, <150 lines)
+   - `frontend/components/LogsView.tsx`
+   - `frontend/hooks/useLogsData.ts`
+
+**Completion Criteria:**
+- ✅ All 3 pages refactored into smaller modules
+- ✅ `npm test -- --coverage` — 80%+ coverage, all tests PASS
+- ✅ `npx playwright test` — all e2e tests still PASS
+- ✅ Manual browser test: All pages load, all features work
+- ✅ Git tag: `phase-6-complete` created
+- ✅ SESSION_STATE.md updated with Phase 6 status (REFACTORING COMPLETE)
+
+---
+
+## Multi-Session Continuity
+
+**To Resume Work:**
+1. Read `REFACTORING_PROGRESS.md` (this file) — see which phase is current
+2. Read `docs/superpowers/plans/YYYY-MM-DD-phase-N.md` — see which tasks remain
+3. Read `SESSION_STATE.md` — see AI context from last session
+4. Start from next unchecked task in the plan
+5. After each task, update this file and SESSION_STATE.md
+
+**Git Markers for Phase Completion:**
+```bash
+# After Phase 1 complete:
+git tag phase-1-complete
+
+# After Phase 2 complete:
+git tag phase-2-complete
+
+# etc.
+
+# View all tags:
+git tag -l
+```
+
+**Rollback Capability:**
+If a phase breaks the codebase, roll back:
+```bash
+git reset --hard phase-N-1-complete
+```
+
+---
+
+## Session Handover Template
+
+**To be updated after each session:**
+
+```
+**Session End: [DATE]**
+- Phase: N
+- Completed: [Task list]
+- In Progress: [Current task]
+- Blocked: [Any blockers]
+- Next Steps: [Resume from task X in Phase N plan]
+- Git Status: [Latest commit hash, tags]
+```
+
+---
+
+## Validation Checklist (All Phases Complete)
+
+After Phase 6 is done:
+- [ ] All 6 test suites passing (85%+ backend, 80%+ frontend, e2e all green)
+- [ ] All 8 large files refactored (<300 lines each)
+- [ ] All functions <10 complexity
+- [ ] Manual validation: Login, Scan, AI extraction, Admin, Offline sync — ALL WORK
+- [ ] No console errors in browser
+- [ ] Mobile responsive (320px, 768px, 1024px+ viewports)
+- [ ] Keyboard navigation works
+- [ ] Merge `refactor/ai-friendly` → `dev`
+- [ ] Create version v1.10.17 with refactoring changes