> ## 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.

# Kokoelma

> Kuratoitu joukko listauksia, joka on koottu esillepanoa ja navigointia varten.

<Frame caption="Katalogi > Kokoelmat">
  <img src="https://mintcdn.com/twicecommerce/Ab7tx7ih94KQsi0k/images/catalog-collections.webp?fit=max&auto=format&n=Ab7tx7ih94KQsi0k&q=85&s=128fb8d8181b0c684e742866578d2585" alt="Kokoelmataulukko Adminissa" width="1920" height="1080" data-path="images/catalog-collections.webp" />
</Frame>

## Määritelmä

<Snippet file="definitions/fi/collection-definition.mdx" />

<Info>
  **Vertaus:** Kokoelma on kuin soittolista. Se ryhmittelee listauksia teeman mukaan, jotta asiakkaat voivat selata, suodattaa ja päätyä kategoriasivulle verkkokaupassa.
</Info>

<Tip>
  **Erityistä TWICEssä:** Kokoelmat ovat joko **manuaalisia** (valitset listaukset itse) tai **älykkäitä** (listaukset kohdistetaan automaattisesti katalogitason tunnisteiden perusteella). Molemmat tyypit ovat samassa mallissa ja näkyvät verkkokaupassa samalla tavalla.
</Tip>

## Missä sitä käytetään?

* **Verkkokaupan navigointi** — jokainen kokoelma muodostaa kategoriasivun osoitteeseen `/collections/{slug}`
* **Verkkokaupan esillepano** — nosta kausi- tai teemakokonaisuus esiin etusivulla
* **Suodatettu selaus** — asiakkaat selaavat kuratoitua osaa katalogista koko varaston sijaan
* **Tunnisteisiin perustuva automaatio** — älykäs kokoelma pysyy ajan tasalla, kun listausten tunnisteet muuttuvat
* **SEO-sisääntulopisteet** — jokaisella kokoelmalla on oma sivun otsikko, metakuvaus ja OpenGraph-metatiedot
* **Massatoiminnot** — käytä kokoelmaa valintajoukkona hintataulukon liittämiseen tai massamuokkauksiin

## Manuaalinen vs. älykäs

`type`-kenttä erottaa nämä kaksi jäsenyysmallia.

| Toiminta                       | Manuaalinen                                     | Älykäs                                                                   |
| ------------------------------ | ----------------------------------------------- | ------------------------------------------------------------------------ |
| Jäsenyyden lähde               | Erikseen lisätyt `catalogItems[]`-rivit         | `smartConditions[]` verrattuna listausten tunnisteisiin                  |
| Listauksen lisäys              | `POST /collections/:id/items`                   | Lisää listaukselle tunniste, johon kokoelma viittaa                      |
| Listauksen poisto              | `DELETE /collections/:id/items?catalogItemId=…` | Poista tunniste listaukselta tai poista älykäs ehto                      |
| Listausten järjestys           | Käsin hallittavissa                             | Määräytyy listauslistan järjestyksen, ei ehtojen järjestyksen mukaan     |
| Reagoi tunnisteiden muutoksiin | Ei                                              | Kyllä — jäsenyys lasketaan uudelleen tunnisteiden muuttuessa             |
| Sopii parhaiten                | Käsin valittuihin nostoihin verkkokaupassa      | Vakiintuneisiin kategorioihin kuten ”Pyörät”, ”Alennuksessa”, ”Uutuudet” |

Kokoelman `type`-arvoa ei voi vaihtaa luonnin jälkeen — valitse oikea tyyppi heti alussa. Älykkäät kokoelmat kohdistuvat vain **katalogitason** tunnisteisiin (ainoa taso, joka näkyy Adminin älykkäiden sääntöjen valitsimessa).

## Älykkään kokoelman ehdot

Älykäs kokoelma sisältää taulukon `smartConditions`. Jokainen ehto on viittaus yhteen tunnisteeseen.

`CollectionSmartCondition` sisältää seuraavat kentät:

| Kenttä         | Tyyppi     | Kuvaus                                           |
| -------------- | ---------- | ------------------------------------------------ |
| `id`           | Merkkijono | Palvelimen luoma tunniste                        |
| `collectionId` | Merkkijono | Älykäs kokoelma, johon ehto kuuluu               |
| `tagId`        | Merkkijono | Katalogitason tunniste, johon ehto kohdistuu     |
| `tag`          | Tag        | Ratkaistu tunnisteobjekti, kun se on laajennettu |

Ehdolla ei ole operaattorikenttää — predikaatti on aina **”listauksella on tämä tunniste”**. Operaattorit kuten `not equals` tai `contains` ja attribuuttivertailut eivät kuulu malliin tällä hetkellä.

Ehtojen välinen yhdistelysääntö asetetaan itse kokoelmaan kentällä `tagMatchType`:

| `tagMatchType` | Merkitys                                                                              |
| -------------- | ------------------------------------------------------------------------------------- |
| `any` (oletus) | Listaus kuuluu kokoelmaan, jos sillä on **vähintään yksi** määritetyistä tunnisteista |
| `all`          | Listaus kuuluu kokoelmaan vain, jos sillä on **kaikki** määritetyt tunnisteet         |

`tagMatchType`-arvoa voi muokata milloin tahansa; jäsenyys lasketaan uudelleen seuraavalla luvulla.

<Warning>
  Koska älykkäät kokoelmat kohdistuvat vain tunnisteisiin, suunnittele tunnistetaksonomiasi ennen kuin skaalaat kokoelmien määrää. Tunnisteilla `bikes`, `road-bikes` ja `discounted` voit rakentaa kokoelmat ”Kaikki pyörät”, ”Maantiepyörät” ja ”Alennetut maantiepyörät” (arvolla `tagMatchType = 'all'`) ilman päällekkäistä ylläpitoa.
</Warning>

## Keskeiset ominaisuudet

| Ominaisuus        | Tyyppi                       | Kuvaus                                                                                                                                    |
| ----------------- | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `id`              | UUID                         | Palvelimen luoma tunniste                                                                                                                 |
| `title`           | Merkkijono                   | Asiakkaille näkyvä kokoelman nimi                                                                                                         |
| `description`     | Merkkijono \| null           | Vapaaehtoinen pitkä kuvaus kategoriasivulla                                                                                               |
| `type`            | `manual` \| `smart`          | Jäsenyysmalli. Kiinteä luonnin jälkeen                                                                                                    |
| `tagMatchType`    | `any` \| `all`               | Älykkäiden kokoelmien predikaattien yhdistelysääntö                                                                                       |
| `catalogItems`    | `CollectionCatalogItem[]`    | Manuaalisen jäsenyyden rivit                                                                                                              |
| `smartConditions` | `CollectionSmartCondition[]` | Älykkäiden kokoelmien käyttämät tunnisteviittaukset                                                                                       |
| `media`           | `CollectionMediaLinks[]`     | Järjestetyt hero- ja bannerikuvat kokoelmasivulle                                                                                         |
| `slugs`           | Merkkijono\[]                | Verkkokaupan osoitepolut. Ensimmäinen on ensisijainen (canonical) polku; muut ovat vaihtoehtoisia. Tyhjänä käytetään kokoelman `id`-arvoa |
| `pageTitle`       | Merkkijono \| null           | SEO-`<title>` (enintään 70 merkkiä Adminissa)                                                                                             |
| `metaDescription` | Merkkijono \| null           | SEO-metakuvaus (enintään 160 merkkiä Adminissa)                                                                                           |
| `ogTitle`         | Merkkijono \| null           | OpenGraph-otsikko sosiaalisen median jakoihin                                                                                             |
| `ogDescription`   | Merkkijono \| null           | OpenGraph-kuvaus                                                                                                                          |
| `ogImage`         | FileResource \| null         | OpenGraph-kuva                                                                                                                            |
| `noindex`         | Totuusarvo                   | Kun `true`, pyytää hakukoneita olemaan indeksoimatta kokoelmasivua                                                                        |
| `aggregateData`   | Objekti                      | Listauspäätepisteiden palauttamat lukumäärät ja muut johdetut kentät                                                                      |

## Suhteet

<AccordionGroup>
  <Accordion title="Sisältää listauksia">
    Kokoelma ryhmittelee [listauksia](/docs/fi/concepts/catalog/listings). Yksittäinen listaus voi kuulua rajattomaan määrään kokoelmia — lukumäärärajoitusta ei ole.
  </Accordion>

  <Accordion title="Käyttää katalogitason tunnisteita">
    Älykkäät kokoelmat viittaavat `Tag`-riveihin, joilla on `scope = 'catalog'`. Tunnisteet ovat yhteisiä listauksille ja kokoelmille, joten tunnisteen lisääminen uudelle listaukselle vaikuttaa välittömästi jokaiseen siihen viittaavaan älykkääseen kokoelmaan.
  </Accordion>

  <Accordion title="Näkyy myyntikanavissa">
    Kokoelmat näkyvät verkkokaupassa osoitteessa `/collections/{urlHandle}`. Se, näkyykö kukin jäsenlistaus, riippuu kyseisen listauksen omista myyntikanavamerkinnöistä. Katso [Verkkokauppa-käsite](/docs/fi/concepts/sales-channels/online-store).
  </Accordion>

  <Accordion title="Liitetty mediatiedostoihin">
    Jokainen `CollectionMediaLinks`-rivi liittää `FileResource`-tiedoston (hero-kuva, banneri) `orderIndex`-järjestyksessä. Ensimmäistä kuvaa käytetään varana sosiaalisen median jakoesikatselussa.
  </Accordion>
</AccordionGroup>

## Kokoelman tietovälilehdet

Kun avaat kokoelman Adminissa:

| Välilehti    | Mitä siinä määritetään                                                                                                                                |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| Yleiset      | Otsikko, kuvaus, hero-media, tyyppikohtainen jäsenyys (manuaalinen valitsin tai älykkäät säännöt + vastaavuustapa)                                    |
| Listaukset   | Kokoelman nykyiset listaukset (vain luku älykkäissä, muokattavissa manuaalisissa)                                                                     |
| Markkinointi | Hakukonenäkyvyys (sivun otsikko, metakuvaus, osoitepolku), hakukoneindeksoinnin kytkin, jakaminen sosiaalisessa mediassa (OG-otsikko, -kuvaus, -kuva) |

## Suorituskykyhuomiot

* **Älykkäät kokoelmat lasketaan luettaessa.** Nykyinen toteutus ratkaisee jäsenyyden kyselyhetkellä yhdistämällä listausten tunnisteet kokoelman ehtoihin. Erillistä ylläpidettävää jäsenyystaulua ei ole.
* **Kokoelmien välinen jäsenyys on ilmaista.** Listaus voi kuulua rajattomaan määrään kokoelmia ilman tallennustilan lisäkuormaa, koska manuaaliset rivit ovat yksinkertaisia liitostietueita ja älykkäät osumat lasketaan.
* **Tunnisteiden muutokset heijastuvat laajasti.** Tunnisteen nimeäminen uudelleen tai poistaminen vaikuttaa jokaiseen siihen viittaavaan älykkääseen kokoelmaan. Uudelleennimeäminen on turvallista; poisto kutistaa kokoelman jäsenyyttä hiljaisesti.
* **Sivutus on tärkeää suurissa kokoelmissa.** Käytä kokoelmakohtaista `listCatalogItems`-päätepistettä jäsenten hakemiseen sivuittain sen sijaan, että lukisit koko kokoelmaobjektin.

## Elinkaari

<Steps>
  <Step title="Luonti">
    `POST /collections` kentillä `title`, `type` ja (älykkäissä) alustava `tagMatchType`.

    <AccordionGroup>
      <Accordion title="Voinko muuttaa manuaalisen kokoelman älykkääksi myöhemmin?">
        Et. `type` on kiinteä luonnin jälkeen. Muunnos onnistuu luomalla uusi halutun tyyppinen kokoelma ja siirtämällä sisältö.
      </Accordion>

      <Accordion title="Tarvitsenko tunnisteita ennen älykkään kokoelman luomista?">
        Et — voit luoda älykkään kokoelman ensin ja lisätä ehdot jälkeenpäin. Ennen ehtojen lisäämistä kokoelmassa on nolla jäsentä.
      </Accordion>
    </AccordionGroup>
  </Step>

  <Step title="Täyttäminen">
    Manuaalinen: lisää listauksia kutsulla `POST /collections/:id/items`. Älykäs: lisää tunnisteita kutsulla `POST /collections/:id/conditions` ja aseta `tagMatchType`.
  </Step>

  <Step title="Julkaisu verkkokaupassa">
    Kokoelmat näkyvät verkkokaupassa automaattisesti, kun niillä on `urlHandle` (tai tunnisteella, jos polkua ei ole asetettu). Erillistä julkaisukytkintä ei ole.
  </Step>

  <Step title="Ylläpito">
    Manuaalinen: lisää ja poista kohteita esillepanon muuttuessa. Älykäs: ylläpidä taustalla olevaa tunnistetaksonomiaa — kokoelma seuraa automaattisesti.
  </Step>

  <Step title="Käytöstä poisto">
    `DELETE /collections/:id` poistaa kokoelman. Jäsenlistauksiin tämä ei vaikuta — vain kokoelman rivit poistetaan.
  </Step>
</Steps>

## Usein kysytyt kysymykset

<AccordionGroup>
  <Accordion title="Voiko listaus kuulua useaan kokoelmaan?">
    Kyllä, rajattomaan määrään. Ylärajaa tai yksinoikeussääntöä ei ole.
  </Accordion>

  <Accordion title="Mikä ero on kokoelmalla ja kategoriataksonomialla?">
    Kategoriat ovat rakenteellinen luokitus siitä, mikä listaus **on** (yksi kanoninen puu). Kokoelmat ovat esillepanon kerros siitä, miten listauksia **ryhmitellään myyntiä varten**. Listauksella on yksi taksonomiakategoria, mutta se voi kuulua moneen kokoelmaan.
  </Accordion>

  <Accordion title="Tukevatko älykkäät kokoelmat `not contains` -ehtoa tai attribuuttivertailua?">
    Eivät tällä hetkellä. Ehdot ovat vain positiivisia tunnisteosumia, jotka yhdistetään säännöllä `any` tai `all`.
  </Accordion>

  <Accordion title="Mitä tapahtuu, kun poistan älykkään kokoelman käyttämän tunnisteen?">
    Vastaava `smartConditions`-rivi poistetaan, ja listaukset, jotka osuivat vain kyseiseen tunnisteeseen, putoavat kokoelmasta seuraavalla luvulla.
  </Accordion>

  <Accordion title="Miten kokoelman sisäistä järjestystä hallitaan?">
    Manuaaliset kokoelmat järjestetään kunkin jäsenyysrivin `orderIndex`-arvon mukaan. Älykkäiden kokoelmien järjestys tulee listauskyselystä, ei ehtojen lisäysjärjestyksestä.
  </Accordion>
</AccordionGroup>

## Kehittäjän viite

Kokoelmat näkyvät API:ssa nimellä `collections`.

<Card title="API: Collections" icon="code" href="https://server.twicecommerce.com/api/internal">
  Avaa päätepiste API-referenssissä.
</Card>

## Aiheeseen liittyvää

<CardGroup cols={2}>
  <Card title="Listaukset" icon="list" href="/docs/fi/concepts/catalog/listings">
    Katalogin rivit, joita kokoelma ryhmittelee
  </Card>

  <Card title="Verkkokauppa" icon="store" href="/docs/fi/concepts/sales-channels/online-store">
    Missä kokoelmasivut näkyvät
  </Card>

  <Card title="Kategoriataksonomia" icon="sitemap" href="/docs/fi/concepts/admin/category-taxonomy">
    Rakenteellinen luokitus, joka täydentää kokoelmia
  </Card>

  <Card title="Hintataulukot" icon="table" href="/docs/fi/concepts/catalog/price-tables">
    Sovella jaettua hintataulukkoa kokoelman jokaiseen listaukseen
  </Card>
</CardGroup>