Skip to main content

Documento de Requisitos — Itens recomendados na tela conferir pedido

Tarefa: #193223
Contexto: #193223 — Criar tela de recomendação upsell

Visão Geral​

No fluxo de venda do zzapp, após a vendedora selecionar itens recomendados na tela de upsell (task-09), o CartDTO é populado com recommendedItems (List<CartItemDTO>?). Ao chegar na tela de conferir pedido (check_sell), esses itens devem ser exibidos em uma nova seção "Recomendados", posicionada entre o botão "ADICIONAR PRODUTOS" e a seção "Endereço de entrega".

A seção inclui um warning informando que os itens ficam disponíveis por 1 hora e uma lista de cards seguindo o mesmo padrão visual dos produtos do carrinho. A vendedora pode aplicar desconto nos itens recomendados (mesmo fluxo de CheckSellProductDiscount) ou removê-los da lista (com modal de confirmação).

Ao gerar o link de pagamento, os recommendedItems selecionados são enviados no payload do POST api/cart como propriedade opcional, para que o backend os persista como CartRecommendedItem vinculados ao Cart recém-criado.

Papéis Envolvidos​

  • Vendedora (zzapp): Visualiza os itens recomendados na tela de conferir pedido, aplica desconto e remove itens indesejados antes de gerar o link de pagamento
  • Cliente (zzlink): Recebe as recomendações no link de pagamento após o cart ser criado

Requisitos Funcionais​

RF-01 — Exibição condicional da seção de recomendados​

História de Usuário:
Como vendedora, quero visualizar os itens recomendados na tela de conferir pedido apenas quando houver recomendações disponíveis, para evitar poluir a interface com seções vazias.

Critérios de Aceitação:

  1. A seção "Recomendados" DEVE ser exibida SOMENTE quando cartDTO.recommendedItems não for nulo e contiver ao menos 1 item

  2. Se cartDTO.recommendedItems for nulo ou vazio, a seção inteira DEVE ser ocultada

Casos de Borda:

  • Se recommendedItems contiver itens mas todos forem removidos pela vendedora, a seção deve desaparecer
  • Se o stepper de upsell (task-09) não tiver populado recommendedItems, a seção não deve ser renderizada

RF-02 — Título da seção e warning de disponibilidade​

História de Usuário:
Como vendedora, quero identificar claramente a seção de itens recomendados e saber por quanto tempo eles ficarão disponíveis para a cliente.

Critérios de Aceitação:

  1. O título da seção DEVE ser "Recomendados"

  2. Abaixo do título, DEVE ser exibido um warning com o texto: "Os produtos recomendados ficarão disponíveis para a cliente por até 1 hora."

  3. O texto do warning É estático — não requer lógica de countdown

Casos de Borda:

  • O warning deve ser exibido mesmo que haja apenas 1 item recomendado
  • O warning não deve ser exibido se a seção inteira estiver oculta (RF-01)

RF-03 — Card de item recomendado​

História de Usuário:
Como vendedora, quero visualizar cada item recomendado no mesmo formato dos produtos do carrinho, para ter consistência visual e funcional na tela de conferir pedido.

Critérios de Aceitação:

  1. Cada item recomendado DEVE ser exibido usando o mesmo padrão visual do card de produto do carrinho (_ProductCard em check_sell_products.dart)

  2. O card DEVE exibir: imagem do produto, nome, SKU, tamanho selecionado, preço cheio, desconto aplicado e preço final

  3. O item recomendado NÃO DEVE exibir quantidade (fixo em 1)

Casos de Borda:

  • Se recommendedItems contiver entre 1 e 3 itens, todos devem ser exibidos
  • O limite de 1-3 itens é garantido pelo stepper de upsell (task-09) — não é necessário validar no check_sell

RF-04 — Remoção de item recomendado​

História de Usuário:
Como vendedora, quero remover um item recomendado da lista antes de gerar o link de pagamento.

Critérios de Aceitação:

  1. Cada card de item recomendado DEVE exibir um botão de excluir (ícone X)

  2. Ao clicar no botão de excluir, DEVE ser exibida uma modal de confirmação (ConfirmBottomSheet)

  3. Ao confirmar, o item DEVE ser removido da lista cartDTO.recommendedItems via changeWith() síncrono (sem chamada API)

  4. Após a remoção, DEVE ser exibido um snackbar verde com o texto "Recomendação removida"

  5. A remoção É apenas local (CartDTO) — não há endpoint backend envolvido nesta etapa do fluxo

Casos de Borda:

  • Se o último item recomendado for removido, a seção inteira deve desaparecer (RF-01)
  • O botão de excluir deve estar visível mesmo quando há apenas 1 item recomendado (diferente do cart, que exige mais de 1 item)

RF-05 — Aplicação de desconto no item recomendado​

História de Usuário:
Como vendedora, quero aplicar desconto nos itens recomendados seguindo as mesmas regras dos produtos do carrinho.

Critérios de Aceitação:

  1. Cada card de item recomendado DEVE exibir o botão "EDITAR" para aplicar desconto

  2. Ao clicar, DEVE abrir o mesmo bottom sheet CheckSellProductDiscount usado para produtos do carrinho

  3. As validações de limite máximo de desconto e desconto de funcionário DEVEM ser aplicadas (mesma lógica do cart)

  4. O desconto aplicado NÃO DEVE impactar o total do carrinho (itemsTotal/total)

Casos de Borda:

  • Itens recomendados são criados com discountType=none e discountValue=0 (task-09) — o desconto é opcional
  • A confirmação sobre se o limite máximo de desconto do pedido deve considerar recommendedItems será feita com PO após o refinamento

RF-06 — Posicionamento da seção na tela​

História de Usuário:
Como vendedora, quero que a seção de recomendados apareça em uma posição lógica na tela de conferir pedido.

Critérios de Aceitação:

  1. A seção de recomendados DEVE ser posicionada entre o widget CheckSellProducts (que contém o botão "ADICIONAR PRODUTOS") e o widget CheckSellAddress ("Endereço de entrega")

  2. A seção DEVE ser um widget CheckSellRecommended que recebe cartController, checkSellController e employeeSalesController

Casos de Borda:

  • Se a tela estiver em modo ecommerce (sem endereço de entrega), a seção deve ser posicionada após CheckSellProducts
  • O widget deve respeitar o padding/margem consistente com os demais widgets da tela

RF-07 — Envio dos itens recomendados no POST api/cart​

História de Usuário:
Como vendedora, quero que os itens recomendados selecionados sejam enviados ao backend ao gerar o link de pagamento.

Critérios de Aceitação:

  1. O toJson() do CartDTO DEVE incluir o campo recommendedItems na serialização

  2. O payload do POST api/cart (enviado por ConfirmPaymentLinkController.onTapGerar) DEVE conter os recommendedItems

  3. Esta serialização É garantida pela task-09 (CartDTO.recommendedItems + toJson/fromJson)

Casos de Borda:

  • Se recommendedItems for nulo, o campo não deve ser enviado ou deve ser enviado como null (comportamento padrão do JSON)
  • Se recommendedItems for uma lista vazia, deve ser enviado como array vazio []

RF-08 — Isolamento dos recommendedItems do total do carrinho​

História de Usuário:
Como vendedora, quero que os itens recomendados não interfiram nos valores e cálculos do carrinho.

Critérios de Aceitação:

  1. Os recommendedItems NÃO DEVEM compor itemsTotal do carrinho

  2. Os recommendedItems NÃO DEVEM compor total do carrinho

  3. Os recommendedItems NÃO DEVEM afetar cálculos de desconto, frete ou CRM Bonus

  4. Este comportamento já é garantido pela task-09 (addRecommendedItems usa changeWith() síncrono sem computeValuesAndTotals())

Casos de Borda:

  • Alterações de desconto em recommendedItems não devem disparar recálculo de total
  • Remoção de recommendedItems não deve disparar recálculo de total

Dependências​

DependênciaDescriçãoStatus
task-09-193223CartDTO.recommendedItems, addRecommendedItems(), MutableCartDTO, serialização toJson/fromJsonPendente
ADR-009Size armazenado em CartRecommendedItems — define contrato do RecommendedItemsInfoDTOAceito
ADR-002Query separada para GetRecommendedItemsAsync no fluxo storeAceito

Questões em Aberto​

  • Confirmação PO — Limite máximo de desconto: Confirmar com PO se as regras de limite máximo de desconto no pedido devem considerar os itens recomendados (além dos itens do carrinho).
  • Confirmação UX/PO — Modal de confirmação ao excluir: Validar com UX e PO se a exclusão de item recomendado deve exibir modal de confirmação (ConfirmBottomSheet) ou se deve ser direta (apenas snackbar).
  • Confirmação PO — Regras de desconto funcionário: Validar com PO se as regras de desconto de funcionário se aplicam integralmente aos itens recomendados.