Fluxograma do Sistema do E-commerce

Links rápidos:

• README principal
• Documentação técnica
• Roadmap do e-commerce
• Backlog P0

Visão ponta a ponta

Este mapa mostra a conexão entre os dois grandes domínios: operação administrativa e experiência do cliente. As seções seguintes quebram cada trecho em subfluxos e variações.

Cliente / Storefront - Navegação e regionalização

O fluxo do cliente começa na entrada do storefront, passa pela regionalização, navegação comercial, carrinho server-side e checkout, e termina com confirmação assíncrona do pedido por webhook do gateway de pagamento.

Cliente / Storefront - Carrinho e checkout

Este subfluxo explicita os caminhos possíveis após a adição ao carrinho: validação de estoque/preço, endereço, entrega, pagamento, rejeição e confirmação por webhook.

Painel / Publicação - Autenticação e permissões

O fluxo administrativo cobre autenticação, sessão segura, autorização por permissões e o ciclo de edição/publicação que transforma rascunhos do painel em snapshots JSON consumidos pelo storefront.

Painel / Publicação - Snapshot e leitura dinâmica

Este subfluxo mostra o contrato de publicação e como o storefront decide entre página dinâmica publicada, rota nativa e erro de rota.

Variações cobertas

• Regionalização opcional ou obrigatória.
• CEP atendido, não atendido ou trocado durante a jornada.
• Produto disponível, indisponível ou substituído por alternativa.
• Carrinho novo, carrinho recuperado e request idempotente repetido.
• Item inválido, carrinho vazio e recálculo de totais.
• Checkout com usuário autenticado, cadastro, login ou convidado.
• Endereço atendido, endereço recusado e fallback para retirada.
• Pagamento aprovado, rejeitado, timeout e confirmação tardia por webhook.
• Admin autenticado, sessão expirada ou ação bloqueada por permissão.
• Rascunho salvo sem publicação, publicação abortada por validação e publicação concluída.
• Storefront com página dinâmica publicada, rota nativa, fallback ou not_found.

Pontos de integração

• ECOM_CONTENT_PATH: caminho compartilhado opcional para publicação e leitura dos snapshots entre EcommPanel e E-commerce.
• site-pages.published.json: snapshot autoritativo de páginas dinâmicas publicadas, pronto para resolução pelo storefront.
• manifest.json: metadados do pacote publicado, como data de geração, quantidade de páginas e checksum.
• Contrato futuro API v1: camada versionada para substituir ou complementar a leitura direta de arquivos quando painel e storefront operarem desacoplados.

Observações operacionais

• O storefront deve ler apenas conteúdo publicado, nunca rascunhos administrativos.
• A publicação em JSON preserva a operação local simples e prepara a transição para persistência real.
• Em runtime de servidor, novas páginas dinâmicas podem ser resolvidas sem criar arquivos novos em src/app/e-commerce.
• Em export estático, novas rotas publicadas exigem nova exportação para entrar na saída final.