docs: save AI-friendly refactoring design specification
This commit is contained in:
386
docs/superpowers/specs/2026-04-18-ai-friendly-refactor-design.md
Normal file
386
docs/superpowers/specs/2026-04-18-ai-friendly-refactor-design.md
Normal file
@@ -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`
|
||||
|
||||
Reference in New Issue
Block a user