boc/QUIXZOOM_CAPTURE_FLOW.md

# quiXzoom Capture Flow — Arkitekturspec
*Beslutad: 2026-06-17. Ägare: Erik Svensson.*

---

## Grundprincip

Användaren ska aldrig behöva gissa vad som är fel.

**Gammalt flöde (oacceptabelt):**
Ta bild → Vänta → Få avslag → Gissa → Ta ny bild

**quiXzoom-flödet:**
Rikta kamera → Följ instruktioner → Grönt ljus → Bild tas → Godkänd direkt

**KPI:** >90% av alla bilder godkänns vid första exponeringen.

---

## Flödets 7 steg

### Steg 1 — Uppdrag accepteras

Zoomer väljer uppdrag. Systemet laddar ett **Mission Context Package**:

```
{
  mission_id, location, control_objects[], reference_images[],
  capture_rules[], ai_knowledge_packs[], acceptance_criteria[]
}
```

Varje `control_object` är kopplat till ett AVO-kunskapspaket.

---

### Steg 2 — AI-styrt kameraläge (Live Guidance)

Istället för direkt kamera öppnas **Live Guidance Mode** — kontinuerlig analys av videoströmmen, ~10 fps.

**Realtidskontroller (alla måste vara ✅ för grönt läge):**

| Check | Fel-feedback |
|-------|-------------|
| Objekt hittat | "Rikta kameran mot [objekt]" |
| Rätt avstånd | "Flytta närmare" / "Backa 1 meter" |
| Rätt vinkel | "Vrid kameran åt höger" / "Höj kameran 15 cm" |
| Tillräckligt ljus | "För mörkt — sök bättre ljus" |
| Hela objektet synligt | "Objekt delvis utanför bild — backa lite" |
| Skärpa godkänd | "Håll kameran still" |
| Geo-match | "Du är inte vid rätt adress" |

**Teknisk implementation:**
- Klientsidig: TensorFlow Lite / CoreML på device (låg latens, offline-kapabel)
- Serversidig fallback för tyngre analyser (sprickor, OCR) vid bra uppkoppling
- Feedback-overlay i AR: grön ram = klar, röd + text = korrigering krävs

---

### Steg 3 — Grönt läge (Capture Ready)

När alla kriterier är uppfyllda:

```
🟢 Objekt verifierat
🟢 Bildkvalitet godkänd
🟢 Redo att fotografera
```

Kameran kan antingen:
- **Autoshoot** — tar bilden automatiskt vid 3 sek stabil grön status
- **Manual unlock** — låser upp avtryckaren, Zoomer tar bilden

Default: autoshoot. Konfigurerbart per uppdragstyp.

---

### Steg 4 — Parallell AI-analys

Efter exponering körs AVO-analyser parallellt (target: <3 sek):

```
┌─────────────────────────────────────────────┐
│  Image received                             │
├──────────────┬──────────────┬───────────────┤
│ AVO instance │ AVO instance │ AVO instance  │
│ control_obj_1│ control_obj_2│ quality_check │
└──────────────┴──────────────┴───────────────┘
         ↓              ↓              ↓
         └──────────────┴──────────────┘
                        ↓
                 Decision Engine
```

Varje AVO-instans kör mot sitt kunskapspaket och returnerar avvikelse-JSON.
Quality check är ett eget paket: blur, exposure, completeness.

---

### Steg 5 — Beslutsmotor

**GODKÄND:**
```
🟢 Uppdragets bildkrav uppfyllda
Bild accepterad. Fortsätt till nästa kontrollpunkt.
```
→ Bild sparas, geo-tagg + timestamp + device-ID loggas, betalningspipeline triggas.

**NEKAD** — AI måste alltid ge en konkret, handlingsbar anledning:

| Avvikelse | Feedback till Zoomer |
|-----------|---------------------|
| OCR-fel: skylt oläsbar | "Registreringsskylten är inte fullt läsbar." |
| Objekt delvis skymt | "Serienumret är skymt." |
| Completeness-fel | "Hela fasaden syns inte." |
| Blur | "Bilden är oskarp." |
| Object mismatch | "Objektet motsvarar inte uppdragets beskrivning." |
| Distance-fel | "Avståndet är för långt." |

**Aldrig:** "Fel uppstod." / "Bild ej godkänd." utan anledning.

---

### Steg 6 — Automatisk återgång

Vid nekad bild: systemet öppnar direkt kameran igen med *uppdaterad* guidance baserad på avvisningsanledningen.

```
Rikta kameran 30 cm lägre.  ← Ny specifik instruktion
Ta med hela objektet.
```

Ingen manuell navigation. Ingen "försök igen"-knapp. Det bara händer.

---

### Steg 7 — Uppdrag slutfört

När alla obligatoriska kontrollobjekt är verifierade:

```
🟢 Uppdrag slutfört
🟢 12 av 12 kontrollpunkter verifierade
🟢 Kvalitetsnivå: 98%
```

Betalning triggas automatiskt via Stripe Connect.
Uppdragsgivaren får leverans i sin dashboard.

---

## AVO-integration (avvikelsemotorn)

Live Guidance (steg 2) och Post-capture (steg 4) delar samma kunskapspaket men körs i olika lägen:

| Läge | Trigger | Latenskrav | AVO-config |
|------|---------|------------|------------|
| **Live** | Videoframe ~10fps | <100ms | Lätt subset av checks — guidance only |
| **Capture** | Exponering | <3 sek | Fullständiga checks — beslutsgrundande |

Live-läget kör aldrig beslutsgrundande analys — det guidar bara.
Post-capture kör fullständig AVO och är det enda som räknas för godkännande.

---

## Kunskapspaket per uppdragstyp (exempel)

```json
{
  "object": "building_facade",
  "checks": ["completeness", "ocr_address", "damage_detection", "lighting_check"],
  "tolerances": { "min_coverage_pct": 85, "max_blur": 0.3 },
  "known_faults": ["crack", "graffiti", "missing_element", "occlusion"],
  "risk_rules": { "ocr_fail": "high", "crack": "medium", "graffiti": "low" },
  "live_guidance": {
    "distance_range_m": [3, 8],
    "preferred_angle": "straight_on",
    "required_elements": ["entrance", "full_height"]
  }
}
```

---

## Teknisk stack (förslag)

| Komponent | Teknologi |
|-----------|-----------|
| Live guidance (client) | TensorFlow Lite / CoreML |
| Post-capture AVO | Server-side (GPU), <3 sek SLA |
| Overlay UI | React Native + Reanimated |
| Geo-validering | Device GPS + ±15m tolerans |
| Bildlagring | S3 (quixzoom-media-prod) |
| Beslutspipeline | aamos-core → AVO → beslut → Stripe |
| Audit trail | Immutable log: image_hash + geo + timestamp + device_id |

---

## Öppna frågor

1. **Autoshoot vs manual unlock** — default per uppdragstyp eller global setting?
2. **Offline-kapabilitet** — live guidance måste fungera utan nät. Post-capture kan queua.
3. **Manipulationsskydd** — hur hindrar vi att Zoomers skickar skärmdumpar av bilder? Device attestation (iOS/Android)?
4. **Max antal omtag per kontrollobjekt** — ska det finnas ett tak? (ex. 5 försök → eskalera till manuell granskning)
5. **Deltagarens integritet** — bilder kan innehålla personer. GDPR-krav på face blurring?

---

*Nästa steg: Bygga MVP-implementation av Live Guidance för iOS.*