E-commerce

Walkthrough voor beginners

Vereisten: Lees de twee onderstaande beginnershandleidingen, voltooi de lokale webconfiguratie en open deze monorepo in de root van uw editor. Webinstellingen horen thuis in apps/web/.env.local; Next.js leest de root .env niet. /dashboard in de standaard nepmodus is een demo zonder database; /auth heeft een gemigreerde database nodig.

Korte termen: een werkruimte bestaat uit de afzonderlijke gebruikers, gegevens en instellingen van één team. De server is de vertrouwde backend; houd providersleutels uit de browser- en telefooncode. Een migratie is een versiebeheer van de database, waarbij tabellen worden gemaakt of bijgewerkt. Een AI-model is de motor die antwoord geeft; de modelcatalogus is de serverlijst met beschikbare model-ID's en prijzen. Een provider is een externe service, zoals een AI-, e-mail- of factureringsservice. Een recht is een subsidie ​​waarmee een werkruimte een functie kan gebruiken. Een webhook is een bericht dat de ene service naar de URL van een andere service verzendt.

1. Als eigenaar of beheerder van de werkruimte opent u /commerce en gebruikt u het productformulier om een ​​concept te maken met een naam, valuta, gehele eenheidsprijs en optionele bijgehouden voorraad (voor USD betekent 1299 $ 12,99).

2. Activeer het en maak een lokale testbestelling aan; bevestig dat de server het totaal berekent en de productmomentopname opslaat.

3. Sluit geen live betalingsprovider aan en breng geen kosten in rekening bij een echte koper. Als een bestelling niet kan doorgaan, controleer dan de beschikbare voorraad en de gedocumenteerde bestelstatus voordat u het opnieuw probeert.

Voor aangepaste code begint u met de meegeleverde prompts/README.md en kopieert u de dichtstbijzijnde prompt: prompts/new-app-screen.md voor een app-scherm of prompts/new-landing-page.md voor een openbare pagina. Voor server-, database- of providerwerk geeft u uw codeeragent de taak van deze handleiding en vraagt ​​u hem om AGENTS.md, .ai/PROJECT_CONTEXT.md en overeenkomende .ai/-mirrors te lezen; inspecteer de exacte bronbestanden die hier worden genoemd; maak een lijst van bestanden en controleer deze voordat u deze bewerkt; behoud van het eigendom van de werkruimte en geheimen voor de server; en laat je het verschil zien. Vertel het gewenste gedrag, invoer- en uitvoervelden, toegestane rollen, verwacht succes en fouten, en het testaccount, de provider of het apparaat. Gebruik voorbeeldwaarden; plak nooit een echt geheim.

• Voordat u begint
• Basisbeginselen van de terminal
• Lokale webinstellingen
• Agentprompts en projectgeheugen

Beheer producten en voorraad

/commerce biedt eigenaar-/beheerdersbeheer voor werkruimteproducten. Productstatussen zijn concept/actief/gearchiveerd; prijzen gebruiken kleine valuta-eenheden en de voorraad wordt optioneel bijgehouden. Gedeelde volharding leeft in packages/db.

Dit is een productbouwmodule. Dit omvat niet de aankoop van deze kit, de levering van de bronrepository of de vervulling van de verkoperslicentie.

Volg de levenscyclus van de bestelling

Bestellingen vooraf in behandeling → betaald → uitgevoerd, met annulerings-/aanvullings- en terugbetalingsgedrag. De server berekent de totalen en slaat momentopnamen van de productnaam/eenheidsprijs van het item op, zodat bewerkingen aan een product historische bestellingen niet herschrijven. commerce.order_*-gebeurtenissen ondersteunen downstream-integraties.

Verbind bewust een echte productbetalingsstroom. Met een overgang naar de beheerdersstatus zijn de kosten of terugbetalingen van een betalingsprovider niet geverifieerd.

Test voorraad- en statusovergangen

Controleer onvoldoende voorraad, gelijktijdige bestellingen, geknoei met klantprijzen, ongeldige achterwaartse transities, herbevoorrading van annuleringen, terugbetalingsgedrag en toegang tot meerdere werkplekken.

• Uitgaande handelsgebeurtenissen
• Productrasterblok
• Recordtabelblok

Setup en configuratie

Het /commerce-oppervlak beheert een productcatalogus en bestellingen voor de actieve workspace. Producten dragen een naam, slug, integer-centprijs, drielettervaluta, optionele afbeeldings-URL en optionele voorraadtracking; bestellingen slaan regels op in commerce_order_item met op de server berekende totalen.

De bestelstatus beweegt alleen vooruit — pending → paid → fulfilled, met annuleren vóór betaling en terugbetaling erna. evaluateOrderStatusChange weigert ongeldige, ongewijzigde of verboden overgangen, dus een geannuleerde of terugbetaalde bestelling kan nooit heropenen.

/commerce                   owner/admin console
src/commerce.ts             money math + lifecycle
src/commerce-actions.ts     owner/admin mutations
commerce_product/order/order_item

Implementatieworkflow

Alleen owners en admins schrijven — elke actie resolveert sessie en workspace via requireWorkspaceManager. createCommerceOrderAction valideert regels (hele aantallen van 1–9999, dubbele producten worden samengevoegd), beperkt regels tot actieve producten, rekent totalen server-side opnieuw en houdt een bestelling op één valuta.

Getrackte voorraad daalt bij het aanmaken van een bestelling en wordt bij annulering aangevuld; een leeg voorraadveld betekent ongetrackt. Het aanmaken van een bestelling en elke statuswijziging zenden commerce.order_created- en commerce.order_status_changed-webhooks plus auditrijen.

Verificatie en probleemoplossing

Verifieer dat een member onder admin geen producten kan aanmaken of bestellingen kan verplaatsen, dat achterwaartse en zijwaartse overgangen worden geweigerd, en dat een betaalde bestelling niet kan worden geannuleerd. Controleer dat totalen van de server komen — vertrouw nooit een door de client geleverd bedrag — en dat de voorraad terugkeert na een annulering.