feat: Receipt Capture Integration #70

New Issue

egullickson · 2026-02-01T18:47:59Z

egullickson commented

2026-02-01 18:47:59 +00:00

Overview

Integrate camera capture and receipt OCR into the FuelLogForm, including the review/correct UI before saving.

Parent Issue: #12 (OCR-powered smart capture)
Priority: P2 - Fuel Receipt OCR
Dependencies: Camera Capture Component, Receipt OCR Pipeline

Scope

FuelLogForm Enhancement

Add camera button to fuel log create dialog
Opens CameraCapture component with receipt guidance
Captured image → Receipt OCR → form population
Review/correct UI before auto-populating fields

User Flow

1. User opens fuel log create dialog
2. User clicks camera icon (or "Scan Receipt" button)
3. CameraCapture opens with receipt aspect-ratio guide
4. User captures photo, optionally crops
5. Loading state: "Extracting receipt data..."
6. OCR returns extracted fields
7. Review modal shows:
   - Extracted fields with confidence indicators
   - Original receipt image for reference
8. User confirms/corrects → form fields populated
9. User can edit any field before final save

Review/Correct UI

┌─────────────────────────────────────────────┐
│  Receipt Data Extracted                     │
├─────────────────────────────────────────────┤
│  ┌─────────┐  ┌─────────────────────────┐  │
│  │         │  │ Station: Shell          │  │
│  │ Receipt │  │ Date: Jan 15, 2024  ●●●○│  │
│  │ Preview │  │ Total: $45.67       ●●●●│  │
│  │         │  │ Gallons: 12.5       ●●●○│  │
│  │         │  │ $/Gal: $3.65        ●●○○│  │
│  │         │  │ Grade: 87           ●●○○│  │
│  └─────────┘  └─────────────────────────┘  │
│                                             │
│  Tap any field to edit before saving.       │
│                                             │
│  [Retake Photo]  [Edit All]    [Accept]    │
└─────────────────────────────────────────────┘

Field Mapping

OCR Field	FuelLog Field	Notes
transactionDate	dateTime	Parse to ISO format
totalAmount	(calculated)	= fuelUnits × costPerUnit
fuelQuantity	fuelUnits	Gallons or liters
pricePerUnit	costPerUnit	Per gallon/liter
fuelGrade	fuelGrade	Map to valid enum
merchantName	locationData.name	Optional station info

Mobile Design

Full-screen camera capture
Bottom sheet for review modal
Thumbnail of receipt visible during review
Touch to edit individual fields
Swipe gestures for navigation

Component Structure

frontend/src/features/fuel-logs/components/
├── FuelLogForm.tsx              # Add camera button
├── ReceiptCameraButton.tsx      # Camera trigger
├── ReceiptOcrReviewModal.tsx    # Review/correct UI
├── ReceiptPreview.tsx           # Thumbnail with zoom
├── ReceiptFieldEditor.tsx       # Inline field editing
└── hooks/
    └── useReceiptOcr.ts         # OCR orchestration

useReceiptOcr Hook

interface UseReceiptOcrResult {
  captureAndExtract: () => Promise<void>;
  isCapturing: boolean;
  isProcessing: boolean;
  extractedFields: ExtractedReceiptFields | null;
  receiptImage: string | null;  // blob URL for preview
  error: string | null;
  reset: () => void;
}

Acceptance Criteria

Camera button appears in FuelLogForm (mobile + desktop)
CameraCapture opens with receipt guidance overlay
Captured image sent to receipt OCR endpoint
Review modal displays extracted fields
Receipt image thumbnail shown for reference
Confidence indicators for each field
User can edit individual fields before accepting
Accepted values populate form correctly
Form validation works after population
Total auto-calculated from units × price
Mobile-responsive (320px - 768px)
Desktop-responsive (1920px)
Error handling for OCR failures
Low confidence fields highlighted

Technical Notes

Total amount from OCR used for validation, not form input
Auto-calculate: if OCR provides gallons and price, verify total matches
Station info populates locationData if StationPicker not already used
Consider saving receipt image to documents feature (optional)

Out of Scope

OCR service implementation (see #12f)
Camera component implementation (see #12c)
Maintenance receipt extraction (Phase 2)

## Overview Integrate camera capture and receipt OCR into the FuelLogForm, including the review/correct UI before saving. **Parent Issue**: #12 (OCR-powered smart capture) **Priority**: P2 - Fuel Receipt OCR **Dependencies**: Camera Capture Component, Receipt OCR Pipeline ## Scope ### FuelLogForm Enhancement - Add camera button to fuel log create dialog - Opens CameraCapture component with receipt guidance - Captured image → Receipt OCR → form population - Review/correct UI before auto-populating fields ### User Flow ``` 1. User opens fuel log create dialog 2. User clicks camera icon (or "Scan Receipt" button) 3. CameraCapture opens with receipt aspect-ratio guide 4. User captures photo, optionally crops 5. Loading state: "Extracting receipt data..." 6. OCR returns extracted fields 7. Review modal shows: - Extracted fields with confidence indicators - Original receipt image for reference 8. User confirms/corrects → form fields populated 9. User can edit any field before final save ``` ### Review/Correct UI ``` ┌─────────────────────────────────────────────┐ │ Receipt Data Extracted │ ├─────────────────────────────────────────────┤ │ ┌─────────┐ ┌─────────────────────────┐ │ │ │ │ │ Station: Shell │ │ │ │ Receipt │ │ Date: Jan 15, 2024 ●●●○│ │ │ │ Preview │ │ Total: $45.67 ●●●●│ │ │ │ │ │ Gallons: 12.5 ●●●○│ │ │ │ │ │ $/Gal: $3.65 ●●○○│ │ │ │ │ │ Grade: 87 ●●○○│ │ │ └─────────┘ └─────────────────────────┘ │ │ │ │ Tap any field to edit before saving. │ │ │ │ [Retake Photo] [Edit All] [Accept] │ └─────────────────────────────────────────────┘ ``` ### Field Mapping | OCR Field | FuelLog Field | Notes | |-----------|---------------|-------| | transactionDate | dateTime | Parse to ISO format | | totalAmount | (calculated) | = fuelUnits × costPerUnit | | fuelQuantity | fuelUnits | Gallons or liters | | pricePerUnit | costPerUnit | Per gallon/liter | | fuelGrade | fuelGrade | Map to valid enum | | merchantName | locationData.name | Optional station info | ### Mobile Design - Full-screen camera capture - Bottom sheet for review modal - Thumbnail of receipt visible during review - Touch to edit individual fields - Swipe gestures for navigation ## Component Structure ``` frontend/src/features/fuel-logs/components/ ├── FuelLogForm.tsx # Add camera button ├── ReceiptCameraButton.tsx # Camera trigger ├── ReceiptOcrReviewModal.tsx # Review/correct UI ├── ReceiptPreview.tsx # Thumbnail with zoom ├── ReceiptFieldEditor.tsx # Inline field editing └── hooks/ └── useReceiptOcr.ts # OCR orchestration ``` ### useReceiptOcr Hook ```typescript interface UseReceiptOcrResult { captureAndExtract: () => Promise<void>; isCapturing: boolean; isProcessing: boolean; extractedFields: ExtractedReceiptFields | null; receiptImage: string | null; // blob URL for preview error: string | null; reset: () => void; } ``` ## Acceptance Criteria - [ ] Camera button appears in FuelLogForm (mobile + desktop) - [ ] CameraCapture opens with receipt guidance overlay - [ ] Captured image sent to receipt OCR endpoint - [ ] Review modal displays extracted fields - [ ] Receipt image thumbnail shown for reference - [ ] Confidence indicators for each field - [ ] User can edit individual fields before accepting - [ ] Accepted values populate form correctly - [ ] Form validation works after population - [ ] Total auto-calculated from units × price - [ ] Mobile-responsive (320px - 768px) - [ ] Desktop-responsive (1920px) - [ ] Error handling for OCR failures - [ ] Low confidence fields highlighted ## Technical Notes - Total amount from OCR used for validation, not form input - Auto-calculate: if OCR provides gallons and price, verify total matches - Station info populates `locationData` if StationPicker not already used - Consider saving receipt image to documents feature (optional) ## Out of Scope - OCR service implementation (see #12f) - Camera component implementation (see #12c) - Maintenance receipt extraction (Phase 2)

egullickson added the

labels 2026-02-01 18:48:38 +00:00

egullickson referenced this issue

2026-02-01 18:49:00 +00:00

feat: OCR-powered smart capture for VIN, receipts, and owner's manuals #12

egullickson added

status

in-progress