AI-szabályok

Ezek a szabályok a Poltura-appokon vagy témákon dolgozó AI-eszközöknek szólnak. A teljes dokumentációs index a https://developers.poltura.com/llms.txt címen található, és minden oldal elérhető Markdown formátumban is, ha a címéhez hozzáadod a .md kiterjesztést.

MindigHivatkozás másolása

• Mielőtt kódot írnál, olvasd el a hozzá tartozó dokumentációs oldalt a .md címén keresztül.
• Kizárólag a nyilvános csomagokat használd: @poltura/app-sdk, @poltura/app-ui, @poltura/app-contracts, @poltura/cli és @poltura/theme-sdk. Soha ne importálj más @poltura/* csomagot, és soha ne nyúlj egy bolt adatbázisához.
• Ne találj ki API-kat. Ha egy név nem szerepel a dokumentációban vagy a csomag típusaiban, akkor nem létezik.
• Mielőtt késznek nyilvánítanád a munkát, futtasd le a poltura check parancsot az app vagy a téma könyvtárában, és javíts ki minden jelzett hibát. Minden találat megnevezi a szabályt, és leírja, mit kell módosítani. Az eredmény beolvasásához használd a poltura check --json parancsot.

AppokHivatkozás másolása

• Egy app a poltura.app.json fájlból és a forrásfájljaiból áll. Az alapstruktúrát a poltura app create <dir> --template native vagy --template hosted paranccsal hozhatod létre.
• Minden módosítás után futtasd a poltura app build és a poltura app validate parancsot, és javíts ki minden hibát, mielőtt továbblépnél. A befejezés előtt futtasd a poltura check parancsot: ez ellenőrzi a jogosultságokat, az AI-ügynök-bejegyzéseket és a kódszabályokat is.
• A bemeneti adatokat ott értelmezd, ahol belépnek a kódodba: ne használj unknown paramétereket vagy visszatérési típusokat, se unknown, any vagy object szótárakat, se runtime typeof vizsgálatot nem értelmezett értékeken; minden type castinghez fűzz egy // SAFETY: megjegyzést.
• Csak a legszükségesebb jogosultságokat deklaráld az apphoz. Minden jogosultsághoz adj meg egy 8 és 280 karakter közötti purpose leírást, amelyet a kereskedő is megért, hiszen a kereskedők ezt elolvassák a jóváhagyás előtt.
• A webáruház-blokkokat és azok beállításait egyszer deklaráld az @poltura/app-sdk/elements csomag defineBlock függvényével, az elements által megnevezett fájlban. A worker a useSettings() függvénnyel olvassa be a kereskedő által megadott értékeket.
• A worker-fájlok a következővel kezdődnek: import '@poltura/app-ui/worker'. A rendereléshez az @poltura/app-ui/worker-runtime csomag startUiWorker(<Root />) függvényét használják, és kizárólag az @poltura/app-ui/admin (adminfelületi célfelületek) vagy az @poltura/app-ui/storefront (webáruházi célfelületek) primitívjeivel rajzolnak felületeket.
• A workerek nem indíthatnak kérést a szervered vagy az App API felé. A backendet a useAction(actionId) hívással érik el, a backend pedig az @poltura/app-sdk/actions csomag createActionHandler függvényével ellenőrzi a kérést.
• A telepítési hozzáférési tokenek a szervereden maradnak. Soha ne küldj tokent workernek, iframe-nek vagy a böngészőnek.
• Az App API-t az @poltura/app-sdk csomagban található PolturaClient segítségével hívd. A listák kurzoralapú paginationt használnak (limit legfeljebb 100, majd nextCursor). Minden írási művelethez tartoznia kell egy Idempotency-Key headernek. A pénzösszegek formátuma { amount: "49.99", currency: "EUR" } a fő pénznemegységben; soha ne szorozd be 100-zal.
• Minden webhookot ellenőrizz az @poltura/app-sdk/webhooks csomag createWebhookVerifier függvényével, mielőtt beolvasnád a bodyját. A kézbesítéseket a rendszer újrapróbálja, ezért egy webhook kétszeri feldolgozása sem okozhat problémát.
• A közzététel a poltura app publish --api "$POLTURA_API" --token "$POLTURA_APP_TOKEN" paranccsal történik, az appId értékét a poltura.app.json fájlban vagy a --app kapcsolóval megadva. A token egy fejlesztői token (CI esetén pltd_, vagy személyes pltu_) a Developer apps felületről. Soha ne commitolj tokent.

TémákHivatkozás másolása

• A téma TSX-ből és JSON-ból áll, amelyet a bolt témakódszerkesztőjében szerkeszthetsz. A mentések a téma piszkozatába kerülnek; a közzététel külön lépés.
• A Poltura API-kat a @poltura/theme-sdk/<module> alól importáld (root szintű import nincs). Ezen kívül a téma importálhatja a saját fájljait, a Reactet, valamint a témavizsgáló által felsorolt rögzített UI librarykat; minden mást elutasít a rendszer.
• Fájlonként egy szekciót (src/sections/<type>.tsx) és fájlonként egy blokkot (src/blocks/<type>.tsx) hozz létre, amelyeket az @poltura/theme-sdk/elements csomag defineSection vagy defineBlock függvényével deklarálsz. A type kebab-case formátumú, megegyezik a fájlnévvel, és rögzített marad, miután a kereskedők használni kezdik; az átnevezéshez a renamedFrom mezőt használd.
• A szekció komponense megkapja az attrs propot. Bontsd ki pontosan egy root elemre, a classokat pedig fésüld össze a @poltura/theme-sdk/ui csomag cn(attrs.className, ...) függvényével. Enélkül a kereskedő stílusbeállításai hatástalanok maradnak.
• A beállítások field.* építők label és default értékkel. Ezeket a típusos settings propból olvasd be, és a kereskedők által helyben szerkeszthető szövegekhez használd az EditableText komponenst.
• Az árakat a price részekkel jelenítsd meg, minden más összeget pedig a useFormat().money() függvénnyel formázz. Soha ne formázz pénzösszeget kézzel.
• A témakód a szerveren renderelődik a bolt minden vásárlója számára: ne használj vásárlónkénti állapotot és idő-queryt modulszinten, valamint ne használj window vagy document objektumot az effecteken kívül.
• Az alapértelmezett szövegekben ne használj gondolatjelet és középső pontot sem.
• A kódszerkesztőben a témavizsgáló minden mentéskor lefut. Közzététel előtt javíts ki minden jelzett hibát.
• Ha fájlokkal dolgozol egy témán, a befejezés előtt futtasd a poltura check parancsot: ez lefuttatja a témavizsgálót és a kódszabályokat is.