Skip to main content

Documento de Requisitos — Ajuste no Endpoint GET api/payment/v2/{id} (GetInfo)

Tarefa: #194879
Contexto: Spike #193127 — Upsell no fluxo de vendas

Visão Geral​

O endpoint GET api/payment/v2/{id} precisa passar a retornar, na resposta do zzlink (fluxo store), os itens recomendados vinculados ao carrinho de compras — desde que dentro da janela de validade de 1 hora a partir da criação do carrinho.

Essa funcionalidade suporta o fluxo de upsell no ponto de venda, permitindo que a cliente visualize itens adicionais recomendados pelo vendedor no momento do pagamento.

Papéis Envolvidos​

  • Vendedor (zzapp): seleciona itens recomendados no momento da criação do carrinho.
  • Cliente (zzlink): visualiza os itens recomendados durante o fluxo de pagamento.
  • Sistema (Checkout API): processa e retorna os itens recomendados com base nas regras de validade e deduplicação.

Requisitos Funcionais​

RF-01 — Retorno de Itens Recomendados no Fluxo Store​

História de Usuário:
Como cliente acessando o zzlink, quero visualizar os itens recomendados pelo vendedor, para que eu possa adicionar produtos ao meu pedido durante o pagamento.

Critérios de Aceitação:

  1. QUANDO o endpoint GET api/payment/v2/{id} for chamado no fluxo store (zzlink) E o carrinho possuir itens recomendados ENTÃO o sistema DEVE retornar a lista de itens recomendados no campo RecommendedItems da resposta.

  2. QUANDO o endpoint for chamado E não houver itens recomendados vinculados ao carrinho ENTÃO o sistema DEVE retornar uma lista vazia ([]) no campo RecommendedItems.

  3. QUANDO o endpoint for chamado no fluxo ecomm (GetInfoEcommAsync) ENTÃO o sistema NÃO DEVE retornar itens recomendados (fluxo não alterado).

Casos de Borda:

  • O campo RecommendedItems nunca deve ser null — sempre retornar lista vazia quando não houver itens.

RF-02 — Janela de Validade de 1 Hora​

História de Usuário:
Como sistema de checkout, quero limitar o tempo de exibição dos itens recomendados, para que recomendações desatualizadas não sejam apresentadas à cliente.

Critérios de Aceitação:

  1. QUANDO DateTime.Now for menor ou igual a cart.DateCreated + 1 hora ENTÃO o sistema DEVE retornar os itens recomendados (respeitando demais regras).

  2. QUANDO DateTime.Now for maior que cart.DateCreated + 1 hora ENTÃO o sistema NÃO DEVE retornar os itens recomendados, devolvendo lista vazia ([]).

  3. O cálculo da janela de validade DEVE ser realizado no handler (GetInfoQueryHandler), não no repositório.

  4. O campo DateCreated do carrinho DEVE ser incluído na resposta do GetCartInfoAsync para possibilitar o cálculo no handler.

Casos de Borda:

  • A validade é calculada a partir do DateCreated do carrinho, não do item recomendado.
  • O cálculo no handler (e não no repositório) é intencional para evitar inconsistências de timezone entre servidor de aplicação e banco de dados.

RF-03 — Comportamento de Log ao Expirar​

História de Usuário:
Como desenvolvedor ou analista de suporte, quero registros de log quando itens recomendados forem suprimidos por expiração, para que eu possa diagnosticar situações onde a cliente não visualizou recomendações.

Critérios de Aceitação:

  1. QUANDO a janela de validade tiver expirado E o carrinho possuir itens recomendados (recommendedItems.Any() for verdadeiro) ENTÃO o sistema DEVE enviar registro para a fila de AllLogs no nível Information com a mensagem: "Itens recomendados não retornados para CartId {cart.Id}: janela de 1 hora expirada."

  2. QUANDO a janela de validade tiver expirado E o carrinho não possuir nenhum item recomendado ENTÃO o sistema NÃO DEVE registrar nenhum log.

Casos de Borda:

  • Não logar para carrinhos sem recomendações evita ruído desnecessário nos logs.

RF-04 — Deduplicação por SKU​

História de Usuário:
Como cliente, quero que itens que já estão no meu carrinho não apareçam como recomendados, para que eu não seja induzida a adicionar produtos duplicados.

Critérios de Aceitação:

  1. QUANDO os itens recomendados forem retornados ENTÃO o sistema DEVE remover da lista quaisquer itens cujo Sku já esteja presente em CartInfoDTO.Items (itens normais do carrinho).

  2. O filtro de deduplicação DEVE ser aplicado após o filtro de validade (RF-02).

  3. SE todos os itens recomendados tiverem SKUs duplicados com o carrinho ENTÃO o sistema DEVE retornar lista vazia ([]).

Casos de Borda:

  • A comparação de SKU é feita entre RecommendedItems e CartItems — itens com mesmo SKU no carrinho principal são removidos das recomendações.

RF-05 — Busca Paralela de Itens Recomendados​

História de Usuário:
Como sistema de checkout, quero buscar os itens recomendados em paralelo com as demais queries, para que o tempo de resposta do endpoint não seja impactado.

Critérios de Aceitação:

  1. QUANDO o GetInfoStoreAsync for executado ENTÃO o sistema DEVE buscar os itens recomendados via GetRecommendedItemsAsync(cart.Id) em paralelo com as demais consultas existentes.

  2. O método GetRecommendedItemsAsync DEVE consultar a tabela CartRecommendedItems com JOIN em Products e ProductPhotos para retornar o contrato completo de RecommendedItemsInfoDTO.

  3. O campo Size do DTO é lido diretamente de CartRecommendedItems.Size — não há JOIN em ProductStockStores no GET, pois o tamanho já foi selecionado pela vendedora no momento da recomendação. (Ver ADR-009)

RF-06 — Contrato de Retorno dos Itens Recomendados​

História de Usuário:
Como cliente acessando o zzlink, quero visualizar informações completas de cada item recomendado — nome, imagens, preço, desconto e o tamanho selecionado pela vendedora — para tomar uma decisão de compra informada.

Critérios de Aceitação:

  1. Cada item em RecommendedItems DEVE conter os seguintes campos:
CampoTipoFonteDescrição
RecommendedItemIdintCartRecommendedItems.IdID do registro da recomendação (usado no POST add-item)
ProductIdintCartRecommendedItems.ProductIdChave interna do produto
SkustringProducts.SkuCódigo SKU do produto
ProductNamestringProducts.NameNome do produto
DescriptionstringProducts.DescriptionDescrição do produto
Thumbnailstring?ProductPhotos.UrlThumbnail (foto com menor Order)URL da thumbnail da foto principal
ImagesList<string>ProductPhotos.UrlURLs das fotos do produto
FullPricedecimalCartRecommendedItems.FullPricePreço cheio do produto
DiscountValuedecimalCartRecommendedItems.DiscountValueValor do desconto
DiscountTypeDiscountTypeCartRecommendedItems.DiscountTipo de desconto (None, Percentage, Value)
SizestringCartRecommendedItems.SizeTamanho selecionado pela vendedora (único, não lista)

  1. Size DEVE retornar o tamanho único selecionado pela vendedora no momento da recomendação.

  2. O cliente NÃO PODE alterar o Size no zzlink — o POST de adicionar item (AddRecommendedItem) recebe apenas o RecommendedItemId e o tamanho é resolvido internamente pelo servidor.

  3. Images DEVE retornar lista vazia ([]) se o produto não possuir fotos cadastradas.

  4. Thumbnail pode ser null se a foto principal não possuir UrlThumbnail cadastrado.

  5. O GET NÃO DEVE filtrar ou excluir itens recomendados por falta de estoque — a validação de estoque é responsabilidade exclusiva do POST (AddRecommendedItem) via Cart API.

Casos de Borda:

  • A ausência de imagens (Images = []) ou de thumbnail (Thumbnail = null) não impede o retorno do item recomendado.
  • O campo Size é imutável no contexto do zzlink — o cliente visualiza e adiciona o item apenas com o tamanho que a vendedora selecionou.

RF-06.1 — Campo IsFromRecommendation em CartItemsInfoDTO​

História de Usuário:
Como sistema de checkout, quero incluir a informação de origem do item do carrinho no retorno do GetInfo, para que o zzlink possa exibir indicadores visuais ou analytics sobre itens adicionados via upsell.

Critérios de Aceitação:

  1. QUANDO os itens do carrinho (CartInfoDTO.Items) forem retornados ENTÃO cada CartItemsInfoDTO DEVE incluir o campo IsFromRecommendation (bool) indicando se o item foi adicionado pela cliente via fluxo de upsell.

  2. O campo IsFromRecommendation DEVE ser populado a partir de CartItemsModel.IsFromRecommendation do banco de dados.

  3. QUANDO CartItemsModel.IsFromRecommendation for true ENTÃO o DTO DEVE retornar IsFromRecommendation: true.

  4. QUANDO CartItemsModel.IsFromRecommendation for false ENTÃO o DTO DEVE retornar IsFromRecommendation: false.

Casos de Borda:

  • Apenas a cliente adiciona itens via recomendações no zzlink. Itens adicionados pela vendedora no zzapp sempre terão IsFromRecommendation = false.
  • Soft delete + readição de item: ao readicionar um item removido, um novo registro de CartItemsModel é criado com o valor adequado de IsFromRecommendation conforme a origem da nova adição.

RF-07 — GetInfo como Operação Somente-Leitura​

História de Usuário:
Como sistema de checkout, quero garantir que o endpoint GetInfo não altere o estado do carrinho ou das recomendações, para que a operação seja idempotente e segura para chamadas repetidas.

Critérios de Aceitação:

  1. QUANDO o endpoint GET api/payment/v2/{id} for executado ENTÃO o sistema NÃO DEVE alterar o estado do carrinho (CartModel).

  2. QUANDO o endpoint for executado ENTÃO o sistema NÃO DEVE alterar o estado das recomendações (CartRecommendedItems).

  3. QUANDO a janela de validade estiver expirada ENTÃO o sistema DEVE retornar lista vazia de RecommendedItems MAS NÃO DEVE remover os registros de CartRecommendedItems do banco de dados.

Casos de Borda:

  • O log de expiração (RF-03) é permitido por ser operação de observabilidade, não alteração de estado de negócio.

Requisitos Não-Funcionais​

RNF-01 — DTO Próprio para Itens Recomendados​

  • Os itens recomendados DEVEM ser representados por um novo DTO dedicado RecommendedItemsInfoDTO, distinto de CartItemsInfoDTO.
  • CartItemsInfoDTO NÃO deve ser modificado para acomodar os campos específicos de recomendações (RF-06).
  • CartItemsInfoDTO DEVE ser estendido com o campo IsFromRecommendation (RF-06.1) para tracking de conversão de upsell.

RNF-02 — Isolamento de Fluxos​

  • As alterações DEVEM se restringir ao fluxo store (GetInfoStoreAsync). O fluxo ecomm (GetInfoEcommAsync) não deve ser modificado.

RNF-03 — Estados de Pagamento​

  • Os construtores dos estados de pagamento (NewPayment, WaitingPayment, ResumePayment, VoidedPayment) NÃO DEVEM ser alterados. O campo RecommendedItems já estará populado no CartInfoDTO que é passado a eles.

Fora de Escopo​

  • Alterações no fluxo ecomm (GetInfoEcommAsync).
  • Modificações na estrutura do DTO CartItemsInfoDTO.
  • Criação da tabela CartRecommendedItems no banco de dados (responsabilidade de outra US).
  • Alterações nos construtores dos estados de pagamento.
  • Lógica de persistência ou atualização dos itens recomendados.

Dependências​

DependênciaDescriçãoStatus
Tabela CartRecommendedItemsDeve ser criada previamente no DbCore (schema tenant) por outra US. Colunas obrigatórias: Id, CartId, ProductId, StoreId, Size, Price, FullPrice, Discount (DiscountType), DiscountValue.Externa
CartItemsModel.IsFromRecommendationCampo bool deve existir na entidade CartItemsModel (DbCore) para indicar se o item foi adicionado via fluxo de upsell.Externa (implementada em US separada)

Questões em Aberto​

  • Nenhuma questão em aberto identificada até o momento.