AgentSkillsCN

checkpoint-from-receipt

使用QR扫描、e-Kasa API和GPS提取创建检查点照片的检查点（10-40秒）

SKILL.md
--- frontmatter
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

code
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