Mini site de documentaçãoDeveloper Atlas

Entrada rápida para navegar arquitetura, APIs, operação e guias técnicos do projeto sem depender da estrutura do repositório.

53 notas

Procure por módulo, API, rota, fluxo operacional ou termo do projeto.

Guias técnicos/docs/guias/ecommerce-minha-conta

Ecommerce - Minha Conta

Explicar como a área do cliente entra no storefront, como o acesso foi separado do admin e quais tabelas e fluxos sustentam essa nova camada.

Recorte da seçãoGuia orientado por fluxo

Leitura pensada para explicar responsabilidades, ordem de execução e trechos reais do código com foco no fluxo da implementação.

Atualizado15 de abr. de 2026
Seções25
Tags4
guiaecommerceminha-contacliente

Objetivo deste guia

Explicar como a área do cliente entra no storefront, como o acesso foi separado do admin e quais tabelas e fluxos sustentam essa nova camada.

Papel do módulo

A seção Minha conta passa a ser a camada de relacionamento do cliente com a loja depois do checkout.

Nesta fase, ela já permite:

  • login principal por e-mail/CPF e senha;
  • login por código enviado por e-mail;
  • cadastro completo de pessoa física ou jurídica;
  • validação do cadastro por código enviado por e-mail antes de ativar a conta;
  • consulta de pedidos vinculados à conta;
  • manutenção de dados cadastrais;
  • caderno de endereços com múltiplos destinos;
  • exportação dos dados da conta;
  • solicitação de exclusão com fila interna de tratamento;
  • separação estrutural entre conta do cliente e acesso do admin.

Política de senha da conta

O cadastro do cliente agora segue a mesma linha forte do painel:

  • mínimo de 12 caracteres;
  • ao menos uma letra maiúscula;
  • ao menos uma letra minúscula;
  • ao menos um número;
  • ao menos um símbolo.

O formulário mostra esses critérios em tempo real para reduzir erro operacional e evitar senhas fracas já na entrada.

Rotas e pontos de entrada

Storefront

  • /e-commerce/login
  • /e-commerce/minha-conta

Pontos do código

  • src/app/e-commerce/minha-conta/page.tsx
  • src/features/ecommerce/components/account/AccountView.tsx
  • src/features/ecommerce/server/customerAccountStore.ts
  • src/features/ecommerce/server/customerAuth.ts
  • src/app/api/ecommerce/account/register/route.ts
  • src/app/api/ecommerce/account/register/verify/route.ts
  • src/app/api/ecommerce/account/login-token/request/route.ts
  • src/app/api/ecommerce/account/login-token/verify/route.ts
  • src/app/api/ecommerce/account/profile/route.ts
  • src/app/api/ecommerce/account/addresses/route.ts
  • src/app/api/ecommerce/account/lgpd/export/route.ts
  • src/app/api/ecommerce/account/lgpd/request-erasure/route.ts
  • src/features/ecommerce/types/account.ts
  • src/features/ecommerce/components/checkout/CheckoutView.tsx

Como funciona agora

O fluxo agora já usa backend e banco dedicado para o domínio do cliente.

Leitura prática:

  1. o cliente entra em /e-commerce/login ou em Minha conta;
  2. o cadastro pode ficar pendente por alguns minutos até o e-mail ser confirmado;
  3. o login principal usa e-mail ou CPF/CNPJ com senha;
  4. o acesso por código continua disponível como alternativa, mas somente para contas já verificadas;
  5. o código de 6 dígitos é emitido em tabela própria de cliente;
  6. ao validar a autenticação, o storefront abre uma sessão dedicada de cliente;
  7. perfil, pedidos e endereços passam a ser lidos do banco.

Validação do cadastro

O fluxo de cadastro agora tem duas fases quando a política estiver ativa no painel:

  1. o formulário grava um cadastro pendente;
  2. um código é enviado para o e-mail informado;
  3. a conta só é ativada depois da validação;
  4. o cliente já entra autenticado após confirmar o código.

Tabela dedicada:

  • customer_pending_registrations

Essa camada existe para:

  • reduzir cadastros descartáveis;
  • evitar ativação imediata de e-mails inválidos;
  • permitir expurgo automático de tentativas não concluídas.

Relação com o painel

O painel agora também consegue operar a mesma base de clientes sem depender da jornada do storefront.

Isso significa que o time interno pode:

  • criar cliente novo direto no admin;
  • completar dados PF ou PJ;
  • cadastrar vários endereços;
  • ajustar consentimentos e status da conta;
  • preparar um cadastro antes mesmo de o cliente acessar Minha conta.

Ou seja: Minha conta e EcommPanel > Clientes não competem. Ambos operam a mesma base com finalidades diferentes.

Tabelas dedicadas do cliente

O domínio novo não reaproveita panel_users nem panel_sessions.

Tabelas centrais:

  • customer_accounts
  • customer_addresses
  • customer_orders
  • customer_login_tokens
  • customer_sessions
  • customer_audit_events

Além disso, o checkout agora também conversa com:

  • commerce_order_drafts
  • commerce_orders
  • commerce_order_events

Isso garante isolamento entre:

  • operação administrativa;
  • navegação do cliente;
  • dados pessoais e comerciais do consumidor.

Como o checkout alimenta a conta

Quando o checkout conclui um pedido:

  1. o pedido é finalizado;
  2. os dados do cliente são normalizados no servidor;
  3. a conta do cliente é localizada ou criada de forma mínima;
  4. a projeção da conta é gravada em customer_orders;
  5. o pedido operacional é consolidado em commerce_orders;
  6. a timeline operacional entra em commerce_order_events;
  7. o endereço usado pode ser reaproveitado em customer_addresses.

Isso faz com que a jornada já fique coerente:

  • o cliente compra;
  • a compra passa a existir em Minha conta;
  • os dados do checkout deixam de ficar soltos;
  • a área do cliente já nasce compatível com a futura API transacional.

O que o cliente já pode fazer

Visão geral

  • ver quantidade de pedidos;
  • ver quantidade de endereços;
  • localizar o último pedido registrado;
  • navegar com links rápidos para checkout, endereços e cadastro.

Pedidos

  • listar pedidos já vinculados à conta no banco;
  • ver ID, data, pagamento, valor e itens do pedido.

Dados

  • atualizar dados pessoais ou empresariais;
  • revisar CPF/CNPJ, RG ou inscrição estadual;
  • ajustar consentimentos e contatos.

Endereços

  • cadastrar múltiplos endereços;
  • editar endereço;
  • excluir endereço;
  • definir padrão de entrega e cobrança.

Privacidade

  • gerar pacote com os dados da conta;
  • registrar solicitação de exclusão;
  • entrar em fila interna de revisão antes da execução final;
  • entender o que pode ser removido imediatamente e o que continua retido por obrigação operacional ou legal.

O que esta fase ainda não faz

Ainda não cobre:

  • recuperação de acesso independente do login por código;
  • favoritos, lista de desejos ou preferências persistidas por servidor.

Por que essa etapa é pertinente

Mesmo antes do backend dedicado completo, essa frente já resolve três problemas importantes:

  1. define a UX da área do cliente;
  2. separa o domínio do cliente do domínio administrativo;
  3. conecta checkout, conta e recompra sem refazer o storefront depois.

Ou seja: não é mais só protótipo local. Já é uma base real de conta do cliente.

Próxima evolução prevista

Fase 1

  • abrir recuperação de acesso;
  • adicionar favoritos e preferências;
  • permitir histórico consolidado em qualquer dispositivo.

Fase 2

  • expor o mesmo contrato para o futuro app mobile;
  • reutilizar conta, pedidos, endereços e preferências na experiência mobile.

Fase 3

  • abrir retenção parametrizável por categoria de dado;
  • evoluir aprovação interna e governança do tratamento LGPD.

Resumo técnico

Estado atual:

  • sessão real de cliente por cookie dedicado;
  • conta, endereço e pedido persistidos no banco;
  • login por código de e-mail;
  • integração direta com o checkout.

Direção planejada:

  • mesma UI;
  • mesma ideia de contrato;
  • expansão do domínio para favoritos, LGPD e app mobile.

Leitura seguinte