Banners

Pré-requisitos de acesso

• Permissão (módulo): viewBanners OU manageBanners (basta um dos módulos para ver a tela). As ações de criar, editar e excluir exigem especificamente manageBanners (botões protegidos por *appHasPermission="'manageBanners'").
• Licença/Feature: Nenhuma.
• Contêiner do menu: GERAL → grupo Comunicação (ícone campaign) → Banners.

O que é / quando usar

Tela para administrar os banners da tela inicial (/home) do Midas-Web: campanhas promocionais, mensagens contextuais e cards de onboarding. O cliente configura tudo (texto, imagem, vigência, ordem, CTA) sem depender de deploy. Os banners são persistidos no CustomerProfileService (CPM) e servidos ao app já filtrados por vigência e ordenados. Use para rodar campanhas, exibir avisos e guiar novos usuários de forma autônoma.

Pré-condições

• Permissão: viewBanners ou manageBanners cadastrado para a role. Permissão no Axia é dupla — enum CPM no backend (manageBanners/viewBanners) e módulo dinâmico no DB; ambos precisam existir para a ação aparecer e funcionar. As mutações (criar/editar/excluir/ativar) exigem manageBanners.
• Licença/Feature: nenhuma.
• Dependências de outras telas: o upload de imagem usa a API de arquivos (POST /api/v1/files, storage de imagens). Nenhuma outra tela precisa existir antes.

Passo a passo

1. Acesse o menu Comunicação → Banners.
2. A tabela lista os banners ordenados por ordem de exibição (display_order). Use o filtro Tipo para restringir a PROMOTIONAL, CONTEXTUAL, ONBOARDING ou Todos.
3. Clique em Adicionar (requer manageBanners) para abrir o formulário.
4. Escolha o Tipo — o formulário mostra/oculta campos conforme o tipo.
5. Preencha textos, imagens (para promocional), CTA, vigência e flags.
6. Clique em Salvar.
7. Na tabela, use o toggle de status para ativar/desativar, o ícone de gráfico para ver métricas de clique, lápis para editar e lixeira para excluir.

Campos

Listagem

Coluna	O que mostra	Origem do dado
Nome (name)	Nome interno do banner	banner.name
Tipo (type)	PROMOTIONAL / CONTEXTUAL / ONBOARDING (chip colorido)	banner.type
Título (title)	Título exibido (ou —)	banner.title
Período (period)	Vigência início → fim (dd/MM/yy)	start_date / end_date
Ordem (order)	Posição de exibição	display_order
Status (status)	Toggle ativo/inativo	is_active
Ações	Métricas / Editar / Excluir	—

Formulário (modal)

Campo	O que é	Obrigatório?	Efeito no sistema/backend
Nome (name)	Identificação interna do banner	Sim	Validado no submit; usado para identificar/excluir.
Tipo (type)	PROMOTIONAL, CONTEXTUAL ou ONBOARDING	Sim	Define o componente que renderiza no app: carrossel imagem+CTA (promocional), alerta com ícone (contextual), card dispensável (onboarding). Controla quais campos aparecem no form.
Ordem de exibição (display_order)	Posição relativa na home	Não (default 0)	Banners são ordenados por display_order crescente, na tabela e no app.
Título (title)	Texto principal	Não	Exibido no banner.
Ícone (icon_name)	Nome do ícone Material (ex.: warning, info, verified)	Não	Só aparece para CONTEXTUAL/ONBOARDING; define o ícone do alerta/card.
Subtítulo (subtitle)	Texto secundário	Não	Exibido abaixo do título.
Imagem principal (image_url)	Imagem do banner	Não	Só aparece para PROMOTIONAL. Upload (≤ 5 MB) via API de arquivos; guarda a URL retornada, não o binário.
Imagem responsiva (image_url_responsive)	Versão mobile da imagem	Não	Só PROMOTIONAL; mesmo fluxo de upload, usada em telas menores.
Rótulo do CTA (cta_label)	Texto do botão de ação	Não	Define o botão; sem rótulo, não há CTA visível.
Rota interna (cta_internal_route)	Destino interno (ex.: /wallet, /exchange)	Não	Navegação interna no app ao clicar no CTA.
URL externa (cta_external_url)	Link externo (https://...)	Não	Alternativa à rota interna; abre URL externa.
Abrir em nova aba (cta_new_tab)	Flag do CTA externo	Não	Se marcado, o link externo abre em nova aba.
Data início (start_date)	Início da vigência	Não	Define quando o banner passa a aparecer. Validado: início não pode ser maior que fim.
Data fim (end_date)	Fim da vigência	Não	Define quando o banner deixa de aparecer.
Ativo (is_active)	Liga/desliga o banner	Não (default ligado)	Banner inativo não é servido ao app independente da vigência.
Dispensável (is_dismissable)	Permite o usuário fechar o banner	Não	Tipicamente para ONBOARDING; o dismiss é lembrado no localStorage do usuário.
Tenant (tenant_id)	Restringe o banner a um tenant	Não	Opcional; usado em ambientes multi-tenant para segmentar a exibição.
Cor de fundo (background_color)	Cor de fundo (ex.: #1f2937)	Não	Customização visual do banner.
Cor do texto (text_color)	Cor do texto (ex.: #ffffff)	Não	Customização visual.
Grupo legado (legacy_group)	Compatibilidade com o sistema antigo (bankingBanners, eniatoBanners, midasWebBanners, crowdfundingBanners, digitalBankingBanners, exchangeBanners, …)	Não	Faz a camada de compatibilidade servir este banner também aos getters legados por tela-alvo. Deixe vazio para banners exclusivos da nova home.

Ações e modais

• Adicionar / Editar: abre o BannerFormDialog. Ao salvar, valida (nome e tipo obrigatórios; início ≤ fim) e chama create ou update. Em erro, exibe a mensagem do backend.
• Toggle de status: alterna is_active direto na tabela (update com o payload invertido).
• Excluir: pede confirmação (Excluir o banner "<nome>"?) e remove via delete.
• Métricas: abre um resumo com total de cliques e data do último clique (metrics). O tracking registra apenas cliques (sem impressões).
• Upload de imagem: seleção de arquivo client-side; rejeita arquivos maiores que 5 MB; ao concluir, grava a URL no campo correspondente.
• Step-up / MFA: não há re-autenticação por padrão nesta tela.

Regras de negócio / cuidados

Atenção

• Imagem (PROMOTIONAL): limite de 5 MB por arquivo; o banner guarda só a URL (S3/MinIO), não o binário. Forneça imagem principal e responsiva para boa exibição em mobile.
• Vigência: start_date não pode ser maior que end_date (bloqueado na validação). Banner inativo (is_active = false) não aparece mesmo dentro da vigência.
• Ícone só faz sentido em CONTEXTUAL/ONBOARDING; em PROMOTIONAL o campo nem aparece. Já as imagens só aparecem em PROMOTIONAL.
• CTA: se preencher rota interna e URL externa, priorize um destino claro; "abrir em nova aba" só se aplica ao link externo.
• Grupo legado muda o alcance: preenchê-lo faz o banner também ser entregue pelos getters do sistema antigo daquela tela-alvo. Use com intenção.
• Métricas: só clique é rastreado; não há contagem de impressões.

• Exclusão é definitiva: remover o banner apaga o registro; prefira desativar (toggle) se quiser apenas tirar de exibição mantendo o histórico.

Exemplos

Cenário 1 — Campanha promocional com carrossel e CTA interno

1. Adicionar → Tipo PROMOTIONAL.
2. Nome: campanha-cartao-junho; Ordem: 1.
3. Faça upload da imagem principal (≤ 5 MB) e da imagem responsiva.
4. CTA: rótulo Quero meu cartão, rota interna /wallet.
5. Vigência: início hoje, fim no último dia do mês; Ativo marcado.
6. Salvar. O banner aparece no topo do carrossel da home (ordem 1) enquanto estiver dentro da vigência. Cliques no CTA são contabilizados nas Métricas.

Cenário 2 — Aviso contextual (alerta com ícone)

1. Adicionar → Tipo CONTEXTUAL.
2. Nome: aviso-manutencao; Ícone: warning.
3. Título: Manutenção programada; Subtítulo: Sábado, das 2h às 5h, alguns serviços ficarão indisponíveis.
4. Cores opcionais: fundo #1f2937, texto #ffffff.
5. Vigência curta (só os dias do aviso); Ativo.
6. Salvar. O app exibe um alerta com o ícone warning; o admin escreve o texto (não há condição automática — é exibição manual durante a vigência).

Cenário 3 — Card de onboarding dispensável

1. Adicionar → Tipo ONBOARDING.
2. Nome: onboarding-kyc; Ícone: verified.
3. Título: Complete sua verificação; CTA rota interna /account/kyc.
4. Marque Dispensável para o usuário poder fechar o card (o dismiss fica no localStorage dele).
5. Salvar. Novos usuários veem o card até concluírem a ação ou dispensarem-no.

Cenário 4 — Reaproveitar no sistema legado (grupo legado)

Para que um banner também apareça onde o app ainda lê do sistema antigo (ex.: tela de banking), defina o Grupo legado como bankingBanners (ou crowdfundingBanners, exchangeBanners, etc.). A camada de compatibilidade passa a servir este banner também via getter legado daquele grupo, no formato antigo { name, url, link }. Deixe vazio quando o banner for exclusivo da nova home.

Telas relacionadas

• Envio de e-mail
• Ação em massa (visão geral)