# Auto-publikacja Allegro i OLX z BaseLinkera

Instrukcja operatorska: jak po zapisie produktu z tej apki (**`addInventoryProduct`**) wystawiać oferty na **Allegro** i **OLX** z panelu Base.com / BaseLinker — **bez** bezpośredniej integracji z API marketplace w repozytorium.

> **Zakres:** Allegro (konto `24646`) + OLX. Erli celowo pominięte.
>
> **Powiązane:** [`ARCHITECTURE.md`](ARCHITECTURE.md), [`BASE_TEMPLATES.md`](BASE_TEMPLATES.md), [`BASELINKER-TEMPLATE-TAGS.md`](BASELINKER-TEMPLATE-TAGS.md), [`rozmowa_z_ai_base.com.md`](rozmowa_z_ai_base.com.md), [`base-com-input-pack.md`](base-com-input-pack.md).

---

## 1. Model przepływu

```mermaid
flowchart TD
  A[Apka: import + AI] --> B[addInventoryProduct]
  B --> C[(Magazyn BL 62360)]
  C --> D[Szablony ofert BL]
  D --> E[Allegro]
  D --> F[OLX]
  G[Reguły / automatyzacje BL] -.-> E
  G -.-> F
```

1. **Apka** zapisuje kartę magazynową: nazwa, opis Base, opisy kanałowe, `features`, zdjęcia, stan, cena.
2. **Szablony ofert** w BL wstawiają treści tagami: `[opis]`, `[opis_dodatkowy1]`…`[opis_dodatkowy4]` (pełna lista: [`BASELINKER-TEMPLATE-TAGS.md`](BASELINKER-TEMPLATE-TAGS.md)).
3. **Publikacja** następuje w panelu BL (ręcznie lub regułą automatyczną po dodaniu produktu).

---

## 2. Co apka wysyła (kontrakt pól)

| Pole BL | Rola w apce | Tag szablonu aukcji | Uwagi |
|---------|-------------|---------------------|-------|
| `text_fields.description` | Nagłówek zaufania + narracja OLX (składane) | `[opis]` | gdy brak OLX — fallback do opisu Base |
| `text_fields.description_extra1` | Pakiet zaufania (kontrola przed wysyłką) | `[opis_dodatkowy1]` | potwierdzony |
| `text_fields.description_extra2` | Pełny opis produktu (AI, kanał base) | `[opis_dodatkowy2]` | potwierdzony |
| `text_fields.description_extra3` | Opis kanału Allegro (AI) | `[opis_dodatkowy3]` | HTML aukcji |
| `text_fields.description_extra4` | Opis kanału OLX (AI, plain text) | `[opis_dodatkowy4]` | bez HTML |
| `text_fields.features.Stan` | Allegro (mapowanie) | parametr kategorii przez regułę BL | przy outlet |

Domyślnie apka ma włączone **`generateMarketplaceChannels: true`** — przy zapisie trafiają opisy Allegro (`extra3`) i OLX (`extra4`), gdy AI je wygenerowało.

### Outlet / brak EAN na Allegro

Gdy `outletMode=true`, apka ustawia:

```json
"features": { "Stan": "używany" }
```

W panelu BL (jednorazowa konfiguracja):

**Allegro → Kategorie i parametry → Parametry Allegro**

| Parametr Allegro | Akcja |
|------------------|--------|
| Stan | Skopiuj z parametru magazynu → **Stan** |

Potwierdzone wartości: `nowy`, `używany`, `po zwrocie`, `outlet`. Dla **zwolnienia z EAN** najpewniej mapuj na **`używany`** (patrz [`rozmowa_z_ai_base.com.md`](rozmowa_z_ai_base.com.md)).

---

## 3. Konfiguracja jednorazowa w panelu BL

### 3.1 Szablon oferty Allegro (`SZABLON Prawidłowy`)

Modułowy układ (apka rozdziela treści — Ty układasz tagi w szablonie):

```text
[opis_dodatkowy1]
[opis_dodatkowy3]
```

Wariant ze składanym opisem głównym (narracja OLX) zamiast dedykowanego Allegro — **niezalecany**; `[opis]` zawiera krótką narrację OLX, nie pełny opis aukcji:

```text
[opis_dodatkowy1]
[opis]
```

Zalecany układ sklepu — pełny opis w extra2:

```text
[opis_dodatkowy2]
```

### 3.2 Szablon oferty OLX

**Pełna instrukcja:** [`szablon_olx`](szablon_olx) (standard) · **rekomendowany:** [`szablon_olx_PREMIUM.md`](szablon_olx_PREMIUM.md) (hierarchia `◆`/`▸`, kuratorowane `[cecha_i_nazwa|…]`).

OLX w apce jest **plain text** (bez HTML). Szablon standardowy (narracja na górze — hook widoczny od razu na mobile):

```text
[opis_dodatkowy4]

[opis_dodatkowy1]

PARAMETRY
[cechy_lista]

Wymiar: [szerokosc] x [dlugosc] cm
EAN: [ean]

Dywanowy Bazar · dywanowy-bazar.pl
Wysyłka kurierem. Zapytaj przez OLX — odpowiadamy szybko.
```

W narracji (`[opis_dodatkowy4]`) nie powtarzaj «sprawdzamy przed wysyłką» — to jest w `[opis_dodatkowy1]`.

`[opis_dodatkowy1]` trafia do magazynu jako **krótki plain text** (bez HTML), żeby uniknąć sklejania słów na OLX (`wysyłkąW`).

Lista parametrów do szablonu PREMIUM (kolejność, etykiety, wykluczenia): [`config/olx-template-curated-features.json`](../config/olx-template-curated-features.json).

**Tytuł ogłoszenia OLX:** domyślnie `[nazwa]` z magazynu (tytuł Base). Tytuł z apki (`channelOutputs.olx.title`) — ręcznie w Publikacje → OLX lub akceptuj `[nazwa]`.

Nie używaj `[opis]` / `[opis_dodatkowy3]` w szablonie OLX.

### 3.3 Domyślne ustawienia kanału Allegro (na koncie)

Zweryfikuj w BL (wartości z rozmowy z AI Base.com — dostosuj do aktualnego konta):

| Ustawienie | Przykład |
|------------|----------|
| Konto Allegro | Dywanowy-Bazar (`24646`) |
| Szablon | SZABLON Prawidłowy |
| Kategoria domyślna | Dom i Ogród → … → Dywany |
| Cennik wysyłki | - Dywany Standard |
| Wysyłka w ciągu | 3 dni |
| GPSR | tekst + producent + osoba odpowiedzialna |
| Faktura | bez VAT (jeśli dotyczy) |

### 3.4 Mapowanie parametrów magazyn → Allegro

Poza **Stan** zmapuj parametry z `text_fields.features` (Materiał, Kolor, Wymiary itd.) na parametry obowiązkowe kategorii Allegro — lista zależy od kategorii liściowej.

Kanonika nazw w apce: [`config/baselinker-feature-canonical.json`](../config/baselinker-feature-canonical.json).

---

## 4. Publikacja pojedynczego produktu (operator)

Po **„Wyślij do Base.com”** w Studio / kreatorze / dashboardzie:

1. **Sprawdź ostrzeżenia** w apce (waga 0, tytuł Allegro, brak zdjęć).
2. Otwórz **kartę produktu w BL** (Studio: ustawienia → *Otwórz kartę* lub *Otwórz publikacje*).
3. W BL uzupełnij ręcznie, jeśli trzeba:
   - **cenę > 0** (apka często wysyła `0` — ustawiasz w BL),
   - **wagę** (źródło Tara często daje 0 kg),
   - kategorię **marketplace** Allegro (≠ kategoria magazynu `category_id`).
4. Zakładka **Publikacje (Channels Data)** — podgląd treści per kanał; ewentualne nadpisanie.
5. **Wystaw na Allegro** / **Wystaw na OLX** (przycisk w BL lub reguła automatyczna).

### Checklist przed wystawieniem

| # | Warunek | Gdzie sprawdzić |
|---|---------|-----------------|
| 1 | Cena > 0 PLN | karta produktu BL |
| 2 | Stan magazynu > 0 | karta produktu BL |
| 3 | Min. 1 zdjęcie | apka + BL |
| 4 | Waga > 0 (Allegro wysyłka) | karta produktu BL |
| 5 | Pakiet zaufania (`description_extra1`) | podgląd payloadu / BL |
| 6 | Opis Allegro (`description_extra3` / `[opis_dodatkowy3]`) | podgląd payloadu / BL |
| 7 | Opis OLX (`description_extra4` / `[opis_dodatkowy4]`) | podgląd payloadu / BL |
| 8 | `features.Stan` przy outlet | payload / parametry BL |
| 9 | Kategoria Allegro + parametry kategorii | zakładka Publikacje |
| 10 | GPSR / dostawa / zwroty | ustawienia konta Allegro w BL |

Apka dodaje te punkty jako **ostrzeżenia** (`meta.validationIssues`, kod `PUBLISH_*`) — nie blokują zapisu do magazynu.

---

## 5. Auto-publikacja (reguły po stronie BL)

Repozytorium **nie** wywołuje API wystawiania ofert. Automatyzacja = konfiguracja w BaseLinkerze, np.:

- reguła: *po dodaniu produktu do magazynu 62360 → utwórz szkic oferty Allegro*,
- reguła: *gdy spełnione warunki (cena, stan, zdjęcie) → opublikuj*,
- harmonogram synchronizacji stanów.

**Kroki do zrobienia w panelu BL (do uzupełnienia po Twojej weryfikacji UI):**

1. **Integracje** → Allegro / OLX — połączenia aktywne.
2. **Magazyn** → **Automatyzacje** (lub odpowiednik w Twojej wersji panelu) → nowa reguła:
   - trigger: dodanie / aktualizacja produktu w inventory `62360`,
   - warunek: tag `OUTLET` lub kategoria, stan > 0, min. 1 zdjęcie,
   - akcja: utwórz ofertę Allegro z szablonem `SZABLON Prawidłowy`.
3. Powtórz analogicznie dla OLX (osobny szablon, plain text).
4. Test na **jednym** produkcie z apki → sprawdź log błędów walidacji w BL.

> Dokładne nazwy menu w BL mogą się różnić między wersjami konta. Jeśli reguł nie ma w UI, publikacja pozostaje ręczna z karty produktu — nadal korzystasz z przygotowanych pól `description_extra*`.

---

## 6. Zmienne środowiskowe (opcjonalne)

| Klucz | Domyślnie | Opis |
|-------|-----------|------|
| `BASELINKER_PANEL_PRODUCT_URL` | `…inventory_products.php?inventory_id={inventoryId}&product_id={productId}` | Karta produktu po zapisie |
| `BASELINKER_PANEL_PUBLISH_URL` | jak wyżej + `&tab=channels` | Link „Publikacje” (dostosuj do swojego panelu) |

Placeholdery: `{inventoryId}`, `{productId}`.

---

## 7. Rozwiązywanie problemów

| Objaw | Przyczyna | Działanie |
|-------|-----------|-----------|
| Pusty opis na Allegro | `generateMarketplaceChannels` wyłączone lub brak AI | Włącz w configu; uruchom regenerację kanałów w kreatorze |
| OLX bez treści | Brak `description_extra4` w payloadzie | Regeneruj kanał OLX; sprawdź profil `OLX_Clearance_Fast` |
| Allegro wymaga EAN | Brak mapowania `Stan` | Ustaw `outletMode` + regułę parametru Stan → `używany` |
| Błąd wysyłki — waga 0 | Tara nie podaje wagi | Uzupełnij ręcznie w BL przed wystawieniem |
| Zła kategoria Allegro | `category_id` to kategoria magazynu | Ustaw kategorię marketplace w Publikacjach |

---

## 8. Powiązanie z kodem

| Plik | Rola |
|------|------|
| [`src/baselinker.js`](../src/baselinker.js) | Zapis `description_extra1`–`extra4` (składanie opisów + kanały) |
| [`config/editor-config.json`](../config/editor-config.json) | Kanały, prompty AI, profile sprzedaży |
| [`src/marketplacePublish.js`](../src/marketplacePublish.js) | Ostrzeżenia `PUBLISH_*`, budowa URL panelu |
| [`public/studioProfile.js`](../public/studioProfile.js) | `afterSave`: `open_base` \| `open_publish` |

---

*Ostatnia aktualizacja: czerwiec 2026 — inventory 62360, Allegro 24646.*