Ecommerce - Pedidos Operacionais

Objetivo deste guia

Explicar a nova camada de pedidos do projeto sem confundir:

• rascunho de checkout;
• pedido consolidado;
• histórico da conta do cliente;
• rastreio público;
• operação interna no painel.

O que mudou

Antes, o checkout gerava um orderId e alimentava uma projeção simples em customer_orders.

Agora existem dois níveis:

1. commerce_order_drafts
2. commerce_orders + commerce_order_events

E a tabela customer_orders continua existindo, mas como visão da conta do cliente, não como fonte principal de operação.

Além disso, quando a malha logística seleciona múltiplas origens para uma mesma compra, o sistema também suporta:

• grupo de compra, que representa o fechamento comercial;
• subpedidos, um por origem operacional.

Tabelas novas

`commerce_order_drafts`

Guarda a intenção de compra enquanto o checkout está sendo preenchido.

Uso prático:

• retomar jornada;
• futuramente tratar carrinho abandonado;
• manter um hash/token público do rascunho sem consolidar o pedido cedo demais.

Política atual:

• o draft só começa a ser persistido depois de 20 minutos de sessão do checkout;
• drafts ativos sem atualização por 20 minutos passam para abandoned;
• drafts abandonados são removidos 5 dias depois para não poluir armazenamento.

Campos centrais:

• id
• public_token
• order_form_id
• status
• customer_email
• items_json
• client_profile_json
• shipping_json
• payment_json
• totals_json
• custom_data_json
• expires_at

`commerce_orders`

É a entidade principal do pedido.

Ela guarda o snapshot operacional do que foi comprado.

Campos centrais:

• id
• public_token
• draft_id
• customer_account_id
• customer_email
• status
• financial_status
• fulfillment_status
• items_json
• totals_json
• customer_snapshot_json
• shipping_snapshot_json
• payment_snapshot_json
• logistics_json

`commerce_order_events`

É a trilha do pedido.

Ela serve para:

• mudança de status;
• observação interna;
• atualização visível ao cliente;
• rastreio público e pós-venda.

Fluxo atual

1. Carrinho e order form

O OrderFormContext continua projetando o carrinho para checkout.

Diferença:

• ele agora sincroniza um rascunho em /api/ecommerce/order-draft.

2. Rascunho persistido

Enquanto o cliente informa:

• itens;
• e-mail;
• endereço;
• pagamento;

o backend atualiza commerce_order_drafts.

3. Checkout concluído

Quando POST /api/checkout é executado:

1. o pedido recebe orderId;
2. a conta do cliente é localizada ou criada;
3. a logística verifica se a compra sai inteira de uma origem ou se precisa quebrar em subpedidos;
4. a projeção da conta é atualizada em customer_orders;
5. o pedido operacional é gravado em commerce_orders;
6. o rascunho é marcado como converted;
7. a timeline recebe o evento inicial do pedido ou do subpedido.

Como o split operacional funciona

Se a opção logística escolhida vier com mais de uma origem:

• o pedido base vira grupo de compra;
• cada origem gera um pedido filho com sufixo -01, -02, -03;
• cada subpedido mantém:

- itens daquele atendimento; - fração do frete e do total; - token público próprio; - timeline própria; - operação própria no painel.

Exemplo:

• grupo: ORD-AB12CD
• subpedidos:

- ORD-AB12CD-01 - ORD-AB12CD-02

Na prática:

• o pagamento continua sendo entendido como a compra daquele grupo;
• a operação logística passa a atuar em cada subpedido separadamente.

Por que isso é melhor

Esse desenho resolve problemas que a projeção simples não resolvia bem:

• separar pedido sensível do histórico resumido do cliente;
• permitir alteração posterior de item, logística e status;
• abrir rastreio sem expor dados pessoais;
• suportar multi-origem sem misturar doca, estoque e SLA em um único registro operacional;
• preparar suporte interno e app mobile com a mesma base.

Relação com Minha conta

Minha conta ainda lê customer_orders.

Isso é intencional.

Leitura prática:

• commerce_orders = operação real;
• customer_orders = visão da área do cliente.

Posteriormente, a conta pode migrar para ler uma projeção derivada do pedido operacional sem mudar a UX.

Tela de pedido confirmado

A rota /e-commerce/checkout/confirmation agora usa o publicToken do pedido principal para renderizar uma confirmação mais completa, no estilo do e-mail transacional.

Essa tela mostra:

• número da compra principal;
• pacotes gerados por split logístico;
• itens de cada pacote;
• total e frete por pacote;
• origem operacional;
• previsão atual de entrega ou retirada;
• primeiros eventos da timeline.

Em compras multi-origem, o cliente consegue entender logo após o checkout que a compra foi separada em mais de um pacote, sem depender apenas da área Minha conta.

Endpoints novos

Storefront

• POST /api/ecommerce/order-draft
• POST /api/checkout

Painel

• GET /api/ecommpanel/orders
• GET /api/ecommpanel/orders/[orderId]
• PATCH /api/ecommpanel/orders/[orderId]

No painel, essa camada aparece como fila operacional para:

• revisão comercial;
• mudança de status;
• ajuste de contato;
• ajuste de endereço;
• observação logística e pós-venda.

Pública

• GET /api/v1/orders/[publicToken]

Esse endpoint público devolve apenas leitura segura de rastreio:

• status;
• status financeiro;
• status logístico;
• datas;
• totais resumidos;
• itens do pacote;
• resumo de entrega e origem;
• timeline pública.

O que ainda falta

Esta etapa já é útil, mas ainda não fecha tudo.

Próximos passos naturais:

• rotina de abandono e recuperação de carrinho;
• UI de pedidos no painel;
• substituição de item com motivo operacional;
• tracking code real da transportadora;
• timeline de estorno, entrega e tentativa de entrega.

Leitura seguinte

• 13 - Ecommerce - Carrinho e Checkout
• 23 - Ecommerce - Minha Conta
• 14 - Mapa de APIs
• 04 - E-commerce - Operacao