# Architektura projektu — jak to się składa

Ten dokument **łączy kropki** między plikami w `docs/`, konfiguracją i kodem, bez etykiet w stylu „stary kod tylko do testów”.

## 1. Cel biznesowy (niezmienny)

- **Baza danych / magazyn docelowy:** Base.com, zapis przez API **BaseLinkera**, metoda [`addInventoryProduct`](https://api.baselinker.com/index.php?endpoint=get_method&method=addInventoryProduct).
- **Ewidencja i proces po stronie sklepu/ERP w DE:** **JTL** (JTL-Shop, JTL-Wawi). Przy **projektowaniu mapowania pól** obowiązuje **nazewnictwo JTL** (`kArtikel`, `kKategorie`, `cName` itd. — por. [JTL DeveloperDocs](https://developer.jtl-software.com)). To jest **wzorzec merytoryczny** wejścia, gdy czytacie dane z Wawi/Shop, nie z „uniwersalnego JSON-a” innej platformy.

## 2. Pliki w `docs/` — co do czego

| Zasób | Rola |
|--------|------|
| [`base-com-input-pack.md`](base-com-input-pack.md) | **Operacyjna prawda o procesie:** ręczna ścieżka od strony oferty w DE (hurtownia/sklep) → tłumaczenie → karta w Base, wymagania Allegro/OLX, pola (`text_fields.description`, EAN, kategoria itd.). Link przykładowy do oferty tara-carpet jest tu **jako przykład realnego katalogu** — **to samo źródło ofert**, z którego w narzędziu bierzecie dane **przez URL** (patrz p. 3). |
| [`AUTO-PUBLISH-BL.md`](AUTO-PUBLISH-BL.md) | **Publikacja Allegro/OLX z magazynu BL** po zapisie z apki — szablony, tagi, checklista, reguły panelu (bez API marketplace w repo). |
| [`Kategorie_BaseLinker.csv`](Kategorie_BaseLinker.csv) | **Słownik kategorii w magazynie BaseLinkera:** kolumna `id` = wartość do **`category_id`** w `addInventoryProduct`. Mapowanie z JTL (ścieżka, folder, `kKategorie` — według waszej tabeli) **na to `id`**. |
| [`BL__Products__simplified_CSV_*.csv`](.) (nazwa z datą) | **Eksport uproszczony** z bazy produktów w Base (np. `product_id`, `sku`, `price`, `quantity`) — odniesienie do tego, co już siedzi w magazynie, nie do źródła JTL. |
| **Ten plik** (`ARCHITECTURE.md`) | **Spójny opis:** JTL = model pól, BaseLinker = API, CSV kategorii = tłumaczenie na `category_id`, a adapter URL w repo = bieżąca droga wejścia danych oferty. |

Uzupełnienie mapowania JTL → `id` z CSV: [`../config/jtl-baselinker-category-map.json`](../config/jtl-baselinker-category-map.json) (np. folder `Garten` → kategoria w pliku).

## 3. Repozytorium — kanał „URL katalogu” (Tara / JSON jak Shopify)

- W kodzie jest **adapter** hosta `tara-carpet.com`, który czyta publiczne **`/products/{handle}.js`** (format typowy dla sklepów opartych o **Shopify**). To **nie** jest reklama Shopify jako systemu operacyjnego sklepu — to **stabilne API pod URI**, które pozwala pobrać wariant, EAN, zdjęcia, opis **z tej samej klasy ofert**, z których i tak kopiujecie ręcznie w [`base-com-input-pack.md`](base-com-input-pack.md).
- Czyli: **nazwa techniczna w kodzie** (Shopify JSON) odnosi się do **formatu odpowiedzi HTTP**, a **biznesowo** to nadal oferta z **katalogu niemieckiego** w linii waszej ręcznej pracy, do czasu aż równolegle stanie pełne **pobieranie tych samych pól z JTL (API/plik Wawi/Shop)**.

**Strategiczne kategorie** w `editor-config.json` używają m.in. pól `shopifyTagKeywords` w konfiguracji — to **klucz konfiguracyjny** odnoszący się do listy tagów w odpowiedzi JSON; nazwa **nie** oznacza, że systemem produkcyjnym miałby być globalny sklep innej marki, tylko **źródło tagów w tym formacie odpowiedzi**.

## 4. Podsumowanie różnic (żeby nie mieszać pojęć)

| Pojęcie | Znaczenie w tym projekcie |
|--------|---------------------------|
| **JTL** | Docelowy, **jawny** model danych (ERP/sklep) i reguły mapowania kategorii z Wawi/Shop. |
| **BaseLinker / addInventoryProduct** | **Jedyny** docelowy kontrakt zapisu do magazynu. |
| **`Kategorie_BaseLinker.csv`** | **Jedyny** słownik `id` kategorii do **`category_id`**. |
| **URL + adapter w repo** | **Bieżąca** implementacja: zamiana „ręcznego kopiowania” z oferty w przeglądarce na draft (spójne z duchem `base-com-input-pack.md`); **następca merytoryczny** to importerski odczyt pól 1:1 z JTL, bez zmiany celu w Base. |

## 5. Co dalej (kierunek, nie aluzja o „złym” kodzie)

- Dopięcie **wejścia JTL** (Wawi/Shop) oznacza **to samo** payloadowanie do Base co dziś — tylko inny **extract** na początku (`kArtikel` itd. zamiast `products/{handle}.js`), nadal z **`category_id` z waszego CSV** po mapowaniu.