boc/vims-backend/docs/UPLOAD_GUIDE.md

# VIMS - Fotoguide & API-uppladdning

## Steg 1: Förberedelser

### Starta servern
```bash
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
```bash
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
```json
{
  "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
```bash
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)
```bash
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
```bash
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
```json
{
  "observations": [
    {
      "id": "obs-uuid",
      "status": "pending",
      "imageUrl": "/uploads/..."
    }
  ],
  "objectId": "DITT-OBJEKT-ID",
  "processed": 1
}
```

---

## Steg 5: Kontrollera resultat

### Hämta observation
```bash
curl http://localhost:3450/api/v1/observations/OBSERVATION-ID
```

### Hämta detektioner
```bash
curl "http://localhost:3450/api/v1/detections?observationId=OBSERVATION-ID"
```

### Hämta larm
```bash
curl "http://localhost:3450/api/v1/alerts?objectId=DITT-OBJEKT-ID"
```

---

## Komplett exempel (bash-script)

```bash
#!/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
```bash
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:
```bash
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:
```bash
docker-compose up -d postgres
```