orderPRO/.serena/memories/gs1-integration/plan.md

Plan integracji MojeGS1 API - przypisywanie EAN z poziomu orderPRO

Cel

Przycisk "Przypisz EAN z GS1" na stronie szczegółów produktu (/products/{id}), który automatycznie generuje kolejny EAN z puli GS1, rejestruje produkt w MojeGS1 i zapisuje EAN lokalnie.

API MojeGS1 v2

• Base URL: https://mojegs1.pl/api/v2
• Auth: HTTP Basic (login + hasło)
• Spec: /api/v2/swagger/external-api/swagger.json

Endpointy używane:

• GET /api/v2/products?page[offset]=X&page[limit]=100&sort=name — lista produktów (paginacja)
• GET /api/v2/products/{Gtin} — pojedynczy produkt
• PUT /api/v2/products/{Gtin} — utwórz/aktualizuj produkt

Wymagane pola PUT:

• brandName (2-200 znaków) — marka
• gpcCode (8-cyfrowy int) — kod klasyfikacji GPC
• netContent (number) + netContentUnit (string: szt, kg, g, l, ml, m, cm, mm, m2, m3)
• status — "ACT" / "WIT" / "HID"
• targetMarket — array, np. ["PL"]
• descriptionLanguage — "PL"
• description — opis (20-4000 znaków, opcjonalne ale zalecane)
• commonName — nazwa zwyczajowa (do 150 znaków)

Struktura request PUT:

{
  "data": {
    "type": "products",
    "id": "{GTIN-13}",
    "attributes": {
      "brandName": "marianek.pl",
      "commonName": "Nazwa produktu",
      "gpcCode": 10008365,
      "netContent": 1,
      "netContentUnit": "szt",
      "status": "ACT",
      "targetMarket": ["PL"],
      "descriptionLanguage": "PL"
    }
  }
}

Stan konta GS1

• 461 produktów zarejestrowanych
• Główny prefiks: 590532390 (9 cyfr, 451 produktów, ciągła sekwencja 000-450)
• Drugi prefiks: 590531617 (10 produktów, starsze)
• Najwyższy GTIN: 5905323904507 (item 450)
• Następny wolny: 5905323904514 (item 451)
• Max capacity: 1000 produktów (item 000-999)

Dane dostępowe API

• Login: user_85c27342-bc97-4f42-8890-f6b27d3233c4
• Hasło: K3sawGA3X?L?e^bJ$ZqyhieFG)w#c8f+?V^z
• UWAGA: dane przechowywane w tabeli app_settings, NIE w kodzie

Plan implementacji

Krok 1: Tabela app_settings — migracja

Plik: database/migrations/20260224_000013_add_gs1_settings.sql Dodać rekordy do app_settings:

• gs1_api_login — login API
• gs1_api_password — hasło API (zaszyfrowane lub plain — zależy od obecnego wzorca)
• gs1_prefix — prefiks GS1 (domyślnie 590532390)
• gs1_default_brand — domyślna marka (domyślnie marianek.pl)
• gs1_default_gpc_code — domyślny kod GPC (domyślnie 10008365)

Sprawdzić czy tabela app_settings już istnieje (migracja 000012).

Krok 2: Strona ustawień GS1

Plik widoku: resources/views/settings/gs1.php Pliki PHP: zmiana w SettingsController.php — dodać metody gs1() i gs1Save() Route: GET /settings/gs1 + POST /settings/gs1

Formularz z polami: login, hasło, prefiks, domyślna marka, domyślny kod GPC. Przycisk "Test połączenia" (opcjonalnie).

Krok 3: Klient MojeGS1

Plik: src/Modules/GS1/MojeGS1Client.php

Metody:

• listProducts(int $page, int $limit): array — lista produktów
• getProduct(string $gtin): ?array — pojedynczy produkt
• upsertProduct(string $gtin, array $attributes): array — PUT produkt
• findHighestGtin(string $prefix): ?string — paginuje i szuka max GTIN z prefiksu
• generateNextEan(string $prefix): string — oblicza kolejny EAN z cyfrą kontrolną

Statyczna metoda:

• calculateEan13CheckDigit(string $partial12): int

Krok 4: Serwis GS1

Plik: src/Modules/GS1/GS1Service.php

Metoda: assignEanToProduct(int $productId): array

1. Pobierz produkt z orderPRO (sprawdź czy nie ma już EAN)
2. Pobierz ustawienia GS1 z app_settings
3. Znajdź najwyższy GTIN w GS1 API
4. Wygeneruj następny EAN
5. Zarejestruj w GS1 (PUT) z danymi produktu (nazwa, marka, gpcCode)
6. Zaktualizuj EAN w produkcie orderPRO
7. Zwróć nowy EAN

Krok 5: Controller endpoint

Plik: src/Modules/Products/ProductsController.php Nowa metoda: assignGs1Ean(Request $request): Response Route: POST /products/{id}/assign-ean

• Walidacja CSRF
• Wywołanie GS1Service::assignEanToProduct
• Flash success/error
• Redirect back do /products/{id}

Krok 6: Widok — przycisk na stronie produktu

Plik: resources/views/products/show.php Dodać przycisk "Przypisz EAN z GS1" widoczny gdy $product['ean'] jest pusty. Formularz POST do /products/{id}/assign-ean.

Krok 7: Tłumaczenia

Plik: resources/lang/pl.php Dodać klucze:

• products.gs1.assign_ean — "Przypisz EAN z GS1"
• products.gs1.ean_assigned — "EAN :ean został przypisany i zarejestrowany w GS1."
• products.gs1.already_has_ean — "Produkt ma już przypisany EAN."
• products.gs1.error — "Błąd podczas przypisywania EAN z GS1."
• settings.gs1.* — etykiety formularza ustawień

Krok 8: Routing

Plik: routes/web.php Dodać:

• POST /products/{id}/assign-ean → ProductsController::assignGs1Ean
• GET /settings/gs1 → SettingsController::gs1
• POST /settings/gs1 → SettingsController::gs1Save

Zależności

• AppSettingsRepository — już istnieje (migracja 000012), sprawdzić API
• ProductRepository — metoda update EAN (sprawdzić czy istnieje)
• Curl extension — wymagany (prawdopodobnie już jest)

Kolejność prac

1 → 3 → 4 → 5 → 6 → 7 → 8 → 2 (ustawienia na końcu, na początku hardcode credentials do testów) Praktycznie: 3 → 4 → 5 → 6 → 7 → 8 (migracja i ustawienia mogą być równolegle)