docs(03-04): complete intake wizard UI plan summary

2026-04-10 06:22:46 +00:00 · 2026-04-10 06:22:46 +00:00 · 7fc7705c84
commit 7fc7705c84
parent 5909025677
1 changed files with 151 additions and 0 deletions
--- a/.planning/phases/03-dashboard-intake-ui/03-04-SUMMARY.md
+++ b/.planning/phases/03-dashboard-intake-ui/03-04-SUMMARY.md
@ -0,0 +1,151 @@
+---
+phase: 03-dashboard-intake-ui
+plan: "04"
+subsystem: ui
+tags: [react, typescript, intake, zustand, react-dropzone, tanstack-router, clickhouse-design]
+
+# Dependency graph
+requires:
+  - web/src/store/ui.ts (Zustand pattern)
+  - web/src/components/ui/button.tsx (Button variants)
+  - web/src/components/ui/card.tsx (Card/CardContent)
+  - web/src/components/ui/badge.tsx (Badge)
+  - POST /api/intake (02-03)
+provides:
+  - web/src/store/intake.ts (useIntakeStore, IntakeResult)
+  - web/src/lib/api.ts (submitIntake, IntakeResponse)
+  - web/src/components/intake/DropZone.tsx
+  - web/src/components/intake/PhotoPreview.tsx
+  - web/src/components/intake/AIResultReview.tsx
+  - web/src/components/intake/ConfirmForm.tsx
+  - web/src/components/layout/AppShell.tsx
+  - web/src/pages/IntakePage.tsx
+  - /intake route (lazy-loaded)
+affects:
+  - web/src/router.tsx (intakeRoute updated from stub to lazy IntakePage)
+
+# Tech tracking
+tech-stack:
+  added: []
+  patterns:
+    - Zustand store per feature concern (intake.ts separate from ui.ts)
+    - react-dropzone with capture="environment" for mobile camera
+    - Lazy Suspense pattern for route-level code splitting
+    - submitIntake() uses native fetch with FormData — no axios
+    - Backend creates record immediately on POST (INTAKE-04); UI review is display-only
+
+key-files:
+  created:
+    - web/src/store/intake.ts
+    - web/src/lib/api.ts
+    - web/src/components/intake/DropZone.tsx
+    - web/src/components/intake/PhotoPreview.tsx
+    - web/src/components/intake/AIResultReview.tsx
+    - web/src/components/intake/ConfirmForm.tsx
+    - web/src/components/layout/AppShell.tsx
+    - web/src/pages/IntakePage.tsx
+  modified:
+    - web/src/router.tsx (intakeRoute lazy-loads IntakePage)
+
+decisions:
+  - "Backend creates NetBox record immediately on first POST /api/intake — review step is display-only; no second confirmation POST needed (carries INTAKE-04 from Phase 2)"
+  - "AppShell created as layout component (not in plan) — IntakePage requires a page wrapper; auto-added as missing critical layout (Rule 2)"
+  - "ConfirmForm exported but not used in IntakePage final flow — wired for possible future confirm-before-create variant; currently review step goes direct to handleDone()"
+
+# Metrics
+duration: 15min
+completed: 2026-04-10
+---
+
+# Phase 3 Plan 04: Intake Wizard UI Summary
+
+**Three-step photo intake wizard (Upload → Submitting → Review) wired to POST /api/intake, using react-dropzone, Zustand store, and ClickHouse design tokens.**
+
+## Performance
+
+- **Duration:** ~15 min
+- **Completed:** 2026-04-10
+- **Tasks:** 2
+- **Files created:** 8
+- **Files modified:** 1
+
+## Accomplishments
+
+- `useIntakeStore` Zustand store tracks wizard step (`upload | submitting | review | done | error`), up to 3 photos, AI result, and editable name
+- `submitIntake()` in `api.ts` posts multipart FormData to `/api/intake` and returns typed `IntakeResponse`
+- `DropZone` uses react-dropzone with `capture="environment"` for mobile camera, volt border glow on drag-active, slot counter, disabled state at 3 photos
+- `PhotoPreview` shows thumbnails in a flex grid with per-photo X remove button (hover reveal)
+- `AIResultReview` renders confidence meter (green ≥85%, yellow 60-84%, red <60%), manufacturer/model/category/tags, editable name input, and ai_notes card
+- `AppShell` minimal layout wrapper with HWLab top-nav and Inventory/Add Item links
+- `IntakePage` orchestrates the three steps: upload → POST → review → navigate to dashboard
+- Analyze button disabled during `step === 'submitting'` (T-03-13 DoS mitigation)
+- `/intake` route lazy-loaded with Suspense fallback spinner (code-split chunk: ~100 KB gzip 30 KB)
+- `npm run build` exits 0 with no TypeScript errors
+
+## Task Commits
+
+1. **Task 1: Intake store, api.ts, DropZone, PhotoPreview** — `709876d`
+2. **Task 2: AIResultReview, ConfirmForm, AppShell, IntakePage, router wiring** — `5909025`
+
+## Files Created/Modified
+
+- `web/src/store/intake.ts` — Zustand intake wizard state (step, photos, aiResult, editedName, error)
+- `web/src/lib/api.ts` — `submitIntake()` multipart POST + `IntakeResponse` type
+- `web/src/components/intake/DropZone.tsx` — react-dropzone with camera capture, volt hover, slot counter
+- `web/src/components/intake/PhotoPreview.tsx` — thumbnail grid with X remove per photo
+- `web/src/components/intake/AIResultReview.tsx` — confidence meter, classification fields, editable name, ai_notes
+- `web/src/components/intake/ConfirmForm.tsx` — confirm/reset action buttons with loading spinner
+- `web/src/components/layout/AppShell.tsx` — page layout wrapper with top nav
+- `web/src/pages/IntakePage.tsx` — intake wizard orchestrator (upload/submitting/review steps)
+- `web/src/router.tsx` — intakeRoute updated from stub to lazy IntakePage
+
+## Decisions Made
+
+- Backend creates NetBox record immediately on POST (INTAKE-04 from Phase 2) — no separate confirmation POST; UI review is display-only
+- Lazy Suspense code-splitting applied to /intake route (keeps main bundle small)
+- `capture="environment"` on file input for mobile rear-camera capture
+
+## Deviations from Plan
+
+### Auto-fixed Issues
+
+**1. [Rule 2 - Missing critical functionality] Created AppShell layout component**
+- **Found during:** Task 2 (IntakePage implementation)
+- **Issue:** IntakePage imports `@/components/layout/AppShell` but no such component existed. The plan listed IntakePage as the wizard orchestrator without noting the layout dependency.
+- **Fix:** Created `web/src/components/layout/AppShell.tsx` — minimal top-nav wrapper with HWLab logo (volt) and Inventory/Add Item nav links using TanStack Router `<Link>`
+- **Files modified:** `web/src/components/layout/AppShell.tsx` (created)
+- **Commit:** 5909025
+
+## Known Stubs
+
+None — all data paths are wired end-to-end. `submitIntake()` calls real `/api/intake`. AI result flows directly from API response into `AIResultReview`. No hardcoded mock data.
+
+## Threat Surface Coverage
+
+All three threats from the plan's threat register are addressed:
+
+| Threat | Mitigation | Where |
+|--------|-----------|-------|
+| T-03-11: Tampering via FormData | Photos sent as bytes; hw_id assigned server-side; no client-controlled ID | api.ts:submitIntake |
+| T-03-12: AI notes XSS | JSX text rendering only; no dangerouslySetInnerHTML | AIResultReview.tsx |
+| T-03-13: Duplicate concurrent POSTs | Analyze button disabled during `step === 'submitting'` | IntakePage.tsx |
+
+## Self-Check
+
+Files created:
+- web/src/store/intake.ts: FOUND
+- web/src/lib/api.ts: FOUND
+- web/src/components/intake/DropZone.tsx: FOUND
+- web/src/components/intake/PhotoPreview.tsx: FOUND
+- web/src/components/intake/AIResultReview.tsx: FOUND
+- web/src/components/intake/ConfirmForm.tsx: FOUND
+- web/src/components/layout/AppShell.tsx: FOUND
+- web/src/pages/IntakePage.tsx: FOUND
+
+Commits:
+- 709876d: feat(03-04): add intake Zustand store, api.ts submitIntake, DropZone, PhotoPreview
+- 5909025: feat(03-04): intake wizard UI — AIResultReview, ConfirmForm, IntakePage, router wiring
+
+`npm run build`: PASSED (tsc -b + vite build, 0 errors, IntakePage code-split chunk ~100 KB)
+
+## Self-Check: PASSED