> ## 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 # Comércio Produtos e pedidos do workspace num ciclo de vida unidirecional. ## Passo a passo para iniciantes Pré-requisitos: Leia os dois guias para iniciantes abaixo, conclua a configuração local da Web e abra este monorepo na raiz do seu editor. As configurações da Web pertencem a `apps/web/.env.local`; Next.js não lê a raiz `.env`. `/dashboard` no modo falso padrão é uma demonstração sem banco de dados; `/auth` precisa de um banco de dados migrado. Termos rápidos: um espaço de trabalho consiste em usuários, dados e configurações separados de uma equipe. O servidor é o back-end confiável; mantenha as chaves do provedor fora do navegador e do código do telefone. Uma migração é uma alteração de versão do banco de dados que cria ou atualiza tabelas. Um modelo de IA é o mecanismo que responde; o catálogo de modelos é a lista do servidor de IDs e preços de modelos disponíveis. Um provedor é um serviço externo, como IA, e-mail ou serviço de cobrança. Um direito é uma concessão que permite que um espaço de trabalho use um recurso. Um webhook é uma mensagem que um serviço envia para o URL de outro serviço. 1. Como proprietário ou administrador do espaço de trabalho, abra `/commerce` e use o formulário do produto para criar um rascunho com nome, moeda, preço unitário menor inteiro e estoque rastreado opcional (para USD, `1299` significa US$ 12,99). 2. Ative-o e crie um pedido de teste local; confirme se o servidor calcula o total e armazena o instantâneo do produto. 3. Não conecte um provedor de pagamento ao vivo nem cobre um comprador real. Se um pedido não puder avançar, verifique o estoque disponível e o estado documentado do pedido antes de tentar novamente. Para código personalizado, comece com o `prompts/README.md` fornecido e copie o prompt mais próximo: `prompts/new-app-screen.md` para uma tela de aplicativo ou `prompts/new-landing-page.md` para uma página pública. Para trabalho de servidor, banco de dados ou provedor, dê ao seu agente de codificação a tarefa deste guia e peça-lhe para ler `AGENTS.md`, `.ai/PROJECT_CONTEXT.md` e espelhos `.ai/` correspondentes; inspecione os arquivos de origem exatos nomeados aqui; listar arquivos e verificações antes de editar; preservar a propriedade do espaço de trabalho e os segredos apenas do servidor; e mostrar a diferença. Informe o comportamento desejado, campos de entrada e saída, funções permitidas, sucessos e erros esperados e a conta de teste, provedor ou dispositivo. Use valores de amostra; nunca cole um segredo real. [Antes de começar](https://supastack.dev/pt/docs/web/before-you-start.md) [Noções básicas sobre terminais](https://supastack.dev/pt/docs/web/terminal-basics.md) [Configuração local da Web](https://supastack.dev/pt/docs/web/ship-in-5-minutes.md) [Avisos do agente e memória do projeto](https://supastack.dev/pt/docs/web/agents.md) ## Gerenciar produtos e estoque `/commerce` fornece gerenciamento de proprietário/administrador para produtos de espaço de trabalho. Os estados do produto são rascunho/ativo/arquivado; os preços usam unidades monetárias menores e o estoque é rastreado opcionalmente. A persistência compartilhada reside em `packages/db`. Este é um módulo de construção de produto. Não inclui a compra deste kit, a entrega do repositório de origem ou o cumprimento da licença do vendedor. ## Siga o ciclo de vida do pedido Pedidos antecipados → pagos → atendidos, com comportamento de cancelamento/reabastecimento e reembolso. O servidor calcula os totais e armazena instantâneos do nome do produto/preço unitário do item para que as edições em um produto não reescrevam o histórico de pedidos. Os eventos `commerce.order_*` suportam integrações downstream. Conecte deliberadamente um fluxo real de pagamento de produto. Uma transição de estado administrativo por si só não verifica uma cobrança ou reembolso do provedor de pagamento. ## Testar estoque e transições de estado Verifique estoque insuficiente, pedidos simultâneos, adulteração de preços do cliente, transições inválidas para trás, cancelamento de reabastecimento, comportamento de reembolso e acesso entre espaços de trabalho. [Eventos de comércio externo](https://supastack.dev/pt/docs/web/project-structure.md) [Bloco de grade do produto](https://supastack.dev/pt/docs/web/project-structure.md) [Bloco de tabela de registros](https://supastack.dev/pt/docs/web/project-structure.md) ## Instalação e configuração A superfície /commerce gere um catálogo de produtos e pedidos para o workspace ativo. Os produtos têm nome, slug, preço em cêntimos inteiros, moeda de três letras, URL de imagem opcional e inventário rastreado opcional; os pedidos guardam linhas em commerce_order_item com totais calculados no servidor. O estado do pedido só avança — pending → paid → fulfilled, com cancelamento antes do pagamento e reembolso depois. O evaluateOrderStatusChange rejeita transições inválidas, inalteradas ou proibidas, pelo que um pedido cancelado ou reembolsado nunca pode reabrir. ``` /commerce owner/admin console src/commerce.ts money math + lifecycle src/commerce-actions.ts owner/admin mutations commerce_product/order/order_item ``` ## Fluxo de implementação Só owners e admins escrevem — cada ação resolve a sessão e o workspace através de requireWorkspaceManager. O createCommerceOrderAction valida as linhas (quantidades inteiras de 1–9999, produtos duplicados são fundidos), restringe as linhas a produtos ativos, recalcula os totais no servidor e mantém o pedido numa única moeda. O inventário rastreado decresce quando um pedido é criado e repõe-se no cancelamento; um campo de inventário vazio significa não rastreado. A criação do pedido e cada mudança de estado emitem os webhooks commerce.order_created e commerce.order_status_changed mais linhas de auditoria. ## Verificação e resolução de problemas Verifica que um membro abaixo de admin não consegue criar produtos nem mover pedidos, que transições para trás ou laterais são rejeitadas, e que um pedido pago não pode ser cancelado. Confirma que os totais vêm do servidor — nunca confies num montante vindo do cliente — e que o stock volta após um cancelamento. ## Seguinte [Páginas de marketing](https://supastack.dev/pt/docs/web/marketing-site.md)