feat: simplify receipt import matching logic and enhance trace logging

2026-05-09 15:17:00 +02:00
parent 1966a92a87
commit 97e7b09bcd
4 changed files with 76 additions and 1 deletions
@@ -15,6 +15,74 @@ Se även:
 - [TEKNISK_BESKRIVNING.md](TEKNISK_BESKRIVNING.md) för teknisk genomgång.
 - [AI-FUNKTIONER.md](_archive/microservice-ai/AI-FUNKTIONER.md) för AI-översikt.

+# Session 2026-05-09: Simplified Matching Logic (Consolidation Phase 3)
+
+Denna session har genomfört den tredje omarbetningsfasen som konsoliderar receipt-import matching-flödet:
+
+## Genomförda förbättringar
+
+### 1. Unified Matcher (`matchAndEnrichReceiptItem`)
+- **Tidigare:** Matching var splittrad mellan `matchProducts()` (alias + word-match) och `enrichWithAiCategories()` (~850 rader).
+- **Nu:** En central metod som gör allt i explicit ordning:
+  1. **Alias lookup** — certifierad match från ReceiptAlias
+  2. **Word-match** — fuzzy produktmatchning med scoring
+  3. **Categorization** — regel-baserad → AI (fallback) → guards → hard overrides
+
+### 2. Improved Context Management (`prepareMatchingContext`)
+- Alla data (aliases, produkter, unit mappings, categories) hämtas **en gång** per receipt
+- Parallell loading med `Promise.all()` — högre performance än tidigare sekventiell loading
+- Context passeras till alla items för effektiv återanvändning
+
+### 3. Better Decision Logging (`enrichCategoryForItem`)
+- Structured trace med steg-för-steg-loggning:
+  - ✓ Rule-based hits with path name
+  - ✓ AI suggestions
+  - ⚠️ Guard remaps (contradiction resolution)
+  - ⚠️ Hard overrides (special cases)
+  - ✅ Final decision with confidence level
+- Debug-träd med alla decision points
+- Kan aktiveras per receipt via `RECEIPT_TRACE_DECISIONS` env-var
+
+### 4. Simplified parseReceipt Flow
+```
+Before:
+  parseReceipt() → matchProducts() → enrichWithAiCategories()
+
+After:
+  parseReceipt() → prepareContext() → matchAndEnrichReceiptItem() (per item)
+```
+
+## Technical Details
+
+**Nya metoder:**
+- `matchAndEnrichReceiptItem()` — unified matching pipeline per item
+- `prepareMatchingContext()` — one-time context preparation
+- `enrichCategoryForItem()` — consolidated categorization logic
+- `findWordMatchWithScore()` — refactored word matching with explicit score return
+
+**Datatyper:**
+- `MatchDecision` interface för strukturerad result (i `dto/match-decision.ts`)
+
+**Build Status:**
+- ✅ Full TypeScript compilation successful
+- ✅ No breaking changes to existing API contracts
+
+## Cleanup Pending
+
+De gamla metoderna är fortfarande i koden men kan nu ta bort:
+- `private async matchProducts()` — deprecated by unified matcher
+- `private async enrichWithAiCategories()` — deprecated by unified matcher
+- `private findWordMatch()` — replaced by findWordMatchWithScore()
+
+**Cleanup tasks:**
+1. Ta bort `matchProducts()`
+2. Ta bort `enrichWithAiCategories()`
+3. Ta bort `findWordMatch()` (gammal version)
+4. Uppdatera kommentarer/docstrings
+5. Kör full test suite för regression detection
+
+Cleanup bör göras i nästa session för att ge tid för monitoring/QA.
+
 # Plan för omarbetning av receptimport

 # 2026-05-07: Säkerhets- och deployförbättringar