crmPRO/.paul/phases/05-finances-fakturownia-import/05-03-PLAN.md

phase, plan, type, wave, depends_on, files_modified, autonomous, delegation

phase	plan	type	wave	depends_on	files_modified	autonomous	delegation
05-finances-fakturownia-import	03	execute	1	05-01 05-02	autoload/Domain/Finances/FakturowniaInvoiceImporter.php	true	off

## Goal Wykluczyć faktury proforma (np. FP2026/04/003) z importu Fakturowni, aby do finansów CRM trafiały tylko właściwe faktury.

Purpose

Faktury proforma to dokumenty informacyjne, nie są dokumentami księgowymi. Ich import zawyża dane finansowe i powoduje duplikaty po wystawieniu właściwej faktury.

Output

Zmodyfikowany FakturowniaInvoiceImporter.php z filtrem pomijającym dokumenty proforma.

## Project Context @.paul/PROJECT.md @.paul/ROADMAP.md

Prior Work

@.paul/phases/05-finances-fakturownia-import/05-01-SUMMARY.md — bazowa logika importu @.paul/phases/05-finances-fakturownia-import/05-02-SUMMARY.md — mapowanie po NIP

Source Files

@autoload/Domain/Finances/FakturowniaInvoiceImporter.php

<acceptance_criteria>

AC-1: Proforma invoices are skipped during import

Given API Fakturowni zwraca dokument z kind="proforma" lub numerem zaczynającym się od "FP"
When importer przetwarza ten dokument
Then dokument jest pomijany (skipped) i nie trafia do finance_operations

AC-2: Regular invoices still import correctly

Given API Fakturowni zwraca zwykłą fakturę (kind="vat" lub numer bez prefiksu "FP")
When importer przetwarza ten dokument
Then dokument jest importowany normalnie jak dotychczas

AC-3: Skipped proforma counted in summary

Given import pomija faktury proforma
When import kończy się
Then licznik skipped uwzględnia pominięte proformy

</acceptance_criteria>

Task 1: Dodać filtr proforma w processSingleDocument autoload/Domain/Finances/FakturowniaInvoiceImporter.php Dodać prywatną metodę `isProformaDocument($rawDocument)` która zwraca true gdy: - pole `kind` === 'proforma' (API Fakturowni zwraca to pole) - LUB numer dokumentu (pole `number` lub `full_number`) zaczyna się od "FP" (case-insensitive)

W metodzie `processSingleDocument()` dodać sprawdzenie zaraz po `matchesDocumentType()` (linia ~117-118):
```php
if ( $this->isProformaDocument( $rawDocument ) )
  return 'skipped';
```

Metoda `isProformaDocument` powinna unwrapować envelope `$rawDocument['invoice']` tak jak inne metody (matchesDocumentType, isDateRelevantForImport).

Avoid: Nie modyfikować logiki matchesDocumentType ani normalizeDocument.
Avoid: Nie dodawać nowego klucza do summary — proformy idą do istniejącego 'skipped'.

1. Przegląd kodu — metoda isProformaDocument istnieje i jest wywoływana w processSingleDocument 2. Sprawdzenie logiki: kind=proforma → true, numer FP... → true, zwykła faktura → false 3. php -l autoload/Domain/Finances/FakturowniaInvoiceImporter.php — brak błędów składniowych AC-1, AC-2, AC-3 satisfied: proformy pomijane, zwykłe faktury importowane, skipped zliczane

DO NOT CHANGE

• autoload/Domain/Finances/FakturowniaApiClient.php (warstwa API bez zmian)
• autoload/Domain/Finances/FakturowniaImportRepository.php (warstwa persystencji bez zmian)
• Logika matchesDocumentType, normalizeDocument, buildClientKey (stabilna, przetestowana)

SCOPE LIMITS

• Tylko filtr proforma — nie dodajemy filtrów na inne typy dokumentów (korekty, zaliczki itp.)
• Nie zmieniamy struktury summary ani formatu komunikatu

Before declaring plan complete: - [ ] php -l autoload/Domain/Finances/FakturowniaInvoiceImporter.php — brak błędów - [ ] Metoda isProformaDocument poprawnie rozpoznaje kind=proforma i prefiks FP - [ ] processSingleDocument wywołuje isProformaDocument przed normalizeDocument - [ ] Zwykłe faktury (kind=vat, numer FV...) przechodzą bez zmian - [ ] All acceptance criteria met

<success_criteria>

• Metoda isProformaDocument dodana i wywoływana
• Dokumenty proforma (kind=proforma lub numer FP*) pomijane podczas importu
• Brak regresji w imporcie zwykłych faktur
• Brak błędów składniowych PHP </success_criteria>

After completion, create `.paul/phases/05-finances-fakturownia-import/05-03-SUMMARY.md`