alva/felsokning/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.

Kunden kan svara direkt i sin delningslänk (POST /api/delad/{kod}/beslut) — den enda skrivande publika vägen i hela API:t, med sex spärrar som var och en verifieras i integrationstestet:

1. Endast delningar på kundnivå (partner-/internlänkar får aldrig svara åt kunden) och aldrig återkallade.
2. Ärendets ursprungliga delningskod saknar registrerad nivå och kan inte heller svara.
3. Det måste finnas ett åtgärdsförslag att svara på.
4. Ett besked per ärende — svaret kan inte ändras i efterhand (kontakta verkstaden i stället).
5. Endast godkant/avbojt/delvis plus en kommentar på högst 500 tecken; inget annat kan skrivas till loggen den vägen.
6. Takt-begränsning per delningskod.

Beskedet loggas som kundbeslut med kanal Delningslänk och avsändaren "Kund via delningslänk" — verkstadens egna registreringar (telefon, på plats …) fungerar precis som förut.

Å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.