boc/vims-backend/docs/UPLOAD_GUIDE.md

VIMS - Fotoguide & API-uppladdning

Steg 1: Förberedelser

Starta servern

cd vims-backend

# Starta databas och redis
docker-compose up -d postgres redis minio

# Starta API-servern
npm run dev

Servern startar på http://localhost:3450

---

Steg 2: Skapa ett objekt (bankomat)

Via curl

curl -X POST http://localhost:3450/api/v1/objects \
  -H "Content-Type: application/json" \
  -d '{
    "objectTypeId": "atm-type-uuid",
    "customerId": "demo-customer",
    "name": "ATM Stureplan 4",
    "externalId": "ATM-001",
    "location": {
      "latitude": 59.3368,
      "longitude": 18.0555
    },
    "address": "Stureplan 4, Stockholm",
    "manufacturer": "NCR",
    "model": "SelfServ 22"
  }'

Svar

{
  "id": "uuid-här",
  "name": "ATM Stureplan 4",
  "currentStatus": "unknown"
}

Spara id - du behöver det för uppladdning!

---

Steg 3: Sätt baseline-bilder

Via curl

curl -X POST http://localhost:3450/api/v1/objects/DITT-OBJEKT-ID/baseline \
  -H "Content-Type: application/json" \
  -d '{
    "images": [
      {
        "angle": "front",
        "imageUrl": "https://ditt-lager.com/atm-001-front.jpg"
      },
      {
        "angle": "left",
        "imageUrl": "https://ditt-lager.com/atm-001-left.jpg"
      },
      {
        "angle": "right",
        "imageUrl": "https://ditt-lager.com/atm-001-right.jpg"
      }
    ]
  }'

---

Steg 4: Ladda upp observation (foto)

Via curl (multipart/form-data)

curl -X POST http://localhost:3450/api/v1/observations \
  -F "images=@/sökväg/till/ditt-foto.jpg" \
  -F "objectId=DITT-OBJEKT-ID" \
  -F "angle=front" \
  -F "zoomerId=demo-zoomer"

Med flera bilder

curl -X POST http://localhost:3450/api/v1/observations \
  -F "images=@front.jpg" \
  -F "images=@left.jpg" \
  -F "images=@right.jpg" \
  -F "objectId=DITT-OBJEKT-ID" \
  -F "angle=front"

Svar

{
  "observations": [
    {
      "id": "obs-uuid",
      "status": "pending",
      "imageUrl": "/uploads/..."
    }
  ],
  "objectId": "DITT-OBJEKT-ID",
  "processed": 1
}

---

Steg 5: Kontrollera resultat

Hämta observation

curl http://localhost:3450/api/v1/observations/OBSERVATION-ID

Hämta detektioner

curl "http://localhost:3450/api/v1/detections?observationId=OBSERVATION-ID"

Hämta larm

curl "http://localhost:3450/api/v1/alerts?objectId=DITT-OBJEKT-ID"

---

Komplett exempel (bash-script)

#!/bin/bash

API_URL="http://localhost:3450"

# 1. Skapa objekt
echo "Skapar objekt..."
OBJECT=$(curl -s -X POST "$API_URL/api/v1/objects" \
  -H "Content-Type: application/json" \
  -d '{
    "objectTypeId": "atm-type-uuid",
    "customerId": "demo-customer",
    "name": "ATM Test",
    "location": {"latitude": 59.3368, "longitude": 18.0555}
  }')

OBJECT_ID=$(echo $OBJECT | grep -o '"id":"[^"]*"' | head -1 | cut -d'"' -f4)
echo "Objekt ID: $OBJECT_ID"

# 2. Ladda upp bild
echo "Laddar upp bild..."
curl -X POST "$API_URL/api/v1/observations" \
  -F "images=@/sökväg/till/bankomat.jpg" \
  -F "objectId=$OBJECT_ID" \
  -F "angle=front"

echo "Klart!"

---

Fototips för bästa resultat

Vinklar

• front: Rakt framifrån, hela framsidan synlig
• left: 45° från vänster
• right: 45° från höger
• detail: Närbild på kortläsare/PIN-pad

Kvalitet

• Minst 640x480 pixlar
• Jämn belysning (undvik skuggor)
• Skarp fokus
• Ingen reflektion från blixt

Vad som ska synas

• Hela bankomaten
• Kortläsaren tydligt
• PIN-pad
• Display
• Omgivningen (vägg, golv)

---

Testa lokalt

Med demo-script

node demo/complete-demo.js

Detta skapar syntetiska bilder och kör hela flödet automatiskt.

---

Felsökning

"Connection refused"

Servern är inte startad. Kör:

npm run dev

"Object not found"

Fel objekt-ID. Kontrollera ID från steg 2.

"Invalid file type"

Endast JPEG, PNG, WebP accepteras.

"Database connection failed"

Starta PostgreSQL:

docker-compose up -d postgres