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)

{
  "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.