update

2026-04-02 12:00:38 +02:00
parent 46dae22a71
commit e743245cee
21 changed files with 2105 additions and 196 deletions
--- a/.paul/ROADMAP.md
+++ b/.paul/ROADMAP.md
@@ -1,42 +1,43 @@
-# Roadmap: crmPRO
+# Roadmap: crmPRO

 ## Overview
-Stabilizacja i poprawa jakości kodu crmPRO — identyfikacja i naprawa błędów, analiza jakości kodu przez SonarQube.
+Stabilizacja i poprawa jakosci kodu crmPRO oraz rozwoj finansow o automatyczny import faktur z Fakturowni.

 ## Current Milestone
-**v0.1 Stabilizacja i jakość kodu** (v0.1.0)
+**v0.1 Stabilizacja i jakosc kodu + import finansow** (v0.1.0)
 Status: In progress
-Phases: 1 of 4 complete
+Phases: 1 of 5 complete

 ## Phases

 | Phase | Name | Plans | Status | Completed |
 |-------|------|-------|--------|-----------|
-| 1 | Konfiguracja SonarQube i baseline | 1/1 | ✅ Complete | 2026-03-15 |
-| 2 | Naprawa błędów krytycznych | TBD | 🔵 Next | - |
-| 3 | Naprawa błędów głównych | TBD | Not started | - |
+| 1 | Konfiguracja SonarQube i baseline | 1/1 | Complete | 2026-03-15 |
+| 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 | - |

 ## Phase Details

-### Phase 1: Konfiguracja SonarQube i baseline ✅
+### Phase 1: Konfiguracja SonarQube i baseline

-**Goal:** Skonfigurować projekt w SonarQube, uruchomić pierwszy skan i uzyskać baseline jakości kodu
+**Goal:** Skonfigurowac projekt w SonarQube, uruchomic pierwszy skan i uzyskac baseline jakosci kodu
 **Depends on:** Nothing (first phase)
 **Completed:** 2026-03-15

 **Results:**
 - sonar-project.properties skonfigurowany
- Pierwszy skan: 88 plików, 9356 LoC
+- Pierwszy skan: 88 plikow, 9356 LoC
 - Baseline: 58 bugs, 1649 code smells, 0% coverage, 5.6% duplikacji
 - Reliability: D, Security: A, Maintainability: A

 **Plans:**
- [x] 01-01: Konfiguracja SonarQube i analiza wyników pierwszego skanu
+- [x] 01-01: Konfiguracja SonarQube i analiza wynikow pierwszego skanu

-### Phase 2: Naprawa błędów krytycznych
+### Phase 2: Naprawa bledow krytycznych

-**Goal:** Naprawić wszystkie bugs i vulnerabilities o priorytecie Critical/Blocker
+**Goal:** Naprawic wszystkie bugs i vulnerabilities o priorytecie Critical/Blocker
 **Depends on:** Phase 1 (wyniki skanu)
 **Research:** Unlikely

@@ -46,11 +47,11 @@ Phases: 1 of 4 complete
 - Reskan po naprawach

 **Plans:**
- [ ] 02-01: TBD (na podstawie wyników Phase 1)
+- [ ] 02-01: TBD (na podstawie wynikow Phase 1)

-### Phase 3: Naprawa błędów głównych
+### Phase 3: Naprawa bledow glownych

-**Goal:** Naprawić bugs o priorytecie Major i code smells wpływające na stabilność
+**Goal:** Naprawic bugs o priorytecie Major i code smells wplywajace na stabilnosc
 **Depends on:** Phase 2
 **Research:** Unlikely

@@ -60,21 +61,36 @@ Phases: 1 of 4 complete
 - Reskan po naprawach

 **Plans:**
- [ ] 03-01: TBD (na podstawie wyników Phase 2)
+- [ ] 03-01: TBD (na podstawie wynikow Phase 2)

 ### Phase 4: Poprawa pokrycia testami

-**Goal:** Dodać testy dla kluczowych modułów zidentyfikowanych przez SonarQube
+**Goal:** Dodac testy dla kluczowych modulow zidentyfikowanych przez SonarQube
 **Depends on:** Phase 3
 **Research:** Unlikely

 **Scope:**
- Testy dla modułów o najniższym pokryciu
- Testy regresji dla naprawionych bugów
+- Testy dla modulow o najnizszym pokryciu
+- Testy regresji dla naprawionych bugow

 **Plans:**
- [ ] 04-01: TBD (na podstawie wyników Phase 3)
+- [ ] 04-01: TBD (na podstawie wynikow Phase 3)
+
+### Phase 5: Import finansow z Fakturowni
+
+**Goal:** Wdrozyc automatyczny import faktur przychodowych i kosztowych z Fakturowni do finansow crmPRO
+**Depends on:** None (moze byc realizowane niezaleznie od prac SonarQube)
+**Research:** Likely (szczegoly endpointow API i semantyka pol dokumentow)
+
+**Scope:**
+- Integracja API Fakturownia (dane z `.env` + data startu importu)
+- Trwale mapowanie klientow i produktow/uslug do struktur finansowych CRM
+- Import cykliczny przez cron z idempotencja i obsluga bledow
+- Panel mapowania brakow w `/finances/main_view/`
+
+**Plans:**
+- [ ] 05-01: Integracja Fakturownia i automatyczny import do finansow

 ---
 *Roadmap created: 2026-03-15*
-*Last updated: 2026-03-15 — Phase 1 complete*
+*Last updated: 2026-04-02 - Phase 5 planned*
--- a/.paul/STATE.md
+++ b/.paul/STATE.md
@@ -1,57 +1,38 @@
-# Project State
+# Project State

 ## Project Reference

 See: .paul/PROJECT.md (updated 2026-03-15)

-**Core value:** Użytkownicy mogą efektywnie zarządzać projektami, zadaniami i klientami w jednym systemie CRM
-**Current focus:** Faza 2 — Naprawa błędów krytycznych
+**Core value:** Uzytkownicy moga efektywnie zarzadzac projektami, zadaniami i klientami w jednym systemie CRM
+**Current focus:** Faza 5 - Import finansow z Fakturowni

 ## Current Position

-Milestone: v0.1 Stabilizacja i jakość kodu
-Phase: 2 of 4 (Naprawa błędów krytycznych) — In Progress
-Plan: 02-02 complete, 02-01 awaiting approval
-Status: Loop closed for 02-02, ready for next plan
-Last activity: 2026-03-15 — Completed .paul/phases/02-critical-bugs-fix/02-02-SUMMARY.md
+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

 Progress:
- Milestone: [██░░░░░░░░] 25%
- Phase 2: [█████░░░░░] 50% (1/2 plans complete)
+- Milestone: [#######---] 35%
+- Phase 5: [########--] 80%

 ## Loop Position

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

-## Accumulated Context
-
-### Decisions
- 2026-03-15: SonarQube URL = https://sonar.project-pro.pl (nie localhost)
- 2026-03-15: Skan automatyczny via sonar-scanner CLI + MCP do odczytu wyników
- 2026-03-15: Usunięto nawigację z layout-cron zamiast ukrywania CSS
- 2026-03-15: JSON.parse zamiast deprecated jQuery.parseJSON
-
-### Deferred Issues
-None yet.
-
-### Blockers/Concerns
-None.
-
-### Git State
-Last commit: e92c9fe
-Branch: main
-Feature branches merged: none
-
 ## Session Continuity

-Last session: 2026-03-15
-Stopped at: Plan 02-02 UNIFY complete
-Next action: Approve and execute plan 02-01 (SonarQube bugs fix) — run /paul:apply .paul/phases/02-critical-bugs-fix/02-01-PLAN.md
-Resume file: .paul/phases/02-critical-bugs-fix/02-02-SUMMARY.md
+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

 ---
-*STATE.md — Updated after every significant action*
+*STATE.md - Updated after every significant action*
--- a/.paul/phases/05-finances-fakturownia-import/05-01-PLAN.md
+++ b/.paul/phases/05-finances-fakturownia-import/05-01-PLAN.md
@@ -0,0 +1,223 @@
+---
+phase: 05-finances-fakturownia-import
+plan: 01
+type: execute
+wave: 1
+depends_on: []
+files_modified:
+  - cron.php
+  - autoload/class.Cron.php
+  - autoload/Controllers/FinancesController.php
+  - autoload/Domain/Finances/FinanceRepository.php
+  - autoload/Domain/Finances/FakturowniaApiClient.php
+  - autoload/Domain/Finances/FakturowniaImportRepository.php
+  - autoload/Domain/Finances/FakturowniaInvoiceImporter.php
+  - templates/finances/main-view.php
+  - templates/finances/fakturownia-import-panel.php
+  - .env.example
+autonomous: true
+---
+
+<objective>
+## Goal
+Dodac automatyczny import faktur przychodowych i kosztowych z Fakturowni do finansow crmPRO, z mechanizmem uczenia mapowan klientow i produktow/uslug.
+
+## Purpose
+Zminimalizowac reczna prace w finansach: pierwsze faktury wymagaja mapowania, ale kolejne dokumenty z tymi samymi klientami i pozycjami maja importowac sie juz calkowicie automatycznie.
+
+## Output
+- Warstwa integracji API Fakturowni z konfiguracja przez `.env`
+- Trwale mapowania klientow i produktow/uslug do struktur finansowych crmPRO
+- Automatyczny import przez cron z idempotencja i data startu
+- Panel w finansach do obslugi brakujacych mapowan
+</objective>
+
+<context>
+## Project Context
+@.paul/PROJECT.md
+@.paul/ROADMAP.md
+@.paul/STATE.md
+
+## Source Files
+@cron.php
+@autoload/class.Cron.php
+@autoload/Controllers/FinancesController.php
+@autoload/Domain/Finances/FinanceRepository.php
+@templates/finances/main-view.php
+@config.php
+</context>
+
+<acceptance_criteria>
+
+## AC-1: Konfiguracja API i data startu importu
+```gherkin
+Given w pliku .env ustawiono dane dostepowe Fakturowni oraz date startu importu
+When cron uruchamia proces importu
+Then importer laczy sie z API Fakturowni i pobiera tylko dokumenty od skonfigurowanej daty
+  And brakujaca konfiguracja zwraca czytelny blad bez przerwania calego crona
+```
+
+## AC-2: Import przychodow i kosztow z idempotencja
+```gherkin
+Given faktura przychodowa lub kosztowa istnieje w Fakturowni
+When dokument ma komplet mapowan klienta i pozycji
+Then powstaje operacja finansowa w crmPRO z poprawnym znakiem kwoty (przychod > 0, koszt < 0)
+  And ponowne uruchomienie importu nie tworzy duplikatu tej samej faktury
+```
+
+## AC-3: Mechanizm uczenia mapowan
+```gherkin
+Given dokument zawiera klienta lub pozycje bez mapowania
+When importer przetwarza dokument
+Then dokument nie jest importowany do finansow, a brakujace mapowania trafiaja na liste do recznego przypisania
+  And po zapisaniu mapowania kolejne faktury z tym klientem/pozycja importuja sie automatycznie
+```
+
+## AC-4: Obsluga mapowan w zakladce finansow
+```gherkin
+Given uzytkownik jest na /finances/main_view/
+When otwiera panel importu Fakturownia
+Then widzi brakujace mapowania klientow i produktow/uslug
+  And moze przypisac klienta CRM i kategorie finansowa
+  And zapis mapowania jest chroniony tokenem CSRF
+```
+
+</acceptance_criteria>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Zbudowac warstwe integracji Fakturownia + trwawe mapowania</name>
+  <files>
+    autoload/Domain/Finances/FakturowniaApiClient.php,
+    autoload/Domain/Finances/FakturowniaImportRepository.php,
+    autoload/Domain/Finances/FinanceRepository.php,
+    .env.example
+  </files>
+  <action>
+    1. Dodac loader `.env` (bez nowych bibliotek) i zdefiniowac klucze:
+       - `FAKTUROWNIA_API_DOMAIN`
+       - `FAKTUROWNIA_API_TOKEN`
+       - `FAKTUROWNIA_START_DATE`
+       - `FAKTUROWNIA_PAGE_LIMIT` (opcjonalnie)
+    2. Dodac klienta API Fakturowni z obsluga paginacji i timeoutow:
+       - pobieranie faktur przychodowych (np. endpoint invoices)
+       - pobieranie faktur kosztowych (np. endpoint costs/expenses)
+    3. Dodac repozytorium importu z tabelami tworzonymi przez `CREATE TABLE IF NOT EXISTS`:
+       - tabela mapowania klientow Fakturownia -> crm_client.id
+       - tabela mapowania pozycji (nazwa produktu/uslugi) -> finance_categories.id
+       - tabela stanu importu i idempotencji (external_id + typ dokumentu)
+       - tabela kolejki brakujacych mapowan do panelu finansow
+    4. Wszystkie zapytania SQL wykonywac przez medoo/query z parametrami bindowanymi (bez sklejania SQL z danymi wejsciowymi).
+    5. W `FinanceRepository` dodac metody pomocnicze do pobierania kategorii i klientow dla panelu mapowan.
+
+    Unikac: trzymania tokenu API w `config.php`, mapowan w sesji i importu bez kontroli duplikatow.
+  </action>
+  <verify>
+    - Odczyt `.env.example` potwierdza nowe klucze integracji.
+    - Odczyt nowych klas potwierdza osobne odpowiedzialnosci (API, repo mapowan, state importu).
+    - Test manualny: dwukrotne wywolanie zapisu importu dla tego samego external_id nie tworzy duplikatu.
+  </verify>
+  <done>AC-1 i AC-2 i AC-3 satisfied: konfiguracja, idempotencja i struktury mapowan gotowe</done>
+</task>
+
+<task type="auto">
+  <name>Task 2: Dodac importer dokumentow i podpiac go pod cron</name>
+  <files>
+    autoload/Domain/Finances/FakturowniaInvoiceImporter.php,
+    autoload/class.Cron.php,
+    cron.php
+  </files>
+  <action>
+    1. Dodac serwis importera, ktory:
+       - pobiera dokumenty od `FAKTUROWNIA_START_DATE`,
+       - scala dane klienta i pozycji,
+       - sprawdza mapowania klienta i pozycji,
+       - przy komplecie mapowan zapisuje operacje finansowe,
+       - przy brakach wpisuje rekordy do kolejki brakow mapowan i pomija import dokumentu.
+    2. Dodac polityke znaku kwoty:
+       - przychodowe -> dodatnie `amount`
+       - kosztowe -> ujemne `amount`
+    3. Wprowadzic idempotencje na poziomie zrodlowego `external_id` + typ dokumentu.
+    4. Rozszerzyc `Cron` i `cron.php` o krok `import_finances_from_fakturownia()`:
+       - uruchamiany przy kazdym cyklu crona,
+       - zwraca statusy `ok|empty|error` analogicznie do obecnych zadan,
+       - loguje krotki komunikat o liczbie zaimportowanych i pominietych dokumentow.
+
+    Unikac: przerywania calego crona przy pojedynczym bledzie faktury.
+  </action>
+  <verify>
+    - Suchy przebieg importera zwraca licznik imported/skipped/unmapped.
+    - Uruchomienie `php cron.php` wykonuje nowy krok i nie psuje istniejacych zadan cron.
+    - Powtorne uruchomienie dla tych samych danych nie dubluje wpisow w `finance_operations`.
+  </verify>
+  <done>AC-1 i AC-2 i AC-3 satisfied: cron importuje faktury cyklicznie i bez duplikatow</done>
+</task>
+
+<task type="auto">
+  <name>Task 3: Dodac panel mapowan Fakturowni w finansach i zapis mapowan</name>
+  <files>
+    autoload/Controllers/FinancesController.php,
+    templates/finances/main-view.php,
+    templates/finances/fakturownia-import-panel.php
+  </files>
+  <action>
+    1. Rozszerzyc `FinancesController` o akcje:
+       - pobranie brakujacych mapowan do widoku finansow,
+       - zapis mapowania klienta,
+       - zapis mapowania produktu/uslugi do kategorii,
+       - wszystkie zapisy z walidacja i `S::csrf_verify()`.
+    2. W `templates/finances/main-view.php` dolaczyc panel importu (partial) pokazujacy:
+       - liste nieprzypisanych klientow z Fakturowni + select klienta CRM,
+       - liste nieprzypisanych pozycji + select kategorii finansowej,
+       - status ostatniego importu (czas, liczba imported/skipped/unmapped).
+    3. W panelu uzyc escapingu danych wyjsciowych (np. `htmlspecialchars`) i komunikatow zgodnych z UI crmPRO.
+
+    Unikac: logiki biznesowej bezposrednio w widoku.
+  </action>
+  <verify>
+    - Wejscie na `/finances/main_view/` pokazuje panel mapowan bez regresji istniejacych statystyk.
+    - Zapis mapowania bez tokenu CSRF jest odrzucany.
+    - Po zapisaniu mapowania i ponownym imporcie dokument znika z listy brakow i tworzy operacje automatycznie.
+  </verify>
+  <done>AC-3 i AC-4 satisfied: mapowania sa obslugiwane z UI i kolejne faktury wpadaja automatycznie</done>
+</task>
+
+</tasks>
+
+<boundaries>
+
+## DO NOT CHANGE
+- modules niezwiązane z finansami (tasks, projects, wiki)
+- mechanizm logowania i sesji poza niezbednym CSRF check
+- istniejace endpointy email importera zadan
+
+## SCOPE LIMITS
+- Ten plan obejmuje tylko import i mapowania Fakturownia -> Finanse
+- Bez refaktoryzacji calego modulu finansow
+- Bez zmian w zewnetrznym harmonogramie systemowym (zakladamy, ze cron systemowy juz wywoluje `cron.php`)
+- Bez automatycznego tworzenia nowych klientow CRM (tylko mapowanie do istniejacych)
+
+</boundaries>
+
+<verification>
+Before declaring plan complete:
+- [ ] `.env.example` zawiera komplet nowych zmiennych Fakturowni
+- [ ] Importer obsluguje dokumenty przychodowe i kosztowe
+- [ ] Idempotencja blokuje duplikaty importu
+- [ ] Brakujace mapowania sa kolejkowane i widoczne w finansach
+- [ ] Zapis mapowan wymaga poprawnego tokenu CSRF
+- [ ] `php cron.php` wykonuje import bez zatrzymywania pozostalych krokow
+- [ ] All acceptance criteria met
+</verification>
+
+<success_criteria>
+- Faktury przychodowe i kosztowe importuja sie automatycznie po uzupelnieniu mapowan
+- Pierwszy import nie robi blednych przypisan: nieznane rekordy trafiaja do kolejki mapowania
+- Kolejne dokumenty z tym samym klientem i pozycja sa przypisywane bez interwencji recznej
+- Import uruchamia sie cyklicznie przez cron i jest bezpieczny na ponowne wykonanie
+</success_criteria>
+
+<output>
+After completion, create `.paul/phases/05-finances-fakturownia-import/05-01-SUMMARY.md`
+</output>