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
2026-05-21 19:16:06 +02:00
parent 026323b72a
commit e079758f1d
3 changed files with 122 additions and 8 deletions
@@ -7,6 +7,15 @@
 - [x] **Produktionsnara fel rattat:** `clean-database.sql` korrigerad efter serverfel (`Table 'ShoppingList' doesn't exist`).
 - [x] **Tabellista hardad:** SQL-filen anvander nu existerande tabeller i nuvarande Prisma-schema och tar bort beroenden i saker ordning med `FOREIGN_KEY_CHECKS`.
 ## Utförda steg (2026-05-21)
 - [x] **Flyer AI-trace persisteras:** `AiFlyerParserService` returnerar trace-data (prompt/rawOutput/chunkCount/retryCount) och `FlyerImportService` sparar detta i `AiTrace` med `source=flyer`.
 - [x] **Admin AI observability utökad:** `AiTraceService` hämtar kompletterande flyer-trace via `sessionId` och exponerar prompt/output/retry/chunk i detaljvyn.
 - [x] **Maskning i trace-detail:** känslig data maskas konsekvent i prompt/raw output/normaliserad output innan retur till admin-UI.
 - [x] **Flyer-kvalitet:** dedupe justerad för att minska dubletter utan att slå ihop olika kampanjer; hårdostnamn använder korrekt åäö.
 - [x] **Kontextstyrd OCR-korrigering:** kända fel (ex. `Pröd`) korrigeras endast i relevant textkontext för att minska falska rättningar.
 - [x] **Flutter Admin AI-panel UX:** selekterbar prompt/output, varningspanel med kopiering och output-trunkering med expandera/kollapsa.
 # Nasta steg
 Detta ar huvudroadmap for Recipe App.
@@ -159,9 +168,11 @@ MVP ar uppnadd nar en vanlig anvandare kan importera, granska och spara kvitto/r
   - Se `SESSION_2026-05-09_RECEIPT_IMPORT.md` för detaljer
   - **Todo:** Deploy till prod, testa i live miljö, ev. add UI för user private rename/merge
 4. Verifiera flyerimportens sessionhydrering end-to-end i test/staging (tab-byte + app-omstart).
-5. Lokalisera kvarvarande stora Flutter-vyer i import/inventarie.
+5. Lägg till retention-policy och schemalagd rensning för `AiTrace` (receipt/flyer) för att styra datalivslängd i produktion.
-6. Förbereda avancerad AI-integration med tydlig loggning/audit.
+6. Lägg till API-stöd för filtrering av trace-lista på `status` och fri textsökning i varningskoder.
-7. Påbörja EAN-stöd via Open Food Facts.
+7. Lokalisera kvarvarande stora Flutter-vyer i import/inventarie.
 8. Förbereda avancerad AI-integration med tydlig loggning/audit.
 9. Påbörja EAN-stöd via Open Food Facts.
 ## Beslut som styr arbetet
@@ -1,3 +1,10 @@
 # Nyheter och förbättringar (2026-05-21)
 - **Flyer AI-trace end-to-end:** flyer-importen sparar nu prompt/output/metadata i `AiTrace` (source=`flyer`) och adminpanelen kan visa detaljerad trace per session.
 - **Bättre produktkvalitet vid flyer-import:** dedupe förbättrad för att minska dubletter, hårdostnamn normaliseras med korrekt åäö, samt kontextstyrd OCR-korrigering för kända fel.
 - **Admin AI-panel förbättrad:** model output och prompt är selekterbara, varningar visas med detaljer + kopieringsstöd, och status har tooltip med förklaring.
 - **Stora outputs hanteras bättre i UI:** outputkortet trunkerar stora JSON-svar och låter admin expandera vid behov.
 # Nyheter och forbattringar (2026-05-20)
 - **Deploy-flode for migrering/rensning uppdaterat:** `deploy.sh` kor automatisk migrering vid vanlig deploy, medan `--clean-database` nu forst kor explicit `prisma migrate deploy` och sedan rensnings-SQL. Flaggan `--migrate` ar borttagen.
@@ -1,3 +1,99 @@
 # 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.