> ## Documentation Index
> Fetch the complete documentation index at: https://www.twicecommerce.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Kolekce
> Kurátorská skupina inzerátů organizovaná pro účely merchandisingu a navigace.
Katalog > Kolekce
## Definice
> [!NOTE]
>
> **Analogie:** Kolekce je playlist. Seskupuje inzeráty do tematického celku, aby zákazníci mohli procházet, filtrovat a přistát na stránce kategorie v internetovém obchodě.
> [!TIP]
>
> **Zvláštnost v TWICE:** Kolekce jsou buď **manuální** (inzeráty vybíráte sami), nebo **chytré** (inzeráty se přiřazují automaticky podle štítků v rozsahu katalogu). Oba typy žijí ve stejném modelu a nabízí stejnou plochu na výkladní skříni.
## Kde to použiji?
* **Navigace v internetovém obchodě** – Každá kolekce vykresluje stránku kategorie na `/collections/{slug}`
* **Merchandising na výkladní skříni** – Propagujte sezónní nebo tematickou sadu na domovské stránce
* **Filtrované procházení** – Zákazníci nakupují ve vybraném výřezu katalogu místo celého skladu
* **Automatizace podle štítků** – Chytrá kolekce zůstává synchronizovaná, jak se inzeráty přeštítkovávají
* **Vstupní body SEO** – Každá kolekce má vlastní titulek stránky, meta popis a metadata OpenGraph
* **Hromadné operace** – Použijte kolekci jako výběrovou sadu pro propojení cenové tabulky nebo hromadné úpravy
## Manuální vs. chytrá
Pole `type` je rozlišovací znak mezi oběma modely členství.
| Chování | Manuální | Chytrá |
| - | - | - |
| Zdroj členství | Řádky `catalogItems[]` přidané výslovně | `smartConditions[]` porovnané se štítky inzerátu |
| Přidání inzerátu | `POST /collections/:id/items` | Oštítkujte inzerát štítkem, na který kolekce odkazuje |
| Odebrání inzerátu | `DELETE /collections/:id/items?catalogItemId=…` | Zrušte štítek inzerátu nebo odstraňte chytrou podmínku |
| Pořadí inzerátů | Ovládací prvek řazení zákazníka na výkladní skříni | Ovládací prvek řazení zákazníka na výkladní skříni |
| Reaguje na změny štítků | Ne | Ano, členství se přepočítá při změně štítků |
| Nejlepší pro | Ručně vybrané funkce na výkladní skříni | Stabilní kategorie jako „Kola", „Ve slevě", „Novinky" |
Typ kolekce (`type`) nelze po vytvoření přepnout, zvolte správný typ hned na začátku. Chytré kolekce porovnávají pouze se štítky v rozsahu **katalog** (jediný rozsah zobrazený ve výběru chytrých pravidel v administraci).
## Podmínky chytré kolekce
Chytrá kolekce nese pole `smartConditions`, což je pole odkazů, každý na jeden štítek.
`CollectionSmartCondition` má následující pole:
| Pole | Typ | Popis |
| - | - | - |
| `id` | String | Identifikátor generovaný serverem |
| `collectionId` | String | Chytrá kolekce, ke které tato podmínka patří |
| `tagId` | String | Štítek v rozsahu katalogu, se kterým tato podmínka porovnává |
| `tag` | Tag | Rozbalený objekt štítku, je-li rozbalený |
Podmínka nemá pole operátoru, predikát je vždy **„inzerát má tento štítek"**. Operátory jako `not equals`, `contains` nebo porovnání atributů dnes nejsou součástí modelu.
Kombinátor mezi podmínkami se nastavuje na samotné kolekci přes `tagMatchType`:
| `tagMatchType` | Význam |
| - | - |
| `any` (výchozí) | Inzerát patří do kolekce, pokud má **alespoň jeden** z nastavených štítků |
| `all` | Inzerát patří do kolekce, jen pokud má **všechny** nastavené štítky |
`tagMatchType` lze kdykoli upravit, členství se přepočítá při dalším čtení.
> [!WARNING]
>
> Protože chytré kolekce porovnávají pouze podle štítků, naplánujte si taxonomii štítků dřív, než začnete kolekce škálovat. Štítek `bikes`, štítek `road-bikes` a štítek `discounted` vám umožní sestavit „Všechna kola", „Silniční kola" a „Silniční kola ve slevě" (s `tagMatchType = 'all'`) bez zdvojené správy.
## Publikování
**Prodejní kanál** je místo, kde je entita katalogu nabízena zákazníkům. Kolekce je nabízena na dvou z nich: **Administrace** (prohlížeč pro vytváření objednávek) a **Internetový obchod** (výkladní skříň). Kanál **Store**, přes který může prodávat inzerát, kolekce nikdy nevykresluje.
**Publikováno do kanálu** je přepínač pro každý kanál zvlášť, který určuje, zda je kolekce na tomto kanálu nabízena. `salesChannelAdmin` i `salesChannelOnline` jsou u nové kolekce oba `true` a obchodník kolekci odpublikuje, aby ji z daného kanálu odstranil, zatímco zůstává plně editovatelná v administraci.
Odpublikování odebere z kanálu **kolekci**, ne její členské inzeráty: publikování každého inzerátu se řídí samo za sebe, takže inzeráty odpublikované kolekce dál prodávají na svých vlastních kanálech.
Dva sousední koncepty jsou záměrně oddělené:
* **Stav publikování** – stav Veřejné / Koncept na kartě Všeobecné inzerátu, který inzerát stáhne ze všech kanálů naráz. Platí jen pro inzeráty, kolekce žádný stav konceptu nemá, jen své přepínače pro jednotlivé kanály.
* **Archivováno** – stav mimo provoz sdílený všemi hlavními aktivy: skryté ze seznamů v administraci i z výkladní skříně, stále čitelné podle id, vratné pomocí Zrušit archivaci. Kolekci na sezónu stáhněte z internetového obchodu odpublikováním, ne archivací.
Více: [Publikování kolekce](https://www.twicecommerce.com/docs/cs/catalog/collections/publishing.md) a [Archivace a mazání](https://www.twicecommerce.com/docs/cs/concepts/repeating-patterns/archiving-and-deletion.md).
## Klíčové vlastnosti
| Vlastnost | Typ | Popis |
| - | - | - |
| `id` | UUID | Identifikátor generovaný serverem |
| `title` | String | Název kolekce zobrazovaný zákazníkům |
| `description` | String \| null | Volitelný dlouhý popis zobrazený na stránce kategorie |
| `type` | `manual` \| `smart` | Model členství. Pevně daný při vytvoření |
| `tagMatchType` | `any` \| `all` | Kombinátor predikátů pro chytré kolekce |
| `catalogItems` | `CollectionCatalogItem[]` | Řádky manuálního členství |
| `smartConditions` | `CollectionSmartCondition[]` | Odkazy na štítky používané chytrými kolekcemi |
| `media` | `CollectionMediaLinks[]` | Seřazené hero / banner obrázky pro stránku kolekce |
| `slugs` | String\[] | URL adresy na výkladní skříni. První položka je hlavní (kanonický) slug, další jsou alternativní sluggy. Bez vyplnění se použije `id` kolekce |
| `pageTitle` | String \| null | SEO `` (v administraci max. 70 znaků) |
| `metaDescription` | String \| null | SEO meta popis (v administraci max. 160 znaků) |
| `ogTitle` | String \| null | Titulek OpenGraph pro sdílení na sociálních sítích |
| `ogDescription` | String \| null | Popis OpenGraph |
| `ogImage` | FileResource \| null | Obrázek OpenGraph |
| `noindex` | Boolean | Když je `true`, požádá vyhledávače, aby stránku této kolekce neindexovaly |
| `salesChannelAdmin` | Boolean | Publikováno do kanálu Administrace (prohlížeč pro vytváření objednávek). U nové kolekce `true` |
| `salesChannelOnline` | Boolean | Publikováno do internetového obchodu. U nové kolekce `true` |
| `archivedAt` | String \| null | Když je nastaveno, kolekce je archivovaná: mimo provoz na všech kanálech a skrytá ze seznamů v administraci |
| `aggregateData` | Object | Počty a další odvozená pole vracená koncovými body seznamů |
## Vztahy
> **Obsahuje inzeráty**
>
> Kolekce seskupuje [inzeráty](https://www.twicecommerce.com/docs/cs/concepts/catalog/listings.md). Jeden inzerát může patřit do libovolného počtu kolekcí, žádné omezení kardinality neplatí.
> **Používá štítky v rozsahu katalogu**
>
> Chytré kolekce odkazují na řádky `Tag` se `scope = 'catalog'`. Štítky jsou sdílené mezi inzeráty a kolekcemi, takže přidání štítku k novému inzerátu okamžitě ovlivní každou chytrou kolekci, která na něj odkazuje.
> **Zobrazuje se na prodejních kanálech**
>
> Kolekce je publikována do dvou vlastních prodejních kanálů, Administrace a Internetový obchod, a vykresluje se v internetovém obchodě na `/collections/{urlHandle}`, dokud je tam publikovaná. Zda se zobrazí každý členský inzerát, závisí na jeho vlastních příznacích prodejního kanálu, které publikování kolekce nikdy nepřebíjí. Viz [koncept Internetový obchod](https://www.twicecommerce.com/docs/cs/concepts/sales-channels/online-store.md).
> **Propojena se soubory médií**
>
> Každý řádek `CollectionMediaLinks` připojuje `FileResource` (hero obrázek, banner) seřazený podle `orderIndex`. První obrázek slouží jako záložní pro náhled při sdílení na sociálních sítích.
## Karty detailu kolekce
Po otevření kolekce v administraci:
| Karta | Co konfiguruje |
| - | - |
| Všeobecné | Název, popis, hero média, členství podle typu (manuální výběr nebo chytrá pravidla + typ shody) |
| Inzeráty | Aktuální sada inzerátů v kolekci (jen ke čtení u chytré, editovatelné u manuální) |
| Publikování | Prodejní kanály, na kterých je kolekce zobrazena: Administrace, Internetový obchod, oba nebo žádný |
| Marketing | Zápis pro vyhledávače (titulek stránky, meta popis, URL adresa), přepínač indexování vyhledávači, sdílení na sociálních sítích (titulek, popis a obrázek OG) |
## Úvahy o výkonu
* **Chytré kolekce se přepočítávají při čtení.** Současná implementace určuje členství v okamžiku dotazu spojením štítků inzerátu s podmínkami kolekce. Neexistuje materializovaná tabulka „členství", kterou by bylo třeba synchronizovat.
* **Členství napříč kolekcemi je zdarma.** Inzerát může být v libovolném počtu kolekcí bez nákladů na úložiště, protože manuální řádky jsou jednoduché spojovací záznamy a chytré shody se počítají.
* **Operace se štítky se šíří dál.** Přejmenování nebo smazání štítku ovlivní každou chytrou kolekci, která na něj odkazuje. Přejmenování jsou bezpečná, smazání tiše zmenší členství kolekce.
* **U velkých kolekcí záleží na stránkování.** Pro načtení členů po stránkách používejte koncový bod `listCatalogItems` na jednotlivou kolekci místo čtení celého objektu kolekce.
## Životní cyklus
**1. Vytvoření**
`POST /collections` s `title`, `type` a (u chytré) počátečním `tagMatchType`.
> **Mohu později změnit manuální kolekci na chytrou?**
>
> Ne. `type` je pevně daný při vytvoření. Pro převod vytvořte novou kolekci požadovaného typu a proveďte migraci.
> **Potřebuji před vytvořením chytré kolekce nějaké štítky?**
>
> Ne, chytrou kolekci můžete vytvořit nejprve a podmínky přidat později. Dokud podmínky neexistují, kolekce má nula členů.
**2. Naplnění**
U manuální: přidejte inzeráty pomocí `POST /collections/:id/items`. U chytré: přidejte štítky pomocí `POST /collections/:id/conditions` a nastavte `tagMatchType`.
**3. Publikování v internetovém obchodě**
Nová kolekce je publikována do obou kanálů a vykresluje se v internetovém obchodě na svém `urlHandle` (nebo podle ID, pokud handle není nastaven). Nastavením `salesChannelOnline` na `false` na kartě Publikování ji z výkladní skříně stáhnete, zpět na `true` ji vrátíte.
**4. Údržba**
U manuální: přidávejte a odebírejte položky podle toho, jak se mění merchandising. U chytré: udržujte podkladovou taxonomii štítků, kolekce se řídí automaticky.
**5. Vyřazení**
`DELETE /collections/:id` odstraní kolekci. Členské inzeráty nejsou dotčeny, mažou se jen řádky kolekce.
## Časté dotazy
> **Může inzerát patřit do více kolekcí?**
>
> Ano, do libovolného počtu. Neplatí žádný limit ani pravidlo výlučnosti.
> **Jaký je rozdíl mezi kolekcí a taxonomií kategorií?**
>
> Kategorie jsou strukturální klasifikace toho, čím inzerát **je** (jeden kanonický strom). Kolekce jsou merchandisingová vrstva toho, jak jsou inzeráty **seskupeny pro prodej**. Inzerát má jednu kategorii taxonomie, ale může být v mnoha kolekcích.
> **Podporují chytré kolekce `not contains` nebo porovnání atributů?**
>
> Zatím ne. Podmínky jsou jen pozitivní shody štítků, kombinované pomocí `any` nebo `all`.
> **Co se stane, když smažu štítek používaný chytrou kolekcí?**
>
> Odpovídající řádek `smartConditions` se odstraní a inzeráty, které do kolekce patřily jen díky tomuto štítku, z ní při dalším čtení vypadnou.
> **Jak se řídí pořadí uvnitř kolekce?**
>
> Rozhoduje o něm zákazník na výkladní skříni. Řádky členství nemají v žádném typu kolekce vlastní pořadí, takže obě jsou řazeny podle ovládacího prvku řazení na výkladní skříni: podle názvu, ceny nebo od nejnovějšího či nejstaršího. Tento ovládací prvek přepínáte pro danou stránku v nastavení [stránky kolekce v editoru motivu](https://www.twicecommerce.com/docs/cs/sales-channels/online-store/theme-editor/pages/collection.md).
## Reference pro vývojáře
Kolekce jsou v API vystaveny jako `collections`.
> **[API: Collections](https://www.twicecommerce.com/docs/api-reference/collections)**
>
> Otevřít koncový bod v referenci API.
## Související články
> **[Inzeráty](https://www.twicecommerce.com/docs/cs/concepts/catalog/listings.md)**
>
> Řádky katalogu, které kolekce seskupuje
> **[Internetový obchod](https://www.twicecommerce.com/docs/cs/concepts/sales-channels/online-store.md)**
>
> Kde se vykreslují stránky kolekcí
> **[Taxonomie kategorií](https://www.twicecommerce.com/docs/cs/concepts/admin/category-taxonomy.md)**
>
> Strukturální klasifikace, doplňující ke kolekcím
> **[Cenové tabulky](https://www.twicecommerce.com/docs/cs/concepts/catalog/price-tables.md)**
>
> Použijte sdílenou cenovou tabulku na každý inzerát v kolekci
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.