Verkkokaupan frontend on oma Svelte- ja Vite-sovelluksensa

AI Commercen julkinen storefront elää aicc-svelte-repositoriossa. Se omistaa Svelte/Vite-käyttöliittymän, SSR Lambdan, client-hydraation, storefront-komponentit, tenant-haarat ja julkaisuskriptit. Se ei omista MVC-kauppalogiikkaa, hallintasovelluksia, AgentCore-runtimea tai infrastruktuurin määrittelyä.

Jaettu käyttäytyminen ja uudelleenkäytettävä rakenne kuuluvat main-haaraan. Tenant-haara omistaa vain todennetun tenant-kohtaisen esityksen, konfiguraation tai komponentin. main-muutokset eivät siirry tenantteihin automaattisesti: ne viedään erillisellä deploy/merge.sh-kierroksella, minkä jälkeen haarat tarkistetaan, pusketaan ja julkaistaan sovitussa järjestyksessä.

Kehitysympäristö käyttää Node.js 22.x- ja npm 10.x -versioita. npm run dev käynnistää paikallisen kehityksen. Ennen muutosta luetaan AGENTS.md, contracts/README.md ja tehtävää koskeva sopimus. Kanoninen validointi on npm run lint && npm test && npm run build.

Juurihakemistot erottavat lähdekoodin, tuotokset ja sopimukset

aicc-svelte-repositorion assets/ sisältää juureen toimitettavat staattiset tiedostot, kuten robots.txt- ja favicon-aineiston. Indeksointiasetus tarkistetaan ennen tuotantoa, eikä kehitysympäristön noindex-rajausta saa jättää julkaistuun robots-tiedostoon. dist/ on generoitu build-tulos: dist/client/ sisältää client-aineiston ja dist/server/ SSR Lambdan nipun. Näitä ei käsitellä lähdekoodin auktoriteettina.

src/ sisältää sovelluskoodin, tests/ testit ja saavutettavuuskattavuuden, contracts/ storefrontin käyttäytymis- ja omistussopimukset, maps/ generoituja ja ylläpidettyjä reittikarttoja, utils/ build- ja reittigeneraattorit sekä deploy/ tenant-kierrosten skriptit. node_modules/ muodostuu package-lock.json-lukituksesta eikä sitä muokata käsin.

Juuritason package.json määrittää komennot ja riippuvuudet. vite.config.dev.js, vite.config.client.js ja vite.config.server.js erottavat paikallisen, client- ja server-buildin. serverless.yml määrittää Node.js 22 -SSR Lambdan, /rest/*-reitit ja S3-uudelleenohjausten lukuoikeuden. eslint.config.js, svelte.config.js, jsconfig.json ja vitest.config.js omistavat kehitys- ja tarkistusasetukset.

src-hakemisto jakaa runtime-vastuut

src/app/ sisältää ydintoimintoja, kuten reitittimen, navigaation, evästeet, otsakkeet, CSP:n, uudelleenohjaukset ja runtime-tilan. src/ext/ sisältää integroitujen ulkoisten palvelujen sovittimia, esimerkiksi chat- ja Builder.io-koodia. src/lib/ sisältää jaettuja storefront-apureita ja configuration.js-tiedoston; siinä ovat esimerkiksi kuvakoot, sivutusrajat ja logoRatio.

src/modals/ ja src/popups/ sisältävät käyttöliittymän uudelleenkäytettäviä modaali- ja popup-rakenteita. src/pages/ sisältää sivut. Staattinen sivu käyttää esimerkiksi +Page.svelte-tiedostoa ja dynaaminen sivu [slug]-hakemistoa, kuten src/pages/product/[slug]/. Sivukohtainen +onBeforeRender.js voi valmistella SSR-datan.

src/renderer/ sisältää yhteisen App.svelte-kuoren sekä +onBeforeRender.js, +onRenderHtml.js ja +onRenderClient.js -vaiheet. src/ssr/ sisältää Lambda-entryn, SSR-ytimen, HTTP keep-aliven ja staattisen virhevastauksen. src/styles/ sisältää global.css, dynamic.css, common.css ja relations.css; komponenttikohtainen tyyli pidetään silti komponentissa, kun tyyli ei ole aidosti globaali.

Partnerin REST-palvelut rajataan services-hakemistoon

Partnerin REST-palvelun rajattu laajennuspinta on src/rest/services/; muu src/rest/ sisältää /rest/*-rajapinnan ydinreitittimen, GraphQL-kuljetuksen ja sallitun julkisen GraphQL-pinnan. Nämä runkotiedostot ovat AI Commercen omistamia. JS-tiedoston polku palveluhakemistossa vastaa REST-URL:ia.

Reititin hyväksyy vain JSON-sarjallistettavan vastauksen ja palauttaa tuntemattomasta reitistä 404:n, puuttuvasta HTTP-metodista 405:n ja palveluvirheestä 500:n. POST-vastaukselta vaaditaan lisäksi success: true. Partneripalvelu käyttää turvallista serveripuolen GraphQL-asiakasta eikä lähetä tenant-tunnuksia selaimeen.

Serveripuolen kuljetus lukee TENANT, AICC_TENANT_SECRET ja AICC_GRAPHQL_SECRET -arvot process.env-ympäristöstä. Niitä ei saa nimetä VITE_-etuliitteellä. GraphQL-pyynnöllä on 8000 millisekunnin aikakatkaisu, ja upstreamin HTTP-, JSON-, GraphQL- ja timeout-virheet muutetaan rajatuiksi REST-virheiksi.

.env.local palvelee paikallista ympäristöä

Paikalliset ympäristöarvot pidetään repoon kuulumattomassa .env.local-tiedostossa. VITE_BACKEND_HOST määrittää paikallisen backend-hostin, VITE_DEV_IMAGE_URL kehityksen kuvapalvelimen, VITE_LANGUAGE_CODE reittikartan kielen ja VITE_LOCALE locale-arvon. VITE_CACHE_KEY voidaan lisätä kehityspyynnön otsakkeeseen välimuistin tarkistusta varten.

Kaikki VITE_-alkuiset arvot on käsiteltävä selaimelle näkyvinä. Älä tallenna niihin salasanoja, tenant-salaisuuksia, GraphQL-salaisuutta tai muuta arkaluontoista dataa. Storefrontin /rest/*-kuljetuksen salaisuudet ovat serveriympäristön muuttujia ilman VITE_-etuliitettä.

Kielitieto tulee ensisijaisesti pyynnön X-Forwarded-Language-otsakkeesta ja muuten määritetystä VITE_LANGUAGE_CODE-arvosta. Runtime ei saa piilottaa puuttuvaa kielikonfiguraatiota kovakoodatulla suomen oletuksella. Kuvien paikallinen proxy käyttää VITE_DEV_IMAGE_URL-arvoa ja API-proxy VITE_BACKEND_HOST-arvoa.

package.json ja package-lock.json omistavat riippuvuudet

Storefrontin riippuvuuksien tarkat versiot tarkistetaan aina package.json- ja package-lock.json-tiedostoista. Nykyisiä keskeisiä devDependencies-paketteja ovat @sveltejs/vite-plugin-svelte 3.1.2, cross-env 7.0.3, dotenv 16.5.0, eslint ^9.29.0, eslint-plugin-svelte ^2.46.1, serverless-prune-plugin ^2.1.0, svelte 4.2.20, svelte-preprocess ^6.0.3, vite ^5.4.21, vite-plugin-compression ^0.5.1 ja vite-plugin-dynamic-import ^1.6.0.

Testi- ja laatutyökaluina ovat lisäksi esimerkiksi vitest ^3.2.6, svelte-check ^4.4.6, prettier ^3.6.2, @testing-library/svelte ^5.3.1, jest-axe ^10.0.0 ja axe-core ^4.10.3. serverless on lukittu versioon 4.33.3. Ainoa varsinainen dependencies-osion paketti on tällä hetkellä @builder.io/sdk-svelte ^5.2.0.

package.json, serverless.yml, ydinhakemistot ja konfiguraatiot ovat CODEOWNERS-suojattuja. Partneri ei lisää tai päivitä riippuvuutta omin päin. Hyväksytyn tenant-kohtaisen riippuvuuden yhteydessä package-lock.json generoidaan kyseisellä haaralla npm install -komennolla; lukitusta ei kopioida toiselta haaralta sokkona.

Reittikartat muodostuvat sivurakenteesta ja kielidatasta

utils/routeMapGenerator.js lukee src/pages/-hakemistosta +Page.svelte-sivut ja kirjoittaa maps/routeMap.js-kartan. Dynaaminen hakemisto, kuten [slug], säilyy reittikuvauksessa. Build muodostaa lisäksi plus-tiedostojen ja reittichunkkien kartat omilla generaattoreillaan.

maps/routeTranslationsMap.js sisältää kielikohtaiset reittikäännökset, ja utils/routeTranslator.js valitsee kartan pyynnön kielen perusteella. Nykyisessä rakenteessa ei ole erillisiä languageMap.js, routeTranslations.js tai routeMap.js-lähdetiedostoja vanhan ohjeen tarkoittamassa muodossa: routeMap.js on generoitu maps/-tuotos ja käännösapu elää utils/-hakemistossa.

Kielireittiä muutettaessa päivitetään sen omistava auktoriteetti ja ajetaan generaattorit; generoituun karttaan ei rakenneta rinnakkaista käsin ylläpidettyä totuutta. npm run dev, npm test ja npm run build ajavat tarvittavia karttageneraattoreita osana omaa ketjuaan.

S3 fallback käsittelee uudelleenohjauksia

AI Commercen utils/s3Fallback.js ei palauta puuttuvaa HTML-sivua S3:sta. Se muodostaa pyydetystä URL:sta avaimen redirects/<polku>/redirect.json ja etsii S3:sta uudelleenohjauskohteen. Dynaamisella backend-reitillä tarkistus tehdään backendin 404-vastauksen jälkeen; puuttuvalle staattiselle reitille sama tarkistus voidaan tehdä suoraan.

Jos redirect-tiedosto sisältää eri kohde-URL:n, runtime rakentaa uudelleenohjauksen ja säilyttää kyselyparametrit. Saman URL:n osoittava kohde hylätään silmukan estämiseksi. Jos kohdetta ei löydy tai JSON on virheellinen, fallback palauttaa null-arvon ja varsinainen virheketju säilyttää 404-tilan.

Tällä rajauksella hakukone saa puuttuvalle sivulle oikean HTTP 404 -vastauksen, mutta aiemmin siirretty URL voidaan ohjata hallitusti uuteen osoitteeseen. S3-oikeus on rajattu redirects/*-objektien lukemiseen; fallbackia ei käytetä yleisenä tiedosto- tai sivupalveluna.

main-haara omistaa jaetun verkkokauppakoodin

AI Commercen yhteiset verkkokauppakorjaukset tehdään ensisijaisesti puhtaaseen main-haaraan. Tenant-muutoksessa valitaan kyseisen tenantin oikea Git-haara; tenanttia ei emuloida muokkaamalla ympäristötiedostoa. Yhdistämisessä säilytetään tenantin havaittava käyttäytyminen, importit, komponenttiomistus ja tenant-kohtaiset riippuvuudet.

Täysi julkaisujärjestys puhtaasta main-haarasta on ./deploy/merge.sh -r, ./deploy/check.sh, ./deploy/push.sh ja ./deploy/deploy.sh. Keskeytynyttä merge- tai check-kierrosta voidaan jatkaa dokumentoidulla -f <branch>-valinnalla. Partneri ei käynnistä monitenanttikierrosta ilman Petroltä saatua toimeksiantoa.

Komennon valmistuminen ei yksin todista tenantin toimivuutta. Yhdistämisen jälkeen tarkistetaan tenantin header, valikko, navigaatio ja komponentti-importit sekä ajetaan haaran omat tarkistukset. Näin yhteinen koodi pysyy yhdessä kanonisessa toteutuksessa mutta tenant-kohtainen käyttöliittymä ei katoa automaattisen konfliktiratkaisun alle.