Moduldokumenten på engelska som källa
De åtta moduldokumenten och exempelflödet får engelska versioner. Kataloger och filnamn följer med: moduler/ → modules/, exempel/ → examples/, och de svenska filnamnen ersätts av engelska. Ett engelskt dokument i moduler/arendebrief.md hade varit inkonsekvent. Bytet gjordes med git mv så historiken följer med, och interna länkar i de svenska versionerna pekar nu på svenska syskon i stället för på filnamn som inte längre finns. Kodidentifierare och JSON-exempel står oöversatta även i de engelska versionerna — falt, hemlig, uppslag och svarsfalt är fältnamn i integrationer.json, inte prosa. 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,104 @@
|
||||
# Brand-specific integrations
|
||||
|
||||
> Canonical version. Swedish: [brand-integrations.sv.md](brand-integrations.sv.md).
|
||||
> Code identifiers are Swedish and appear verbatim.
|
||||
|
||||
The workshop already has its contracts. The Volvo workshop has VIDA, the VAG
|
||||
workshop has erWin, the independent workshop has a vehicle-data vendor. None of
|
||||
them wants us to be the middleman for their subscription — and none of them has
|
||||
the same set as the workshop next door.
|
||||
|
||||
That is why **the customer configures their own integrations** under
|
||||
**Settings → Brand-specific integrations**, with their own credentials. We
|
||||
provide the frame, not the account.
|
||||
|
||||
## Principles
|
||||
|
||||
**The credentials never reach the browser.** The same rule as for the
|
||||
platform's own API keys: secrets live on the server. Credentials are encrypted
|
||||
with AES-256-GCM before being written to the database, and the API returns
|
||||
secret fields masked (`••••3456`). The client can see *that* an integration
|
||||
exists and when it last worked — never what the key is.
|
||||
|
||||
**All lookups are performed by the server.** The client sends an identifier
|
||||
(VIN or registration number); the server fetches the credentials, decrypts them
|
||||
in memory, calls the vendor and returns only the mapped vehicle fields.
|
||||
|
||||
**Fail closed.** If the encryption key (`INTEGRATION_NYCKEL`) is missing,
|
||||
nothing is saved — the API answers 503 and the settings page explains why. The
|
||||
alternative, storing in plaintext "for now", does not exist.
|
||||
|
||||
**System administrator only.** Adding, changing and removing integrations
|
||||
requires the `admin` role. A technician can read the register of available
|
||||
vendors (otherwise the settings page cannot show them) but never any
|
||||
organisation's credentials.
|
||||
|
||||
**Organisation-scoped.** Integrations belong to the organisation, just like case
|
||||
data. No tenant sees another's.
|
||||
|
||||
## Vendors are data, not code
|
||||
|
||||
The register lives in `services/plattform/integrationer.json` and can be swapped
|
||||
for a ConfigMap mount via `INTEGRATIONER_FIL`. A vendor is described entirely
|
||||
declaratively:
|
||||
|
||||
```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` (fields) — what the administrator has to fill in. `hemlig: true`
|
||||
(secret) governs both encryption and masking.
|
||||
* `uppslag.auth` (lookup auth) — `bearer`, `header`, `basic` or `query`. No
|
||||
vendor-specific code branches; all variation lives in the register.
|
||||
* `svarsfalt` (response fields) — mapping from the vendor's JSON (dot notation
|
||||
supported) to our vehicle fields.
|
||||
* `nyckeltyp: "regnr"` — the lookup is done on registration number instead of
|
||||
VIN. `{vin}` / `{regnr}` in the URL template are substituted URL-encoded.
|
||||
|
||||
A new brand is therefore added by describing it — not by rebuilding the
|
||||
application.
|
||||
|
||||
## What a lookup does and does not do
|
||||
|
||||
The lookup fills in the **vehicle description** (make, model, year, engine,
|
||||
transmission). That is context data, not evidence: an answer from a vendor is
|
||||
never a performed check and does not count in the
|
||||
[evidence engine](evidence-engine.md). If the vendor returns no known fields,
|
||||
the system says so plainly instead of showing empty rows.
|
||||
|
||||
Every lookup writes `senast_testad` (last tested) and `senaste_status` (last
|
||||
status) on the integration. An expired subscription therefore shows up in
|
||||
settings as an error message from the vendor, not as silently empty answers.
|
||||
|
||||
## API
|
||||
|
||||
| Route | Method | Role | What |
|
||||
| --- | --- | --- | --- |
|
||||
| `/api/integrationer/leverantorer` | GET | logged in | The register (field definitions, no credentials) |
|
||||
| `/api/integrationer` | GET | admin | The organisation's integrations, secrets masked |
|
||||
| `/api/integrationer` | POST | admin | Save/update credentials (encrypted) |
|
||||
| `/api/integrationer/{leverantor}` | DELETE | admin | Remove |
|
||||
| `/api/integrationer/{leverantor}/uppslag` | POST | logged in | Look up VIN/registration via the server |
|
||||
|
||||
Fully documented in `services/plattform/openapi.yaml`.
|
||||
|
||||
## Operations
|
||||
|
||||
`INTEGRATION_NYCKEL` is 32 bytes of hex or base64 (`openssl rand -hex 32`),
|
||||
delivered via the secret `felsokning-hemligheter` — see
|
||||
[OPERATIONS.md](../OPERATIONS.md). If the key is rotated, the integrations must
|
||||
be saved again; the service then shows no values rather than guessing.
|
||||
@@ -0,0 +1,104 @@
|
||||
# Märkesspecifika kopplingar
|
||||
|
||||
> **Svensk översättning.** Källan är [brand-integrations.md](brand-integrations.md) (engelska).
|
||||
> Vid avvikelse gäller det engelska dokumentet.
|
||||
|
||||
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](evidence-engine.sv.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,154 @@
|
||||
# Module: The case brief
|
||||
|
||||
> Canonical version. Swedish: [case-brief.sv.md](case-brief.sv.md).
|
||||
|
||||
## Purpose
|
||||
|
||||
When a new technician takes over an ongoing case, they should become productive
|
||||
in under a minute, without having to read the whole history.
|
||||
|
||||
The system automatically generates a structured summary of the case, updated
|
||||
continuously.
|
||||
|
||||
This is not a chat but a **living case** in which the system maintains an
|
||||
up-to-date working picture at all times.
|
||||
|
||||
---
|
||||
|
||||
## Example
|
||||
|
||||
**Object**
|
||||
|
||||
> Volvo XC60 D4 2019
|
||||
> Registration ABC123
|
||||
> Customer: Anders Svensson
|
||||
|
||||
**Customer's description**
|
||||
|
||||
> The car vibrates at around 88 km/h.
|
||||
> The symptom occurs only while driving.
|
||||
|
||||
**Checks performed**
|
||||
|
||||
- ✓ Tyre pressure checked
|
||||
- ✓ Wheel torque checked
|
||||
- ✓ DOT codes documented
|
||||
- ✓ Four wheels photographed
|
||||
- ✓ Road test carried out
|
||||
- ✓ Balance weights checked
|
||||
|
||||
**Observations**
|
||||
|
||||
- The right front tyre shows uneven wear.
|
||||
- No obvious damage to the rims.
|
||||
- The vibration is felt mainly in the steering wheel.
|
||||
- No change under acceleration.
|
||||
|
||||
**Not checked**
|
||||
|
||||
- Radial runout
|
||||
- Driveshafts
|
||||
- Wheel bearings
|
||||
- Four-wheel alignment
|
||||
|
||||
**Recommended next step**
|
||||
|
||||
1. Measure radial runout.
|
||||
2. Check the driveshafts.
|
||||
3. New road test.
|
||||
|
||||
**Total working time**
|
||||
|
||||
2 hours 14 minutes
|
||||
|
||||
**Reliability**
|
||||
|
||||
- 🟢 Customer details verified
|
||||
- 🟢 Images documented
|
||||
- 🟢 Measured values recorded
|
||||
- 🟡 Root cause not yet verified
|
||||
|
||||
---
|
||||
|
||||
## The role of the analysis
|
||||
|
||||
The system should not merely summarise the history but also keep track of the
|
||||
case's current position. When a new technician joins, it should be able to
|
||||
answer questions such as:
|
||||
|
||||
- "What is left?"
|
||||
- "What is most likely worth checking next?"
|
||||
- "Which tests have already been performed?"
|
||||
- "Are there any contradictory observations?"
|
||||
- "What needs verifying before we go further?"
|
||||
|
||||
---
|
||||
|
||||
## Collaboration
|
||||
|
||||
This is built as a genuine multi-user system. Each case becomes a workspace in
|
||||
which several people can take part.
|
||||
|
||||
Example:
|
||||
|
||||
```
|
||||
Case #45281
|
||||
Responsible: Anna
|
||||
Participants: Johan, Erik, Lisa
|
||||
```
|
||||
|
||||
- Everyone sees the same information in real time.
|
||||
- All images end up in the same case.
|
||||
- All measured values end up in the same log.
|
||||
- All comments are timestamped.
|
||||
- All generated summaries update automatically.
|
||||
|
||||
---
|
||||
|
||||
## Shift change — handover in one click
|
||||
|
||||
At shift change the technician simply presses **Hand over work**. The system
|
||||
then generates a handover report automatically.
|
||||
|
||||
The incoming technician receives:
|
||||
|
||||
- what the customer experiences,
|
||||
- what has already been done,
|
||||
- which measurements exist,
|
||||
- which images have been taken,
|
||||
- which conclusions can be drawn with high confidence,
|
||||
- which questions remain unanswered,
|
||||
- the recommended next step.
|
||||
|
||||
Nobody has to read through hundreds of chat messages.
|
||||
|
||||
The same function is used for escalation: when a technician leaves their shift
|
||||
or escalates a case, a short briefing is generated automatically containing:
|
||||
|
||||
- current position,
|
||||
- verified facts,
|
||||
- remaining work,
|
||||
- risks or uncertainties,
|
||||
- recommended next steps.
|
||||
|
||||
This lets the next technician carry on almost immediately, which is especially
|
||||
valuable in larger workshops and service organisations where several people work
|
||||
on the same object across different shifts.
|
||||
|
||||
---
|
||||
|
||||
## Architecture
|
||||
|
||||
The module fits a multi-tenant SaaS architecture well:
|
||||
|
||||
- **Tenant** = workshop or service organisation.
|
||||
- **User** = technician, supervisor, workshop manager, administrator.
|
||||
- **Case** = a shared workspace with common context.
|
||||
- **Model context** = a structured, continuously maintained summary of the case,
|
||||
used for briefing and guidance.
|
||||
|
||||
The last point matters: the model should not have to read the entire history
|
||||
every time someone opens a case. Instead a structured case summary is
|
||||
maintained and updated after every relevant event. That makes the system faster,
|
||||
cheaper to run and more consistent, while the full log still remains for audit
|
||||
and export.
|
||||
@@ -0,0 +1,140 @@
|
||||
# Modul: Ärendebrief
|
||||
|
||||
> **Svensk översättning.** Källan är [case-brief.md](case-brief.md) (engelska).
|
||||
> Vid avvikelse gäller det engelska dokumentet.
|
||||
|
||||
## 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,106 @@
|
||||
# Module: Communication model (voice)
|
||||
|
||||
> Canonical version. Swedish: [communication-model.sv.md](communication-model.sv.md).
|
||||
|
||||
## Core principle
|
||||
|
||||
**The user speaks, the system writes.**
|
||||
|
||||
The system uses voice-to-text for all spoken input. The technician should never
|
||||
have to type on a keyboard while work is in progress.
|
||||
|
||||
No voice agent: the system does not hold a running spoken conversation, does not
|
||||
read long answers aloud, and does not try to imitate a human conversation. The
|
||||
communication is **speech in, text out**.
|
||||
|
||||
## Important design principle
|
||||
|
||||
> All voice is treated as an input method, not as a separate interface.
|
||||
|
||||
All logic in the system is built on text. Voice-to-text is only a way of
|
||||
producing that text. That makes the solution easier to maintain, easier to
|
||||
search, easier to export, and easier to develop further with new models in the
|
||||
future.
|
||||
|
||||
## Workflow
|
||||
|
||||
1. The technician presses the microphone: *"I've measured between pin 14 and
|
||||
ground. I get 12.4 volts."*
|
||||
2. Voice-to-text transcribes the speech.
|
||||
3. The transcribed text is sent to the model as an ordinary text request.
|
||||
4. The answer always comes back in writing: *Verified: supply voltage present at
|
||||
pin 14. Next step: check the ground connection at pin 7.*
|
||||
|
||||
## Why this choice?
|
||||
|
||||
- it works better in noisy workshops,
|
||||
- it produces a permanent text log with no extra step,
|
||||
- it makes the history easy to search,
|
||||
- it reduces the risk of misunderstanding compared with a continuous spoken
|
||||
conversation,
|
||||
- it suits cases where several technicians work on the same job.
|
||||
|
||||
## Push-to-talk (PTT)
|
||||
|
||||
Voice input works on a push-to-talk basis. The app listens **only** while the
|
||||
user actively holds the microphone button, or after they have started an
|
||||
explicit recording. No background listening. No automatic activation.
|
||||
|
||||
### Flow
|
||||
|
||||
1. The user holds down the microphone button (or presses a clear "Record"
|
||||
button, depending on the platform).
|
||||
2. Recording starts immediately.
|
||||
3. The app shows clearly that recording is in progress: a red indicator, a
|
||||
timer, a level meter, and the text "Recording".
|
||||
4. The speech is transcribed in real time — the user watches the text appear and
|
||||
gets immediate feedback on whether the speech was understood correctly.
|
||||
5. When the recording ends, the transcribed text is shown in an **editable**
|
||||
text field.
|
||||
6. The user can accept, edit or re-record.
|
||||
7. **Only when the user confirms** is the text sent onward and saved to the work
|
||||
log.
|
||||
|
||||
### Editing before sending
|
||||
|
||||
The transcription is always editable. Common corrections: registration numbers,
|
||||
serial numbers, component designations, personal names, technical terms.
|
||||
|
||||
**"Send" never happens automatically.** The technician always gets a quick
|
||||
chance to correct the transcription before it becomes part of the permanent work
|
||||
log. That reduces the risk of incorrect registration numbers, component
|
||||
designations and measured values.
|
||||
|
||||
### No hidden functionality
|
||||
|
||||
The user must always be able to see:
|
||||
|
||||
- when recording is in progress,
|
||||
- when it has ended,
|
||||
- what will be sent,
|
||||
- what has actually been saved.
|
||||
|
||||
There must never be any doubt about when audio is being recorded or when
|
||||
information is being sent.
|
||||
|
||||
## Automatic record keeping
|
||||
|
||||
Every transcribed sentence automatically becomes part of the work log:
|
||||
|
||||
```
|
||||
08:14 "Measured voltage between pin 14 and ground. 12.4 volts."
|
||||
08:14 System: Supply voltage verified.
|
||||
08:15 "Relay doesn't click."
|
||||
08:15 System: Check the control signal to the relay.
|
||||
```
|
||||
|
||||
Everything is saved without the technician having to type a single line.
|
||||
|
||||
## Hands-free working
|
||||
|
||||
The app is optimised for busy or dirty hands. During a normal case the user
|
||||
should be able to identify the object with the camera, photograph components,
|
||||
dictate observations, be shown the next step and carry on working — without
|
||||
typing manually. The interface has to work with gloves, dirty hands, strong
|
||||
sunlight, noise and vibration; the microphone button is large, easy to hit and
|
||||
gives clear visual feedback.
|
||||
@@ -0,0 +1,81 @@
|
||||
# Modul: Kommunikationsmodell (röst)
|
||||
|
||||
> **Svensk översättning.** Källan är [communication-model.md](communication-model.md) (engelska).
|
||||
> Vid avvikelse gäller det engelska dokumentet.
|
||||
|
||||
## 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,34 @@
|
||||
# Module: Shareable customer report (customer view)
|
||||
|
||||
> Canonical version. Swedish: [customer-report.sv.md](customer-report.sv.md).
|
||||
|
||||
## Purpose
|
||||
|
||||
Instead of the customer receiving a line on the invoice reading "Diagnosis —
|
||||
2.5 hours", they can be given a clear timeline of what was actually done.
|
||||
|
||||
Example:
|
||||
|
||||
```
|
||||
08:03 Vehicle identified
|
||||
08:10 Fault description recorded
|
||||
08:18 Tyres documented
|
||||
08:26 Visual check completed
|
||||
08:42 Tyre pressure verified
|
||||
08:57 Road test carried out
|
||||
09:18 Conclusion and recommendation documented
|
||||
```
|
||||
|
||||
With images, measured values and comments it becomes clear what the customer has
|
||||
actually paid for. That strengthens trust and can reduce arguments about
|
||||
diagnostic time.
|
||||
|
||||
---
|
||||
|
||||
## Relationship to the other modules
|
||||
|
||||
The customer report is a derived view of the same event log that
|
||||
[Work log and time tracking](work-log-and-time-tracking.md) builds on — no
|
||||
separate documentation has to be created. The workshop chooses what level of
|
||||
detail is shared with the customer, in line with the role-based permission
|
||||
model.
|
||||
@@ -0,0 +1,28 @@
|
||||
# Modul: Delningsbar kundrapport (Kundvy)
|
||||
|
||||
> **Svensk översättning.** Källan är [customer-report.md](customer-report.md) (engelska).
|
||||
> Vid avvikelse gäller det engelska dokumentet.
|
||||
|
||||
## 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](work-log-and-time-tracking.sv.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,251 @@
|
||||
# Module: The Evidence Engine (ECM — Evidence & Compliance Matrix)
|
||||
|
||||
> Canonical version. Swedish: [evidence-engine.sv.md](evidence-engine.sv.md).
|
||||
> Code identifiers are Swedish and appear verbatim.
|
||||
|
||||
**Version: ECM v2.0** · ECM is its own subsystem — not a table in the database
|
||||
— and the engine that governs the whole platform: it decides what documentation
|
||||
is required, when documentation is missing, what level of evidence has been
|
||||
reached, which rules apply, and whether a case may be closed.
|
||||
**The system can never write a conclusion that ECM has not approved.**
|
||||
|
||||
The rule library is versioned and separate from the application logic
|
||||
(`src/felsokning/ecm.ts`); the views only call the engine's pure functions.
|
||||
|
||||
## The six engines
|
||||
|
||||
### 1. Evidence Engine
|
||||
|
||||
Catalogues all evidence from the event log. Each evidence entry receives an id,
|
||||
timestamp, technician, category, evidence level, summary and a **content hash**
|
||||
— the same entry always yields the same hash, and the append-only log (database
|
||||
triggers) makes every attempt at alteration impossible.
|
||||
|
||||
| Level | Type | Probative value |
|
||||
| --- | --- | --- |
|
||||
| E0 | No supporting evidence | 0 % |
|
||||
| E1 | Technician's observation | Low |
|
||||
| E2 | Photo | Medium |
|
||||
| E3 | Video (with sound — for what makes noise or moves) | High |
|
||||
| E4 | Measured value | High |
|
||||
| E5 | Diagnostic data / document | Very high |
|
||||
| E6 | Multiple independent sources | Highest |
|
||||
|
||||
### 2. Rule Engine
|
||||
|
||||
The documentation requirements: the methodology's `krav` field per check, plus
|
||||
the automatic rules — *can it be photographed → require a photo; does it make
|
||||
noise → video with sound; does it move → video; is it measured → a measured
|
||||
value; does a display show the information → photograph the display; does a
|
||||
document exist → photograph the document.* The exemption reasons ("supporting
|
||||
evidence cannot be obtained") live here.
|
||||
|
||||
### 3. Compliance Engine
|
||||
|
||||
The case type determines which rules apply on top of the methodology. The case
|
||||
type is chosen in the identity row and logged (`arendetyp_satt`):
|
||||
|
||||
| Case type | Additional requirements (v2.0) |
|
||||
| --- | --- |
|
||||
| Warranty | Odometer documented · service history checked · claim/warranty number |
|
||||
| Goodwill | Odometer · service history |
|
||||
| Insurance | Claim reference · photographic evidence |
|
||||
| Complaint | History and previous attempts checked |
|
||||
| Used-vehicle warranty | Odometer |
|
||||
|
||||
**The ECM Knowledge Library is implemented**: the rules are declarative data
|
||||
(requirement type, not code) and are distributed from the platform via
|
||||
`GET /api/ecm/regler` (`services/plattform/ecm-regler.json` — replaceable in the
|
||||
cluster via a ConfigMap and the environment variable `ECM_REGLER_FIL`). The
|
||||
client fetches the pack on page load, caches it, and falls back to its built-in
|
||||
default pack when offline; broken packs and unknown requirement types are
|
||||
filtered out. The rule pack's version travels with every traceability package.
|
||||
New rules — warranty terms per manufacturer, insurers' requirements, consumer
|
||||
complaint legislation, OEM checkpoints — are added in operations without
|
||||
rebuilding the application.
|
||||
|
||||
### 4. Validation Engine
|
||||
|
||||
No claims without support, in three layers: (a) the orchestrator's base prompt —
|
||||
never "OK / checked / no faults / repaired" without evidence, instead "Evidens
|
||||
saknas" (evidence missing) plus a request for the right documentation; (b) the
|
||||
projections — hypotheses can never become confirmed faults; (c) the quality gate
|
||||
below.
|
||||
|
||||
### 5. Completion Engine
|
||||
|
||||
The quality gate before the final report and closing — printing is blocked until
|
||||
every mandatory row is green:
|
||||
|
||||
| Check | Requirement |
|
||||
| --- | --- |
|
||||
| Vehicle/object identification verified | Mandatory |
|
||||
| Work order read in | Recommended |
|
||||
| Vehicle history checked or justified | Mandatory |
|
||||
| Incoming odometer reading documented | Mandatory |
|
||||
| Customer's fault description verified | Recommended |
|
||||
| Customer's decision on the repair proposal | Mandatory when work has been performed |
|
||||
| Repair documented or justified | Mandatory on closing |
|
||||
| Quality check performed | Mandatory on closing after a repair |
|
||||
| Outgoing odometer reading | Mandatory on closing |
|
||||
| Methodology checks: evidence or documented exemption | Mandatory |
|
||||
| Photos for photo-requiring checks | Mandatory |
|
||||
| The case type's compliance requirements | Mandatory |
|
||||
| Technician's conclusion signed | Automatic on closing |
|
||||
| Evidence level above E0 | Mandatory |
|
||||
|
||||
### 6. Traceability Engine
|
||||
|
||||
Every export carries a traceability package: ECM version, case type, evidence
|
||||
level, gate status per rule id, and all evidence entries with their hashes.
|
||||
Together with the log, every conclusion can be traced: which image → which
|
||||
measurement → which technician → which rule → which rule-set version → when.
|
||||
|
||||
## Pre-Diagnostic Validation
|
||||
|
||||
No diagnosis begins until the basic checks are performed or documented as
|
||||
justified — the methodology unlocks only afterwards:
|
||||
|
||||
1. **Vehicle history** — the system automatically retrieves the organisation's
|
||||
earlier cases on the same object (registration/VIN) together with their
|
||||
documented root causes (`GET /api/fordon/{identifierare}/historik`; the local
|
||||
store when offline) and shows them in the history step. The technician can
|
||||
link the **causal chain** to the current case with one tap ("linked to
|
||||
earlier case #N — …"), acknowledge the check — or answer No with a mandatory
|
||||
reason → quality warning.
|
||||
2. **Incoming odometer reading** — the instrument cluster is photographed; the
|
||||
image interpretation proposes the value and the technician confirms it. The
|
||||
photo becomes the official incoming reading.
|
||||
3. **Customer's fault description verified** — additional symptoms are
|
||||
documented as separate observations, never mixed in with the customer's
|
||||
description.
|
||||
4. **Early observations** — traces of previous repair, modifications, damage,
|
||||
leakage and so on are documented with a photo or observation, or acknowledged
|
||||
as "none further".
|
||||
|
||||
The **outgoing odometer reading** is photographed before closing and becomes
|
||||
mandatory in the gate when the case is closed. The report shows in and out.
|
||||
|
||||
## Symptom Verification Protocol (SVP)
|
||||
|
||||
A fault is never diagnosed straight from a vague customer description. The chain
|
||||
is always: **documented → clarified → reproduced, or documented as not
|
||||
reproducible.**
|
||||
|
||||
- The customer's description is recorded verbatim at case start and verified in
|
||||
pre-diagnostics; new symptoms become separate observations.
|
||||
- Clarification happens through the methodology's symptom questions (when /
|
||||
where / how / conditions / frequency — the generic methodology carries the
|
||||
full SVP question set).
|
||||
- **Reproduction** (Yes / Partly / No) is documented before closing: Yes
|
||||
requires how and under what conditions; Partly requires what could and could
|
||||
not be recreated; No requires a justification. The system never writes "fault
|
||||
confirmed" without reproduction or other verification — instead: *"The
|
||||
customer's description could not be reproduced under the conditions that
|
||||
prevailed during the examination."* (also encoded in the orchestrator's base
|
||||
prompt).
|
||||
- The report's chain of evidence always separates: the customer's description →
|
||||
verified observation → root-cause analysis → recommended action.
|
||||
|
||||
## Root-cause analysis
|
||||
|
||||
A case never closes with merely "component defective, replace component". Every
|
||||
confirmed fault requires four mandatory answers:
|
||||
|
||||
1. **Observed deviation** — the quality rule rejects generic phrasing ("broken",
|
||||
"defective", "worn", "needs replacing") without explanation.
|
||||
2. **Most probable cause** — one or more categories (normal wear, material
|
||||
fatigue, manufacturing defect, poor maintenance, incorrect previous repair,
|
||||
external influence, corrosion, overheating, modification … plus *Unknown
|
||||
cause*, which requires a justification).
|
||||
3. **Supporting evidence** — at least one evidence source, and the source is
|
||||
validated against the log: "Photo" is accepted only if a photo actually
|
||||
exists.
|
||||
4. **Confidence level** — high / medium / low; at medium or low, the technician
|
||||
must state which further checks would strengthen the assessment.
|
||||
|
||||
The close button is blocked until SVP and the root-cause analysis are
|
||||
documented, and the quality gate makes both mandatory when the case is closed.
|
||||
The fleet data is already running: the **root-cause statistics** in the
|
||||
supervisor view (`GET /api/statistik/felorsaker`) aggregate the cause categories
|
||||
across the organisation — which components fail from wear, which after previous
|
||||
repairs, which point to a design problem.
|
||||
|
||||
## Customer approval before work
|
||||
|
||||
The workshop may never carry out proposed work without the customer's decision
|
||||
being recorded and traceable:
|
||||
|
||||
- **The repair proposal** is written in the guide (pre-filled from the
|
||||
root-cause analysis's recommended action) with any estimated cost, and is
|
||||
**shown to the customer in Live Share** — it is customer-shareable material.
|
||||
- **The customer's decision** is recorded with an outcome (approved / declined /
|
||||
partial), a **channel** (telephone, in person, e-mail, SMS, share link) and a
|
||||
justification when declined or partial. The log entry carries who at the
|
||||
workshop received the decision and when.
|
||||
- **The "Document work performed" button is locked** as long as a proposal has
|
||||
no decision — and stays locked when the decision is a refusal. The "No work
|
||||
performed" path is open and refers to the recorded decision.
|
||||
- The quality gate requires a recorded decision when work has been performed,
|
||||
and flags the conflict *"Work performed despite a declined proposal"* as a
|
||||
hard error.
|
||||
|
||||
**The customer can answer directly in their share link**
|
||||
(`POST /api/delad/{kod}/beslut`) — the only writing public route in the entire
|
||||
API, with six safeguards, each verified in the integration test:
|
||||
|
||||
1. Only shares at **customer level** (partner and internal links may never
|
||||
answer on the customer's behalf) and never revoked ones.
|
||||
2. The case's original share code has no recorded level and therefore cannot
|
||||
answer either.
|
||||
3. There must be a repair proposal to answer.
|
||||
4. **One decision per case** — the answer cannot be changed afterwards (contact
|
||||
the workshop instead).
|
||||
5. Only `godkant` / `avbojt` / `delvis` plus a comment of at most 500
|
||||
characters; nothing else can be written to the log by that route.
|
||||
6. Rate limiting per share code.
|
||||
|
||||
The decision is logged as `kundbeslut` with the channel `Delningslänk` (share
|
||||
link) and the sender "Kund via delningslänk" — the workshop's own entries
|
||||
(telephone, in person …) work exactly as before.
|
||||
|
||||
## The repair phase (Repair & Verification)
|
||||
|
||||
The loop opened by symptom verification is closed here — a case cannot be
|
||||
finished without it being clear what was done and whether it helped:
|
||||
|
||||
1. **Repair documented or justified** — either what was actually performed (with
|
||||
any parts), or why no work was done (the customer declined, waiting for a
|
||||
part, investigation only, quotation submitted, repair at another workshop).
|
||||
2. **Quality check** — mandatory when a repair has actually been performed: is
|
||||
the symptom gone, does it remain wholly or partly, or could it not be
|
||||
verified? The outcome is documented together with how the verification was
|
||||
carried out (the same conditions under which the symptom was reproduced).
|
||||
|
||||
A remaining symptom is never hidden: the gate states in writing that the case
|
||||
should not be closed as repaired. The close button is blocked until the chain
|
||||
**symptom verification → root-cause analysis → repair → quality check** is
|
||||
complete, and the report presents it in its own sections.
|
||||
|
||||
## Case identity and vehicle context
|
||||
|
||||
The vehicle object is the connecting thread: the identity is recorded **once**
|
||||
(normally via the work-order scan, which now also reads claim/warranty numbers
|
||||
and insurance references) and is then reused everywhere:
|
||||
|
||||
- **Identity row in the workspace** — work order, claim, insurance reference,
|
||||
vehicle, registration, VIN, odometer, responsible technician, plus the case
|
||||
type selector.
|
||||
- **Live Share** — a locked panel at the top with vehicle, references and
|
||||
status, derived from the level-filtered record.
|
||||
- **First page of the final report** — case information and vehicle information,
|
||||
automatically.
|
||||
- **The export** — identity plus traceability package in every JSON.
|
||||
|
||||
## Terminology
|
||||
|
||||
The product is never described as an "AI app" but as an **evidence-based
|
||||
diagnostic system** / **intelligent decision support**. In the user interface
|
||||
and in documents the words used are *the system, the analysis, the assessment,
|
||||
the interpretation, the image interpretation, the decision support, the rule
|
||||
engine* — not "AI", unless technically necessary.
|
||||
@@ -0,0 +1,245 @@
|
||||
# Modul: Evidensmotorn (ECM — Evidence & Compliance Matrix)
|
||||
|
||||
> **Svensk översättning.** Källan är [evidence-engine.md](evidence-engine.md) (engelska).
|
||||
> Vid avvikelse gäller det engelska dokumentet.
|
||||
|
||||
**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,90 @@
|
||||
# Module: Live Share
|
||||
|
||||
> Canonical version. Swedish: [live-share.sv.md](live-share.sv.md).
|
||||
|
||||
## Purpose
|
||||
|
||||
Every case can be published through a unique secure share link. The link shows
|
||||
the case's current status in real time and updates automatically as new
|
||||
information is recorded. No manual export is needed.
|
||||
|
||||
A live view is of great value to customers, supervisors, insurers and
|
||||
manufacturers — but it must **always remain under the workshop's control**, with
|
||||
clear permissions and security levels.
|
||||
|
||||
## Example customer view
|
||||
|
||||
```
|
||||
Case: Volvo XC60
|
||||
Status: 🟢 Diagnosis in progress
|
||||
|
||||
Customer's fault description
|
||||
The car vibrates at about 88 km/h.
|
||||
|
||||
Current status
|
||||
✔ Object identified
|
||||
✔ Road test carried out
|
||||
✔ Tyres documented
|
||||
✔ Tyre pressure checked
|
||||
🔄 Wheel balancing being checked
|
||||
⏳ Driveshafts not checked
|
||||
|
||||
Images · Measurements · Timeline
|
||||
|
||||
Recommended next step
|
||||
Check radial runout.
|
||||
```
|
||||
|
||||
## Live updating
|
||||
|
||||
While the technician works, the page updates automatically without reloading.
|
||||
The recipient immediately sees new images, new measurements, new comments and
|
||||
status changes.
|
||||
|
||||
## Permission levels
|
||||
|
||||
Links can be created with different access levels:
|
||||
|
||||
- **Customer** — read access to the information the workshop has chosen to
|
||||
share.
|
||||
- **Internal** — full visibility for colleagues and supervisors.
|
||||
- **External partner** — for example an insurer or a manufacturer, with a
|
||||
restricted set of information (including hypotheses, clearly marked as
|
||||
unverified).
|
||||
|
||||
Implemented in the platform: every link is created with a level, the filtering
|
||||
happens server-side, and links can be revoked — a revoked link returns 404.
|
||||
|
||||
## Export
|
||||
|
||||
From the same case it should be possible to export:
|
||||
|
||||
- PDF
|
||||
- JSON
|
||||
- CSV
|
||||
- API
|
||||
- Print-friendly HTML
|
||||
|
||||
All exports build on the same data source (the event log), which reduces the
|
||||
risk of discrepancies.
|
||||
|
||||
## Versioning
|
||||
|
||||
Every export is stamped with:
|
||||
|
||||
- a version number,
|
||||
- date,
|
||||
- time,
|
||||
- who exported it,
|
||||
- the export format.
|
||||
|
||||
That makes it possible to establish afterwards exactly what information was
|
||||
shared at a given moment.
|
||||
|
||||
## Product vision
|
||||
|
||||
A diagnostic case is not merely a chat or a log, but a **living digital work
|
||||
journal**. It can be followed in real time, taken over by a colleague, reviewed
|
||||
by a supervisor, shared with the customer and concluded with a complete report —
|
||||
all from the same data model. That reduces duplicated work and means every party
|
||||
starts from the same current information.
|
||||
@@ -0,0 +1,75 @@
|
||||
# Modul: Live Share
|
||||
|
||||
> **Svensk översättning.** Källan är [live-share.md](live-share.md) (engelska).
|
||||
> Vid avvikelse gäller det engelska dokumentet.
|
||||
|
||||
## 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,84 @@
|
||||
# Module: Verified checklists
|
||||
|
||||
> Canonical version. Swedish: [verified-checklists.sv.md](verified-checklists.sv.md).
|
||||
|
||||
## Core principle
|
||||
|
||||
A check item is not complete merely by ticking a box.
|
||||
|
||||
The system records not only *that* a box has been ticked — it collects
|
||||
**evidence and context**. Every check must contain one or more of the following:
|
||||
|
||||
- ✔ Confirmation that the check was performed.
|
||||
- 📝 A short observation or conclusion.
|
||||
- 📷 A photo (where relevant).
|
||||
- 📹 Video (where needed).
|
||||
- 🎤 Speech-to-text (for quick documentation).
|
||||
- 📏 A measured value (where applicable).
|
||||
|
||||
In this way every step becomes both traceable and comprehensible.
|
||||
|
||||
## Examples
|
||||
|
||||
**Check battery voltage**
|
||||
|
||||
> The technician marks "Performed".
|
||||
> The system: *What value was measured?* → **12.63 V**
|
||||
> The system: *How was this measured? (optional)* → **Directly at the battery
|
||||
> terminals.**
|
||||
> The check item is marked as verified.
|
||||
|
||||
**Check fuse F24**
|
||||
|
||||
> ✔ Performed
|
||||
> The system: *What was observed?* → **The fuse is intact and voltage is present
|
||||
> on both sides.**
|
||||
> The check item is closed.
|
||||
|
||||
## The role of the analysis
|
||||
|
||||
The system helps detect when documentation appears incomplete:
|
||||
|
||||
> "You have marked wheel balancing as checked, but no observation or measurement
|
||||
> has been recorded. Would you like to add a short comment before moving on?"
|
||||
|
||||
It should be **support, not an obstacle**.
|
||||
|
||||
## Adapted to the type of check
|
||||
|
||||
Not every step needs the same level of documentation.
|
||||
|
||||
| Type of check | Minimum requirement |
|
||||
| --- | --- |
|
||||
| Visual check | Confirmation + short comment |
|
||||
| Measurement | Measured value + comment |
|
||||
| Disassembly | Comment, photo where needed |
|
||||
| Road test | Summary of the result |
|
||||
| Image-based check | Photo + observation |
|
||||
|
||||
## Purpose
|
||||
|
||||
The aim is not to "catch" the technician, but to create a working record that
|
||||
shows:
|
||||
|
||||
- what was checked,
|
||||
- how it was checked,
|
||||
- what the result was,
|
||||
- and which conclusions it is reasonable to draw.
|
||||
|
||||
That strengthens the quality of the work, makes handovers easier, and gives a
|
||||
better record towards the customer and management.
|
||||
|
||||
## Important design principle
|
||||
|
||||
Avoid making free text mandatory everywhere. If every check requires long
|
||||
passages of text, the system quickly feels cumbersome. Use instead a combination
|
||||
of:
|
||||
|
||||
- preset answers where they fit,
|
||||
- short speech-to-text for observations,
|
||||
- measured-value fields,
|
||||
- and photo or video where they add the most value.
|
||||
|
||||
The documentation then becomes rich without slowing the workflow — and the
|
||||
technicians use the system consistently in everyday work.
|
||||
@@ -0,0 +1,76 @@
|
||||
# Modul: Verifierade checklistor
|
||||
|
||||
> **Svensk översättning.** Källan är [verified-checklists.md](verified-checklists.md) (engelska).
|
||||
> Vid avvikelse gäller det engelska dokumentet.
|
||||
|
||||
## 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.
|
||||
@@ -0,0 +1,141 @@
|
||||
# Module: Work log and time tracking
|
||||
|
||||
> Canonical version. Swedish: [work-log-and-time-tracking.sv.md](work-log-and-time-tracking.sv.md).
|
||||
|
||||
## Purpose
|
||||
|
||||
All work carried out during a diagnostic case should be timed, traceable and
|
||||
tied to concrete activities.
|
||||
|
||||
The system records not only how long a piece of work took, but also what was
|
||||
done during that time.
|
||||
|
||||
This is more than a time clock — it is a digital work record in which time,
|
||||
activity and technical reasoning hang together. It produces a considerably
|
||||
stronger record than traditional time reporting.
|
||||
|
||||
---
|
||||
|
||||
## Starting work
|
||||
|
||||
The technician begins by identifying the object.
|
||||
|
||||
For example:
|
||||
|
||||
- A photo of the registration plate
|
||||
- A VIN scan
|
||||
- A QR code
|
||||
- A serial number
|
||||
- A machine number
|
||||
|
||||
Once the object is verified, the work log starts.
|
||||
|
||||
Example:
|
||||
|
||||
```
|
||||
08:03 Work started
|
||||
Object: ABC123
|
||||
Volvo XC60
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Automatic timeline
|
||||
|
||||
All activities are timestamped automatically.
|
||||
|
||||
Example:
|
||||
|
||||
```
|
||||
08:03 Object identified
|
||||
08:05 Fault description recorded
|
||||
08:11 Fuse F23 checked
|
||||
08:18 Supply voltage measured
|
||||
08:27 Photo uploaded
|
||||
08:35 Direct feed applied
|
||||
08:48 Wiring diagram opened
|
||||
09:01 New check
|
||||
09:09 Diagnosis completed
|
||||
```
|
||||
|
||||
No manual administration is required.
|
||||
|
||||
---
|
||||
|
||||
## Active working time
|
||||
|
||||
The system distinguishes between:
|
||||
|
||||
- active diagnosis
|
||||
- waiting time
|
||||
- administrative time
|
||||
- parts lookup
|
||||
- road testing
|
||||
- customer contact
|
||||
|
||||
This gives a fairer account of the time spent.
|
||||
|
||||
---
|
||||
|
||||
## Context after longer breaks
|
||||
|
||||
If a longer period passes without activity, the system can ask for context, for
|
||||
example:
|
||||
|
||||
> "No activity has been recorded in the last 20 minutes. Briefly describe what
|
||||
> was done during this period."
|
||||
|
||||
The technician can answer in text or by voice, for example:
|
||||
|
||||
> "Removed the instrument panel to reach the wiring harness."
|
||||
|
||||
That becomes part of the work log.
|
||||
|
||||
---
|
||||
|
||||
## The system as documentation support
|
||||
|
||||
The system does not judge whether the technician is working "fast enough". What
|
||||
it does is help ensure the log is comprehensible and complete. If a step lacks
|
||||
context, it can ask for a short clarification so the report is useful to the
|
||||
customer or to the technician's own organisation.
|
||||
|
||||
---
|
||||
|
||||
## Final report
|
||||
|
||||
When the work is finished, a report is generated automatically, for example:
|
||||
|
||||
**Total time: 1 hour 37 minutes**
|
||||
|
||||
Distribution:
|
||||
|
||||
- Diagnosis: 54 min
|
||||
- Disassembly: 18 min
|
||||
- Measurements: 11 min
|
||||
- Documentation: 6 min
|
||||
- Road test: 8 min
|
||||
|
||||
The report also contains:
|
||||
|
||||
- checks performed,
|
||||
- measured values,
|
||||
- attached images,
|
||||
- technical conclusions,
|
||||
- recommended next steps.
|
||||
|
||||
---
|
||||
|
||||
## Business value
|
||||
|
||||
This function may become one of the system's strongest arguments, because it:
|
||||
|
||||
- reduces administration after the work is finished,
|
||||
- gives the customer a clear basis for the invoice,
|
||||
- strengthens the record in warranty and insurance cases,
|
||||
- makes internal follow-up easier,
|
||||
- creates a searchable knowledge base of earlier diagnoses.
|
||||
|
||||
It makes Guidad Felsökning more than an assistant — it becomes a complete work
|
||||
tool in which identification, methodical diagnosis, documentation and time
|
||||
tracking form one coherent and traceable process.
|
||||
@@ -0,0 +1,131 @@
|
||||
# Modul: Arbetslogg & Tidredovisning
|
||||
|
||||
> **Svensk översättning.** Källan är [work-log-and-time-tracking.md](work-log-and-time-tracking.md) (engelska).
|
||||
> Vid avvikelse gäller det engelska dokumentet.
|
||||
|
||||
## 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.
|
||||
Reference in New Issue
Block a user