Task #193223 — Criar tela de recomendação upsell

Task pai: Feature: Upsell

Status do refinamento: concluído
Requisitos EARS: task-193223-criar-tela-recomendacao-upsell-requisitos.md
Pesquisas técnicas: pesquisa-cards-e-modal-upsell · pesquisa-cart-dto-fluxo-add-produto
ADRs:

---

Resumo

Tela exibida como step "Recomendar" no fluxo de venda do zzapp, entre Cliente e Conferir, quando o UpsellRecommendationController indicar upsell ativo (feature flag + loja habilitada + carrinho estoque loja).

A tela permite que a vendedora visualize até 3 itens recomendados por uma API externa, selecione tamanhos com indicadores de estoque e decida quais adicionar como sugestão ao carrinho.

Fluxo da tela

1. Entrada → se primeira visita na venda, chama API externa de recomendação (CPF, StoreId, itens do cart)
2. Loading → skeleton de carregamento
3. Dados recebidos → lista de cards com UpsellRecommendationCard ou estado vazio/erro
4. Seleção → vendedora toca no trailing (plus_circle) → modal de tamanho (padrão AddProductBottomSheet) → seleciona → card mostra chip único
5. ADICIONAR RECOMENDAÇÃO → itens selecionados viram CartItemDTO → salvos em cartDTO.recommendedItems (lista separada, não compõe total) → navega para Conferir
6. NÃO QUERO RECOMENDAR → limpa seleções → navega para Conferir

Estados da tela

Estado	Visual	Bottom bar
Loading	Skeleton	Visível, botões sem ação
Cards	ListView com UpsellRecommendationCard	Ambos habilitados
Vazio	"Nenhuma recomendação encontrada" (centralizado)	Ambos habilitados
Erro	"Ocorreu um problema" + descrição + botão TENTE NOVAMENTE	ADICIONAR desabilitado, NÃO QUERO habilitado

Componentes principais

Componente	Responsabilidade
UpsellRecommendationCard	Card stand-alone (imagem 60x60 + detalhes) com chips NumerationListText. Apenas o trailing (plus/check) é interativo — corpo do card sem ação de toque.
UpsellRecommendationController	LazySingleton no GetIt. Cache por venda. fetchRecommendations(), retry(), addRecommendedProducts(). Reseta quando activeCartDTO → null.
UpsellRecommendationItem	Model de tela: id, sku, name, image, price, fullPrice, sizesStockStore, selectedSize, isSelected. Método buildSizeChips().
Modal	AddProductBottomSheet adaptado: botão "ADICIONAR PRODUTO", apenas sizes com estoque > 0
CartDTO.recommendedItems	Campo List<CartItemDTO>? — não compõe itemsTotal/total. Método addRecommendedItems().
CartController.addRecommendedProducts()	Filtra isSelected, converte para CartItemDTO, salva via changeWith()

Botões

Botão	Comportamento
ADICIONAR RECOMENDAÇÃO	Filtra itens com selectedSize != null → salva em cartDTO.recommendedItems → navega para Conferir. Se nenhum selecionado: modal de alerta. Desabilitado durante erro de API.
NÃO QUERO RECOMENDAR	Limpa selectedSize de todos os itens → navega para Conferir. Sempre habilitado após skeleton.

Cache e preservação de estado

• O controller (lazySingleton) mantém recommendedItems em cache enquanto activeCartDTO != null
• Ao retornar para a tela na mesma venda: restaura cache sem re-fetch da API
• Ao finalizar a venda (activeCartDTO → null): reset automático (ADR-010, RF-04 da task-08)
• Ao iniciar nova venda: controller limpo, fetch disparado normalmente

Dependências

Dependência	Descrição	Status
Task 08 — Stepper condicional	Controller base (lazySingleton, isActive, auto-reset) + get_it	Pendente
Task 07 — Feature flags	enableUpsellRecommendation + byCodeStore	Pendente
API de recomendação externa	GET — CPF, StoreId, itens cart → máx 3 produtos	Pendente
POST cart com recommendedItems	Body opcional recommendedItems no POST cart	Pendente
Tela Conferir — seção recomendações	Exibição de cartDTO.recommendedItems em cards	Pendente
Navegação step Recomendar	Botão AVANÇAR: Cliente → Recomendar → Conferir	Pendente

Referencia do figma

---

Arquivos desta pasta

Arquivo	Descrição
task-193223-criar-tela-recomendacao-upsell.md	Este arquivo — sumário e índice da task
task-193223-criar-tela-recomendacao-upsell-requisitos.md	Documento de requisitos em formato EARS (pt-BR): histórias de usuário, critérios de aceitação e casos de borda