---
phase: 56-order-payments
plan: 01
type: execute
wave: 1
depends_on: []
files_modified:
  - database/migrations/20260330_000073_create_order_payments_table.sql
  - src/Modules/Orders/OrdersController.php
  - src/Modules/Orders/OrdersRepository.php
  - src/Modules/Settings/ShopproApiClient.php
  - resources/views/orders/show.php
  - resources/lang/pl.php
  - resources/scss/modules/_order-details.scss
  - public/assets/css/app.css
  - routes/web.php
  - DOCS/DB_SCHEMA.md
  - DOCS/ARCHITECTURE.md
  - DOCS/TECH_CHANGELOG.md
autonomous: false
---

<objective>
## Goal
Uruchomienie funkcji dodawania platnosci do zamowienia z poziomu zakladki Platnosci w widoku zamowienia. Po dodaniu platnosci — automatyczny push statusu platnosci do shopPRO API (dla zamowien source=shoppro).

## Purpose
Sprzedawca moze oznaczyc zamowienie jako oplacone bezposrednio z orderPRO i ta informacja jest synchronizowana do sklepu shopPRO.

## Output
- Tabela `order_payments` w bazie (migracja)
- Formularz dodawania platnosci w zakladce Platnosci
- Endpoint POST `/orders/{id}/payment/add`
- Push `set_paid` do shopPRO API po dodaniu platnosci (source=shoppro)
</objective>

<context>
## Project Context
@.paul/PROJECT.md
@.paul/ROADMAP.md
@.paul/STATE.md

## Source Files
@database/drafts/20260302_orders_schema_v1.sql (linie 102-121 — draft schemat order_payments)
@src/Modules/Orders/OrdersController.php
@src/Modules/Orders/OrdersRepository.php (loadOrderPayments, findDetails)
@src/Modules/Orders/OrderImportRepository.php (replacePayments)
@src/Modules/Settings/ShopproPaymentStatusSyncService.php (wzorzec update + push)
@src/Modules/Settings/ShopproApiClient.php (requestJsonPut)
@src/Modules/Settings/ShopproIntegrationsRepository.php
@resources/views/orders/show.php (zakladka Platnosci linie 559-648)
@routes/web.php (pattern: /orders/{id}/...)
</context>

<acceptance_criteria>

## AC-1: Tabela order_payments istnieje w bazie
```gherkin
Given migracja 20260330_000073 zostala uruchomiona
When wykonam SHOW CREATE TABLE order_payments
Then tabela zawiera kolumny: id, order_id, source_payment_id, external_payment_id, payment_type_id, payment_date, amount, currency, comment, payload_json, created_at, updated_at
And istnieje FK na orders(id) z ON DELETE CASCADE
```

## AC-2: Formularz dodawania platnosci w zakladce Platnosci
```gherkin
Given otwieram zamowienie /orders/130
When klikam zakladke Platnosci
Then widze przycisk "Dodaj platnosc" nad tabela platnosci
And po kliknieciu pojawia sie formularz inline z polami: kwota, typ platnosci (select), data platnosci, komentarz
And formularz zawiera przyciski Zapisz i Anuluj
```

## AC-3: Zapis platnosci przez AJAX
```gherkin
Given wypelniam formularz platnosci (kwota, typ, data)
When klikam Zapisz
Then platnosc jest zapisana w tabeli order_payments
And kolumny orders.payment_status i orders.total_paid sa zaktualizowane
And zakladka Platnosci odswieza sie z nowa platnoscia na liscie
And pojawia sie komunikat sukcesu
```

## AC-4: Push set_paid do shopPRO po dodaniu platnosci
```gherkin
Given zamowienie ma source=shoppro i polaczona integracje
When dodaje platnosc pokrywajaca pelna kwote zamowienia
Then orderPRO wywoluje PUT shopPRO API /api.php?endpoint=orders&action=set_paid&id={source_order_id}
And w activity_log zapisuje informacje o pushu
```

## AC-5: Walidacja formularza
```gherkin
Given otwieram formularz dodawania platnosci
When probuje zapisac bez kwoty lub z kwota <= 0
Then formularz nie jest wysylany i pojawia sie komunikat bledu walidacji
```

</acceptance_criteria>

<tasks>

<task type="auto">
  <name>Task 1: Migracja order_payments + update orders columns</name>
  <files>database/migrations/20260330_000073_create_order_payments_table.sql, DOCS/DB_SCHEMA.md</files>
  <action>
    Utworz migracje tworzaca tabele order_payments na podstawie draftu (database/drafts/20260302_orders_schema_v1.sql linie 102-121).
    Uzyj CREATE TABLE IF NOT EXISTS — migracja idempotentna.
    Schemat: id, order_id, source_payment_id, external_payment_id, payment_type_id, payment_date, amount, currency, comment, payload_json, created_at, updated_at.
    Indexy: UNIQUE (order_id, source_payment_id), INDEX (order_id), INDEX (payment_date).
    FK: order_payments_order_fk -> orders(id) ON DELETE CASCADE ON UPDATE CASCADE.

    Sprawdz tez czy kolumny payment_status, total_paid, external_payment_type_id istnieja w tabeli orders. Jezeli nie — dodaj ALTER TABLE (idempotentnie przez IF NOT EXISTS pattern z prepared statements).

    Zaktualizuj DOCS/DB_SCHEMA.md o nowa tabele.
  </action>
  <verify>Uruchom migracje na serwerze: sprawdz SHOW CREATE TABLE order_payments</verify>
  <done>AC-1 satisfied: tabela order_payments istnieje z poprawnym schematem</done>
</task>

<task type="auto">
  <name>Task 2: Backend — endpoint dodawania platnosci + push do shopPRO</name>
  <files>src/Modules/Orders/OrdersController.php, src/Modules/Orders/OrdersRepository.php, src/Modules/Settings/ShopproApiClient.php, routes/web.php, resources/lang/pl.php, DOCS/ARCHITECTURE.md</files>
  <action>
    1. W routes/web.php dodaj route:
       POST /orders/{id}/payment/add -> OrdersController->addPayment

    2. W OrdersRepository dodaj metode addPayment(int $orderId, array $data): int
       - INSERT INTO order_payments (order_id, payment_type_id, payment_date, amount, currency, comment)
       - Przelicz total_paid: SELECT SUM(amount) FROM order_payments WHERE order_id
       - UPDATE orders SET total_paid = sum, payment_status = (2 jesli sum >= total_with_tax, 1 jesli sum > 0, 0 jesli sum = 0)
       - Zwroc nowy payment ID

    3. W OrdersController dodaj metode addPayment(Request $request): Response
       - Walidacja: orderId > 0, amount > 0, payment_type_id niepusty
       - CSRF token
       - Wywolaj OrdersRepository::addPayment()
       - Jezeli zamowienie ma source=shoppro i payment_status stalo sie 2 (oplacone):
         - Pobierz dane integracji (integration_id z zamowienia)
         - Wywolaj ShopproApiClient::pushPaymentPaid() do set_paid
         - Zaloguj w activity_log
       - Return JSON response {ok, payment, payment_status, total_paid}

    4. W ShopproApiClient dodaj metode pushPaymentPaid(string $baseUrl, string $apiKey, int $timeout, string $sourceOrderId): array
       - PUT {baseUrl}/api.php?endpoint=orders&action=set_paid&id={sourceOrderId}
       - Body: {"send_email": 0}
       - Uzyj istniejacego requestJsonPut()

    5. Zaktualizuj resources/lang/pl.php o klucze bledow/komunikatow platnosci.

    6. Zaktualizuj DOCS/ARCHITECTURE.md.
  </action>
  <verify>
    curl -X POST /orders/130/payment/add z danymi platnosci — odpowiedz 200 z JSON
  </verify>
  <done>AC-3, AC-4, AC-5 satisfied: platnosc zapisywana, push do shopPRO, walidacja</done>
</task>

<task type="auto">
  <name>Task 3: Frontend — formularz platnosci w zakladce + AJAX</name>
  <files>resources/views/orders/show.php, resources/scss/modules/_order-details.scss, public/assets/css/app.css</files>
  <action>
    1. W show.php, w sekcji data-order-tab-panel="payments" (linia ~606):
       - Dodaj przycisk "Dodaj platnosc" (klasa btn btn--sm btn--primary) nad tabela/komunikatem "Brak platnosci"
       - Po kliknieciu — pokaz formularz inline (ukryty domyslnie):
         - Kwota (input number, step=0.01, required) — domyslna: total_with_tax - total_paid
         - Typ platnosci (select: ONLINE, TRANSFER, CASH_ON_DELIVERY)
         - Data platnosci (input date, domyslna: dzisiaj)
         - Komentarz (input text, opcjonalny)
         - Przyciski: Zapisz (submit AJAX), Anuluj (ukryj formularz)

    2. JavaScript na dole widoku (pattern jak inne formularze AJAX w tym pliku):
       - POST /orders/{orderId}/payment/add
       - Wysylaj JSON: {amount, payment_type_id, payment_date, comment, _token}
       - On success: window.location.reload() dla odswiezenia karty
       - On error: pokaz blad przez OrderProAlerts.error()

    3. Style w _order-details.scss:
       - .payment-add-form — kompaktowy formularz inline
       - .payment-add-form__row — flex row z gap
       - Responsywnosc (na mobile kolumny zawijaja sie)

    4. Zbuduj SCSS: npm run build (lub sass compile)
  </action>
  <verify>
    Otworz /orders/130, kliknij Platnosci, kliknij "Dodaj platnosc", wypelnij formularz, zapisz — platnosc pojawia sie na liscie
  </verify>
  <done>AC-2, AC-3 satisfied: formularz widoczny, zapis dziala, lista odswieza sie</done>
</task>

<task type="checkpoint:human-verify" gate="blocking">
  <what-built>Formularz dodawania platnosci + push do shopPRO</what-built>
  <how-to-verify>
    1. Otworz: https://orderpro.projectpro.pl/orders/130
    2. Kliknij zakladke "Platnosci"
    3. Kliknij "Dodaj platnosc"
    4. Wypelnij kwote (np. 100.00), wybierz typ "Platnosc online", data dzisiejsza
    5. Kliknij "Zapisz"
    6. Sprawdz: platnosc pojawia sie w tabeli, status platnosci zaktualizowal sie
    7. Sprawdz shopPRO: czy zamowienie zostalo oznaczone jako oplacone
    8. Sprobuj dodac platnosc z kwota 0 — powinien byc blad walidacji
  </how-to-verify>
  <resume-signal>Type "approved" to continue, or describe issues to fix</resume-signal>
</task>

</tasks>

<boundaries>

## DO NOT CHANGE
- src/Modules/Settings/ShopproPaymentStatusSyncService.php (istniejacy cron sync — nie modyfikowac)
- src/Modules/Orders/OrderImportRepository.php (import platnosci z API — nie modyfikowac)
- database/migrations/ istniejace migracje (nie modyfikowac)
- src/Modules/Cron/* (nie modyfikowac handlerow crona)

## SCOPE LIMITS
- Tylko dodawanie platnosci — nie edycja ani usuwanie
- Nie implementujemy zwrotow (refunds)
- Push do shopPRO tylko przez istniejace API set_paid — nie dodajemy nowego endpointu w shopPRO
- Nie modyfikujemy synchronizacji platnosci Allegro
- Nie dodajemy nowych cron jobow

</boundaries>

<verification>
Before declaring plan complete:
- [ ] Migracja uruchomiona — tabela order_payments istnieje
- [ ] POST /orders/{id}/payment/add zwraca 200 z poprawnymi danymi
- [ ] Formularz w UI wyswietla sie poprawnie
- [ ] Platnosc zapisana w order_payments
- [ ] orders.payment_status i total_paid zaktualizowane
- [ ] Push set_paid do shopPRO (source=shoppro) dziala
- [ ] Walidacja formularza — kwota > 0, typ niepusty
- [ ] DOCS zaktualizowane
- [ ] SCSS zbudowany do CSS
</verification>

<success_criteria>
- Wszystkie taski ukonczone
- Wszystkie AC spelnione
- Platnosc dodana z UI pojawia sie w zakladce Platnosci
- shopPRO otrzymuje informacje o oplaceniu
- Brak bledow PHP/JS w konsoli
</success_criteria>

<output>
After completion, create `.paul/phases/56-order-payments/56-01-SUMMARY.md`
</output>
