Kowal_Affiliate - instrukcja instalacji i konfiguracji

Ten dokument opisuje sposób instalacji, aktywacji i pierwszej konfiguracji modułu Kowal_Affiliate dla Magento 2. Instrukcja obejmuje zarówno wymagania techniczne, jak i praktyczne kroki potrzebne do uruchomienia programu afiliacyjnego w sklepie.

1. Wymagania systemowe

Moduł jest przeznaczony dla:

• Magento Open Source / Adobe Commerce 2.4.7+
• PHP 8.2 lub 8.3

W projekcie Magento powinny być dostępne co najmniej moduły:

• Magento_Store
• Magento_Cms
• Magento_Customer
• Magento_Email
• Magento_Quote
• Magento_Sales
• Magento_SalesRule
• Magento_Backend

2. Metody instalacji

Moduł można wdrożyć standardowo jako pakiet Composer.

2.1. Instalacja przez Composer

Moduł jest dystrybuowany jako pakiet Composer, przykładowy proces wygląda następująco:

composer require kowal/module-affiliate
bin/magento module:enable Kowal_Affiliate
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento cache:flush

2.3. Tryb produkcyjny

Jeśli sklep działa w production mode, po instalacji warto również wykonać:

bin/magento setup:static-content:deploy

3. Co tworzy moduł podczas instalacji

Podczas instalacji moduł:

• tworzy własne tabele bazy danych związane z afiliacją,
• rozszerza quote i sales_order o pola afiliacyjne,
• dodaje atrybuty klienta wykorzystywane do zarządzania afiliantem,
• tworzy domyślną stronę CMS programu partnerskiego,
• przygotowuje konfigurację systemową i cron jobs,
• rejestruje szablony maili i zasoby panelu administracyjnego.

3.1. Domyślna strona CMS

Po instalacji tworzona jest przykładowa strona programu partnerskiego:

identifier: affiliate-program
title: Affiliate Partnership Program

Strona ma charakter uniwersalny i może być użyta produkcyjnie po drobnej personalizacji treści.

Patch jest idempotentny:

• jeśli strona o tym identifier już istnieje, moduł jej nie nadpisze.

4. Gdzie znaleźć konfigurację modułu

Panel konfiguracji znajduje się w:

Stores -> Configuration -> Affiliate Program

Najważniejsze sekcje:

• General
• Commission
• Payouts
• Affiliate Portal
• Notifications
• Fraud
• AI
• Reporting

5. Pierwsza konfiguracja po instalacji

Po aktywacji modułu zalecany jest następujący porządek konfiguracji:

1. włącz moduł globalnie,
2. ustaw rejestrację afiliantów,
3. skonfiguruj prowizję i hold period,
4. ustaw minimalny próg wypłat,
5. uzupełnij treści portalu afilianta,
6. skonfiguruj powiadomienia administratora,
7. opcjonalnie skonfiguruj AI,
8. wykonaj test rejestracji, kliknięcia afiliacyjnego i zamówienia.

6. Szczegółowa konfiguracja

6.1. General

Enable Module

Globalny przełącznik modułu.

Jeśli ustawienie jest wyłączone:

• tracking afiliacyjny nie powinien działać,
• formularz rejestracji nie powinien działać,
• prowizje i payouty nie będą obsługiwane.

Rekomendacja:

• Yes na środowisku produkcyjnym po zakończeniu testów,
• No tylko na czas wyłączenia programu.

Enable Affiliate Registration

Włącza formularz zgłoszeniowy programu afiliacyjnego na froncie sklepu.

Jeśli opcja jest wyłączona:

• nowi partnerzy nie zarejestrują się samodzielnie,
• administrator nadal może ręcznie oznaczyć klienta jako afilianta.

Tracking Cookie Lifetime (days)

Określa czas życia atrybucji opartej o cookie po kliknięciu w link afiliacyjny.

Przykłady:

• 30 dla standardowego programu afiliacyjnego,
• 7 dla krótkich kampanii,
• 60 lub 90 tylko wtedy, gdy regulamin programu to przewiduje.

Default Redirect Path

Ścieżka zapasowa używana wtedy, gdy tracking link nie zawiera poprawnego target.

Przykłady:

• /
• promotions
• catalog/category/view/id/12

6.2. Commission

Enable Commissions

Włącza naliczanie prowizji dla zamówień afiliacyjnych.

Jeśli pole jest wyłączone:

• afiliacja może być zapisywana,
• ale wpis w tabeli prowizji nie zostanie utworzony.

Default Commission Rate (%)

Domyślna stawka prowizji procentowej.

Przykład:

• 10 oznacza prowizję 10% od aktualnej podstawy naliczania.

Commission Hold Period (days)

Liczba dni, przez które prowizja pozostaje w statusie oczekującym.

Po upływie tego okresu cron może automatycznie zatwierdzić prowizję.

Rekomendacja:

• 14 jako bezpieczna wartość domyślna,
• 0 tylko przy bardzo prostym programie bez ryzyka zwrotów.

6.3. Payouts

Enable Payouts

Włącza workflow wypłat dla afiliantów.

Jeśli opcja jest wyłączona:

• partner nie złoży wniosku o payout,
• administrator może nadal analizować prowizje, ale nie obsłuży wypłaty w module.

Minimum Payout Amount

Minimalne saldo wymagane do zgłoszenia wypłaty.

Przykłady:

• 100
• 250
• 500

6.4. Affiliate Portal

Ta sekcja kontroluje treści wyświetlane w dashboardzie afilianta.

Dashboard Intro

Krótki opis na górze dashboardu afilianta.

Powinien wyjaśniać partnerowi:

• gdzie znajdzie link afiliacyjny,
• gdzie zobaczy prowizje,
• jak działa panel.

Program Rules

Widoczne zasady współpracy dla afilianta.

Najlepiej wpisywać:

• jedną zasadę w jednej linii,
• zwięzłe i jednoznaczne komunikaty.

Banner Title

Domyślny tytuł przykładowego materiału promocyjnego.

Banner Subtitle

Krótki opis pod tytułem banera.

Banner Target Path

Domyślna ścieżka targetu dla linków afiliacyjnych i banerów.

Przykłady:

• /
• promotions/spring
• catalog/category/view/id/24

6.5. Notifications

Enable Notifications

Włącza wewnętrzny system powiadomień i kolejkę notyfikacji.

Admin Notification Email

Adres e-mail administratora, który ma otrzymywać najważniejsze komunikaty operacyjne.

Jeżeli pole pozostanie puste:

• moduł może używać domyślnego adresu general Magento jako fallback w wybranych flow.

Notification Log Retention (days)

Określa, jak długo wpisy w logu notyfikacji mają być przechowywane przed cleanupem.

6.6. Fraud

Enable Fraud Checks

Włącza podstawowe kontrole antyfraudowe.

Block Self Referral

Blokuje prowizję wtedy, gdy klient składający zamówienie jest jednocześnie afiliantem powiązanym z tym zamówieniem.

6.7. AI

Sekcja AI jest opcjonalna i nie jest wymagana do podstawowego działania programu afiliacyjnego.

Enable AI

Główny przełącznik funkcji AI.

OpenAI API Key

Klucz API do komunikacji z OpenAI.

Pole jest przechowywane w konfiguracji szyfrowanej.

AI Model Name

Model używany do funkcji AI.

Lista modeli może być pobierana z OpenAI po poprawnym zapisaniu klucza API.

OpenAI Request Timeout (seconds)

Maksymalny czas oczekiwania na odpowiedź z OpenAI.

Praktyczna rekomendacja:

• 60 sekund dla stabilniejszej pracy na produkcji.

Enable AI Diagnostic Logging

Włącza diagnostyczne logowanie requestów i odpowiedzi AI.

Przydatne w:

• integracji,
• testach,
• analizie timeoutów i błędów odpowiedzi.

AI Diagnostic Max Chars

Maksymalna długość logowanego preview payloadu.

Enable Affiliate Assistant

Włącza asystenta afilianta, jeśli sklep chce korzystać z tej funkcji.

Enable Weekly AI Reports

Pozwala generować cykliczne podsumowania AI.

Enable Product Knowledge Retrieval

Pozwala używać wiedzy produktowej z Vector Store.

Enable Program Knowledge Retrieval

Pozwala używać wiedzy o programie afiliacyjnym, FAQ i dokumentacji.

Product Vector Store Scope

Określa, jak rozwiązywany jest product_vector_store_id.

Product Vector Store ID

Identyfikator Vector Store, jeśli sklep korzysta z retrievalu.

Redact Personal Data

Usuwa lub maskuje dane osobowe przed wysłaniem promptu do warstwy AI.

6.8. Reporting

Enable Reporting

Włącza generowanie raportów i eksportów CSV.

Export Directory

Ścieżka katalogu, w którym mają być zapisywane wygenerowane eksporty.

Przykład:

var/export/affiliate

7. Konfiguracja klienta jako afilianta

Po instalacji moduł rozszerza edycję klienta Magento o pola afiliacyjne.

W edycji klienta można zarządzać między innymi:

• Affiliate Participant
• Affiliate Status
• Affiliate Referral Code
• Affiliate Website URL
• Affiliate Notes
• Affiliate Balance
• Affiliate Coupon Discount (%)

7.1. Affiliate Participant

Oznacza, czy klient należy do programu afiliacyjnego.

7.2. Affiliate Status

Najważniejsze statusy:

• Pending
• Active
• Suspended
• Rejected
• Blocked

7.3. Affiliate Balance

Saldo jest wyliczane automatycznie z prowizji zatwierdzonych i gotowych do wypłaty.

Pole:

• jest widoczne w edycji klienta,
• nie powinno być edytowane ręcznie,
• aktualizuje się automatycznie po zmianach prowizji.

7.4. Affiliate Coupon Discount (%)

To pole pozwala przypisać afiliantowi procent rabatu, który będzie działał na jego referral_code.

Jeśli wpiszesz wartość większą niż 0, moduł:

• utworzy lub zaktualizuje regułę koszykową Magento,
• ustawi kupon równy kodowi afilianta,
• umożliwi klientom używanie tego kodu jako kuponu w koszyku,
• przypisze zamówienie do afilianta na podstawie coupon_code.

Przykład:

• afiliant ma kod FMX1FBXXY3
• administrator wpisuje 5
• klient wpisuje FMX1FBXXY3 jako kupon rabatowy
• Magento nalicza 5% rabatu
• moduł przypisuje zamówienie do afilianta.

8. Cron jobs modułu

Moduł korzysta z cronów w grupie default.

8.1. Auto approve commissions

job: kowal_affiliate_auto_approve_commissions
schedule: */15 * * * *

Zadanie:

• sprawdza prowizje pending,
• po upływie hold period zmienia je na approved.

8.2. Process notifications

job: kowal_affiliate_process_notifications
schedule: */10 * * * *

Zadanie:

• przetwarza kolejkę powiadomień,
• oznacza wpisy jako wysłane,
• w przypadku kanału e-mail wysyła wiadomości transakcyjne.

8.3. Cleanup notification log

job: kowal_affiliate_cleanup_notification_log
schedule: 30 2 * * *

Zadanie:

• usuwa stare wpisy z logu powiadomień zgodnie z retencją.

8.4. Weekly AI insights

job: kowal_affiliate_generate_weekly_ai_insights
schedule: 0 6 * * 1

Zadanie:

• generuje tygodniowe insighty AI, jeśli funkcja jest aktywna.

9. Komendy CLI

Moduł udostępnia komendy serwisowe:

bin/magento kowal:affiliate:auto-approve
bin/magento kowal:affiliate:process-notifications
bin/magento kowal:affiliate:cleanup-notifications
bin/magento kowal:affiliate:generate-ai-insights
bin/magento kowal:affiliate:export-report

Najbardziej przydatne przy pierwszym uruchomieniu są:

bin/magento kowal:affiliate:process-notifications
bin/magento kowal:affiliate:auto-approve

10. Pierwszy test po instalacji

Po skonfigurowaniu modułu rekomendowany jest prosty test end-to-end.

10.1. Test rejestracji afilianta

1. Wejdź na formularz rejestracji afilianta.
2. Wyślij zgłoszenie.
3. Sprawdź, czy konto afilianta zostało utworzone.
4. Sprawdź, czy klient ma status Pending.
5. Sprawdź, czy powstały wpisy notyfikacji.

10.2. Test aktywacji

1. Otwórz edycję klienta w panelu admina.
2. Ustaw status afilianta na Active albo użyj akcji zatwierdzenia.
3. Sprawdź, czy klient widzi dashboard afilianta.

10.3. Test linku afiliacyjnego

1. Skopiuj link afiliacyjny z dashboardu.
2. Wejdź do sklepu przez ten link.
3. Dodaj produkt do koszyka.
4. Złóż zamówienie.
5. Sprawdź, czy zamówienie ma:
   • affiliate_id
   • affiliate_referral_code
   • is_affiliate_order = 1

10.4. Test kuponu afiliacyjnego

1. Ustaw afiliantowi Affiliate Coupon Discount (%), np. 5.
2. Zapisz klienta.
3. Upewnij się, że afiliant ma status Active.
4. W koszyku wpisz jego Referral Code jako kupon.
5. Złóż zamówienie.
6. Sprawdź:
   • czy rabat został naliczony,
   • czy zamówienie zostało przypisane afiliantowi,
   • czy utworzona została prowizja.

10.5. Test payoutów

1. Zatwierdź prowizję albo poczekaj na auto-approve.
2. Sprawdź saldo afilianta.
3. Złóż wniosek o wypłatę.
4. Oznacz payout jako opłacony w panelu admina.

11. Najczęstsze problemy po instalacji

11.1. Brak prowizji po zamówieniu

Sprawdź:

• czy zamówienie ma affiliate_id,
• czy włączone są prowizje,
• czy moduł działa po poprawce tworzenia prowizji po zapisaniu danych afiliacyjnych na orderze,
• czy w tabeli kowal_affiliate_commission pojawia się rekord.

11.2. Grid klientów nie pokazuje aktualnego salda afilianta

Sprawdź:

• czy indeks customer_grid został odświeżony,
• czy po zapisach działa reindexRow,
• czy wartość w edycji klienta zgadza się z wartością w gridzie.

Jeśli trzeba, uruchom:

bin/magento indexer:reindex customer_grid

11.3. AI nie odpowiada

Sprawdź:

• czy Enable AI jest włączone,
• czy zapisany został poprawny OpenAI API Key,
• czy wybrany został model,
• czy timeout nie jest zbyt niski,
• czy var/log nie pokazuje błędów requestu do OpenAI.

11.4. Powiadomienia nie są wysyłane

Sprawdź:

• czy działają crony Magento,
• czy Enable Notifications jest aktywne,
• czy wpisy są zapisywane do kowal_affiliate_notification_log,
• czy można ręcznie uruchomić:

bin/magento kowal:affiliate:process-notifications

12. Rekomendowana konfiguracja startowa

Dla pierwszego wdrożenia produkcyjnego rekomendowany jest taki zestaw:

• Enable Module = Yes
• Enable Affiliate Registration = Yes
• Tracking Cookie Lifetime = 30
• Enable Commissions = Yes
• Default Commission Rate = 10
• Commission Hold Period = 14
• Enable Payouts = Yes
• Minimum Payout Amount = 100
• Enable Notifications = Yes
• Block Self Referral = Yes
• Enable AI = No na start, jeśli sklep nie potrzebuje AI od pierwszego dnia

13. Podsumowanie

Po poprawnej instalacji i konfiguracji Kowal_Affiliate pozwala uruchomić w Magento 2 pełny program partnerski obejmujący:

• afiliantów,
• linki polecające,
• kody afiliacyjne,
• kupony rabatowe afiliantów,
• prowizje,
• payouty,
• powiadomienia,
• dashboard partnera,
• podstawowe bezpieczeństwo i automatyzację.