Skip to main content

Documento de Requisitos — Alterar POST api/cart

Tarefa: #196022 Contexto: Sequência de implementação #4

Visão Geral​

Modificar o endpoint POST api/cart para aceitar o campo opcional RecommendationsId (Guid?) e publicar o evento RecommendationCartCreated na fila SQS FIFO quando o campo estiver presente.

Papéis Envolvidos​

PapelResponsabilidade
Desenvolvedor Back-endAlterar DTO, adicionar handler no chain e estender repositório

Requisitos Funcionais​

RF-01 — Receber RecommendationsId no CreateCartCommand​

História de Usuário: Como sistema, quero receber o RecommendationsId na criação do carrinho para associar o evento de histórico ao fluxo de upsell.

Critérios de Aceitação:

  1. WHEN o CreateCartCommand for declarado THEN o sistema SHALL conter o campo RecommendationsId (Guid?) como propriedade opcional
  2. WHEN RecommendationsId não for enviado na requisição THEN o sistema SHALL tratá-lo como null e seguir o fluxo normalmente sem associar recomendação
  3. WHEN RecommendationsId for enviado com formato inválido THEN o sistema SHALL rejeitar a requisição com HTTP 400 (validação nativa do model binding para Guid?)

Localização: Cart.Domain/Commands/CreateCartCommand.cs

RF-02 — PublishRecommendationHistoryHandler​

História de Usuário: Como sistema, quero publicar o evento RecommendationCartCreated na fila de histórico após a persistência bem-sucedida do carrinho, sem impactar a resposta ao cliente.

Critérios de Aceitação:

  1. WHEN o handler for executado E Command.RecommendationsId for null THEN o sistema SHALL retornar o context sem publicar nenhum evento
  2. WHEN o handler for executado E Command.RecommendationsId não for null THEN o sistema SHALL buscar o CodeStore via IStoreRepository.GetCodeStoreById(context.CartModel.StoreId)
  3. WHEN GetCodeStoreById retornar null THEN o sistema SHALL publicar o evento com CodeStore = string.Empty
  4. WHEN o CodeStore for resolvido THEN o sistema SHALL publicar CartRecommendationsEvent.RecommendationCartCreated(recommendationsId, cartId, customerId, codeStore) via IMessageBusService.SendFifoAsync
  5. WHEN SendFifoAsync lançar exceção THEN o sistema SHALL logar o erro e retornar o context sem adicionar erros (fire-and-forget — falha de observabilidade não deve impactar a criação do carrinho)
  6. WHEN o carrinho já existia (re-execução por idempotency) THEN o sistema SHALL publicar o evento normalmente — duplicatas são intencionais para diagnóstico
  7. WHEN o handler for posicionado no chain THEN o sistema SHALL ser inserido imediatamente após SaveCartHandler

Localização: Cart.API/Application/Handlers/CreateCart/PublishRecommendationHistoryHandler.cs

Injeção de dependências (primary constructor):

  • IMessageBusService messageBusService
  • IStoreRepository storeRepository
  • ILogger<PublishRecommendationHistoryHandler> logger

RF-03 — GetCodeStoreById no IStoreRepository​

História de Usuário: Como sistema, quero buscar o CodeStore a partir do StoreId inteiro para compor o evento de histórico.

Critérios de Aceitação:

  1. WHEN a interface for declarada THEN o sistema SHALL expor Task<string?> GetCodeStoreById(int storeId)
  2. WHEN a implementação em StoreRepository for criada THEN o sistema SHALL consultar _dbContextRead.Stores.AsNoTracking() filtrando por x.Id == storeId e retornar x.CodeStore
  3. WHEN CacheStoreRepositoryDecorator for atualizado THEN o sistema SHALL implementar GetCodeStoreById com cache key "StoreModel-{schema}-StoreId-{storeId}" e SetAbsoluteExpiration(TimeSpan.FromHours(12))
  4. WHEN o resultado da query for null THEN o sistema SHALL não escrever no cache

Localização:

  • Interface: Cart.Domain/Interfaces/Repositories/IStoreRepository.cs
  • Implementação: Cart.Infrastructure/Data/Repositories/StoreRepository.cs
  • Decorator: Cart.Infrastructure/Data/Repositories/Cached/CacheStoreRepositoryDecorator.cs

RF-04 — Registrar IMessageBusService no CartService​

Critérios de Aceitação:

  1. WHEN o CartService for instanciado THEN o sistema SHALL receber IMessageBusService via construtor e repassá-lo ao PublishRecommendationHistoryHandler
  2. WHEN o chain de handlers for montado THEN o sistema SHALL inserir PublishRecommendationHistoryHandler imediatamente após SaveCartHandler

Localização: Cart.API/Application/CartService.cs

Fora de Escopo​

  • Alterar outros endpoints do carrinho
  • Alterar endpoints de recomendação (cobertos pelas tasks #196023–#196025)
  • Retry ou DLQ para falhas de publicação na fila

Dependências​

DependênciaDescriçãoStatus
Task #196020CartRecommendationsEvent, QueueTypes.AWS_SQS_CART_RECOMMENDATION_HISTORY_FIFOPendente
Task #196021Serviço de histórico para consumir eventosPendente

Arquivos alterados​

ArquivoProjetoAção
Commands/CreateCartCommand.csCart.DomainAdicionar Guid? RecommendationsId
Interfaces/Repositories/IStoreRepository.csCart.DomainAdicionar GetCodeStoreById(int)
Data/Repositories/StoreRepository.csCart.InfrastructureImplementar GetCodeStoreById
Data/Repositories/Cached/CacheStoreRepositoryDecorator.csCart.InfrastructureAdicionar cache para GetCodeStoreById
Handlers/CreateCart/PublishRecommendationHistoryHandler.csCart.APINovo
Application/CartService.csCart.APIInjetar IMessageBusService, adicionar handler no chain