122 lines
4.9 KiB
Markdown
122 lines
4.9 KiB
Markdown
---
|
|
phase: 05-finances-fakturownia-import
|
|
plan: 01
|
|
subsystem: finances
|
|
tags: [php, medoo, cron, fakturownia, import]
|
|
requires:
|
|
- phase: 01-sonarqube-baseline
|
|
provides: baseline quality and project instrumentation
|
|
provides:
|
|
- fakturownia api integration for income and cost invoices
|
|
- persistent client and item mappings with unmapped queue
|
|
- cron step for cyclical import with idempotency
|
|
affects: [finances, cron, fakturownia-import]
|
|
tech-stack:
|
|
added: []
|
|
patterns: [repository for import state, importer service, controller actions with csrf]
|
|
key-files:
|
|
created:
|
|
- autoload/Domain/Finances/FakturowniaApiClient.php
|
|
- autoload/Domain/Finances/FakturowniaImportRepository.php
|
|
- autoload/Domain/Finances/FakturowniaInvoiceImporter.php
|
|
- templates/finances/fakturownia-import-panel.php
|
|
modified:
|
|
- autoload/Controllers/FinancesController.php
|
|
- autoload/Domain/Finances/FinanceRepository.php
|
|
- autoload/class.Cron.php
|
|
- cron.php
|
|
- templates/finances/main-view.php
|
|
- .env.example
|
|
key-decisions:
|
|
- "Client mapping key supports id/tax/name with deterministic fallback order."
|
|
- "Invoice import is atomic per document (transaction per document)."
|
|
patterns-established:
|
|
- "Queue-first approach for missing mappings instead of creating partial operations."
|
|
- "Idempotency stored by external document key (type:id)."
|
|
duration: ~1d
|
|
started: 2026-04-02T09:00:00+02:00
|
|
completed: 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*
|