Skip to main content

Documento de Requisitos — Criar fila para centralizar a gravação do histórico

Tarefa: #196020 Contexto: Sequência de implementação #2

Visão Geral​

Criar a fila SQS FIFO AWS_SQS_CART_RECOMMENDATION_HISTORY_FIFO no Message BUS e o evento CartRecommendationsEvent para transportar eventos de histórico de upsell ao serviço de registro.

Papéis Envolvidos​

PapelResponsabilidade
Desenvolvedor Back-endCriar fila (QueueType + StructureStack) e evento no submódulo Message BUS

Requisitos Funcionais​

RF-01 — Constante da fila no QueueTypes​

História de Usuário: Como sistema, quero uma constante nomeada para identificar a fila, seguindo a convenção do Message BUS.

Critérios de Aceitação:

  1. WHEN a constante for declarada THEN o sistema SHALL usar o nome AWS_SQS_CART_RECOMMENDATION_HISTORY_FIFO_XXX
  2. WHEN a constante for declarada THEN o sistema SHALL posicioná-la em Coezzion.MessageBus.QueueTypes (submódulo coezzion-submodule-message-bus), após a constante AWS_SQS_LOG_QUEUE_EVENTS_FIFO
  3. IF o nome contiver _FIFO_ THEN o sistema SHALL tratar a fila como FIFO (criação com .fifo e validação no SendFifoAsync)

RF-02 — Entrada no StructureStack​

História de Usuário: Como sistema, quero que a fila seja criada automaticamente pelo CreateEnvironmentScaffold em cada ambiente (DEV/QA/PRD), com configurações análogas ao AllLogs.

Critérios de Aceitação:

  1. WHEN o CreateEnvironmentScaffold processar o StructureStack.List THEN o sistema SHALL criar a fila com VisibilityTimeout = "600" segundos
  2. WHEN a fila for criada THEN o sistema SHALL usar o valor default do SQS para retenção de mensagens (4 dias)
  3. WHEN a fila for criada THEN o sistema SHALL não associar DLQ (fora de escopo)
  4. WHEN a entrada for declarada THEN o sistema SHALL posicioná-la após a entrada AWS_SQS_LOG_QUEUE_EVENTS_FIFO

RF-03 — Evento CartRecommendationsEvent​

História de Usuário: Como producer (BFF + API Cart) e consumer (serviço de histórico), quero um contrato compartilhado para serialização e desserialização dos eventos de histórico.

Critérios de Aceitação:

  1. WHEN a classe for declarada THEN o sistema SHALL estender TenancyEvent (herda IdEvent, Timestamp, EventName de Event e SchemaName de TenancyEvent)
  2. WHEN a classe for declarada THEN o sistema SHALL conter os campos: RecommendationsId (Guid), EventType (string), CartId (int?), CustomerId (int), CodeStore (string), Url (string?), Request (string?), Response (string?), StatusCode (int?), DurationMs (long?), Message (string?)
  3. WHEN a classe for declarada THEN o sistema SHALL não conter campo createdAt — usar Timestamp herdado de Event
  4. WHEN a classe for declarada THEN o sistema SHALL fornecer 5 factory methods estáticos:
    • RecommendationRequested(Guid recommendationsId, int customerId, string codeStore, ...) → EventType = "RecommendationRequested", CartId = null
    • RecommendationCartCreated(Guid recommendationsId, int cartId, int customerId, string codeStore, ...) → EventType = "RecommendationCartCreated"
    • RecommendationProductAddedToOrder(Guid recommendationsId, int cartId, int customerId, string codeStore, ...) → EventType = "RecommendationProductAddedToOrder"
    • RecommendationProductRemovedToOrder(Guid recommendationsId, int cartId, int customerId, string codeStore, ...) → EventType = "RecommendationProductRemovedToOrder"
    • Create(Guid recommendationsId, string eventType, int? cartId, int customerId, string codeStore, ...) → EventType livre (para extensibilidade futura)
  5. WHEN a classe for declarada THEN o sistema SHALL usar init accessors (consistente com LogoutUserEvent e demais eventos do submódulo)
  6. WHEN a classe for declarada THEN o sistema SHALL residir em Coezzion.MessageBus/Events/CartRecommendationsEvent.cs

RF-04 — Estratégia de ordenação e deduplicação​

História de Usuário: Como sistema, quero que a fila replique o comportamento consolidado do AllLogs (AWS_SQS_LOG_QUEUE_EVENTS_FIFO).

Critérios de Aceitação:

  1. WHEN uma mensagem for publicada via SendFifoAsync THEN o sistema SHALL usar MessageGroupId = Guid.NewGuid() por mensagem (padrão do submódulo, sem ordenação entre mensagens do mesmo RecommendationsId)
  2. WHEN uma mensagem for publicada THEN o sistema SHALL não setar MessageDeduplicationId — deduplicação fica na camada de aplicação do consumer
  3. WHEN a fila for criada THEN o sistema SHALL não habilitar ContentBasedDeduplication

Justificativa: O Timestamp do evento (populado no publish, via Event.Timestamp) garante a fidelidade temporal no registro. A tabela CartRecommendationsHistory é append-only e não possui dependências entre linhas que exijam processamento sequencial.

Requisitos Não-Funcionais​

  • Performance: Publicação fire-and-forget — falha no publish não deve impactar a resposta ao cliente
  • Convenção: Seguir nomenclatura e padrões existentes do submódulo Message BUS (análogo ao AWS_SQS_LOG_QUEUE_EVENTS_FIFO)

Fora de Escopo​

  • DLQ (Dead Letter Queue) — será tratado em task separada se necessário
  • Monitoramento e alarmes
  • Alterações em IMessageBusService ou MessageBusService — sem overloads novos
  • Enum CartRecommendationsEventType — EventType é string livre

Dependências​

DependênciaDescriçãoStatus
Message BUS (submódulo)Infraestrutura de mensageria coezzion-submodule-message-busDisponível
Task #196018Tabela CartRecommendationsHistory deve existir antes do consumoPendente

Referências​

ArtefatoDescrição
ADR-011 — Deduplicação e orderingDecisão de arquitetura sobre estratégia de dedup/ordering
Pesquisa: padrão FIFO AllLogsAnálise do comportamento análogo no LogQueueConsumerService
Task #01 — Tabela de históricoSchema da tabela e eventos suportados
Pre-refinamentoDefinição original da fila e schema do evento

Arquivos alterados​

ArquivoSubmóduloAção
QueueType.cscoezzion-submodule-message-busAdicionar constante AWS_SQS_CART_RECOMMENDATION_HISTORY_FIFO
QueueType.cscoezzion-submodule-message-busAdicionar Structure com visibilityTimeout = "600"
CartRecommendationsEvent.cscoezzion-submodule-message-busNovo arquivo — classe CartRecommendationsEvent : TenancyEvent