For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /pt/docs/web/commerce.md (or send Accept: text/markdown).
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.
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.
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_itemFluxo 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.