# Carrinhos

Os carrinhos armazenam os produtos que um cliente pretende comprar. A plataforma suporta tanto carrinhos autenticados (vinculados a uma conta de usuário) quanto carrinhos de visitante (para visitantes que não fizeram login). No painel administrativo você pode navegar por todos os carrinhos ativos, inspecionar seus conteúdos e até modificar itens em nome de um cliente.

## Navegando pelos carrinhos

Abra **Carts** na barra lateral do painel administrativo para ver todos os carrinhos ativos. A tabela exibe o usuário associado (ou "Guest" para carrinhos anônimos), a quantidade de itens e a data de criação.

![Carts list](/features/carts/carts-list.png)

| Coluna     | Descrição                                                    |
| ---------- | ------------------------------------------------------------ |
| User       | Nome e e-mail do cliente, ou _Guest_ para carrinhos anônimos |
| Items      | Número de produtos distintos no carrinho                     |
| Created At | Data em que o carrinho foi criado pela primeira vez          |

Você pode **ordenar** clicando nos cabeçalhos das colunas e **pesquisar** por nome ou e-mail do cliente usando a barra de pesquisa. Use o filtro **User** para exibir todos os carrinhos, apenas carrinhos de usuários registrados ou apenas carrinhos de visitantes.

> **Tip:** Carrinhos de visitantes não podem ser pesquisados por nome ou e-mail, pois não possuem usuário associado. Use o filtro "Guest Only" para visualizá-los.

## Visualizando um carrinho

Clique em qualquer linha na lista de carrinhos para abrir a página de detalhes do carrinho. A página exibe as informações do carrinho e um gerenciador completo de itens.

![Cart detail](/features/carts/cart-detail.png)

### Informações do carrinho

| Campo      | Descrição                                                    |
| ---------- | ------------------------------------------------------------ |
| User       | Nome e e-mail do cliente, ou "Guest" para carrinhos anônimos |
| Created At | Quando o carrinho foi criado pela primeira vez               |
| Updated At | Quando o carrinho foi modificado pela última vez             |

### Itens do carrinho

A seção de itens exibe uma tabela com a miniatura de cada produto, título (link para o editor do produto), preço unitário, quantidade e subtotal. O total é exibido na parte inferior.

## Gerenciando itens do carrinho

Como administrador, você pode modificar o carrinho de um cliente diretamente na página de detalhes:

- **Adicionar um produto** — clique no botão de adicionar e pesquise um produto para incluir no carrinho
- **Atualizar quantidade** — use os controles de quantidade (+ / −) ou digite um número diretamente
- **Remover um item** — clique no botão de excluir em qualquer linha de item

Clique em **Save** para salvar suas alterações. A quantidade deve ser pelo menos 1 para cada item.

## Como os clientes usam o carrinho

### Adicionando produtos

Os clientes adicionam produtos ao carrinho nas páginas de produtos usando o botão **Add to Basket**. Cada clique adiciona uma unidade. Se o produto estiver sem estoque, o botão muda para **Out of Stock** e fica desabilitado.

Quando um item é adicionado, um breve indicador de sucesso é exibido. Se o cliente tentar adicionar mais do que o estoque disponível, uma mensagem de erro é exibida.

### A página do carrinho

Os clientes acessam seu carrinho clicando no ícone do carrinho na barra de navegação ou navegando para `/cart`.

![Storefront cart page](/features/carts/storefront-cart.png)

A página do carrinho exibe todos os itens com as seguintes informações:

| Elemento          | Descrição                                                       |
| ----------------- | --------------------------------------------------------------- |
| Product image     | Miniatura do produto                                            |
| Product title     | Link clicável para a página do produto                          |
| Stock badge       | Verde "In Stock", âmbar "Only X left" ou vermelho "Unavailable" |
| Unit price        | Preço por item                                                  |
| Line total        | Preço unitário multiplicado pela quantidade                     |
| Quantity controls | Botões Menos / Mais para ajustar a quantidade                   |
| Remove button     | Remove o item do carrinho                                       |

**Badges de estoque:**

- **In Stock** (verde) — o item está disponível e a quantidade está dentro dos limites do estoque
- **Only X left** (âmbar) — o cliente tem mais unidades no carrinho do que as atualmente em estoque
- **Unavailable** (vermelho) — o produto foi desativado ou está completamente sem estoque

> **Important:** O botão de adicionar fica desabilitado quando a quantidade atinge o estoque disponível, impedindo os clientes de adicionar mais do que o disponível.

### Barra lateral de resumo do pedido

O lado direito da página do carrinho exibe um resumo com:

- Quantidade de itens
- Subtotal
- Aviso de envio ("Calculated at checkout")
- Total
- Botão **Proceed to Checkout**
- Uma nota sobre impostos e frete calculados no checkout
- Um selo de confiança de checkout seguro

### Carrinho vazio

Quando o carrinho está vazio, uma mensagem amigável é exibida com um botão **Continue Shopping** que leva de volta à página inicial.

## Carrinhos de visitantes

Visitantes que não estão logados ainda podem adicionar produtos a um carrinho. O sistema cria um carrinho de visitante e armazena seu ID no armazenamento local do navegador.

Quando um visitante faz login ou cria uma conta posteriormente, o carrinho de visitante é **automaticamente mesclado** ao carrinho autenticado:

- Produtos que existem em ambos os carrinhos têm suas quantidades combinadas (até o limite de estoque)
- Produtos presentes apenas no carrinho de visitante são adicionados ao carrinho autenticado
- O carrinho de visitante é então excluído

Se a mesclagem precisar reduzir uma quantidade combinada para caber no estoque disponível, o cliente vê um aviso explicando qual linha foi ajustada, sem mudanças silenciosas. Os clientes nunca perdem os itens adicionados antes de fazer login.

## Validação de estoque

O estoque é validado em vários pontos para evitar vendas além do disponível:

| Ponto                   | Validação                                                                      |
| ----------------------- | ------------------------------------------------------------------------------ |
| Adicionando ao carrinho | O produto deve estar ativo e ter estoque > 0                                   |
| Atualizando quantidade  | A nova quantidade não pode exceder o estoque disponível                        |
| Entrando no checkout    | O estoque é **reservado** (decrementado do inventário do produto)              |
| Expiração do checkout   | Se a sessão de checkout expirar (15 minutos), o estoque reservado é restaurado. O cliente vê um toast de aviso dois minutos antes da expiração, dando uma chance de finalizar ou estender a sessão. |
| Conclusão do pedido     | O estoque permanece decrementado; o snapshot de checkout é excluído            |

## Ciclo de vida do carrinho

Cada carrinho passa por um ciclo de vida simples de dois status:

| Status    | Significado                                                                    |
| --------- | ------------------------------------------------------------------------------ |
| Active    | O carrinho está em uso — itens podem ser adicionados, atualizados ou removidos |
| Completed | O cliente concluiu o checkout e um pedido foi criado                           |

Quando um cliente clica em **Proceed to Checkout**, um snapshot de checkout é criado a partir do carrinho. O carrinho permanece ativo durante o checkout. Assim que o pedido é realizado com sucesso, o carrinho é marcado como concluído e um novo carrinho ativo pode ser iniciado.

> **Tip:** A lista de carrinhos do painel administrativo exibe apenas carrinhos ativos. Carrinhos concluídos não são mais exibidos, pois foram convertidos em pedidos.