# 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:
```json
{
  "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)