Merge main: Guidad Felsökning flyttar ur roten till felsokning/
Main är sedan den här grenen skapades en helt annan produkt — Semantika,
en mobilapp med egen CDK-infrastruktur. Den äger nu repots rot: en
npm-workspaces-monorepo med apps/mobile, services/api och infra.
För att båda ska rymmas i samma repo flyttar Guidad Felsökning in i en
egen katalog i stället för att göra anspråk på roten:
felsokning/app webbklienten (Vite, egen package.json och
eslint-/vitest-konfiguration)
felsokning/services plattformstjänsten och AI-orkestern
felsokning/infra Terraform och databasschemat
felsokning/docs vision, moduler, drift
felsokning/supabase edge-funktion och migrationer
Merge:n hade tagit bort 128 filer som Guidad Felsökning bygger på —
värdapplikationens komponenter, Supabase-klienten, tillgångar — eftersom
main raderat dem och den här grenen inte råkat ändra just dem. De är
återställda på sin nya plats. Utan dem gick varken bygget eller
testerna: ai.ts och synk.ts importerar Supabase-klienten.
Semantikas rotfiler är orörda: package.json, eslint.config.js och
.github/workflows/ är deras. Guidad Felsökning har egna motsvarigheter i
sin katalog.
CI flyttar samtidigt från GitHub Actions till .gitea/workflows — samma
syntax, egna runners. .github/workflows/ tillhör Semantika härefter.
Verifierat på den nya platsen: 96 vitest-tester, typkontroll, eslint på
både klient och tjänster, bygge, och integrationstest mot riktig Postgres.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012EQg3rJsrQ1ZNTvkzmQAtt
This commit is contained in:
Claude
@@ -0,0 +1,128 @@
|
||||
# Modul: Arbetslogg & Tidredovisning
|
||||
|
||||
## Syfte
|
||||
|
||||
Allt arbete som utförs under ett felsökningsärende ska vara tidsatt, spårbart och kopplat till konkreta aktiviteter.
|
||||
|
||||
Systemet registrerar inte bara hur lång tid ett arbete tagit, utan även vad som utförts under tiden.
|
||||
|
||||
Det här är mer än en stämpelklocka – ett digitalt arbetsprotokoll där tid, aktivitet och tekniskt resonemang hänger ihop. Det ger ett betydligt starkare underlag än traditionell tidrapportering.
|
||||
|
||||
---
|
||||
|
||||
## Start av arbete
|
||||
|
||||
Teknikern börjar genom att identifiera objektet.
|
||||
|
||||
Exempel:
|
||||
|
||||
- Foto av registreringsnummer
|
||||
- VIN-skanning
|
||||
- QR-kod
|
||||
- Serienummer
|
||||
- Maskinnummer
|
||||
|
||||
När objektet är verifierat startar arbetsloggen.
|
||||
|
||||
Exempel:
|
||||
|
||||
```
|
||||
08:03 Arbete startat
|
||||
Objekt: ABC123
|
||||
Volvo XC60
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Automatisk tidslinje
|
||||
|
||||
Alla aktiviteter tidsstämplas automatiskt.
|
||||
|
||||
Exempel:
|
||||
|
||||
```
|
||||
08:03 Objekt identifierat
|
||||
08:05 Felbeskrivning registrerad
|
||||
08:11 Säkring F23 kontrollerad
|
||||
08:18 Mätning av matningsspänning
|
||||
08:27 Foto uppladdat
|
||||
08:35 Direktmatning utförd
|
||||
08:48 Elschema öppnat
|
||||
09:01 Ny kontroll
|
||||
09:09 Felsökning avslutad
|
||||
```
|
||||
|
||||
Ingen manuell administration krävs.
|
||||
|
||||
---
|
||||
|
||||
## Aktiv arbetstid
|
||||
|
||||
Systemet skiljer på:
|
||||
|
||||
- aktiv felsökning
|
||||
- väntetid
|
||||
- administrativ tid
|
||||
- reservdelssökning
|
||||
- provkörning
|
||||
- kundkontakt
|
||||
|
||||
Det ger en mer rättvisande tidsredovisning.
|
||||
|
||||
---
|
||||
|
||||
## Kontext vid längre avbrott
|
||||
|
||||
Om det gått en längre stund utan aktivitet kan systemet fråga efter sammanhang, exempelvis:
|
||||
|
||||
> ”Ingen aktivitet har registrerats de senaste 20 minuterna. Beskriv kort vad som gjorts under denna period.”
|
||||
|
||||
Teknikern kan svara med text eller tal, till exempel:
|
||||
|
||||
> ”Demonterade instrumentpanelen för att komma åt kabelstammen.”
|
||||
|
||||
Det blir en del av arbetsloggen.
|
||||
|
||||
---
|
||||
|
||||
## AI som dokumentationsstöd
|
||||
|
||||
AI bedömer inte om teknikern arbetar ”tillräckligt snabbt”. Däremot hjälper den till att säkerställa att loggen blir begriplig och komplett. Om ett steg saknar sammanhang kan den be om ett kort förtydligande så att rapporten blir användbar för kunden eller den egna organisationen.
|
||||
|
||||
---
|
||||
|
||||
## Slutrapport
|
||||
|
||||
När arbetet avslutas genereras automatiskt en rapport med exempelvis:
|
||||
|
||||
**Total tid: 1 timme 37 minuter**
|
||||
|
||||
Fördelning:
|
||||
|
||||
- Diagnos: 54 min
|
||||
- Demontering: 18 min
|
||||
- Mätningar: 11 min
|
||||
- Dokumentation: 6 min
|
||||
- Provkörning: 8 min
|
||||
|
||||
Rapporten innehåller även:
|
||||
|
||||
- utförda kontroller,
|
||||
- mätvärden,
|
||||
- bifogade bilder,
|
||||
- tekniska slutsatser,
|
||||
- rekommenderade nästa steg.
|
||||
|
||||
---
|
||||
|
||||
## Affärsvärde
|
||||
|
||||
Den här funktionen kan bli ett av systemets starkaste argument, eftersom den:
|
||||
|
||||
- minskar administration efter avslutat arbete,
|
||||
- ger kunden ett tydligt underlag för debiteringen,
|
||||
- stärker underlaget vid garanti- och försäkringsärenden,
|
||||
- gör intern uppföljning enklare,
|
||||
- skapar en sökbar kunskapsbank över tidigare felsökningar.
|
||||
|
||||
Det gör att Guidad Felsökning blir mer än en AI-assistent – den blir ett komplett arbetsverktyg där identifiering, metodisk felsökning, dokumentation och tidredovisning bildar en sammanhängande och spårbar process.
|
||||
@@ -0,0 +1,137 @@
|
||||
# Modul: Ärendebrief
|
||||
|
||||
## Syfte
|
||||
|
||||
När en ny tekniker tar över ett pågående ärende ska denne kunna bli produktiv på under en minut, utan att behöva läsa hela historiken.
|
||||
|
||||
Systemet genererar automatiskt en strukturerad sammanfattning av ärendet som uppdateras löpande.
|
||||
|
||||
Det här är inte en chatt, utan ett **levande ärende** där AI:n hela tiden håller en uppdaterad arbetsbild.
|
||||
|
||||
---
|
||||
|
||||
## Exempel
|
||||
|
||||
**Objekt**
|
||||
|
||||
> Volvo XC60 D4 2019
|
||||
> Reg.nr ABC123
|
||||
> Kund: Anders Svensson
|
||||
|
||||
**Kundens beskrivning**
|
||||
|
||||
> Bilen vibrerar runt 88 km/h.
|
||||
> Symptomet uppträder endast under körning.
|
||||
|
||||
**Utförda kontroller**
|
||||
|
||||
- ✓ Lufttryck kontrollerat
|
||||
- ✓ Hjulmoment kontrollerat
|
||||
- ✓ DOT-koder dokumenterade
|
||||
- ✓ Fyra hjul fotograferade
|
||||
- ✓ Provkörning genomförd
|
||||
- ✓ Balanseringsvikter kontrollerade
|
||||
|
||||
**Observationer**
|
||||
|
||||
- Höger framdäck visar ojämnt slitage.
|
||||
- Ingen uppenbar skada på fälgar.
|
||||
- Vibration känns främst i ratten.
|
||||
- Ingen förändring vid acceleration.
|
||||
|
||||
**Ej kontrollerat**
|
||||
|
||||
- Radialkast
|
||||
- Drivaxlar
|
||||
- Hjullager
|
||||
- Fyrhjulsmätning
|
||||
|
||||
**Rekommenderat nästa steg**
|
||||
|
||||
1. Mät radialkast.
|
||||
2. Kontrollera drivaxlar.
|
||||
3. Ny provkörning.
|
||||
|
||||
**Total arbetstid**
|
||||
|
||||
2 timmar 14 minuter
|
||||
|
||||
**Tillförlitlighet**
|
||||
|
||||
- 🟢 Kunduppgifter verifierade
|
||||
- 🟢 Bilder dokumenterade
|
||||
- 🟢 Mätvärden registrerade
|
||||
- 🟡 Felorsak ännu inte verifierad
|
||||
|
||||
---
|
||||
|
||||
## AI:s roll
|
||||
|
||||
AI:n ska inte bara sammanfatta historiken, utan också hålla reda på ärendets aktuella läge. Om en ny tekniker ansluter ska systemet kunna svara på frågor som:
|
||||
|
||||
- ”Vad återstår?”
|
||||
- ”Vad är mest sannolikt att kontrollera härnäst?”
|
||||
- ”Vilka tester är redan utförda?”
|
||||
- ”Finns det några motsägelsefulla observationer?”
|
||||
- ”Vad behöver verifieras innan vi går vidare?”
|
||||
|
||||
---
|
||||
|
||||
## Samarbete
|
||||
|
||||
Detta byggs som ett riktigt fleranvändarsystem. Varje ärende blir en arbetsyta där flera personer kan delta.
|
||||
|
||||
Exempel:
|
||||
|
||||
```
|
||||
Ärende #45281
|
||||
Ansvarig: Anna
|
||||
Deltagare: Johan, Erik, Lisa
|
||||
```
|
||||
|
||||
- Alla ser samma information i realtid.
|
||||
- Alla bilder hamnar i samma ärende.
|
||||
- Alla mätvärden hamnar i samma logg.
|
||||
- Alla kommentarer tidsstämplas.
|
||||
- Alla AI-sammanfattningar uppdateras automatiskt.
|
||||
|
||||
---
|
||||
|
||||
## Skiftbyte – Överlämning med ett klick
|
||||
|
||||
Vid skiftbyte trycker teknikern bara på **Lämna över arbete**. Systemet genererar då automatiskt en överlämningsrapport.
|
||||
|
||||
Den nya teknikern får:
|
||||
|
||||
- vad kunden upplever,
|
||||
- vad som redan gjorts,
|
||||
- vilka mätningar som finns,
|
||||
- vilka bilder som tagits,
|
||||
- vilka slutsatser som kan dras med hög säkerhet,
|
||||
- vilka frågor som fortfarande är obesvarade,
|
||||
- nästa rekommenderade steg.
|
||||
|
||||
Ingen behöver läsa igenom hundratals chattmeddelanden.
|
||||
|
||||
Samma funktion används vid eskalering: när en tekniker lämnar sitt pass eller eskalerar ett ärende genereras automatiskt en kort briefing med:
|
||||
|
||||
- nuläge,
|
||||
- verifierade fakta,
|
||||
- återstående arbete,
|
||||
- risker eller osäkerheter,
|
||||
- rekommenderade nästa steg.
|
||||
|
||||
Det gör att nästa tekniker kan fortsätta arbetet nästan omedelbart, vilket är särskilt värdefullt i större verkstäder och serviceorganisationer där flera personer arbetar med samma objekt under olika skift.
|
||||
|
||||
---
|
||||
|
||||
## Arkitektur
|
||||
|
||||
Modulen passar mycket bra med en multi-tenant SaaS-arkitektur:
|
||||
|
||||
- **Tenant** = verkstad eller serviceorganisation.
|
||||
- **Användare** = tekniker, arbetsledare, verkstadschef, administratör.
|
||||
- **Ärende** = en delad arbetsyta med gemensam kontext.
|
||||
- **AI-kontext** = en strukturerad, löpande sammanfattning av ärendet som används för briefing och vägledning.
|
||||
|
||||
Det sista är viktigt: AI:n bör inte behöva läsa hela historiken varje gång någon öppnar ett ärende. I stället underhålls en strukturerad ärendesammanfattning som uppdateras efter varje relevant händelse. Det gör systemet snabbare, billigare att köra och mer konsekvent, samtidigt som hela loggen fortfarande finns kvar för revision och export.
|
||||
@@ -0,0 +1,242 @@
|
||||
# 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.
|
||||
@@ -0,0 +1,78 @@
|
||||
# Modul: Kommunikationsmodell (röst)
|
||||
|
||||
## Grundprincip
|
||||
|
||||
**Användaren pratar, systemet skriver.**
|
||||
|
||||
Systemet använder tal-till-text (Voice-to-Text) för all röstinmatning. Teknikern ska aldrig behöva skriva med tangentbord under ett pågående arbete.
|
||||
|
||||
Ingen röstagent: systemet för inte ett löpande röstsamtal, läser inte upp långa svar och försöker inte efterlikna en mänsklig konversation. Kommunikationen är **tal in, text ut**.
|
||||
|
||||
## Viktig designprincip
|
||||
|
||||
> All röst behandlas som ett inmatningssätt, inte som ett separat gränssnitt.
|
||||
|
||||
All logik i systemet bygger på text. Voice-to-Text är endast ett sätt att skapa den texten. Det gör lösningen enklare att underhålla, enklare att söka i, enklare att exportera och enklare att utveckla vidare med nya AI-modeller i framtiden.
|
||||
|
||||
## Arbetsflöde
|
||||
|
||||
1. Teknikern trycker på mikrofonen: *"Jag har mätt mellan stift 14 och jord. Jag får 12,4 volt."*
|
||||
2. Voice-to-Text transkriberar talet.
|
||||
3. Den transkriberade texten skickas till AI:n som en vanlig textförfrågan.
|
||||
4. AI:n svarar alltid skriftligt: *Verifierat: Matningsspänning finns på stift 14. Nästa steg: Kontrollera jordanslutningen på stift 7.*
|
||||
|
||||
## Varför detta val?
|
||||
|
||||
- fungerar bättre i bullriga verkstäder,
|
||||
- ger en permanent textlogg utan extra steg,
|
||||
- gör det enkelt att söka i historiken,
|
||||
- minskar risken för missförstånd jämfört med ett kontinuerligt röstsamtal,
|
||||
- passar bättre när flera tekniker arbetar i samma ärende.
|
||||
|
||||
## Push-to-Talk (PTT)
|
||||
|
||||
Röstinmatning fungerar enligt Push-to-Talk. Appen lyssnar **endast** när användaren aktivt håller inne mikrofonknappen eller har startat en tydlig inspelning. Ingen bakgrundslyssning. Ingen automatisk aktivering.
|
||||
|
||||
### Flöde
|
||||
|
||||
1. Användaren håller inne mikrofonknappen (eller trycker på en tydlig "Spela in"-knapp beroende på plattform).
|
||||
2. Inspelning startar omedelbart.
|
||||
3. Appen visar tydligt att inspelning pågår: röd indikator, timer, ljudnivåmätare, texten "Inspelning pågår".
|
||||
4. Talet transkriberas i realtid — användaren ser texten växa fram och får direkt återkoppling om talet uppfattats korrekt.
|
||||
5. När inspelningen avslutas visas den transkriberade texten i ett **redigerbart** textfält.
|
||||
6. Användaren kan godkänna, redigera eller spela in på nytt.
|
||||
7. **Först när användaren bekräftar** skickas texten vidare till AI:n och sparas i arbetsloggen.
|
||||
|
||||
### Redigering före skick
|
||||
|
||||
Transkriberingen är alltid redigerbar. Vanliga korrigeringar: registreringsnummer, serienummer, komponentbeteckningar, personnamn, facktermer.
|
||||
|
||||
**"Skicka" sker aldrig automatiskt.** Teknikern får alltid en snabb chans att rätta transkriberingen innan den blir en del av den permanenta arbetsloggen. Det minskar risken för felaktiga registreringsnummer, komponentbeteckningar och mätvärden.
|
||||
|
||||
### Ingen dold funktionalitet
|
||||
|
||||
Användaren ska alltid kunna se:
|
||||
|
||||
- när inspelning pågår,
|
||||
- när den är avslutad,
|
||||
- vad som kommer att skickas,
|
||||
- vad som faktiskt har sparats.
|
||||
|
||||
Det ska aldrig råda någon tvekan om när ljud spelas in eller när information skickas.
|
||||
|
||||
## Automatisk journalföring
|
||||
|
||||
Varje transkriberad mening blir automatiskt en del av arbetsloggen:
|
||||
|
||||
```
|
||||
08:14 "Mätt spänning mellan stift 14 och jord. 12,4 volt."
|
||||
08:14 AI: Matningsspänning verifierad.
|
||||
08:15 "Relä klickar inte."
|
||||
08:15 AI: Kontrollera styrsignal till relä.
|
||||
```
|
||||
|
||||
Allt sparas utan att teknikern behöver skriva en enda rad.
|
||||
|
||||
## Handsfree-arbete
|
||||
|
||||
Appen är optimerad för upptagna eller smutsiga händer. Under ett normalt ärende ska användaren kunna identifiera objektet med kameran, fotografera komponenter, diktera observationer, få nästa steg presenterat och fortsätta arbetet — utan att skriva manuellt. Gränssnittet ska fungera med handskar, smutsiga händer, starkt solljus, buller och vibrationer; mikrofonknappen är stor, lätt att träffa och har tydlig visuell återkoppling.
|
||||
@@ -0,0 +1,25 @@
|
||||
# Modul: Delningsbar kundrapport (Kundvy)
|
||||
|
||||
## Syfte
|
||||
|
||||
I stället för att kunden får en rad på fakturan som säger ”Felsökning – 2,5 timmar” kan de få en tydlig tidslinje över vad som faktiskt utförts.
|
||||
|
||||
Exempel:
|
||||
|
||||
```
|
||||
08:03 Fordonet identifierat
|
||||
08:10 Felbeskrivning registrerad
|
||||
08:18 Däck dokumenterade
|
||||
08:26 Visuell kontroll genomförd
|
||||
08:42 Lufttryck verifierat
|
||||
08:57 Provkörning utförd
|
||||
09:18 Slutsats och rekommendation dokumenterad
|
||||
```
|
||||
|
||||
Med bilder, mätvärden och kommentarer blir det tydligt vad kunden faktiskt har betalat för. Det stärker förtroendet och kan minska diskussioner om felsökningstid.
|
||||
|
||||
---
|
||||
|
||||
## Relation till övriga moduler
|
||||
|
||||
Kundrapporten är en härledd vy av samma händelselogg som [Arbetslogg & Tidredovisning](arbetslogg-och-tidredovisning.md) bygger på – ingen separat dokumentation behöver skapas. Verkstaden väljer vilken detaljnivå som delas med kund, i linje med den rollbaserade behörighetsstyrningen.
|
||||
@@ -0,0 +1,72 @@
|
||||
# Modul: Live Share
|
||||
|
||||
## Syfte
|
||||
|
||||
Varje ärende kan publiceras via en unik säker delningslänk. Länken visar ärendets aktuella status i realtid och uppdateras automatiskt när ny information registreras. Ingen manuell export behövs.
|
||||
|
||||
En livevy ger stort värde för kunder, arbetsledare, försäkringsbolag och tillverkare — men den ska **alltid vara under verkstadens kontroll**, med tydliga behörigheter och säkerhetsnivåer.
|
||||
|
||||
## Exempel på kundvy
|
||||
|
||||
```
|
||||
Ärende: Volvo XC60
|
||||
Status: 🟢 Felsökning pågår
|
||||
|
||||
Kundens felbeskrivning
|
||||
Bilen vibrerar vid cirka 88 km/h.
|
||||
|
||||
Aktuell status
|
||||
✔ Objekt identifierat
|
||||
✔ Provkörning utförd
|
||||
✔ Däck dokumenterade
|
||||
✔ Lufttryck kontrollerat
|
||||
🔄 Hjulbalansering kontrolleras
|
||||
⏳ Drivaxlar ej kontrollerade
|
||||
|
||||
Bilder · Mätvärden · Tidslinje
|
||||
|
||||
Rekommenderat nästa steg
|
||||
Kontroll av radialkast.
|
||||
```
|
||||
|
||||
## Liveuppdatering
|
||||
|
||||
När teknikern arbetar uppdateras sidan automatiskt, utan omladdning. Mottagaren ser direkt nya bilder, nya mätvärden, nya kommentarer och statusändringar.
|
||||
|
||||
## Behörighetsnivåer
|
||||
|
||||
Länkar kan skapas med olika åtkomstnivåer:
|
||||
|
||||
- **Kund** – läsbehörighet till den information verkstaden valt att dela.
|
||||
- **Intern** – full insyn för kollegor och arbetsledare.
|
||||
- **Extern partner** – exempelvis försäkringsbolag eller tillverkare, med avgränsad information (inklusive hypoteser, tydligt märkta som ej verifierade).
|
||||
|
||||
Implementerat i plattformen: varje länk skapas med en nivå, filtreringen sker på serversidan och länkar kan återkallas — en återkallad länk ger 404.
|
||||
|
||||
## Export
|
||||
|
||||
Från samma ärende ska det gå att exportera:
|
||||
|
||||
- PDF
|
||||
- JSON
|
||||
- CSV
|
||||
- API
|
||||
- Utskriftsvänlig HTML
|
||||
|
||||
Alla exporter bygger på samma datakälla (händelseloggen), vilket minskar risken för avvikelser.
|
||||
|
||||
## Versionshantering
|
||||
|
||||
Varje export märks med:
|
||||
|
||||
- versionsnummer,
|
||||
- datum,
|
||||
- tid,
|
||||
- vem som exporterade,
|
||||
- exportformat.
|
||||
|
||||
Det gör det möjligt att i efterhand se exakt vilken information som delades vid en viss tidpunkt.
|
||||
|
||||
## Produktvision
|
||||
|
||||
Ett felsökningsärende är inte bara en chatt eller en logg, utan en **levande digital arbetsjournal**. Den kan följas i realtid, tas över av en kollega, granskas av en arbetsledare, delas med kunden och avslutas med en komplett rapport — allt från samma datamodell. Det minskar dubbelarbete och gör att alla parter utgår från samma aktuella information.
|
||||
@@ -0,0 +1,101 @@
|
||||
# Märkesspecifika kopplingar
|
||||
|
||||
Verkstaden har redan sina avtal. Volvo-verkstaden har VIDA, VAG-verkstaden
|
||||
har erWin, den fria verkstaden har en fordonsdataleverantör. Ingen av dem
|
||||
vill att vi ska vara mellanhand för deras abonnemang — och ingen av dem
|
||||
har samma uppsättning som grannen.
|
||||
|
||||
Därför konfigurerar **kunden själv** sina kopplingar under
|
||||
**Inställningar → Märkesspecifika kopplingar**, med sina egna credentials.
|
||||
Vi tillhandahåller ramen, inte kontot.
|
||||
|
||||
## Principer
|
||||
|
||||
**Uppgifterna når aldrig webbläsaren.** Samma regel som för
|
||||
plattformens egna API-nycklar: hemligheter bor på servern. Credentials
|
||||
krypteras med AES-256-GCM innan de skrivs till databasen, och API:t
|
||||
returnerar hemliga fält maskerade (`••••3456`). Klienten kan se *att* en
|
||||
koppling finns och när den senast fungerade — aldrig vad nyckeln är.
|
||||
|
||||
**Alla uppslag görs av servern.** Klienten skickar en identifierare
|
||||
(VIN eller regnr); servern hämtar uppgifterna, dekrypterar dem i minnet,
|
||||
anropar leverantören och returnerar bara de mappade fordonsfälten.
|
||||
|
||||
**Fail closed.** Saknas krypteringsnyckeln (`INTEGRATION_NYCKEL`) sparas
|
||||
ingenting — API:t svarar 503 och inställningssidan förklarar varför.
|
||||
Alternativet, att lagra i klartext "så länge", finns inte.
|
||||
|
||||
**Endast systemadministratören.** Att lägga till, ändra och ta bort
|
||||
kopplingar kräver rollen `admin`. Teknikern kan läsa registret över
|
||||
tillgängliga leverantörer (annars kan inställningssidan inte visa dem)
|
||||
men aldrig någon organisations uppgifter.
|
||||
|
||||
**Organisationsknutet.** Kopplingarna hör till organisationen, precis
|
||||
som ärendedata. Ingen tenant ser en annans.
|
||||
|
||||
## Leverantörer är data, inte kod
|
||||
|
||||
Registret ligger i `services/plattform/integrationer.json` och kan bytas
|
||||
mot en ConfigMap-mount via `INTEGRATIONER_FIL`. En leverantör beskrivs
|
||||
helt deklarativt:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "volvo_vida",
|
||||
"namn": "Volvo VIDA",
|
||||
"falt": [
|
||||
{ "nyckel": "bas_url", "etikett": "Bas-URL (använd {vin} som platshållare)", "hemlig": false },
|
||||
{ "nyckel": "api_nyckel", "etikett": "API-nyckel", "hemlig": true }
|
||||
],
|
||||
"uppslag": {
|
||||
"urlFalt": "bas_url",
|
||||
"auth": "header",
|
||||
"authHeader": "X-Api-Key",
|
||||
"authFalt": "api_nyckel",
|
||||
"svarsfalt": { "marke": "make", "modell": "model", "arsmodell": "year" }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
* `falt` — vad administratören ska fylla i. `hemlig: true` styr både
|
||||
kryptering och maskering.
|
||||
* `uppslag.auth` — `bearer`, `header`, `basic` eller `query`. Inga
|
||||
leverantörsspecifika kodgrenar; all variation ligger i registret.
|
||||
* `svarsfalt` — mappning från leverantörens JSON (punktnotation stöds)
|
||||
till våra fordonsfält.
|
||||
* `nyckeltyp: "regnr"` — uppslaget sker på registreringsnummer i stället
|
||||
för VIN. `{vin}`/`{regnr}` i URL-mallen ersätts URL-kodat.
|
||||
|
||||
Ett nytt märke läggs alltså till genom att beskriva det — inte genom att
|
||||
bygga om applikationen.
|
||||
|
||||
## Vad ett uppslag gör och inte gör
|
||||
|
||||
Uppslaget fyller i **fordonsbeskrivningen** (märke, modell, årsmodell,
|
||||
motor, växellåda). Det är kontextdata, inte evidens: ett svar från en
|
||||
leverantör är aldrig en utförd kontroll och räknas inte i
|
||||
[evidensmotorn](evidensmotor.md). Returnerar leverantören inga kända fält
|
||||
säger systemet det rakt ut i stället för att visa tomma rader.
|
||||
|
||||
Varje uppslag skriver `senast_testad` och `senaste_status` på
|
||||
kopplingen. Ett utgånget abonnemang syns därför i inställningarna som ett
|
||||
felmeddelande från leverantören, inte som tysta tomma svar.
|
||||
|
||||
## API
|
||||
|
||||
| Väg | Metod | Roll | Vad |
|
||||
| --- | --- | --- | --- |
|
||||
| `/api/integrationer/leverantorer` | GET | inloggad | Registret (fältdefinitioner, inga uppgifter) |
|
||||
| `/api/integrationer` | GET | admin | Organisationens kopplingar, hemligheter maskerade |
|
||||
| `/api/integrationer` | POST | admin | Spara/uppdatera credentials (krypteras) |
|
||||
| `/api/integrationer/{leverantor}` | DELETE | admin | Ta bort |
|
||||
| `/api/integrationer/{leverantor}/uppslag` | POST | inloggad | Slå upp VIN/regnr via servern |
|
||||
|
||||
Fullständigt dokumenterat i `services/plattform/openapi.yaml`.
|
||||
|
||||
## Drift
|
||||
|
||||
`INTEGRATION_NYCKEL` är 32 byte hex eller base64 (`openssl rand -hex 32`),
|
||||
levererad via secret:en `felsokning-hemligheter` — se
|
||||
[DRIFT.md](../DRIFT.md). Byts nyckeln måste kopplingarna sparas om;
|
||||
tjänsten visar då inga värden i stället för att gissa.
|
||||
@@ -0,0 +1,73 @@
|
||||
# Modul: Verifierade checklistor
|
||||
|
||||
## Grundprincip
|
||||
|
||||
En kontrollpunkt är inte slutförd enbart genom att kryssa i en ruta.
|
||||
|
||||
Systemet registrerar inte bara *att* en ruta har kryssats i — det samlar in **bevis och kontext**. Varje kontroll ska innehålla ett eller flera av följande:
|
||||
|
||||
- ✔ Bekräftelse att kontrollen är utförd.
|
||||
- 📝 Kort observation eller slutsats.
|
||||
- 📷 Foto (när det är relevant).
|
||||
- 📹 Video (vid behov).
|
||||
- 🎤 Tal-till-text (för snabb dokumentation).
|
||||
- 📏 Mätvärde (när tillämpligt).
|
||||
|
||||
På så sätt blir varje moment både spårbart och begripligt.
|
||||
|
||||
## Exempel
|
||||
|
||||
**Kontrollera batterispänning**
|
||||
|
||||
> Teknikern markerar "Utförd".
|
||||
> Systemet: *Vilket värde uppmättes?* → **12,63 V**
|
||||
> Systemet: *Hur mättes detta? (valfritt)* → **Direkt på batteripolerna.**
|
||||
> Kontrollpunkten markeras som verifierad.
|
||||
|
||||
**Kontrollera säkring F24**
|
||||
|
||||
> ✔ Utförd
|
||||
> Systemet: *Vad observerades?* → **Säkringen är hel och spänning finns på båda sidor.**
|
||||
> Kontrollpunkten avslutas.
|
||||
|
||||
## AI:s roll
|
||||
|
||||
AI:n hjälper till att upptäcka när dokumentationen verkar ofullständig:
|
||||
|
||||
> "Du har markerat att hjulbalanseringen är kontrollerad, men ingen observation eller mätning har registrerats. Vill du lägga till en kort kommentar innan du går vidare?"
|
||||
|
||||
Det ska vara ett **stöd, inte ett hinder**.
|
||||
|
||||
## Anpassning efter kontrolltyp
|
||||
|
||||
Alla moment behöver inte samma nivå av dokumentation.
|
||||
|
||||
| Kontrolltyp | Minimikrav |
|
||||
| --- | --- |
|
||||
| Visuell kontroll | Bekräftelse + kort kommentar |
|
||||
| Mätning | Mätvärde + kommentar |
|
||||
| Demontering | Kommentar, foto vid behov |
|
||||
| Provkörning | Sammanfattning av resultat |
|
||||
| Bildbaserad kontroll | Foto + observation |
|
||||
|
||||
## Syfte
|
||||
|
||||
Målet är inte att "fånga" teknikern, utan att skapa ett arbetsunderlag som visar:
|
||||
|
||||
- vad som kontrollerades,
|
||||
- hur det kontrollerades,
|
||||
- vad resultatet blev,
|
||||
- och vilka slutsatser som är rimliga att dra.
|
||||
|
||||
Det stärker kvaliteten i arbetet, gör överlämningar enklare och ger ett bättre underlag gentemot kund och arbetsledning.
|
||||
|
||||
## Viktig designprincip
|
||||
|
||||
Undvik att göra fritext obligatorisk överallt. Om varje kontroll kräver långa texter upplevs systemet snabbt som tungrott. Använd i stället en kombination av:
|
||||
|
||||
- förvalda svar där det passar,
|
||||
- kort tal-till-text för observationer,
|
||||
- mätvärdesfält,
|
||||
- och foto eller video när det ger mest värde.
|
||||
|
||||
Då blir dokumentationen rik utan att arbetsflödet bromsas — och teknikerna använder systemet konsekvent i vardagen.
|
||||
Reference in New Issue
Block a user