Files

2026-04-03 14:53:58 +02:00

4.9 KiB

Raw Blame History

phase, plan, subsystem, tags, requires, provides, affects, tech-stack, key-files, key-decisions, patterns-established, duration, started, completed

phase

plan

subsystem

tags

requires

provides

affects

tech-stack

key-files

key-decisions

patterns-established

duration

started

completed

05-finances-fakturownia-import

finances

php

medoo

cron

fakturownia

import

phase	provides
01-sonarqube-baseline	baseline quality and project instrumentation

fakturownia api integration for income and cost invoices

persistent client and item mappings with unmapped queue

cron step for cyclical import with idempotency

finances

cron

fakturownia-import

added

patterns

repository for import state

importer service

controller actions with csrf

created

modified

autoload/Domain/Finances/FakturowniaApiClient.php

autoload/Domain/Finances/FakturowniaImportRepository.php

autoload/Domain/Finances/FakturowniaInvoiceImporter.php

templates/finances/fakturownia-import-panel.php

autoload/Controllers/FinancesController.php

autoload/Domain/Finances/FinanceRepository.php

autoload/class.Cron.php

cron.php

templates/finances/main-view.php

.env.example

Client mapping key supports id/tax/name with deterministic fallback order.

Invoice import is atomic per document (transaction per document).

Queue-first approach for missing mappings instead of creating partial operations.

Idempotency stored by external document key (type:id).

~1d

2026-04-02T09:00:00+02:00

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

4.9 KiB Raw Blame History