update

.paul/phases/05-finances-fakturownia-import/05-02-SUMMARY.md

@@ -0,0 +1,91 @@
+---
+phase: 05-finances-fakturownia-import
+plan: 02
+subsystem: finances
+tags: [php, fakturownia, mapping, nip]
+requires:
+  - phase: 05-finances-fakturownia-import
+    provides: import engine and mapping UI from plan 05-01
+provides:
+  - nip-first client key strategy
+  - backward compatibility for legacy id-based mappings
+  - nip visibility in pending client mappings panel
+affects: [finances, fakturownia-import]
+tech-stack:
+  added: []
+  patterns: [key normalization, compatibility fallback]
+key-files:
+  created: []
+  modified:
+    - autoload/Domain/Finances/FakturowniaInvoiceImporter.php
+    - templates/finances/fakturownia-import-panel.php
+key-decisions:
+  - "Client key now prefers normalized tax number over client_id."
+  - "Importer reads legacy id mapping before queuing unmapped client."
+patterns-established:
+  - "NIP normalization by stripping non-digits."
+duration: ~20min
+started: 2026-04-03T14:24:00+02:00
+completed: 2026-04-03T14:48:00+02:00
+---
+
+# Phase 5 Plan 02: NIP-first mapping summary
+
+Mapowanie klienta w imporcie Fakturownia zostalo domkniete: klucz klienta ma priorytet NIP, a historyczne mapowania po `id:` pozostaja zgodne wstecznie.
+
+## Performance
+
+| Metric | Value |
+|--------|-------|
+| Duration | ~20 min |
+| Started | 2026-04-03T14:24:00+02:00 |
+| Completed | 2026-04-03T14:48:00+02:00 |
+| Tasks | 3 completed |
+| Files modified | 2 |
+
+## Acceptance Criteria Results
+
+| Criterion | Status | Notes |
+|-----------|--------|-------|
+| AC-1: Priorytet mapowania klienta po NIP | Pass | `buildClientKey()` preferuje `tax:` przed `id:` |
+| AC-2: Stabilna normalizacja NIP | Pass | NIP normalizowany przez usuwanie znakow nienumerycznych |
+| AC-3: Kompatybilnosc wsteczna mapowan | Pass | fallback odczytu mapowania po `id:` przed queue unmapped |
+| AC-4: NIP widoczny w panelu brakow mapowania | Pass | UI pokazuje NIP z payloadu przy kliencie |
+
+## Accomplishments
+
+- Zmieniono strategie klucza klienta na NIP-first (`tax -> id -> name`).
+- Dodano fallback na historyczne klucze `id:{client_id}`.
+- Rozszerzono panel brakow mapowania o widok NIP.
+
+## Files Created/Modified
+
+| File | Change | Purpose |
+|------|--------|---------|
+| `autoload/Domain/Finances/FakturowniaInvoiceImporter.php` | Modified | NIP-first key, normalizacja NIP i fallback legacy `id:` |
+| `templates/finances/fakturownia-import-panel.php` | Modified | Wyswietlanie NIP dla brakujacych mapowan klientow |
+
+## Verification Results
+
+- `php -l autoload/Domain/Finances/FakturowniaInvoiceImporter.php` -> no syntax errors
+- `php -l templates/finances/fakturownia-import-panel.php` -> no syntax errors
+
+## Deviations from Plan
+
+Brak odchylen od planu.
+
+## Next Phase Readiness
+
+**Ready:**
+- Import ma docelowe mapowanie klienta po NIP.
+- Wsteczna zgodnosc z mapowaniami `id:` zostala zachowana.
+
+**Concerns:**
+- Istniejace wpisy queue z kluczem `id:` moga jeszcze byc widoczne do czasu kolejnego poprawnego przebiegu importu.
+
+**Blockers:**
+- None
+
+---
+*Phase: 05-finances-fakturownia-import, Plan: 02*
+*Completed: 2026-04-03*