alva/docs/moduler/evidensmotor.md

# Modul: Evidensmotorn (ECM — Evidence & Compliance Matrix)

**Version: ECM v2.0** · ECM är ett eget subsystem — inte en tabell i
databasen — och motorn som styr hela plattformen: den avgör vilken
dokumentation som krävs, när dokumentation saknas, vilken bevisnivå som
uppnåtts, vilka regler som gäller och om ett ärende kan avslutas.
**Systemet kan aldrig skriva en slutsats som ECM inte har godkänt.**

Regelbiblioteket är versionshanterat och skilt från applikationslogiken
(`src/felsokning/ecm.ts`); vyerna anropar bara motorns rena funktioner.

## De sex motorerna

### 1. Evidence Engine
Katalogiserar all bevisning ur händelseloggen. Varje evidenspost får
id, tidpunkt, tekniker, kategori, evidensnivå, sammanfattning och
**innehållshash** — samma post ger alltid samma hash, och den
append-only-låsta loggen (databastriggers) gör varje ändringsförsök
omöjligt.

| Nivå | Typ | Bevisvärde |
| --- | --- | --- |
| E0 | Inget underlag | 0 % |
| E1 | Teknikerns observation | Lågt |
| E2 | Foto | Medel |
| E3 | Video (med ljud — för det som låter eller rör sig) | Högt |
| E4 | Mätvärde | Högt |
| E5 | Diagnosdata/dokument | Mycket högt |
| E6 | Flera oberoende källor | Högsta |

### 2. Rule Engine
Dokumentationskraven: metodikens `krav`-fält per kontroll plus de
automatiska reglerna — *kan det fotograferas → begär foto; låter det →
video med ljud; rör det sig → video; mäts det → mätvärde; visar en
display informationen → fota displayen; finns ett dokument → fota
dokumentet.* Undantagsorsakerna ("Underlag kan inte tas fram") ligger
här.

### 3. Compliance Engine
Ärendetypen styr vilka regler som gäller utöver metodiken. Ärendetyp
väljs i identitetsraden och loggas (`arendetyp_satt`):

| Ärendetyp | Extra krav (v2.0) |
| --- | --- |
| Garanti | Miltal dokumenterat · servicehistorik kontrollerad · claim-/garantinummer |
| Goodwill | Miltal · servicehistorik |
| Försäkring | Skadenummer · bildbevis |
| Reklamation | Historik och tidigare försök kontrollerade |
| Begagnatgaranti | Miltal |

**ECM Knowledge Library är implementerat**: reglerna är deklarativa data
(krav-typ, inte kod) och distribueras från plattformen via
`GET /api/ecm/regler` (`services/plattform/ecm-regler.json` — i klustret
utbytbar via ConfigMap och miljövariabeln `ECM_REGLER_FIL`). Klienten
hämtar paketet vid sidladdning, cachar det och faller tillbaka till sitt
inbyggda standardpaket offline; trasiga paket och okända krav-typer
filtreras. Regelpaketets version följer med i varje spårbarhetspaket.
Nya regler — garantivillkor per tillverkare, försäkringsbolagens krav,
reklamationslagstiftning, OEM-kontrollpunkter — läggs till i driften
utan att applikationen byggs om.

### 4. Validation Engine
Inga påståenden utan underlag, i tre lager: (a) orkesterns grundprompt —
aldrig "OK/kontrollerad/inga fel/åtgärdad" utan evidens, i stället
"Evidens saknas" plus begäran om rätt underlag; (b) projektionerna —
hypoteser kan aldrig bli konstaterade fel; (c) kvalitetsgrinden nedan.

### 5. Completion Engine
Kvalitetsgrinden före slutrapport/avslut — utskriften är spärrad tills
alla obligatoriska rader är gröna:

| Kontroll | Krav |
| --- | --- |
| Fordons-/objektidentifiering verifierad | Obligatorisk |
| Arbetsorder inläst | Rekommenderas |
| Fordonshistorik kontrollerad eller motiverad | Obligatorisk |
| Ingående mätarställning dokumenterad | Obligatorisk |
| Kundens felbeskrivning verifierad | Rekommenderas |
| Kundens besked på åtgärdsförslaget | Obligatoriskt när arbete utförts |
| Åtgärd dokumenterad eller motiverad | Obligatorisk vid avslut |
| Kvalitetskontroll genomförd | Obligatorisk vid avslut efter utförd åtgärd |
| Utgående mätarställning | Obligatorisk vid avslut |
| Metodikens kontroller: evidens eller dokumenterat undantag | Obligatorisk |
| Foton för fotokrävande kontroller | Obligatorisk |
| Ärendetypens compliance-krav | Obligatoriska |
| Teknikerns slutsats signerad | Automatisk vid avslut |
| Evidensnivå över E0 | Obligatorisk |

### 6. Traceability Engine
Varje export bär ett spårbarhetspaket: ECM-version, ärendetyp,
evidensnivå, grindstatus per regel-id och samtliga evidensposter med
hash. Tillsammans med loggen kan varje slutsats härledas: vilken bild →
vilken mätning → vilken tekniker → vilken regel → vilken regelverksversion
→ när.

## Pre-Diagnostic Validation

Ingen felsökning påbörjas förrän grundkontrollerna är genomförda eller
dokumenterat motiverade — metodiken låses upp först därefter:

1. **Fordonshistorik** — systemet hämtar automatiskt organisationens
   tidigare ärenden på samma objekt (regnr/VIN) med deras dokumenterade
   felorsaker (`GET /api/fordon/{identifierare}/historik`; lokala storen
   offline) och visar dem i historiksteget. Teknikern kan koppla
   **orsakskedjan** till det aktuella ärendet med ett tryck ("kopplat
   till tidigare ärende #N — …"), kvitterar kontrollen — eller anger Nej
   med obligatorisk orsak → kvalitetsvarning.
2. **Ingående mätarställning** — instrumentpanelen fotograferas;
   bildtolkningen föreslår värdet, teknikern bekräftar. Fotot blir den
   officiella ingående mätarställningen.
3. **Kundens felbeskrivning verifierad** — ytterligare symptom
   dokumenteras som separata observationer, aldrig hopblandade med
   kundens beskrivning.
4. **Tidiga observationer** — reparationsspår, modifieringar, skador,
   läckage m.m. dokumenteras med foto/observation, eller kvitteras
   "inga ytterligare".

**Utgående mätarställning** fotograferas inför avslut och blir
obligatorisk i grinden när ärendet stängs. Rapporten visar in/ut.

## Symptom Verification Protocol (SVP)

Ett fel diagnostiseras aldrig direkt från en vag kundbeskrivning.
Kedjan är alltid: **dokumenterats → förtydligats → reproducerats eller
dokumenterats som ej reproducerbart.**

- Kundens beskrivning registreras ordagrant vid ärendestart och
  verifieras i pre-diagnostiken; nya symptom blir separata observationer.
- Förtydligandet sker genom metodikens symptomfrågor (när/var/hur/
  förhållanden/frekvens — generiska metodiken har hela SVP-frågesetet).
- **Reproducering** (Ja/Delvis/Nej) dokumenteras innan avslut: Ja kräver
  hur och under vilka förhållanden; Delvis vad som kunde respektive inte
  kunde återskapas; Nej kräver motivering. Systemet skriver aldrig
  "felet konstaterat" utan reproducering eller annan verifiering — i
  stället: *"Kundens beskrivning kunde inte reproduceras under de
  förhållanden som rådde vid undersökningen."* (kodat även i orkesterns
  grundprompt).
- Rapportens beviskedja skiljer alltid: kundens beskrivning →
  verifierad observation → felorsaksanalys → rekommenderad åtgärd.

## Felorsaksanalys (Root Cause Analysis)

Ett ärende avslutas aldrig med enbart "komponent defekt, byt komponent".
Varje konstaterat fel kräver fyra obligatoriska svar:

1. **Konstaterad avvikelse** — kvalitetsregeln avvisar generella
   formuleringar ("trasig", "defekt", "sliten", "behöver bytas") utan
   förklaring.
2. **Mest sannolik orsak** — en eller flera kategorier (normalt slitage,
   materialutmattning, tillverkningsfel, bristande underhåll, felaktig
   tidigare reparation, yttre påverkan, korrosion, överhettning,
   modifiering … samt *Okänd orsak*, som kräver motivering).
3. **Underlag** — minst en evidenskälla, och källan valideras mot
   loggen: "Foto" godtas bara om ett foto faktiskt finns.
4. **Säkerhetsnivå** — hög/medel/låg; vid medel/låg krävs vilka
   ytterligare kontroller som skulle stärka bedömningen.

Avslutsknappen är spärrad tills SVP + felorsaksanalys är dokumenterade,
och kvalitetsgrinden gör båda obligatoriska när ärendet stängs.
Flottdatan är redan igång: **felorsaksstatistiken** i arbetsledarvyn
(`GET /api/statistik/felorsaker`) aggregerar orsakskategorierna över
organisationen — vilka komponenter fallerar av slitage, vilka efter
tidigare reparationer, vilka tyder på konstruktionsproblem.

## Kundgodkännande före arbete

Verkstaden får aldrig utföra föreslaget arbete utan att kundens besked är
registrerat och spårbart:

- **Åtgärdsförslaget** skrivs i guiden (förifyllt ur felorsaksanalysens
  rekommenderade åtgärd) med eventuell uppskattad kostnad, och **visas
  för kunden i Live Share** — det är kunddelbart material.
- **Kundens besked** registreras med utfall (godkänt/avböjt/delvis),
  **kanal** (telefon, på plats, e-post, SMS, delningslänk) och
  motivering vid avböjt/delvis. Loggposten bär vem i verkstaden som tog
  emot beskedet och när.
- **Knappen "Dokumentera utförd åtgärd" är låst** så länge ett förslag
  saknar besked — och förblir låst vid avböjt besked. Vägen "Ingen
  åtgärd utförd" är öppen och hänvisar till det registrerade beskedet.
- Kvalitetsgrinden kräver registrerat besked när arbete utförts, och
  flaggar konflikten *"Utfört arbete trots avböjt åtgärdsförslag"* som
  ett hårt fel.

Avgränsning: kunden godkänner i dagsläget genom kontakt med verkstaden —
plattformen registrerar beskedet. Publikt godkännande direkt i
delningslänken kräver en skrivande publik endpoint och hanteras separat.

## Åtgärdsfasen (Repair & Verification)

Loopen som symptomverifieringen öppnade sluts här — ett ärende kan inte
avslutas utan att det framgår vad som gjordes och om det hjälpte:

1. **Åtgärd dokumenterad eller motiverad** — antingen vad som faktiskt
   utfördes (med eventuella delar), eller varför ingen åtgärd gjordes
   (kunden avböjde, väntar på reservdel, endast utredning beställd,
   kostnadsförslag lämnat, åtgärd hos annan verkstad).
2. **Kvalitetskontroll** — obligatorisk när en åtgärd faktiskt utförts:
   är symptomet borta, kvarstår det helt eller delvis, eller kunde det
   inte verifieras? Utfallet dokumenteras med hur verifieringen gick
   till (samma förhållanden som symptomet reproducerades under).

Kvarstående symptom döljs aldrig: grinden skriver ut att ärendet inte
bör avslutas som åtgärdat. Avslutsknappen är spärrad tills kedjan
**symptomverifiering → felorsaksanalys → åtgärd → kvalitetskontroll** är
komplett, och rapporten redovisar den i egna avsnitt.

## Ärendeidentitet (Case Identity & Vehicle Context)

Fordonsobjektet är den röda tråden: identiteten registreras **en gång**
(normalt via arbetsorderskanningen, som nu även läser claim-/garantinummer
och skadenummer) och återanvänds sedan överallt:

- **Identitetsrad i arbetsytan** — AO, claim, skadenummer, fordon, regnr,
  VIN, miltal, ansvarig tekniker + ärendetypsval.
- **Live Share** — låst panel överst med fordon, referenser och status,
  härledd ur det nivåfiltrerade underlaget.
- **Slutrapportens första sida** — Ärendeinformation + Fordonsinformation
  automatiskt.
- **Exporten** — identitet + spårbarhetspaket i varje JSON.

## Terminologi

Produkten beskrivs aldrig som en "AI-app" utan som ett **evidensbaserat
diagnossystem** / **intelligent beslutsstöd**. I användargränssnitt och
dokument används *systemet, analysen, bedömningen, tolkningen,
bildtolkningen, beslutsstödet, regelmotorn* — inte "AI", om det inte är
tekniskt nödvändigt.