Bundle Rules (JSON Rules) mahdollistaa dynaamisten riippuvuuksien rakentamisen bundle-tuotteen optioiden välille. Kun asiakas tekee valintoja bundle-konfiguraattorissa, aiempien optioiden valinnat (ja niiden määrä) voivat automaattisesti rajata myöhemmän option sallittuja tuotteita. Tämä varmistaa että asiakas voi tilata vain tuoteyhdistelmiä jotka toimivat järkevänä kokonaisuutena.

Mitä tämä tekee asiakkaan näkökulmasta

• Sääntöjen perusteella osa tuotteista muuttuu disabloiduiksi (harmaaksi / ei klikattavaksi) bundle-konfiguraattorissa.
• Jos asiakas oli jo valinnut tuotteen, joka muuttuu sääntöjen takia epäkelvoksi, valinta poistetaan automaattisesti.
• Toiminta tapahtuu ennen ostoskoria (konfigurointivaiheessa).

Mitä tämä tekee Hallintapaneelissa

• Bundle-optionin editoinnissa on “Bundle Rules” -paneeli, jossa sääntöjä luodaan käyttöliittymästä.
• JSONia ei kirjoiteta käsin, vaan editori muodostaa sen automaattisesti.

Esivaatimukset

1) Bundle Rules -editori käytössä Hallintapaneelissa

• Bundle-option edit -näkymässä näkyy “Bundle Rules” -paneeli.
• Paneelissa on taulukko riveistä (yksi sääntö per rivi).
• Paneelissa on painikkeet: Add rule, Show JSON, Copy JSON.
• Taustalla on piilotettu kenttä rules_json, joka tallennetaan tietokantaan.

3) Storefrontin bundle-konfiguraattorin tuki

• Integraatiopartneri voi kustomoida liiketoimintalogiikat kauppanne tarpeiden mukaan. AI Commerce toimittaa oletustason komponentit. 
• Jokaisella “linked productilla” tulee olla numeerinen kenttä, jota sääntö vertaa (esim. products_length, products_height).
• Jos tuotteelta puuttuu targetField-arvo tai se ei ole numero, tuote tulkitaan sääntöä vasten epäkelvoksi ja se disabloituu.

Keskeiset käsitteet

Option code

• Jokaisella bundle-optiolla on option_code.
• Säännöt viittaavat lähdeoptioon nimenomaan option_code-arvolla.
• Jos option_code jätetään tyhjäksi, järjestelmä voi generoida sen muodossa option_{ID}.
• Suositus: käytä pysyviä ja helposti luettavia koodeja, esim. signs, post, brackets.

Source option vs Target option

• Source option = optio, josta lasketaan valittujen tuotteiden määrä (esim. “Kyltit”).
• Target option = optio, jonka tuotteita rajoitetaan (esim. “Tolppa”).
• Sääntö tallennetaan aina target-optionin rules-kenttään (ei source-optionille).

Sääntötyypit

Tuetut sääntötyypit määritetään type-kentällä.

1) min_field_by_stack

• Tuote on sallittu, jos product[targetField] >= computedValue.
• Käyttö: minimipituus, minimikantavuus, minimikorkeus.

2) max_field_by_stack

• Tuote on sallittu, jos product[targetField] <= computedValue.
• Käyttö: maksipaino, maksikorkeus, maksileveys.

3) exact_field_by_stack

• Tuote on sallittu, jos product[targetField] == computedValue.
• Käyttö: “täsmälleen 22”, “täsmälleen 2400”, jne.
• Tarkennus: “exact” vertailee numeroita käytännössä tiukasti. Suositus on käyttää kokonaislukuja ja yhtenäisiä yksiköitä.

Count mode

countMode määrittää, miten “montako” lasketaan source-optiossa.

selected_count

• Lasketaan montako eri tuotetta on valittuna source-optiossa.
• Esimerkki: valittu 4 eri kylttiä → count = 4.

selected_qty

• Lasketaan valittujen tuotteiden selection_qty-summana.
• Jos selection_qty puuttuu tai ei ole kelvollinen → oletetaan 1 per valittu tuote.
• Esimerkki: yksi kyltti, mutta sillä selection_qty=4 → count = 4.

Käytännön valinta

• Jos asiakkaan “määrä” = valittujen rivien määrä → käytä selected_count.
• Jos “määrä” = valinnan qty → käytä selected_qty.

Target field

targetField on tuotteen numeerinen kenttä, jota verrataan sääntöä vasten. Tyypillisiä valintoja editorissa ovat:

• products_length
• products_width
• products_height
• products_weight
• Valitun kentän tulee löytyä tuotteilta numerona.
• Kentän tulee olla mukana bundle-palvelun payloadissa storefrontille.

Laskentakaava: base + perIntermediate + last

Kaikille *_field_by_stack-säännöille lasketaan ensin odotusarvo:

• count = (selected_count tai selected_qty)
• computedValue = base + max(count - 1, 0) * perIntermediate + (count > 0 ? last : 0)

Intuitio

• perIntermediate = “välissä olevien” kappaleiden lisä
• last = “viimeisen” kappaleen lisä (voi olla pienempi)
• base = perusvaatimus (esim. 0 tai perusmitta)

Vinkki: jos jokainen kappale lisää saman verran X

• Aseta perIntermediate = X
• Aseta last = X
• Tällöin computedValue = base + X * count

Mistä editoidaan

• Hallintapaneeli: bundle-tuotteen bundle-editori → target-optio → Edit → “Bundle Rules” -paneeli.
• Sääntö tallennetaan aina target-optionille (eli siihen optioon, jonka tuotteita halutaan rajoittaa).

Säännön luominen Hallintapaneelissa

1. Avaa bundle-tuote Hallintapaneelissa ja siirry bundle-editoriin.
2. Etsi target-optio (esim. “Tolppa”) ja paina Edit.
3. Varmista, että optiolla on option_code (suositus: pysyvä ja selkeä, esim. post).
4. Siirry “Bundle Rules” -paneeliin.
5. Paina Add rule.
6. Täytä rivin kentät:
   • Type (min / max / exact)
   • Source option (esim. “Kyltit (signs)” tai option_63)
   • Count mode (selected_count / selected_qty)
   • Target field (esim. products_length)
   • Base, Per intermediate, Last
7. Lisää tarvittaessa useita sääntöjä (useita rivejä).
   • Huom: useat säännöt samassa optiossa yhdistetään AND-logiikalla → tuotteen pitää läpäistä kaikki säännöt.
8. Tallenna optio painamalla Save.

JSONin tarkistaminen ja kopiointi

• Show JSON näyttää luodun JSONin (pretty-printed).
• Copy JSON kopioi compact-version (hyödyllinen, kun sääntösetti kopioidaan toiseen optioniin tai dokumentoidaan).

Esimerkit

Esimerkki 1: Tolpan minimipituus kylttien määrän perusteella

• Sääntö target-optionille “Tolppa”.
• Case: “montako kylttiä on valittu → mikä tolpan minimipituus on sallittu”, jossa viimeinen lisää vähemmän.

[
    {
        "type": "min_field_by_stack",
        "sourceOptionCode": "option_63",
        "countMode": "selected_qty",
        "targetField": "products_length",
        "base": 0,
        "perIntermediate": 40,
        "last": 20
    }
]

• Lasketaan kylttien määrä option_63:sta.
• Required = 0 + (count-1)*40 + last(20).
• Tolppa-tuote sallitaan vain jos products_length >= required.

Esimerkki 2: Korkeus täsmälleen määrästä riippuen (exact)

• Sama target-optio voi sisältää myös “exact”-tyyppisen rajoitteen, esim. korkeudelle.

[
    {
        "type": "exact_field_by_stack",
        "sourceOptionCode": "option_62",
        "countMode": "selected_count",
        "targetField": "products_height",
        "base": 22,
        "perIntermediate": 40,
        "last": 20
    }
]

• Lasketaan count option_62:sta.
• Computed = 22 + (count-1)*40 + last(20).
• Tuote sallitaan vain jos products_height == computed.

Yhdistelmä: useita sääntöjä samassa target-optiossa

• Kun molemmat säännöt ovat samassa target-optionissa, tuote on sallittu vain jos se täyttää sekä pituuden minimivaatimuksen että korkeuden exact-vaatimuksen.

[
  {
    "type": "min_field_by_stack",
    "sourceOptionCode": "option_63",
    "countMode": "selected_qty",
    "targetField": "products_length",
    "base": 0,
    "perIntermediate": 40,
    "last": 20
  },
  {
    "type": "exact_field_by_stack",
    "sourceOptionCode": "option_62",
    "countMode": "selected_count",
    "targetField": "products_height",
    "base": 22,
    "perIntermediate": 40,
    "last": 20
  }
]

Testaus-checklist

1. Avaa bundle-tuote storefrontissa.
2. Ennen valintoja: varmista, että target-optiossa näkyy useita tuotteita.
3. Tee valintoja source-optiossa:
   • Lisää 1 tuote → tarkista, miten target-optio reagoi.
   • Lisää 2–4 tuotetta → tarkista, miten computedValue muuttuu käytännössä (disabloidut tuotteet päivittyvät).
4. Varmista, että:
   • Disabloitua tuotetta ei voi klikata.
   • Jos aiemmin valittu tuote menee epäkelvoksi, se unselectataan automaattisesti.

Troubleshooting

“Kaikki target-option tuotteet ovat disabloituja”

• Yleisin syy: tuotteilta puuttuu targetField payloadissa tai arvo ei ole numero.
• Tarkista, että bundle-palvelu palauttaa products_length/products_height/… jokaiselle linked_products-itemille.
• Tarkista, että kentässä on numeerinen arvo (ei tyhjä, ei null).

“Sääntö ei tee mitään”

• Tarkista, että sourceOptionCode täsmää olemassa olevaan option_code-arvoon.
• Tarkista, että sääntö on tallennettu target-optionille (ei source-optionille).
• Tarkista, että storefrontissa bundle payload sisältää rules-tiedon.

“selected_qty ei käyttäydy kuten odotettiin”

• selected_qty laskee valittujen tuotteiden selection_qty-summan.
• Jos selection_qty on kaikilla 1 → selected_qty on käytännössä lähellä selected_count-arvoa.
• Jos tarkoitus on laskea “montako riviä valittu”, käytä selected_count.

“Exact ei osu”

• exact vaatii, että tuotteen kentän arvo on täsmälleen computedValue.
• Jos data ei ole “siistiä” (eri yksiköt, pyöristys), vaihtoehtona on käyttää:
  • min_field_by_stack + max_field_by_stack (eli range)

Parhaat käytännöt

• Tee option_code-arvoista pysyviä (esim. signs, post) – helpottaa sääntöjen lukemista ja ylläpitoa.
• Suunnittele riippuvuudet “eteenpäin” (aikaisempi optio → myöhempi optio), jotta logiikka on asiakkaalle intuitiivinen.
• Käytä samoja yksiköitä kaikissa arvoissa (tuotekenttä ja base/per/last).
• Pidä säännöt yksinkertaisina ja dokumentoi yhdessä asiakkaan kanssa, mitä base, perIntermediate ja last tarkoittavat käytetyissä yksiköissä (esim. mm/cm).

Yhteenveto

• Bundle Rules tuo automaattiset rajoitteet bundle-optioden välille ja estää virheelliset yhdistelmät jo konfigurointivaiheessa.
• Suositeltu eteneminen: määritä ensin yksi selkeä sääntö target-optionille, testaa toiminta storefrontissa ja lisää vasta sitten lisäsäännöt (AND-logiikka huomioiden).
• Lisädokumentaatioksi on usein hyödyllistä julkaista erillinen FAQ-osio sekä lyhyt “Quick start” -ohje tyypillisimmälle käyttötapaukselle (esim. liikennemerkkitolpan mitoitus).

Avainsanat

• Bundle Rules
• JSON Rules
• bundle-konfiguraattori
• bundle-option
• option_code
• selected_count
• selected_qty
• targetField
• min_field_by_stack
• exact_field_by_stack