---
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*
