feat(05-finances): filtr proforma w imporcie Fakturowni
Phase 5 Plan 03 complete: - Dodano isProformaDocument() — pomija faktury proforma (kind=proforma lub prefiks FP) - Wywolanie w processSingleDocument() przed normalizeDocument() - Phase 5 complete: import Fakturowni z mapowaniem NIP i filtrem proforma Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
123
.paul/phases/05-finances-fakturownia-import/05-03-PLAN.md
Normal file
123
.paul/phases/05-finances-fakturownia-import/05-03-PLAN.md
Normal file
@@ -0,0 +1,123 @@
|
||||
---
|
||||
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>
|
||||
93
.paul/phases/05-finances-fakturownia-import/05-03-SUMMARY.md
Normal file
93
.paul/phases/05-finances-fakturownia-import/05-03-SUMMARY.md
Normal file
@@ -0,0 +1,93 @@
|
||||
---
|
||||
phase: 05-finances-fakturownia-import
|
||||
plan: 03
|
||||
subsystem: finances
|
||||
tags: [fakturownia, proforma, import, filter]
|
||||
|
||||
requires:
|
||||
- phase: 05-finances-fakturownia-import
|
||||
provides: FakturowniaInvoiceImporter with full import pipeline
|
||||
provides:
|
||||
- Proforma invoice filter in Fakturownia import
|
||||
affects: []
|
||||
|
||||
tech-stack:
|
||||
added: []
|
||||
patterns: [envelope-unwrap pattern consistent with existing methods]
|
||||
|
||||
key-files:
|
||||
created: []
|
||||
modified: [autoload/Domain/Finances/FakturowniaInvoiceImporter.php]
|
||||
|
||||
key-decisions:
|
||||
- "Filter by both API kind field AND number prefix FP for robustness"
|
||||
|
||||
patterns-established: []
|
||||
|
||||
duration: 3min
|
||||
started: 2026-04-11T00:00:00Z
|
||||
completed: 2026-04-11T00:00:00Z
|
||||
---
|
||||
|
||||
# Phase 5 Plan 03: Filtr proforma Summary
|
||||
|
||||
**Dodano filtr pomijający faktury proforma (kind=proforma lub numer FP*) w imporcie z Fakturowni.**
|
||||
|
||||
## Performance
|
||||
|
||||
| Metric | Value |
|
||||
|--------|-------|
|
||||
| Duration | ~3min |
|
||||
| Tasks | 1 completed |
|
||||
| Files modified | 1 |
|
||||
|
||||
## Acceptance Criteria Results
|
||||
|
||||
| Criterion | Status | Notes |
|
||||
|-----------|--------|-------|
|
||||
| AC-1: Proforma invoices are skipped | Pass | isProformaDocument() checks kind + FP prefix |
|
||||
| AC-2: Regular invoices still import | Pass | Method returns false for non-proforma docs |
|
||||
| AC-3: Skipped proforma counted in summary | Pass | Returns 'skipped' — counted in existing summary counter |
|
||||
|
||||
## Accomplishments
|
||||
|
||||
- Added `isProformaDocument()` method with dual detection: `kind === 'proforma'` and number prefix `FP` (case-insensitive)
|
||||
- Integrated filter call in `processSingleDocument()` after `matchesDocumentType()`, before `normalizeDocument()`
|
||||
- PHP syntax verified clean
|
||||
|
||||
## Files Created/Modified
|
||||
|
||||
| File | Change | Purpose |
|
||||
|------|--------|---------|
|
||||
| `autoload/Domain/Finances/FakturowniaInvoiceImporter.php` | Modified | Added isProformaDocument() method and call in processSingleDocument() |
|
||||
|
||||
## Decisions Made
|
||||
|
||||
| Decision | Rationale | Impact |
|
||||
|----------|-----------|--------|
|
||||
| Dual detection (kind + FP prefix) | API may not always populate kind field; prefix is reliable fallback | More robust filtering |
|
||||
| Filter before normalizeDocument | Avoids unnecessary API calls for invoice details on proforma docs | Better performance |
|
||||
|
||||
## Deviations from Plan
|
||||
|
||||
None — plan executed exactly as written.
|
||||
|
||||
## Issues Encountered
|
||||
|
||||
None.
|
||||
|
||||
## Next Phase Readiness
|
||||
|
||||
**Ready:**
|
||||
- Fakturownia import now correctly skips proforma invoices
|
||||
- Phase 5 scope complete (05-01 base import, 05-02 NIP mapping, 05-03 proforma filter)
|
||||
|
||||
**Concerns:**
|
||||
- None
|
||||
|
||||
**Blockers:**
|
||||
- None
|
||||
|
||||
---
|
||||
*Phase: 05-finances-fakturownia-import, Plan: 03*
|
||||
*Completed: 2026-04-11*
|
||||
Reference in New Issue
Block a user