checkpoint-from-receipt

name	checkpoint-from-receipt
description	Create checkpoints from receipt photos using QR scanning, e-Kasa API, and GPS extraction (10-40s)

Checkpoint from Receipt Skill

Purpose

Automatically create checkpoints from receipt photos using QR scanning, e-Kasa API, and GPS extraction.

When to Activate

• User pastes image (auto-detect)
• Keywords: "refuel", "fill up", "got gas", "checkpoint", "receipt"
• File extensions: .jpg, .png, .pdf

Instructions

Workflow: 3-Stage Orchestration

QR scan (2-5s) → e-Kasa API (5-30s) → GPS extraction (2-5s) → Checkpoint creation → Gap detection

Total time: 10-40 seconds typically

---

Stage 1: QR Code Scanning

1. When image pasted: "📷 Receipt detected. Scanning QR code..."
2. Call: ekasa-api.scan_qr_code (multi-scale: 1x, 2x, 3x)
3. Progress:
   • "Trying 1x scale..."
   • "Trying 2x scale... Found!"
4. Extract: receipt_id (e.g., "O-123456789ABC")

If QR not found:

• "QR code not detected. Try better lighting or different angle."
• Fallback: "What's the e-Kasa receipt ID? (starts with O-)"

---

Stage 2: e-Kasa API (SLOW - Show Progress!)

1. Start: "🔄 Fetching from e-Kasa API... (may take up to 60s)"
2. Call: ekasa-api.fetch_receipt_data
3. Progress updates:
   • 15s: "Still fetching... (15s elapsed)"
   • 30s: "Almost there... (30s elapsed)"
   • 45s: "Taking longer than usual... (45s elapsed)"

If timeout (60s):

• "⏱️ e-Kasa timed out. Options:"
• "1) Retry"
• "2) Manual entry (fuel type, liters, price)"

If success:

• Parse fuel items using Slovak patterns:
  • "Diesel", "Nafta", "Motorová nafta"
  • "Natural 95", "BA 95", "Benzín 95"
  • "Natural 98", "BA 98", "Benzín 98"
  • "LPG", "Autoplyn"
• Show: "✅ 52.3L Diesel @ €1.45/L = €75.84"

If multiple fuel items:

• List all items
• Ask: "Which fuel was for your vehicle?"

---

Stage 3: Dashboard Photo GPS

1. Ask: "📸 Now paste dashboard photo for GPS location"
2. Call: dashboard-ocr.extract_metadata
3. Extract:
   • GPS coordinates (latitude, longitude) from EXIF
   • Timestamp from EXIF
   • Odometer reading (OCR with confidence > 80%)

If GPS found:

• "📍 Location: 48.1486, 17.1077 (Bratislava)"
• Optional: Reverse geocode to show address

If no GPS:

• "📍 No GPS data found. Options:"
• "1) Enable location services and retake photo"
• "2) Enter GPS coordinates manually"
• "3) Enter address (I'll geocode it)"

If OCR odometer found:

• "📊 Detected odometer: 125,340 km (confidence: 92%)"
• "Is this correct? (yes/no)"

If OCR fails or low confidence:

• "What's the current odometer reading in kilometers?"

---

Stage 4: Create Checkpoint & Detect Gap

1. Combine data:

   • Receipt: fuel_type, fuel_liters, price, vendor, receipt_id
   • GPS: latitude, longitude, address (optional)
   • Datetime: from receipt or dashboard photo
   • Odometer: from OCR or user input

2. Slovak compliance check:

   • Ask for driver name if missing
   • Separate refuel timing from trip timing
   • Note: Refuel location may differ from trip start/end

3. Call: car-log-core.create_checkpoint

4. Success: "✅ Checkpoint created at 125,340 km!"

5. Auto-detect gap:

   • Call: car-log-core.detect_gap
   • If gap > 100km: "⚠️ Gap detected: 820 km over 7 days. Reconstruct trips?"
   • If gap detected → Auto-trigger trip-reconstruction skill

---

Timing Breakdown

• QR scan: 2-5 seconds
• e-Kasa API: 5-30 seconds (show progress!)
• GPS extraction: 1-2 seconds
• Checkpoint creation: 1 second
• Gap detection: 1 second
• Total: 10-40 seconds typically

Error Handling

QR Scan Failed

• Try multi-scale (1x, 2x, 3x)
• If all fail: Manual receipt ID entry

e-Kasa Timeout

• Show elapsed time
• Offer retry or manual entry
• Cache successful responses

No GPS

• Fallback to address geocoding
• Manual GPS entry
• Continue without location (warn about compliance)

Multiple Fuel Items

• List all items with prices
• Ask user to select correct one

Ambiguous Geocoding

• Show alternatives with confidence
• Ask user to select correct location

Slovak Compliance

Critical Requirements

• Driver name: Mandatory for tax deduction
• Refuel timing: Separate from trip start/end timing
• Location: Refuel station may differ from trip origin/destination
• L/100km format: Always use European standard

Data Storage

• Store refuel_datetime separately from trip timing
• Store refuel_location separately from trip endpoints
• Link checkpoint to trips via gap detection

Related Skills

Auto-triggers

• trip-reconstruction: If gap > 100km detected
• data-validation: Automatic validation after checkpoint creation

Links to

• vehicle-setup: If no vehicle registered
• report-generation: After sufficient checkpoints collected

---

For detailed examples: See GUIDE.md For MCP tools: See REFERENCE.md For timeout troubleshooting: See ../TROUBLESHOOTING.md