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

<objective>
## 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.
</objective>

<context>
## 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
</context>

<acceptance_criteria>

## AC-1: Proforma invoices are skipped during import
```gherkin
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
```gherkin
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
```gherkin
Given import pomija faktury proforma
When import kończy się
Then licznik skipped uwzględnia pominięte proformy
```

</acceptance_criteria>

<tasks>

<task type="auto">
  <name>Task 1: Dodać filtr proforma w processSingleDocument</name>
  <files>autoload/Domain/Finances/FakturowniaInvoiceImporter.php</files>
  <action>
    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'.
  </action>
  <verify>
    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
  </verify>
  <done>AC-1, AC-2, AC-3 satisfied: proformy pomijane, zwykłe faktury importowane, skipped zliczane</done>
</task>

</tasks>

<boundaries>

## 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

</boundaries>

<verification>
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
</verification>

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

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