update

2026-04-03 14:53:58 +02:00
parent 2b4f24e766
commit 164b9b6a46
9 changed files with 510 additions and 23 deletions
--- a/.paul/ROADMAP.md
+++ b/.paul/ROADMAP.md
@@ -6,7 +6,7 @@ Stabilizacja i poprawa jakosci kodu crmPRO oraz rozwoj finansow o automatyczny i
 ## Current Milestone
 **v0.1 Stabilizacja i jakosc kodu + import finansow** (v0.1.0)
 Status: In progress
-Phases: 1 of 5 complete
+Phases: 2 of 5 complete

 ## Phases

@@ -16,7 +16,7 @@ Phases: 1 of 5 complete
 | 2 | Naprawa bledow krytycznych | TBD | Next | - |
 | 3 | Naprawa bledow glownych | TBD | Not started | - |
 | 4 | Poprawa pokrycia testami | TBD | Not started | - |
-| 5 | Import finansow z Fakturowni | 0/1 | Planning | - |
+| 5 | Import finansow z Fakturowni | 2/2 | Complete | 2026-04-03 |

 ## Phase Details

@@ -89,8 +89,9 @@ Phases: 1 of 5 complete
 - Panel mapowania brakow w `/finances/main_view/`

 **Plans:**
- [ ] 05-01: Integracja Fakturownia i automatyczny import do finansow
+- [x] 05-01: Integracja Fakturownia i automatyczny import do finansow
+- [x] 05-02: Mapowanie klienta po NIP + kompatybilnosc mapowan historycznych

 ---
 *Roadmap created: 2026-03-15*
-*Last updated: 2026-04-02 - Phase 5 planned*
+*Last updated: 2026-04-03 - Phase 5 completed (05-01, 05-02)*
--- a/.paul/STATE.md
+++ b/.paul/STATE.md
@@ -10,29 +10,29 @@ See: .paul/PROJECT.md (updated 2026-03-15)
 ## Current Position

 Milestone: v0.1 Stabilizacja i jakosc kodu
-Phase: 5 of 5 (Import finansow z Fakturowni) - Apply complete
-Plan: 05-01 executed, awaiting unify
-Status: APPLY complete, ready for UNIFY
-Last activity: 2026-04-02 11:03 - Executed .paul/phases/05-finances-fakturownia-import/05-01-PLAN.md
+Phase: 5 of 5 (Import finansow z Fakturowni) - Complete
+Plan: 05-02 unified
+Status: Loop complete, ready for next PLAN
+Last activity: 2026-04-03 14:48 - Unified .paul/phases/05-finances-fakturownia-import/05-02-PLAN.md

 Progress:
- Milestone: [#######---] 35%
- Phase 5: [########--] 80%
+- Milestone: [########--] 40%
+- Phase 5: [##########] 100%

 ## Loop Position

 Current loop state:
 ```
 PLAN --> APPLY --> UNIFY
-  ✓       ✓        ○     [Apply completed, ready for reconciliation]
+  ✓       ✓        ✓     [Loop complete - ready for next PLAN]
 ```

 ## Session Continuity

-Last session: 2026-04-02 11:03
-Stopped at: Apply finished for plan 05-01
-Next action: Run $paul-unify .paul/phases/05-finances-fakturownia-import/05-01-PLAN.md
-Resume file: .paul/phases/05-finances-fakturownia-import/05-01-PLAN.md
+Last session: 2026-04-03 14:48
+Stopped at: Plan 05-02 closed
+Next action: Plan next work item (recommended: $paul-plan for Phase 2)
+Resume file: .paul/phases/05-finances-fakturownia-import/05-02-SUMMARY.md

 ---
 *STATE.md - Updated after every significant action*
--- a/.paul/phases/05-finances-fakturownia-import/05-01-SUMMARY.md
+++ b/.paul/phases/05-finances-fakturownia-import/05-01-SUMMARY.md
@@ -0,0 +1,121 @@
+---
+phase: 05-finances-fakturownia-import
+plan: 01
+subsystem: finances
+tags: [php, medoo, cron, fakturownia, import]
+requires:
+  - phase: 01-sonarqube-baseline
+    provides: baseline quality and project instrumentation
+provides:
+  - fakturownia api integration for income and cost invoices
+  - persistent client and item mappings with unmapped queue
+  - cron step for cyclical import with idempotency
+affects: [finances, cron, fakturownia-import]
+tech-stack:
+  added: []
+  patterns: [repository for import state, importer service, controller actions with csrf]
+key-files:
+  created:
+    - autoload/Domain/Finances/FakturowniaApiClient.php
+    - autoload/Domain/Finances/FakturowniaImportRepository.php
+    - autoload/Domain/Finances/FakturowniaInvoiceImporter.php
+    - templates/finances/fakturownia-import-panel.php
+  modified:
+    - autoload/Controllers/FinancesController.php
+    - autoload/Domain/Finances/FinanceRepository.php
+    - autoload/class.Cron.php
+    - cron.php
+    - templates/finances/main-view.php
+    - .env.example
+key-decisions:
+  - "Client mapping key supports id/tax/name with deterministic fallback order."
+  - "Invoice import is atomic per document (transaction per document)."
+patterns-established:
+  - "Queue-first approach for missing mappings instead of creating partial operations."
+  - "Idempotency stored by external document key (type:id)."
+duration: ~1d
+started: 2026-04-02T09:00:00+02:00
+completed: 2026-04-03T14:24:00+02:00
+---
+
+# Phase 5 Plan 01: Fakturownia import summary
+
+Automatyczny import faktur przychodowych i kosztowych z Fakturowni zostal wdrozony razem z panelami mapowania klientow i pozycji.
+
+## Performance
+
+| Metric | Value |
+|--------|-------|
+| Duration | ~1 day |
+| Started | 2026-04-02T09:00:00+02:00 |
+| Completed | 2026-04-03T14:24:00+02:00 |
+| Tasks | 3 completed |
+| Files modified | 10 |
+
+## Acceptance Criteria Results
+
+| Criterion | Status | Notes |
+|-----------|--------|-------|
+| AC-1: Konfiguracja API i data startu importu | Pass | `.env` config, walidacja i pobieranie od daty startu sa zaimplementowane |
+| AC-2: Import przychodow i kosztow z idempotencja | Pass | importer rozroznia income/cost, kwoty maja poprawny znak, duplikaty sa blokowane |
+| AC-3: Mechanizm uczenia mapowan | Pass | brak mapowan trafia do queue, po zapisaniu mapowan kolejne importy dzialaja automatycznie |
+| AC-4: Obsluga mapowan w zakladce finansow | Pass | panel `/finances/main_view/` pokazuje braki i zapisuje mapowania z CSRF |
+
+## Accomplishments
+
+- Dodano kompletna warstwe domenowa integracji z Fakturownia (API client, importer, repository stanu/mapowan).
+- Podpieto import do crona i zapis podsumowania ostatniego importu.
+- Dodano UI mapowan klientow i pozycji w module finansow.
+
+## Task Commits
+
+Repozytorium zawiera zbiorcze commity `update`, bez atomowych commitow task-per-task dla tego planu.
+
+## Files Created/Modified
+
+| File | Change | Purpose |
+|------|--------|---------|
+| `autoload/Domain/Finances/FakturowniaApiClient.php` | Created | Komunikacja z API Fakturowni |
+| `autoload/Domain/Finances/FakturowniaImportRepository.php` | Created | Tabele i operacje mapowan/stanu importu |
+| `autoload/Domain/Finances/FakturowniaInvoiceImporter.php` | Created | Logika importu dokumentow |
+| `autoload/class.Cron.php` | Modified | Nowy krok importu finansow |
+| `cron.php` | Modified | Uruchamianie importu w harmonogramie |
+| `autoload/Controllers/FinancesController.php` | Modified | Dane panelu i akcje zapisu mapowan |
+| `templates/finances/main-view.php` | Modified | Osadzenie panelu importu |
+| `templates/finances/fakturownia-import-panel.php` | Created | Widok brakow mapowania i formularze zapisu |
+| `autoload/Domain/Finances/FinanceRepository.php` | Modified | Listy klientow/kategorii do mapowania |
+| `.env.example` | Modified | Konfiguracja integracji Fakturownia |
+
+## Decisions Made
+
+| Decision | Rationale | Impact |
+|----------|-----------|--------|
+| Zapis idempotencji po `document_type:id` | unikniecie duplikatow przy cyklicznym cronie | bezpieczne wielokrotne uruchomienia |
+| Braki mapowan trafiaja do queue | brak ryzyka blednych przypisan | wymusza kontrolowana decyzje uzytkownika |
+| Mapowanie klienta oparte o klucz z fallbackiem | rozne payloady API | baza pod dalsze usprawnienia mapowania po NIP |
+
+## Deviations from Plan
+
+Brak istotnych odchylen od zakresu. W trakcie UAT wykryto potrzebe doprecyzowania mapowania klienta po NIP (zaplanowane jako kolejny plan 05-02).
+
+## Issues Encountered
+
+| Issue | Resolution |
+|-------|------------|
+| Powtarzalne mapowanie tego samego kontrahenta dla czesci faktur kosztowych | Dodane jako nowy plan 05-02 (priorytet: NIP-first + normalizacja) |
+
+## Next Phase Readiness
+
+**Ready:**
+- Integracja i UI sa gotowe do iteracji nad jakoscia mapowania klienta.
+- Struktura tabel i kolejek pozwala rozszerzyc mapowanie bez refaktoryzacji crona.
+
+**Concerns:**
+- Dla czesci dokumentow klucz klienta moze byc oparty o `id:` zamiast NIP.
+
+**Blockers:**
+- None
+
+---
+*Phase: 05-finances-fakturownia-import, Plan: 01*
+*Completed: 2026-04-03*
--- a/.paul/phases/05-finances-fakturownia-import/05-02-PLAN.md
+++ b/.paul/phases/05-finances-fakturownia-import/05-02-PLAN.md
@@ -0,0 +1,158 @@
+---
+phase: 05-finances-fakturownia-import
+plan: 02
+type: execute
+wave: 1
+depends_on: ["05-01"]
+files_modified:
+  - autoload/Domain/Finances/FakturowniaInvoiceImporter.php
+  - templates/finances/fakturownia-import-panel.php
+autonomous: true
+---
+
+<objective>
+## Goal
+Usprawnic mapowanie klienta w imporcie Fakturownia tak, aby priorytetowo mapowac po NIP i ograniczyc reczne mapowanie tej samej firmy przy kolejnych fakturach kosztowych.
+
+## Purpose
+W aktualnym imporcie czesc dokumentow kluczuje klienta po `client_id`, co moze powodowac tworzenie kolejnych rekordow "brak mapowania" dla tego samego kontrahenta. Zmiana ma zapewnic stabilny klucz po NIP.
+
+## Output
+- Zmieniony algorytm `buildClientKey()` z priorytetem NIP
+- Normalizacja NIP do wspolnego formatu klucza
+- Kompatybilnosc wsteczna: fallback do starego klucza `id:...` podczas importu
+- Widoczny NIP przy brakujacych mapowaniach klienta w panelu finansow
+</objective>
+
+<context>
+## Project Context
+@.paul/PROJECT.md
+@.paul/ROADMAP.md
+@.paul/STATE.md
+@.paul/phases/05-finances-fakturownia-import/05-01-PLAN.md
+@.paul/phases/05-finances-fakturownia-import/05-01-SUMMARY.md
+
+## Source Files
+@autoload/Domain/Finances/FakturowniaInvoiceImporter.php
+@templates/finances/fakturownia-import-panel.php
+@autoload/Controllers/FinancesController.php
+@autoload/Domain/Finances/FakturowniaImportRepository.php
+</context>
+
+<acceptance_criteria>
+
+## AC-1: Priorytet mapowania klienta po NIP
+```gherkin
+Given dokument z Fakturowni zawiera NIP kontrahenta
+When importer buduje klucz klienta
+Then klucz jest oparty o NIP (prefiks `tax:`) niezaleznie od obecnosci `client_id`
+```
+
+## AC-2: Stabilna normalizacja NIP
+```gherkin
+Given NIP wystepuje w roznych formatach (spacje, myslniki, inne separatory)
+When importer normalizuje NIP
+Then wszystkie formy daja ten sam klucz mapowania klienta
+```
+
+## AC-3: Kompatybilnosc wsteczna mapowan
+```gherkin
+Given istnieje historyczne mapowanie klienta zapisane po kluczu `id:...`
+When importer nie znajdzie mapowania po nowym kluczu `tax:...`
+Then wykona fallback do starego klucza `id:...` i zaimportuje dokument bez ponownego recznego mapowania
+```
+
+## AC-4: NIP widoczny w panelu brakow mapowania
+```gherkin
+Given klient trafia do listy "Brakujace mapowania klientow"
+When uzytkownik otwiera panel w `/finances/main_view/`
+Then przy rekordzie widzi NIP z payloadu (jesli dostepny), co ulatwia wybor klienta CRM
+```
+
+</acceptance_criteria>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Zmienic algorytm klucza klienta na NIP-first z normalizacja</name>
+  <files>autoload/Domain/Finances/FakturowniaInvoiceImporter.php</files>
+  <action>
+    1. Zmienic `buildClientKey()` tak, aby kolejnosc byla:
+       - `tax:{normalized_tax_no}`
+       - `id:{client_id}`
+       - `name:{normalized_name}`
+    2. Dodac pomocnicza normalizacje NIP usuwajaca znaki nienumeryczne i biale znaki.
+    3. Gdy normalizacja da pusty wynik, traktowac NIP jako niedostepny i przejsc do fallbacku.
+
+    Unikac: zmiany semantyki mapowania pozycji (`buildItemKey`) i modyfikacji niezwiązanych z klientem.
+  </action>
+  <verify>
+    Odczyt kodu potwierdza, ze `buildClientKey()` sprawdza najpierw NIP, a NIP jest normalizowany do stalego formatu.
+  </verify>
+  <done>AC-1 i AC-2 satisfied</done>
+</task>
+
+<task type="auto">
+  <name>Task 2: Dodac fallback odczytu mapowania po historycznym kluczu id</name>
+  <files>autoload/Domain/Finances/FakturowniaInvoiceImporter.php</files>
+  <action>
+    1. W `processSingleDocument()` po braku mapowania po nowym `client_key` wykonac probe odczytu mapowania po starym kluczu `id:{client_id}`, o ile `client_id` istnieje i nowy klucz jest inny.
+    2. Jesli fallback znajdzie mapowanie, kontynuowac import bez queue dla klienta.
+    3. Jesli fallback nie znajdzie mapowania, zachowac obecne zachowanie queue `client`.
+
+    Unikac: zapisu nowego mapowania automatycznie bez decyzji uzytkownika.
+  </action>
+  <verify>
+    Sciezka warunkowa importera zawiera probe fallbacku `id:` przed `queueUnmapped('client', ...)`.
+  </verify>
+  <done>AC-3 satisfied</done>
+</task>
+
+<task type="auto">
+  <name>Task 3: Pokazac NIP w panelu brakujacych mapowan klientow</name>
+  <files>templates/finances/fakturownia-import-panel.php</files>
+  <action>
+    1. W tabeli "Brakujace mapowania klientow" wyswietlic NIP z payloadu (`tax_no`) przy danym rekordzie, z escapowaniem.
+    2. Zachowac dotychczasowe informacje o kluczu i liczbie wystapien.
+    3. Nie zmieniac endpointow zapisu mapowania i CSRF.
+  </action>
+  <verify>
+    Widok panelu renderuje dodatkowa linie z NIP (gdy payload ma `tax_no`) i pozostaje bezpieczny pod XSS.
+  </verify>
+  <done>AC-4 satisfied</done>
+</task>
+
+</tasks>
+
+<boundaries>
+
+## DO NOT CHANGE
+- mechanizm importu pozycji i mapowania kategorii
+- struktura tabel SQL w `FakturowniaImportRepository` (bez migracji w tym planie)
+- endpointy i routing niezwiązane z finansami
+
+## SCOPE LIMITS
+- Tylko mapowanie klienta i prezentacja NIP w panelu
+- Bez tworzenia klientow CRM automatycznie
+- Bez zmian w harmonogramie cron
+
+</boundaries>
+
+<verification>
+Before declaring plan complete:
+- [ ] `buildClientKey()` ma priorytet `tax -> id -> name`
+- [ ] NIP jest normalizowany do stabilnego formatu klucza
+- [ ] Importer ma fallback odczytu mapowania po historycznym `id:...`
+- [ ] Panel brakow mapowan klientow wyswietla NIP (jesli dostępny)
+- [ ] All acceptance criteria met
+</verification>
+
+<success_criteria>
+- Brak ponownego mapowania tej samej firmy, gdy dokumenty roznia sie `client_id`, ale maja ten sam NIP
+- Istniejace mapowania po `id:` nie przestaja dzialac po wdrozeniu zmiany
+- Uzytkownik widzi NIP w panelu i szybciej mapuje klienta
+</success_criteria>
+
+<output>
+After completion, create `.paul/phases/05-finances-fakturownia-import/05-02-SUMMARY.md`
+</output>
--- a/.paul/phases/05-finances-fakturownia-import/05-02-SUMMARY.md
+++ b/.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*