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

---
phase: 05-finances-fakturownia-import
plan: 06
type: execute
wave: 1
depends_on: []
files_modified:
  - autoload/Domain/Finances/FinanceRepository.php
  - autoload/Controllers/FinancesController.php
  - templates/finances/operation-edit.php
autonomous: true
delegation: off
---

<objective>
## Goal
Dodac w edycji operacji finansowej (tylko operacje z importu Fakturownia) opcje zmiany dopasowania pozycji faktury do kategorii oraz natychmiastowa zmiane kategorii biezacej operacji, z opcjonalnym masowym przepieciem pozostalych pasujacych operacji.

## Purpose
Po blednym przypisaniu pozycji faktury do kategorii uzytkownik ma szybko skorygowac mapowanie bez recznej edycji wielu rekordow.

## Output
- Rozszerzony formularz `operation-edit` o sekcje "Edycja dopasowania Fakturownia".
- Endpoint backendowy do zmiany mapowania itemu i przepiecia kategorii.
- Logika repozytorium do znalezienia operacji powiazanych z tym samym itemem oraz ich aktualizacji.
</objective>

<context>
<clarifications>
- **[Zakres]** - Czy funkcja ma dotyczyc tylko operacji z Fakturowni czy wszystkich?
  -> Odpowiedz: tylko operacje z Fakturowni; reczne zostaja ze standardowa zmiana kategorii.
- **[Skala]** - Czy po zmianie mapowania przepiac tez pozostale operacje z tym samym itemem?
  -> Odpowiedz: tak, mozna masowo przepiac pozostale pasujace.
- **[UI]** - Gdzie ma byc akcja?
  -> Odpowiedz: jako rozszerzenie istniejacej edycji operacji.
</clarifications>

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

## Prior Work
@.paul/phases/05-finances-fakturownia-import/05-05-SUMMARY.md

## Source Files
@autoload/Domain/Finances/FinanceRepository.php
@autoload/Controllers/FinancesController.php
@templates/finances/operation-edit.php
@autoload/Domain/Finances/FakturowniaImportRepository.php
</context>

<acceptance_criteria>

## AC-1: Widocznosc opcji tylko dla operacji z Fakturowni
```gherkin
Given uzytkownik otwiera /finances/operation_edit dla operacji recznej
When formularz edycji zostaje wyrenderowany
Then sekcja "Edycja dopasowania Fakturownia" nie jest widoczna
```

## AC-2: Zmiana dopasowania aktualizuje mapowanie i biezaca operacje
```gherkin
Given operacja pochodzi z Fakturowni i ma identyfikowalny external_item_key
When uzytkownik wybierze nowa kategorie i zapisze zmiane dopasowania
Then rekord w fakturownia_item_mappings otrzyma nowa finance_category_id
And aktualnie edytowana operacja dostanie nowa category_id
```

## AC-3: Masowe przepiecie pozostalych pasujacych operacji
```gherkin
Given istnieja inne operacje z tym samym external_item_key
When uzytkownik zaznaczy opcje masowego przepiecia
Then wszystkie pasujace operacje z importu Fakturownia otrzymaja nowa category_id
And operacje reczne nie zostana zmodyfikowane
```

## AC-4: Bezpieczny fallback
```gherkin
Given operacja nie ma powiazania z external_item_key
When uzytkownik probuje zapisac edycje dopasowania
Then system zwroci czytelny komunikat o braku mozliwosci zmiany dopasowania
And standardowa edycja operacji pozostaje bez regresji
```

</acceptance_criteria>

<tasks>

<task type="auto">
  <name>Task 1: Dodac identyfikacje powiazania operacji z itemem Fakturownia</name>
  <files>autoload/Domain/Finances/FinanceRepository.php</files>
  <action>
    Dodac metody repozytorium, ktore:
    - dla operation_id odczytaja dokument importu Fakturownia z `fakturownia_imported_documents`,
    - z `meta_json` wyciagna item_key odpowiadajacy tej operacji,
    - zwroca dane niezbedne do edycji dopasowania (external_item_key, external_name, czy masowe przepiecie jest mozliwe).
    Dodatkowo dodac metode aktualizujaca category_id dla:
    - biezacej operacji,
    - opcjonalnie wszystkich operacji powiazanych z tym samym item_key (tylko import Fakturownia).
    Unikaj: SQL string concatenation; tylko medoo/prepared statements.
  </action>
  <verify>php -l autoload/Domain/Finances/FinanceRepository.php</verify>
  <done>AC-2 i AC-3 maja pokrycie po stronie danych</done>
</task>

<task type="auto">
  <name>Task 2: Dodac endpoint kontrolera do zapisu edycji dopasowania</name>
  <files>autoload/Controllers/FinancesController.php</files>
  <action>
    Dodac nowa akcje kontrolera (POST) z walidacja CSRF i danych:
    - operation_id, finance_category_id, apply_to_all (0/1),
    - sprawdzenie istnienia kategorii,
    - sprawdzenie czy operacja jest powiazana z itemem Fakturownia.
    Akcja ma:
    - zaktualizowac `fakturownia_item_mappings`,
    - przepiac kategorie w `finance_operations` (biezaca + opcjonalnie masowo),
    - zwrocic jasny komunikat sukcesu/bledu i redirect do listy operacji.
  </action>
  <verify>php -l autoload/Controllers/FinancesController.php</verify>
  <done>AC-2 i AC-4 spelnione po stronie backendu</done>
</task>

<task type="auto">
  <name>Task 3: Rozszerzyc formularz operation-edit o edycje dopasowania Fakturownia</name>
  <files>templates/finances/operation-edit.php</files>
  <action>
    W formularzu edycji:
    - wyswietlic dodatkowa sekcje tylko, gdy operacja ma powiazanie z itemem Fakturownia,
    - dodac select kategorii + checkbox "przepnij wszystkie pasujace operacje",
    - dodac submit kierowany do nowej akcji kontrolera.
    Dla operacji recznych nic nie zmieniac wizualnie ani funkcjonalnie.
  </action>
  <verify>php -l templates/finances/operation-edit.php</verify>
  <done>AC-1 i AC-3 spelnione w UI</done>
</task>

</tasks>

<boundaries>

## DO NOT CHANGE
- Logika importu dokumentow Fakturownia (cron + importer).
- Istniejaca standardowa akcja `operation_save` i reczna edycja operacji.
- Moduly poza finansami.

## SCOPE LIMITS
- Brak zmian dla operacji recznych poza obecna mozliwoscia recznej zmiany kategorii.
- Brak migracji schematu DB.
- Brak zmian w raportach i podsumowaniach finansowych.

</boundaries>

<verification>
Before declaring plan complete:
- [ ] `php -l` dla wszystkich zmienionych plikow
- [ ] Reczna proba: operacja z Fakturowni - zmiana dopasowania aktualizuje kategorie biezaca
- [ ] Reczna proba: zaznaczone masowe przepiecie zmienia pozostale pasujace operacje
- [ ] Reczna proba: operacja reczna nie pokazuje nowej sekcji
- [ ] Wszystkie AC spelnione
</verification>

<success_criteria>
- Uzytkownik moze poprawic bledne dopasowanie kategorii bez opuszczania edycji operacji.
- Zmiana mapowania od razu poprawia kategorie na aktualnej operacji.
- Masowe przepiecie dziala tylko dla operacji z tym samym itemem Fakturownia.
- Brak regresji dla recznej edycji operacji.
</success_criteria>

<output>
Po wykonaniu utworz `.paul/phases/05-finances-fakturownia-import/05-06-SUMMARY.md`.
</output>