From dcc167d00b5cd0a529821c753a2197187c08a834 Mon Sep 17 00:00:00 2001 From: Daniel Bedeleanu Date: Sat, 18 Apr 2026 17:14:51 +0000 Subject: [PATCH] docs: save AI-friendly refactoring design specification --- .claude/settings.local.json | 12 +- .../2026-04-18-ai-friendly-refactor-design.md | 386 ++++++++++++++++++ 2 files changed, 397 insertions(+), 1 deletion(-) create mode 100644 docs/superpowers/specs/2026-04-18-ai-friendly-refactor-design.md diff --git a/.claude/settings.local.json b/.claude/settings.local.json index 62b0584b..f1099f56 100644 --- a/.claude/settings.local.json +++ b/.claude/settings.local.json @@ -44,7 +44,17 @@ "Bash(save-version --help)", "Bash(git --version)", "mcp__plugin_context-mode_context-mode__ctx_stats", - "mcp__plugin_context-mode_context-mode__ctx_execute_file" + "mcp__plugin_context-mode_context-mode__ctx_execute_file", + "Bash(git checkout *)", + "Bash(python -m py_compile backend/tests/conftest.py)", + "Bash(python -m py_compile backend/tests/test_users.py)", + "Bash(python *)", + "Bash(python3.12 -m venv backend/venv)", + "Bash(backend/venv/bin/pip install *)", + "Bash(sudo apt-get *)", + "Bash(PYTHONPATH=/data/programare_AI/tfm_ainventory:/data/programare_AI/tfm_ainventory/backend backend/venv/bin/pytest backend/tests/test_items.py::TestItemCRUD::test_create_item -v)", + "Bash(PYTHONPATH=/data/programare_AI/tfm_ainventory:/data/programare_AI/tfm_ainventory/backend backend/venv/bin/pytest backend/tests/test_items.py::TestItemCRUD::test_create_item -vv)", + "Bash(git tag *)" ] } } diff --git a/docs/superpowers/specs/2026-04-18-ai-friendly-refactor-design.md b/docs/superpowers/specs/2026-04-18-ai-friendly-refactor-design.md new file mode 100644 index 00000000..134e6e83 --- /dev/null +++ b/docs/superpowers/specs/2026-04-18-ai-friendly-refactor-design.md @@ -0,0 +1,386 @@ +# AI-Friendly Code Refactoring Design +**Date:** 2026-04-18 +**Status:** Design Review +**Approach:** Test-First, Full Coverage, Functional Preservation + +--- + +## 1. Executive Summary + +Refactor the codebase to be "AI-friendly" by breaking monolithic files into smaller, focused modules (<300 lines) while maintaining 100% functional parity. Strategy: **Test Everything First → Refactor by Priority → Validate Continuously**. + +**Risk Mitigation:** Previous session left GUI broken (50% functional). This design ensures zero regression through comprehensive test coverage before any code changes. + +--- + +## 2. Current State & Problem + +| Metric | Current | Target | +|--------|---------|--------| +| Test Files | 1 (backend only) | 30+ (backend + frontend) | +| Frontend Test Coverage | 0% | 80%+ | +| Largest File | 979 lines (page.tsx) | <300 lines | +| Cyclomatic Complexity | Unknown (likely >10) | <10 per function | +| Files >300 lines | 8 critical | 0 | + +**Critical Files to Refactor (Priority Order):** +1. **Backend** (Phase 1): + - `backend/routers/users.py` (443 lines) + - `backend/routers/operations.py` (298 lines) + - `backend/routers/items.py` (240 lines) + +2. **Components** (Phase 2): + - `frontend/components/AIOnboarding.tsx` (641 lines) + - `frontend/components/Scanner.tsx` (367 lines) + - `frontend/components/AdminOverlay.tsx` (253 lines) + +3. **Pages** (Phase 3): + - `frontend/app/page.tsx` (979 lines) + - `frontend/app/inventory/page.tsx` (857 lines) + - `frontend/app/logs/page.tsx` (341 lines) + +--- + +## 3. Testing Strategy: Comprehensive Coverage + +### 3.1 Backend Testing (Pytest) + +**Target:** 85%+ coverage of all routers, models, auth, business logic. + +**Structure:** +``` +backend/tests/ +├── test_admin.py (existing - expand) +├── test_users.py (new - auth, CRUD) +├── test_items.py (new - inventory ops) +├── test_operations.py (new - check-in/out) +├── test_categories.py (new - category mgmt) +├── test_ai_extraction.py (new - AI pipeline) +├── test_offline_sync.py (new - UUID idempotency) +└── conftest.py (shared fixtures) +``` + +**Test Types:** +- Unit tests: Individual functions (validators, formatters) +- Integration tests: Full API workflows (auth → CRUD → audit log) +- Fixtures: Mocked auth, test DB (in-memory SQLite), AI responses + +**Coverage Targets:** +- `routers/`: 85% +- `models.py`: 90% (data integrity critical) +- `auth.py`: 90% (security critical) +- `ai/`: 80% (extraction pipeline) + +### 3.2 Frontend Testing (Vitest) + +**Target:** 80%+ coverage of components, hooks, utilities. + +**Structure:** +``` +frontend/tests/ +├── components/ +│ ├── Scanner.test.tsx +│ ├── AIOnboarding.test.tsx +│ ├── AdminOverlay.test.tsx +│ ├── IdentityCheckOverlay.test.tsx +│ └── ... +├── hooks/ +│ ├── useAdmin.test.ts +│ └── useSync.test.ts (if exists) +├── lib/ +│ ├── api.test.ts +│ └── labels.test.ts +└── integration/ + ├── scanner-workflow.test.tsx + └── inventory-workflow.test.tsx +``` + +**Test Types:** +- Unit: Component rendering, prop validation, event handlers +- Hook tests: State updates, side effects, async operations +- Integration: Multi-component workflows (scanner → validation → sync) +- Snapshot tests: Critical UI layouts (StatCard, BottomNav) + +**Coverage Targets:** +- Components: 80% +- Hooks: 85% +- Utils/lib: 90% +- Pages: Covered by integration tests (lower % due to complexity) + +### 3.3 E2E Testing (Playwright) + +**Target:** Critical user paths only (avoid bloat). + +**Workflows to Automate:** +1. Login flow +2. Scan item → Match → Stock adjustment +3. Create new item (AI extraction) +4. Admin settings change +5. Offline sync (simulate network loss) + +**Coverage:** 5-8 test suites, ~30 min total runtime. + +--- + +## 4. Refactoring Approach: Functional Preservation + +### 4.1 Refactoring Rules + +**All refactors must satisfy:** + +1. **File Size Limit:** Files ≤300 lines (AGENTS.md standard) +2. **Complexity Limit:** Cyclomatic complexity <10 per function (AGENTS.md) +3. **Export Clarity:** Each module has ONE clear purpose +4. **No Behavior Change:** Tests pass 100% before and after +5. **Internal-only refactors:** No public API changes unless documented + +### 4.2 Refactoring Strategy by Phase + +**Phase 1: Backend Routers** +- Extract route handlers into smaller service modules +- Split `users.py` (443 lines) into: + - `services/user_service.py` (CRUD logic) + - `validators/user_validator.py` (input validation) + - `routers/users.py` (endpoints only, <150 lines) +- Repeat for `operations.py`, `items.py` + +**Phase 2: Components** +- Split large components into smaller sub-components +- Extract state management logic into custom hooks +- Example: `AIOnboarding.tsx` (641 lines) → + - `components/AIOnboarding.tsx` (orchestrator, <150 lines) + - `components/AIOnboarding/StepValidator.tsx` + - `components/AIOnboarding/ImageCapture.tsx` + - `hooks/useAIExtraction.ts` (AI logic) + +**Phase 3: Pages** +- Extract page logic into custom hooks +- Move form components into separate files +- Example: `app/page.tsx` (979 lines) → + - `app/page.tsx` (layout only, <100 lines) + - `components/InventoryDashboard.tsx` (dashboard logic) + - `hooks/useDashboardData.ts` + +--- + +## 5. Testing & Refactoring Workflow + +### 5.1 Phase 1: Backend Tests (Week 1) + +**Steps:** +1. Create `backend/tests/` suite with 7 test files +2. Write integration tests for all routers (baseline) +3. Add unit tests for critical functions +4. Achieve 85%+ coverage +5. **All tests PASS** before any code changes + +**Validation:** +```bash +pytest backend/tests/ --cov=backend --cov-report=html +# Expected: 85%+ coverage, all tests passing +``` + +### 5.2 Phase 2: Frontend Tests (Week 2) + +**Steps:** +1. Create `frontend/tests/` suite with component + hook tests +2. Test all components (Scanner, AIOnboarding, AdminOverlay, etc.) +3. Test all custom hooks (useAdmin, etc.) +4. Add snapshot tests for UI layouts +5. Achieve 80%+ coverage + +**Validation:** +```bash +npm test -- --coverage +# Expected: 80%+ coverage, all tests passing +``` + +### 5.3 Phase 3: E2E Tests (Week 2) + +**Steps:** +1. Create 5-8 Playwright test suites for critical workflows +2. Login → Scan → Stock adjustment +3. Create new item with AI +4. Admin config changes +5. Offline sync + +**Validation:** +```bash +npx playwright test +# Expected: All workflows automated, <30min runtime +``` + +### 5.4 Phase 4: Backend Refactoring + Testing + +**For each module (users.py, operations.py, items.py):** +1. Run full backend test suite (PASS) +2. Refactor: Split into smaller modules +3. Run full backend test suite again (PASS) +4. Verify no behavior changes +5. Commit with message: `refactor: split {module} into smaller modules` + +**Gating:** No refactor commit until all tests pass. + +### 5.5 Phase 5: Component Refactoring + Testing + +**For each component (AIOnboarding, Scanner, etc.):** +1. Run Vitest suite for component (PASS) +2. Refactor: Split into sub-components + hooks +3. Run Vitest suite again (PASS) +4. Manual browser test: Verify UI unchanged +5. Commit: `refactor: decompose {component} into smaller modules` + +### 5.6 Phase 6: Page Refactoring + Testing + +**For each page (page.tsx, inventory/page.tsx, etc.):** +1. Run Vitest + e2e tests for page (PASS) +2. Refactor: Extract logic into hooks + components +3. Run tests again (PASS) +4. Manual browser test: All buttons/features work +5. Commit: `refactor: extract {page} logic into hooks` + +--- + +## 6. Functional Preservation: Validation Checkpoints + +### Pre-Refactoring Baseline (Week 1-2) + +**Test Suite Created & Passing:** +- ✅ 85%+ backend coverage (pytest) +- ✅ 80%+ frontend coverage (vitest) +- ✅ 5+ e2e workflows automated (playwright) +- ✅ Manual checklist signed off (UI inspection) + +**Manual Validation Checklist (Browser):** +``` +[ ] Login works (LDAP + local) +[ ] Scan item → matches inventory +[ ] Scan new item → AI extraction popup +[ ] Create category → appears in dropdown +[ ] Admin page loads → all sections visible +[ ] Scanner viewport responsive (mobile + desktop) +[ ] Offline mode: scan offline → sync on reconnect +[ ] Buttons/icons visible + clickable +[ ] No console errors +``` + +### Post-Refactoring Validation (After each phase) + +**Automated Tests Must Pass:** +```bash +pytest backend/tests/ --cov=backend +npm test -- --coverage +npx playwright test +``` + +**Manual Tests (Regression Checklist):** +- Same checklist as above +- Focus on the refactored module +- Test mobile (320px, 768px viewports) +- Test accessibility (keyboard nav, focus indicators) + +**Diff Inspection:** +- Code review each commit +- Verify no logic changes (only structure) +- Ensure no hidden side effects + +--- + +## 7. AGENTS.md Updates + +**New sections to add:** + +### Testing Standards +```markdown +## Testing Strategy (AI-Friendly Refactoring) +- **Backend:** Pytest with 85%+ coverage (unit + integration tests) +- **Frontend:** Vitest with 80%+ coverage (components, hooks, snapshots) +- **E2E:** Playwright for critical workflows (login, scan, sync) +- **Coverage Tools:** --cov=backend for pytest, --coverage for vitest +- **Test-First Approach:** All tests written and passing BEFORE refactoring +- **Functional Preservation:** Zero behavior changes; all tests must pass pre/post refactor +``` + +### Refactoring Guidelines +```markdown +## Code Refactoring (AI-Friendly Modularity) +- **Target:** Break monolithic files into focused modules (<300 lines) +- **Phases:** Backend → Components → Pages +- **Validation:** Tests PASS before and after each refactor +- **Gating:** No refactor commit without passing test suite +- **Regression:** Manual checklist + automated tests catch UI breakage +``` + +### Git Conventions (Add to existing) +```markdown +- Refactoring commits: `refactor: split {module} into smaller modules` +- Testing commits: `test: add {suite} coverage for {module}` +- All commits must include test results in message body +``` + +--- + +## 8. Risk Mitigation + +**Problem:** Previous session = GUI broken 50% post-refactor. + +**Solution in this Design:** +- ✅ Comprehensive test coverage BEFORE refactoring (prevents breakage) +- ✅ Tests as gating condition (no code changes if tests fail) +- ✅ Manual checklist for UI regression (buttons, cards, functions) +- ✅ E2E workflows for critical paths (scan, sync, admin) +- ✅ Phased approach (validate each phase before moving to next) +- ✅ Rollback capability (git history preserved; revert if needed) + +--- + +## 9. Timeline & Effort + +| Phase | Duration | Deliverable | +|-------|----------|-------------| +| Phase 1: Backend Tests | 3 days | 7 test files, 85%+ coverage | +| Phase 2: Frontend Tests | 3 days | Component + hook tests, 80%+ coverage | +| Phase 3: E2E Tests | 2 days | 5+ Playwright workflows | +| Phase 4: Backend Refactor | 5 days | 3 routers split, tests passing | +| Phase 5: Component Refactor | 5 days | 3-4 components split, tests passing | +| Phase 6: Page Refactor | 4 days | 3 pages refactored, tests passing | +| **Total** | **~22 days** | AI-friendly codebase, 100% functional | + +--- + +## 10. Success Criteria + +✅ **All Tests Passing** +- Backend: 85%+ coverage (pytest) +- Frontend: 80%+ coverage (vitest) +- E2E: All 5+ workflows automated + +✅ **Files Refactored** +- Zero files >300 lines (except config/generated files) +- All functions <10 complexity + +✅ **Functional Parity** +- All buttons/cards/functions visible and working +- No UI regression (vs. current v1.10.16) +- Offline sync still works +- AI extraction still works + +✅ **Documentation** +- AGENTS.md updated with testing + refactoring guidelines +- Comments added to extracted modules explaining purpose + +✅ **Git History** +- Clean commit chain: test → refactor (alternating) +- No force pushes; full history preserved + +--- + +## Next Steps (If Approved) + +1. Create new branch `refactor/ai-friendly` from `dev` +2. Begin Phase 1: Backend test suite +3. Validate baseline (all tests passing) +4. Proceed to Phase 2-6 in sequence +5. Update AGENTS.md during Phase 1 +6. Final validation before merging back to `dev` +