update

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