From 86efbaaca51647d2d22237f363b7b4dfacf8da2d Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 4 Aug 2026 20:19:47 +0000 Subject: [PATCH] =?UTF-8?q?Moduldokumenten=20p=C3=A5=20engelska=20som=20k?= =?UTF-8?q?=C3=A4lla?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 Claude-Session: https://claude.ai/code/session_012EQg3rJsrQ1ZNTvkzmQAtt --- .../docs/examples/vibration-at-88-km-h.md | 109 ++++++++ .../vibration-at-88-km-h.sv.md} | 3 + felsokning/docs/modules/brand-integrations.md | 104 ++++++++ .../brand-integrations.sv.md} | 5 +- felsokning/docs/modules/case-brief.md | 154 +++++++++++ .../case-brief.sv.md} | 3 + .../docs/modules/communication-model.md | 106 ++++++++ .../communication-model.sv.md} | 3 + felsokning/docs/modules/customer-report.md | 34 +++ .../customer-report.sv.md} | 5 +- felsokning/docs/modules/evidence-engine.md | 251 ++++++++++++++++++ .../evidence-engine.sv.md} | 3 + felsokning/docs/modules/live-share.md | 90 +++++++ .../live-share.sv.md} | 3 + .../docs/modules/verified-checklists.md | 84 ++++++ .../verified-checklists.sv.md} | 3 + .../modules/work-log-and-time-tracking.md | 141 ++++++++++ .../work-log-and-time-tracking.sv.md} | 3 + 18 files changed, 1102 insertions(+), 2 deletions(-) create mode 100644 felsokning/docs/examples/vibration-at-88-km-h.md rename felsokning/docs/{exempel/vibration-vid-88-km-h.md => examples/vibration-at-88-km-h.sv.md} (94%) create mode 100644 felsokning/docs/modules/brand-integrations.md rename felsokning/docs/{moduler/markesspecifika-kopplingar.md => modules/brand-integrations.sv.md} (94%) create mode 100644 felsokning/docs/modules/case-brief.md rename felsokning/docs/{moduler/arendebrief.md => modules/case-brief.sv.md} (96%) create mode 100644 felsokning/docs/modules/communication-model.md rename felsokning/docs/{moduler/kommunikationsmodell.md => modules/communication-model.sv.md} (96%) create mode 100644 felsokning/docs/modules/customer-report.md rename felsokning/docs/{moduler/kundrapport.md => modules/customer-report.sv.md} (81%) create mode 100644 felsokning/docs/modules/evidence-engine.md rename felsokning/docs/{moduler/evidensmotor.md => modules/evidence-engine.sv.md} (98%) create mode 100644 felsokning/docs/modules/live-share.md rename felsokning/docs/{moduler/live-share.md => modules/live-share.sv.md} (94%) create mode 100644 felsokning/docs/modules/verified-checklists.md rename felsokning/docs/{moduler/verifierade-checklistor.md => modules/verified-checklists.sv.md} (94%) create mode 100644 felsokning/docs/modules/work-log-and-time-tracking.md rename felsokning/docs/{moduler/arbetslogg-och-tidredovisning.md => modules/work-log-and-time-tracking.sv.md} (94%) diff --git a/felsokning/docs/examples/vibration-at-88-km-h.md b/felsokning/docs/examples/vibration-at-88-km-h.md new file mode 100644 index 0000000..56ab702 --- /dev/null +++ b/felsokning/docs/examples/vibration-at-88-km-h.md @@ -0,0 +1,109 @@ +# Worked example: "The car vibrates at around 88 km/h" + +> Canonical version. Swedish: [vibration-at-88-km-h.sv.md](vibration-at-88-km-h.sv.md). + +This example illustrates how Guidad Felsökning works in practice: a digital +diagnostic process, not a chat. The system does not jump straight to "it's +probably wheel balancing" — it follows a reproducible method. + +--- + +## The case + +**Customer's description** + +> "The car vibrates at around 88 km/h." + +--- + +## Step 1 — Verify the symptom + +The system asks: + +- Is the vibration speed-dependent? +- Is it felt in the steering wheel, the seat, or the whole car? +- Does it occur under acceleration, at steady speed, or under braking? +- Does it disappear above or below a particular speed range? + +Once the answers are documented, the process moves on. + +--- + +## Step 2 — Visual check + +The system asks the technician to photograph: + +- The left front wheel +- The right front wheel +- The left rear wheel +- The right rear wheel + +The image analysis can then help identify things that are genuinely observable, +for example: + +- the tyre's DOT/manufacturing date (via OCR), +- unusual or uneven wear, +- visible damage or deformation, +- missing or loose balance weights, if clearly visible, +- an incorrect tyre size or mismatched tyre types. + +What matters is that the system distinguishes **observation** from +**conclusion**. For instance it may say: + +> "A balance weight appears to be missing on the right front wheel. Check the +> wheel manually." + +rather than asserting that this is the cause of the fault. + +--- + +## Step 3 — Recommended checks + +The system then proposes the next steps, for example: + +- check tyre pressure, +- check wheel torque, +- check radial and lateral runout, +- check wheel balancing, +- check bushings and joints, +- carry out a road test. + +Each item is ticked off and documented. + +--- + +## Step 4 — Road test + +The system summarises what is to be verified during the road test: + +- The speed at which the vibration occurs. +- Any change under acceleration. +- Any change under engine braking. +- Any change when cornering. +- Whether the vibration is felt in the steering wheel or the body. + +--- + +## Step 5 — Summary + +When the technician chooses to pause or finish the work, a report is generated +automatically, for example: + +**Checks performed** + +- Four wheels photographed. +- DOT codes documented. +- Tyre wear checked. +- Tyre pressure verified. +- Wheel balancing checked. +- Road test carried out. + +**Result** + +Observations and measured values are summarised without the system drawing +conclusions that lack support. + +**Recommended next steps** + +For example checking the driveshafts, wheel bearings or other components if the +earlier checks have not identified the cause. diff --git a/felsokning/docs/exempel/vibration-vid-88-km-h.md b/felsokning/docs/examples/vibration-at-88-km-h.sv.md similarity index 94% rename from felsokning/docs/exempel/vibration-vid-88-km-h.md rename to felsokning/docs/examples/vibration-at-88-km-h.sv.md index 98e9d68..b9b7f7c 100644 --- a/felsokning/docs/exempel/vibration-vid-88-km-h.md +++ b/felsokning/docs/examples/vibration-at-88-km-h.sv.md @@ -1,5 +1,8 @@ # Exempelflöde: ”Bilen vibrerar runt 88 km/h” +> **Svensk översättning.** Källan är [vibration-at-88-km-h.md](vibration-at-88-km-h.md) (engelska). +> Vid avvikelse gäller det engelska dokumentet. + Det här exemplet illustrerar hur Guidad Felsökning fungerar i praktiken: en digital diagnostikprocess, inte en AI-chat. AI:n hoppar inte direkt till ”det är nog hjulbalansering”, utan följer en reproducerbar metod. --- diff --git a/felsokning/docs/modules/brand-integrations.md b/felsokning/docs/modules/brand-integrations.md new file mode 100644 index 0000000..9406f8e --- /dev/null +++ b/felsokning/docs/modules/brand-integrations.md @@ -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. diff --git a/felsokning/docs/moduler/markesspecifika-kopplingar.md b/felsokning/docs/modules/brand-integrations.sv.md similarity index 94% rename from felsokning/docs/moduler/markesspecifika-kopplingar.md rename to felsokning/docs/modules/brand-integrations.sv.md index 6b35736..61a4deb 100644 --- a/felsokning/docs/moduler/markesspecifika-kopplingar.md +++ b/felsokning/docs/modules/brand-integrations.sv.md @@ -1,5 +1,8 @@ # 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 @@ -74,7 +77,7 @@ bygga om applikationen. 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 +[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å diff --git a/felsokning/docs/modules/case-brief.md b/felsokning/docs/modules/case-brief.md new file mode 100644 index 0000000..3338736 --- /dev/null +++ b/felsokning/docs/modules/case-brief.md @@ -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. diff --git a/felsokning/docs/moduler/arendebrief.md b/felsokning/docs/modules/case-brief.sv.md similarity index 96% rename from felsokning/docs/moduler/arendebrief.md rename to felsokning/docs/modules/case-brief.sv.md index e1ee6f6..bcb7c08 100644 --- a/felsokning/docs/moduler/arendebrief.md +++ b/felsokning/docs/modules/case-brief.sv.md @@ -1,5 +1,8 @@ # 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. diff --git a/felsokning/docs/modules/communication-model.md b/felsokning/docs/modules/communication-model.md new file mode 100644 index 0000000..746aa75 --- /dev/null +++ b/felsokning/docs/modules/communication-model.md @@ -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. diff --git a/felsokning/docs/moduler/kommunikationsmodell.md b/felsokning/docs/modules/communication-model.sv.md similarity index 96% rename from felsokning/docs/moduler/kommunikationsmodell.md rename to felsokning/docs/modules/communication-model.sv.md index 0f6ec75..64d72f8 100644 --- a/felsokning/docs/moduler/kommunikationsmodell.md +++ b/felsokning/docs/modules/communication-model.sv.md @@ -1,5 +1,8 @@ # 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.** diff --git a/felsokning/docs/modules/customer-report.md b/felsokning/docs/modules/customer-report.md new file mode 100644 index 0000000..c4eb32e --- /dev/null +++ b/felsokning/docs/modules/customer-report.md @@ -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. diff --git a/felsokning/docs/moduler/kundrapport.md b/felsokning/docs/modules/customer-report.sv.md similarity index 81% rename from felsokning/docs/moduler/kundrapport.md rename to felsokning/docs/modules/customer-report.sv.md index fea5cf3..98e9554 100644 --- a/felsokning/docs/moduler/kundrapport.md +++ b/felsokning/docs/modules/customer-report.sv.md @@ -1,5 +1,8 @@ # 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. @@ -22,4 +25,4 @@ Med bilder, mätvärden och kommentarer blir det tydligt vad kunden faktiskt har ## 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. +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. diff --git a/felsokning/docs/modules/evidence-engine.md b/felsokning/docs/modules/evidence-engine.md new file mode 100644 index 0000000..4f2e131 --- /dev/null +++ b/felsokning/docs/modules/evidence-engine.md @@ -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. diff --git a/felsokning/docs/moduler/evidensmotor.md b/felsokning/docs/modules/evidence-engine.sv.md similarity index 98% rename from felsokning/docs/moduler/evidensmotor.md rename to felsokning/docs/modules/evidence-engine.sv.md index 1c1de6a..f272356 100644 --- a/felsokning/docs/moduler/evidensmotor.md +++ b/felsokning/docs/modules/evidence-engine.sv.md @@ -1,5 +1,8 @@ # 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 diff --git a/felsokning/docs/modules/live-share.md b/felsokning/docs/modules/live-share.md new file mode 100644 index 0000000..e672b31 --- /dev/null +++ b/felsokning/docs/modules/live-share.md @@ -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. diff --git a/felsokning/docs/moduler/live-share.md b/felsokning/docs/modules/live-share.sv.md similarity index 94% rename from felsokning/docs/moduler/live-share.md rename to felsokning/docs/modules/live-share.sv.md index b054240..39de07b 100644 --- a/felsokning/docs/moduler/live-share.md +++ b/felsokning/docs/modules/live-share.sv.md @@ -1,5 +1,8 @@ # 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. diff --git a/felsokning/docs/modules/verified-checklists.md b/felsokning/docs/modules/verified-checklists.md new file mode 100644 index 0000000..1818718 --- /dev/null +++ b/felsokning/docs/modules/verified-checklists.md @@ -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. diff --git a/felsokning/docs/moduler/verifierade-checklistor.md b/felsokning/docs/modules/verified-checklists.sv.md similarity index 94% rename from felsokning/docs/moduler/verifierade-checklistor.md rename to felsokning/docs/modules/verified-checklists.sv.md index 188a2d6..3d801f3 100644 --- a/felsokning/docs/moduler/verifierade-checklistor.md +++ b/felsokning/docs/modules/verified-checklists.sv.md @@ -1,5 +1,8 @@ # 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. diff --git a/felsokning/docs/modules/work-log-and-time-tracking.md b/felsokning/docs/modules/work-log-and-time-tracking.md new file mode 100644 index 0000000..ad5d48f --- /dev/null +++ b/felsokning/docs/modules/work-log-and-time-tracking.md @@ -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. diff --git a/felsokning/docs/moduler/arbetslogg-och-tidredovisning.md b/felsokning/docs/modules/work-log-and-time-tracking.sv.md similarity index 94% rename from felsokning/docs/moduler/arbetslogg-och-tidredovisning.md rename to felsokning/docs/modules/work-log-and-time-tracking.sv.md index cea7b4e..59aeb31 100644 --- a/felsokning/docs/moduler/arbetslogg-och-tidredovisning.md +++ b/felsokning/docs/modules/work-log-and-time-tracking.sv.md @@ -1,5 +1,8 @@ # 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.