tfm_ainventory/.planning/phases/5-core-v2-features/5-PLAN-01.md

plan, feature, status, estimated_tasks, total_lines

plan	feature	status	estimated_tasks	total_lines
5-PLAN-01	Quick Quantity Adjustment	ready	5	~450

Phase 5 Plan 01: Quick Quantity Adjustment

Overview

Implement hybrid quantity adjustment UI combining persistent +/- buttons with tap-to-edit on number display. Eliminates modal friction for check-in/check-out workflows by allowing both button-based increment/decrement AND direct number input via tap-to-edit inline.

Tasks

Task 1: Refactor QuantityDisplay Component (UI Layer)

• File: frontend/components/inventory/QuantityDisplay.tsx
• Component: QuantityDisplay(itemId: string, currentQuantity: number, onQuantityChange: (newQty: number) => Promise<void>) → JSX.Element
• Lines: ~120
• Description: Create editable quantity display with tap-to-edit mode. Render number as pressable text that toggles edit mode; show inline input field with +/- buttons flanking the number.
• Acceptance Criteria:
  • Normal state: displays quantity as tappable text
  • Tap triggers edit mode: input field + +/- buttons visible
  • +/- buttons increment/decrement in-field value without API call (optimistic UI)
  • Blur or Enter key commits change to backend via onQuantityChange
  • Escape key cancels edit without changes
  • Input only accepts positive integers
  • Accessibility: proper ARIA labels on buttons, input has focus indicators
  • Unit tests pass (Vitest)

Task 2: Create useQuantityAdjustment Hook

• File: frontend/hooks/useQuantityAdjustment.ts
• Hook: useQuantityAdjustment(itemId: string, initialQuantity: number) → { quantity: number; isLoading: boolean; error: string | null; adjustQuantity: (delta: number | absolute: number) => Promise<void>; resetError: () => void }
• Lines: ~80
• Description: Custom hook managing quantity state, API calls, optimistic updates, and error handling. Supports both delta (increment/decrement) and absolute (direct input) adjustments.
• Acceptance Criteria:
  • Optimistic UI: state updates immediately; reverts on API failure
  • API call to PATCH /items/{itemId} with new quantity
  • Handles network errors gracefully with user-facing message
  • Validates quantity >= 0
  • Debounces rapid successive calls (100ms)
  • Unit tests cover success, failure, validation scenarios

Task 3: Update Inventory Page Main UI (Integration)

• File: frontend/app/inventory/page.tsx
• Component: Update inventory item list rendering section
• Lines: ~60
• Description: Integrate new QuantityDisplay component into main inventory grid/list. Replace or augment existing quantity display with hybrid tap-to-edit UI.
• Acceptance Criteria:
  • Each item row displays new QuantityDisplay component
  • Quantity changes persist immediately (no modal needed)
  • Layout remains responsive on mobile/desktop
  • Spinner shows during API call
  • Error toast appears on failure
  • No modal opens for quantity adjustment
  • Integration tests confirm full workflow

Task 4: Backend Endpoint Enhancement (PATCH /items/{itemId})

• File: backend/routers/items.py
• Endpoint: PATCH /items/{itemId} with body { quantity: int }
• Function: update_item_quantity(itemId: str, body: UpdateQuantityRequest, auth: User) → ItemResponse
• Lines: ~40
• Description: Ensure endpoint handles direct quantity updates (no modal validation needed). Create audit log entry for quantity change.
• Acceptance Criteria:
  • Accepts POST/PATCH with { quantity: int }
  • Validates quantity >= 0
  • Creates AuditLog entry with old_qty → new_qty delta
  • Returns updated Item with new quantity
  • Authorization: users can adjust inventory they have access to
  • Unit tests confirm audit logging

Task 5: Integration & E2E Tests

• File: frontend/tests/inventory/quick-adjust.test.ts
• Test: Full workflow: tap number → edit → +/- button → commit
• Lines: ~150
• Description: End-to-end test of quantity adjustment workflow without modal. Verify UI state transitions, API calls, error handling.
• Acceptance Criteria:
  • Test case: tap number displays edit mode UI
  • Test case: +/- buttons change input value (no API yet)
  • Test case: Enter key commits, calls API, updates UI
  • Test case: Error from API shows toast, reverts quantity
  • Test case: Escape cancels without API call
  • All assertions pass (Vitest)
  • Backend integration test: PATCH /items/{itemId} creates audit log

Dependencies

• Task 1 (UI) must complete before Task 3 (integration)
• Task 2 (hook) must complete before Task 1 (UI needs the hook)
• Task 4 (backend endpoint) can run in parallel with Tasks 1-2
• Task 5 (tests) depends on Tasks 1-4

Testing Strategy

• Unit tests: QuantityDisplay component (Vitest), useQuantityAdjustment hook (Vitest)
• Integration tests: Inventory page with QuantityDisplay (Vitest)
• Backend tests: PATCH endpoint audit logging (Pytest)
• E2E: Manual verification on mobile device (tap number, edit, +/-, commit)

Blockers & Workarounds

• Mobile tap detection: Ensure click/tap handlers work consistently on iOS/Android. Use onClick + onTouchEnd for maximum compatibility.
• Input validation: Client-side validation prevents invalid input; backend validation is final authority.
• Concurrent edits: If user edits quantity twice rapidly, second edit overwrites first. Acceptable per Phase 5 scope (single-user offline scenario).