Skip to main content

Requisitos — [Front] Dinâmica de itens recomendados

Task #196865​

Task pai: US 196869 ADRs relacionados: — Contrato de referência: cart-detail.json

Status: refinado Sessão de grilling: 25/06/2026

Visão geral​

Integrar o bloco "Recomendados" na tela CartStatusDetailScreen do zzapp, exibindo os itens de cartItemRecommendations retornados pela API de detalhe do pedido.

A task cobre:

  • Deserialização de cartItemRecommendations no model CartDetail
  • Nova seção visual no final da tela (após "Resumo do pedido")
  • Listagem somente leitura dos itens recomendados pendentes
  • Reflexão do estado pós-conversão via zzlink (item sai de cartItemRecommendations e aparece em productCartDetails com fromRecommendation: true)

A conversão em si é server-side (zzlink + API Cart). O front não implementa a ação de adicionar recomendado — apenas renderiza o estado retornado pela API.

Tela: CartStatusDetailScreen → nova seção _ContentRecommendations ("Recomendados")

Papéis​

PapelResponsabilidade
VendedoraAcompanhar na Status do Pedido quais recomendações ainda estão pendentes e quais foram convertidas pela cliente
ClienteAdicionar itens recomendados ao pedido via zzlink (fora do escopo desta task)
Desenvolvedor Front-endIntegrar seção "Recomendados", estender CartDetail e consumir factory recommended da task 196866

Requisitos​

RF-01 — Visibilidade do bloco "Recomendados"​

User Story: Como vendedora, eu quero ver o bloco "Recomendados" apenas quando aplicável, para não poluir pedidos sem upsell.

Acceptance Criteria:

  1. WHEN o pedido for de estoque da loja (saleEcommerce: false) e cartItemRecommendations possuir ao menos um item THEN o sistema SHALL exibir a seção "Recomendados" na CartStatusDetailScreen.
  2. WHEN cartItemRecommendations for null ou lista vazia THEN o sistema SHALL ocultar a seção inteira (título, subtítulo e lista).
  3. WHEN o pedido for de Prateleira Infinita (saleEcommerce: true) THEN o sistema SHALL NOT exibir a seção "Recomendados", independentemente do conteúdo de cartItemRecommendations.

Casos de Borda:

  • WHEN a API retornar cartItemRecommendations para pedido de PI THEN o sistema SHALL ignorar os dados na renderização da seção.

RF-02 — Posicionamento e estrutura visual da seção​

User Story: Como vendedora, eu quero localizar as recomendações no final da tela de Status, conforme o layout definido no Figma.

Acceptance Criteria:

  1. WHEN a seção "Recomendados" for exibida THEN o sistema SHALL posicioná-la após a seção "Resumo do pedido" e antes do padding final da ListView da tela.
  2. WHEN a seção for renderizada THEN o sistema SHALL exibir o título "Recomendados" com estilo equivalente ao título da seção "Itens" (ZZTextNew, ZZFontSize.xs, ZZFontWeight.semibold).
  3. WHEN a seção for renderizada THEN o sistema SHALL exibir o subtítulo "Produtos que você recomendou para a cliente." abaixo do título.
  4. WHEN a seção for renderizada THEN o sistema SHALL utilizar o padrão visual da seção "Itens" (Column com título + lista), sem envolver o bloco em CartStatusDetailCard.
  5. WHEN a seção for renderizada THEN o sistema SHALL NOT exibir o banner de aviso de 1 hora presente em CheckSellRecommended.

Referência visual:

Posicionamento da lista

Nova seção

RF-03 — Deserialização de cartItemRecommendations em CartDetail​

User Story: Como desenvolvedor front-end, eu quero consumir cartItemRecommendations da API de detalhe do pedido, para alimentar a seção "Recomendados".

Acceptance Criteria:

  1. WHEN a resposta da API de detalhe do pedido for parseada THEN o model CartDetail SHALL mapear cartItemRecommendations para List<CartItemRecommendation>.
  2. WHEN a chave cartItemRecommendations estiver ausente ou for null THEN o sistema SHALL tratar como lista vazia para fins de visibilidade (RF-01.2).
  3. WHEN cada item de cartItemRecommendations for deserializado THEN o sistema SHALL utilizar o model CartItemRecommendation conforme contrato em cart-detail.json.

RF-04 — Listagem de produtos recomendados​

User Story: Como vendedora, eu quero visualizar apenas os produtos que recomendei e que ainda não foram adicionados ao pedido, para acompanhar o upsell pendente.

Acceptance Criteria:

  1. WHEN a seção "Recomendados" for exibida THEN o sistema SHALL listar exclusivamente os itens de cartItemRecommendations na ordem retornada pela API.
  2. WHEN cada item recomendado for renderizado THEN o sistema SHALL utilizar CartStatusProductCardNew.recommended (factory da task 196866).
  3. WHEN um produto recomendado for exibido THEN ele SHALL NOT compor productCartDetails, valores, quantidades ou totalizadores do bloco "Resumo do pedido".
  4. WHEN um produto recomendado for exibido THEN o sistema SHALL apresentá-lo com finalidade exclusivamente informativa (somente leitura).
  5. WHEN um card recomendado for exibido na Status THEN o sistema SHALL NOT oferecer ações de editar desconto, remover item ou onTap (diferente de CheckSellRecommended).

RF-05 — Conversão de recomendado em item do pedido (reflexão de estado)​

User Story: Como vendedora, eu quero ver na Status do Pedido quando a cliente converteu uma recomendação via zzlink, para acompanhar o resultado do upsell.

Acceptance Criteria:

  1. WHEN a cliente adicionar um produto recomendado ao pedido via zzlink e a vendedora reentrar na CartStatusDetailScreen THEN o sistema SHALL remover o produto de cartItemRecommendations na listagem "Recomendados".
  2. WHEN a conversão ocorrer THEN o sistema SHALL exibir o produto na seção "Itens" (productCartDetails).
  3. WHEN o item convertido for exibido na seção "Itens" THEN o sistema SHALL renderizar a tag "Item recomendado adicionado ao pedido" quando fromRecommendation for true (controle delegado ao componente da task 196866, RF-09).
  4. WHEN todos os itens recomendados forem convertidos THEN o sistema SHALL ocultar a seção "Recomendados" conforme RF-01.2.

Casos de Borda:

  • WHEN a vendedora permanecer na tela sem sair após conversão via zzlink THEN o sistema SHALL NOT atualizar automaticamente os blocos (sem polling nesta task).

RF-06 — Consistência entre blocos "Itens" e "Recomendados"​

User Story: Como vendedora, eu quero que os blocos reflitam o estado atual do pedido sem duplicidade de produtos.

Acceptance Criteria:

  1. WHEN a vendedora reentrar na CartStatusDetailScreen THEN o sistema SHALL reexecutar CartController.find e refletir o estado atualizado nos blocos "Itens" e "Recomendados".
  2. WHEN um produto constar em productCartDetails THEN o sistema SHALL NOT exibi-lo simultaneamente em cartItemRecommendations.
  3. WHEN o estado do pedido for alterado no backend THEN o sistema SHALL confiar na resposta da API como fonte de verdade para a composição dos dois blocos.

RF-07 — Preservação de comportamentos AS-IS​

User Story: Como vendedora, eu quero que a inclusão do bloco "Recomendados" não altere o funcionamento existente da tela de Status.

Acceptance Criteria:

  1. WHEN a seção "Recomendados" for integrada THEN o sistema SHALL manter inalterados os blocos existentes (Loja, Cliente, Entrega, Pedido, Pagamento, Itens, Resumo do pedido).
  2. WHEN o pedido for de Prateleira Infinita THEN o sistema SHALL manter o comportamento AS-IS de ocultar "Resumo do pedido" (saleEcommerce: true) sem impacto na regra de RF-01.3.
  3. WHEN a listagem de pedidos for atualizada ao retornar do detalhe THEN o sistema SHALL manter o refresh existente em cartStoreController.findSearchCartStore.

Fora de Escopo​

  • Criação do novo layout de card e factory recommended (task 196866)
  • Tag visual "Item recomendado adicionado ao pedido" — componente e prop fromRecommendation (task 196866, RF-09)
  • Lógica de recomendação de produtos e conversão via zzlink (backend / zzlink)
  • Fluxo de criação de carrinho e tela CheckSellRecommended
  • Banner de aviso de 1 hora na Status do Pedido
  • Pull-to-refresh ou polling na CartStatusDetailScreen
  • Ações de editar desconto ou remover recomendação na Status
  • Alterações no contrato da API Cart Detail

Dependências​

DependênciaDescriçãoStatus
Task 196866CartStatusProductCardNew.recommended, model CartItemRecommendation, campos fromRecommendation em ProductCartDetailPendente
API Cart DetailEndpoint retorna cartItemRecommendations e fromRecommendation conforme cart-detail.jsonDisponível
Figma ZZAPP 2.0Posicionamento, subtítulo e cards da seção "Recomendados"Disponível
US 196869Critérios de aceite CA-1 a CA-4Disponível

Decisões de refinamento​

#Decisão
1Bloco visível somente para pedidos com estoque da loja (saleEcommerce: false)
2Posição: após "Resumo do pedido", no final da tela
3Subtítulo: "Produtos que você recomendou para a cliente."
4Atualização de estado: re-fetch ao reentrar na tela (sem pull-to-refresh nesta task)
5Sem banner de aviso de 1 hora (diferente de CheckSellRecommended)
6Cards somente leitura (sem editar, remover ou onTap)
7Seção inteira oculta quando cartItemRecommendations for null ou vazio
8Estrutura visual no padrão da seção "Itens" (título + subtítulo + lista, sem CartStatusDetailCard)