orderPRO/.paul/phases/56-order-payments/56-01-PLAN.md

phase, plan, type, wave, depends_on, files_modified, autonomous

phase	plan	type	wave	depends_on	files_modified	autonomous
56-order-payments	01	execute	1		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	false

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

## 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}/...)

<acceptance_criteria>

AC-1: Tabela order_payments istnieje w bazie

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

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

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

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

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>

Task 1: Migracja order_payments + update orders columns database/migrations/20260330_000073_create_order_payments_table.sql, DOCS/DB_SCHEMA.md 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.

Uruchom migracje na serwerze: sprawdz SHOW CREATE TABLE order_payments AC-1 satisfied: tabela order_payments istnieje z poprawnym schematem Task 2: Backend — endpoint dodawania platnosci + push do shopPRO 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 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.

curl -X POST /orders/130/payment/add z danymi platnosci — odpowiedz 200 z JSON AC-3, AC-4, AC-5 satisfied: platnosc zapisywana, push do shopPRO, walidacja Task 3: Frontend — formularz platnosci w zakladce + AJAX resources/views/orders/show.php, resources/scss/modules/_order-details.scss, public/assets/css/app.css 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)

Otworz /orders/130, kliknij Platnosci, kliknij "Dodaj platnosc", wypelnij formularz, zapisz — platnosc pojawia sie na liscie AC-2, AC-3 satisfied: formularz widoczny, zapis dziala, lista odswieza sie Formularz dodawania platnosci + push do shopPRO 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 Type "approved" to continue, or describe issues to fix

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

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

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

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