docs(release): update documentation for AI trace and flyer import improvements

- Update NEXT_STEPS.md with completed AI trace persistence and admin panel enhancements
- Add new section for executed steps (2026-05-21) documenting AI trace integration
- Update README.md with new AI trace features and improvements
- Enhance TEKNISK_BESKRIVNING.md with detailed technical description of AI trace implementation
- Document backend flow, persistence, masking, and UI improvements
- Add next steps including retention policy and API filtering for AiTrace

TEKNISK_BESKRIVNING.md

@@ -1,4 +1,100 @@
-# Nyheter och forbattringar (2026-05-20)
+# Nyheter och förbättringar (2026-05-21)
+
+- **AI observability utökad för flyer:** `AiFlyerParserService.parseWithAI(...)` returnerar nu både `items` och `trace` med `prompt`, `rawOutput`, `chunkCount`, `retryCount`. Detta gör att admin kan felsöka varför en flyer fick varningar/fel utan att gå via debugfiler.
+- **Persistenta flyer-traces i databasen:** `FlyerImportService.parseAndMatch(...)` sparar nu en `AiTrace`-rad (`source=flyer`) efter parse/match med fälten `sessionId`, `model`, `prompt`, `rawOutput`, `normalizedOutput`, `status`, `error`, `durationMs`.
+- **Detail-hydrering i admin trace service:** `AiTraceService` hämtar nu kompletterande flyer-trace-data från `AiTrace` via `sessionId` och returnerar prompt/output/retry/chunk i `GET /api/ai/traces/:id` för flyer.
+- **Varningsförklaring i listvyn:** trace-listan för flyer berikas med mer förklarande text när status är `warning`, och detaljvyn exponerar samtliga varningar (`parseReasons`/`matchReasons`) i en separat lista.
+- **Maskering av känslig data i trace-output:** prompt och raw output maskas innan retur i admin-API med nyckelbaserad maskning (`personnummer`, `telefon`, `email`, `address`, `namn`) samt textbaserade regex-regler för e-post/telefon/personnummer.
+- **Dedupe-härdning för flyerprodukter:** `dedupeItems(...)` använder nu normaliserad signatur av namn/brand/pris/jämförpris/enheter och kampanjsignatur (`offerSignature`) för att minska både dubletter och felaktig hopslagning av olika kampanjer.
+- **Språk- och OCR-korrigeringar i normalisering:** hårdost-varianter återges nu med korrekt svenska tecken (`Prästost`, `Herrgårdsost`) och kända OCR-fel korrigeras kontextstyrt (ex. `Pröd`→`Spröd` i fisk-kontext).
+- **UI-förbättring i admin AI-panel:** prompt/output är nu selekterbar text (`SelectionArea`/`SelectableText`), varningar visas i egen panel med kopiering per rad/alla rader, status-chip visar tooltip med förklaring.
+- **Prestandaskydd i UI för stora outputs:** model output trunkeras initialt vid stora payloads och kan expanderas via `Visa hela outputen` för bättre rendering i web/desktop.
+
+## Teknisk beskrivning: AI-trace för flyer (2026-05-21)
+
+### Översikt
+
+Målet med ändringen är att ge administratörer full observability för flyer-importens AI-led: vad som skickades till modellen, vad modellen svarade, varför status blev `warning/error`, och hur många chunk/retry som användes. Designen bygger på att:
+
+1. samla trace-data nära parse-punkten,
+2. persistera den i `AiTrace`,
+3. exponera den säkert (maskad) i befintliga admin-endpoints,
+4. göra den operativt användbar i Flutter-adminpanelen.
+
+### Backend-flöde steg för steg
+
+1. **AI-parse med spårbarhet**
+   - Fil: `backend/src/flyer-import/services/ai-flyer-parser.service.ts`
+   - `parseWithAI(text)` returnerar nu:
+     - `items: AiFlyerParseResult[]`
+     - `trace: { prompt, rawOutput, chunkCount, retryCount }`
+   - Varje chunk-försök returnerar prompt + rått model-svar + antal försök (`attemptsUsed`).
+
+2. **Normalisering och matchning**
+   - Fil: `backend/src/flyer-import/flyer-import.service.ts`
+   - `parseViaInternal(...)` normaliserar `aiParseResult.items` med `FlyerNormalizerService` och returnerar även `trace` vidare upp i kedjan.
+
+3. **Persistens av trace**
+   - Fil: `backend/src/flyer-import/flyer-import.service.ts`
+   - Efter `persistSessionWithItems(...)` körs `persistFlyerTrace(...)` som skriver till `AiTrace` med:
+     - `source: 'flyer'`
+     - `sessionId` (koppling till `FlyerSession`)
+     - `model: 'ministral-8b-2512'`
+     - `prompt`, `rawOutput`
+     - `normalizedOutput` med `itemCount`, `warnings`, `chunkCount`, `retryCount`
+     - `status: success|warning|error`
+     - `durationMs` (mätt end-to-end i `parseAndMatch`)
+
+4. **Admin-API läser och sammanfogar trace**
+   - Fil: `backend/src/ai/ai-trace.service.ts`
+   - För flyer-detail hämtas först `FlyerSession` + items, sedan kompletterande trace från `AiTrace` via `sessionId`.
+   - `AiTraceService` returnerar:
+     - `prompt` (maskad)
+     - `rawOutput` (maskad)
+     - `retryCount`, `chunkCount`
+     - `warnings` (aggregerat från `parseReasons` + `matchReasons`)
+
+### Säkerhet och dataskydd
+
+- Trace-endpoints är fortsatt admin-skyddade (`@Roles('admin')`).
+- Maskning sker innan payload lämnar backend:
+  - nyckelbaserad maskning i objektträd,
+  - regex-maskning i fri text för e-post/telefon/personnummer,
+  - tillämpas på både `prompt`, `rawOutput` och `normalizedOutput`.
+
+### Dedupe och datakvalitet
+
+- Dedupe-signatur inkluderar nu både produktidentitet och kampanjsignatur.
+- Syfte:
+  - undvika dubbletter från chunk-overlap,
+  - behålla separata rader när kampanjer faktiskt skiljer sig.
+
+### OCR/språk-normalisering
+
+- Ost-varianter använder nu korrekt svenska diakritiska tecken.
+- OCR-fixar är medvetet kontextstyrda för att minimera falska korrigeringar.
+
+### Flutter Admin AI-panel
+
+- Fil: `flutter/lib/features/admin/presentation/admin_ai_panel.dart`
+- Förbättringar:
+  - selekterbar prompt/output (del-kopiering),
+  - varningspanel med kopiera per varning/alla varningar,
+  - tooltip på status-chip med snabb förklaring,
+  - trunkering/expandering av stora outputs.
+
+### Verifiering och testtäckning
+
+- Backend:
+  - `src/ai/ai-trace.service.spec.ts`
+  - `src/flyer-import/services/ai-flyer-parser.service.spec.ts`
+  - `src/flyer-import/services/flyer-normalizer.service.spec.ts`
+- Flutter:
+  - `test/features/admin/presentation/admin_ai_panel_test.dart`
+- Byggverifiering:
+  - `npm run -s build` i `backend/`
+
+# Nyheter och forbattringar (2026-05-20)
 
 - **Deploy-flode forenklat:** `deploy.sh` har kvar `--clean-database` men separat `--migrate` ar borttagen for att undvika redundant migreringslogik.
 - **Migrering i runtime-miljo:** Vid `--clean-database` kor `deploy.sh` alltid `npx prisma migrate deploy --schema prisma/schema.prisma` i `recipe-api` efter att backend ar redo.