> ## Documentation Index > Fetch the complete documentation index at: https://supastack.dev/llms.txt > Use this file to discover all available pages before exploring further. > For the full documentation corpus in one file, fetch: https://supastack.dev/llms-full.txt # Commercio Prodotti e ordini del workspace su un ciclo di vita unidirezionale. ## Procedura dettagliata per principianti Prerequisiti: leggi le due guide per principianti di seguito, completa la configurazione locale del Web e apri questo monorepo alla radice nel tuo editor. Le impostazioni Web appartengono a `apps/web/.env.local`; Next.js non legge la radice `.env`. `/dashboard` nella modalità falsa predefinita è una demo senza database; `/auth` necessita di un database migrato. Termini rapidi: uno spazio di lavoro è costituito da utenti, dati e impostazioni separati di un team. Il server è il backend affidabile; mantenere le chiavi del provider fuori dal browser e dal codice del telefono. Una migrazione è una modifica del database con versione che crea o aggiorna tabelle. Un modello AI è il motore che risponde; il catalogo dei modelli è l'elenco del server degli ID e dei prezzi dei modelli disponibili. Un fornitore è un servizio esterno come un servizio di intelligenza artificiale, posta elettronica o fatturazione. Un diritto è una concessione che consente a un'area di lavoro di utilizzare una funzionalità. Un webhook è un messaggio che un servizio invia allo URL di un altro servizio. 1. In qualità di proprietario o amministratore di un'area di lavoro, apri `/commerce` e utilizza il modulo del prodotto per creare una bozza con nome, valuta, prezzo unitario minore intero e stock tracciabile opzionale (per USD, `1299` significa $ 12,99). 2. Attivalo e crea un ordine di prova locale; confermare che il server calcola il totale e memorizza l'istantanea del prodotto. 3. Non connettere un fornitore di servizi di pagamento in tempo reale né addebitare costi a un acquirente reale. Se un ordine non può avanzare, controlla le scorte disponibili e lo stato documentato dell'ordine prima di riprovare. Per il codice personalizzato, inizia con `prompts/README.md` in dotazione e copia il prompt più vicino: `prompts/new-app-screen.md` per la schermata di un'app o `prompts/new-landing-page.md` per una pagina pubblica. Per il lavoro su server, database o provider, assegna al tuo agente di codifica il compito di questa guida e chiedigli di leggere `AGENTS.md`, `.ai/PROJECT_CONTEXT.md` e i mirror `.ai/` corrispondenti; controllare gli esatti file sorgente nominati qui; elencare file e controlli prima della modifica; preservare la proprietà dello spazio di lavoro e i segreti solo del server; e mostrarti la differenza. Indicagli il comportamento desiderato, i campi di input e output, i ruoli consentiti, i successi e gli errori previsti e l'account, il fornitore o il dispositivo di prova. Utilizzare valori campione; non incollare mai un vero segreto. [Prima di iniziare](https://supastack.dev/it/docs/web/before-you-start.md) [Nozioni di base sui terminali](https://supastack.dev/it/docs/web/terminal-basics.md) [Configurazione locale Web](https://supastack.dev/it/docs/web/ship-in-5-minutes.md) [Messaggi dell'agente e memoria del progetto](https://supastack.dev/it/docs/web/agents.md) ## Gestire prodotti e inventario `/commerce` fornisce la gestione proprietario/amministratore per i prodotti Workspace. Gli stati del prodotto sono bozza/attivo/archiviato; i prezzi utilizzano unità valutarie minori e l'inventario viene facoltativamente monitorato. La persistenza condivisa vive in `packages/db`. Questo è un modulo di creazione del prodotto. Non include l'acquisto di questo kit, la consegna del repository di origine o l'adempimento della licenza del venditore. ## Segui il ciclo di vita dell'ordine Gli ordini avanzano in attesa → pagati → evasi, con modalità di annullamento/riassortimento e rimborso. Il server calcola i totali e memorizza le istantanee del nome prodotto/prezzo unitario dell'articolo in modo che le modifiche a un prodotto non riscrivano gli ordini storici. Gli eventi `commerce.order_*` supportano le integrazioni downstream. Collega deliberatamente un flusso di pagamento del prodotto reale. La sola transizione dello stato amministrativo non verifica l'addebito o il rimborso del fornitore di servizi di pagamento. ## Testare le transizioni azionarie e statali Verifica inventario insufficiente, ordini simultanei, manomissione dei prezzi cliente, transizioni all'indietro non valide, riassortimento annullato, comportamento di rimborso e accesso cross-workspace. [Eventi di commercio in uscita](https://supastack.dev/it/docs/web/project-structure.md) [Blocco griglia prodotto](https://supastack.dev/it/docs/web/project-structure.md) [Blocco tabella record](https://supastack.dev/it/docs/web/project-structure.md) ## Installazione e configurazione La superficie /commerce gestisce un catalogo prodotti e gli ordini per il workspace attivo. I prodotti portano nome, slug, prezzo in centesimi interi, valuta a tre lettere, URL immagine opzionale e inventario tracciato opzionale; gli ordini salvano le righe in commerce_order_item con totali calcolati sul server. Lo stato dell'ordine avanza solo in avanti — pending → paid → fulfilled, con annullamento prima del pagamento e rimborso dopo. evaluateOrderStatusChange rifiuta transizioni non valide, invariate o vietate, quindi un ordine annullato o rimborsato non può mai riaprirsi. ``` /commerce owner/admin console src/commerce.ts money math + lifecycle src/commerce-actions.ts owner/admin mutations commerce_product/order/order_item ``` ## Flusso di implementazione Solo owner e admin scrivono — ogni azione risolve sessione e workspace tramite requireWorkspaceManager. createCommerceOrderAction valida le righe (quantità intere da 1 a 9999, prodotti duplicati uniti), limita le righe ai prodotti attivi, ricalcola i totali lato server e mantiene l'ordine su una sola valuta. L'inventario tracciato decrementa alla creazione dell'ordine e si rifornisce all'annullamento; un campo inventario vuoto significa non tracciato. La creazione dell'ordine e ogni cambio di stato emettono i webhook commerce.order_created e commerce.order_status_changed più righe di audit. ## Verifica e risoluzione dei problemi Verifica che un membro sotto il ruolo admin non possa creare prodotti né spostare ordini, che le transizioni all'indietro o laterali siano rifiutate, e che un ordine pagato non possa essere annullato. Controlla che i totali arrivino dal server — non fidarti mai di un importo fornito dal client — e che lo stock torni dopo un annullamento. ## Successivo [Pagine di marketing](https://supastack.dev/it/docs/web/marketing-site.md)