Status: Approved · v2.2 · SPEC-DOMAIN-SHARE-001
depends_on: SPEC-BRAND-001, SPEC-DOMAIN-MATCH-001, SPEC-DOMAIN-RANKING-001
used_by: IS-MVP-12.3, IS-MVP-17.4, IS-POST-12.1
Cards compartilháveis
Arte pública gerada a partir de dados canônicos para WhatsApp e Instagram, com assinatura discreta do RaizFC.
Objetivo e limites
Esta especificação define o comportamento canônico do domínio Cards compartilháveis no RaizFC. Ela deve ser consultada antes de alterar contratos, mocks, endpoints, telas, permissões ou Increment Specifications relacionados.
Incluído no MVP
- Formatos story 1080×1920, square 1080×1080 e vertical 1080×1350.
- Resultado, próximo jogo, escalação lista, convocação, reforço, título, ranking, artilharia, perfil time/jogador/torcida/campeonato e apoio.
- Marca RaizFC obrigatória.
- Geração client-side quando possível.
- Fallback texto+link.
Fora do MVP
- Animação/vídeo.
- Templates premium.
- Remoção de marca.
- Patrocínio no card.
- Editor livre.
Atores e responsabilidades
| Ator | Responsabilidade |
|---|---|
| Visitante/usuário | Compartilha card permitido. |
| Gestor | Gera cards oficiais de entidade e jogo. |
| Jogador | Gera perfil quando privacidade permite. |
| Sistema | Monta templates e fallback de texto/link. |
Conceitos canônicos
ShareableCard
Representação visual gerável.
Template
Layout controlado por tipo/formato.
Brand Signature
RaizFC + domínio/tagline discretos.
Source Snapshot
Dados públicos capturados no momento da geração.
Fallback Share
Texto e link quando imagem falha.
Invariantes
- Card nunca expõe dado privado.
- Marca RaizFC é obrigatória no MVP.
- Time/jogador/conteúdo é protagonista; plataforma é assinatura.
- Patrocínio não aparece no card no MVP.
- Resultado contestado não pode ser apresentado como definitivo.
- Perfil privado não gera card público.
- Template não busca dados diretamente; recebe props/DTO.
- Todo card possui link de destino quando aplicável.
Estados
| Estado | Significado | Visibilidade/efeito |
|---|---|---|
| draft | Configuração iniciada | Não compartilhável. |
| preview | Renderização local | Pode ajustar opções permitidas. |
| generated | Imagem pronta | Compartilhável. |
| failed | Falha | Fallback disponível. |
| expired | Link/asset temporário expirado | Pode regenerar. |
Transições permitidas
| Origem | Ação | Destino | Autoridade | Efeitos |
|---|---|---|---|---|
| — | create | draft | Usuário/gestor | Valida tipo/source. |
| draft | preview | preview | Cliente | Renderiza. |
| preview | generate | generated | Cliente/servidor | Cria asset. |
| draft/preview | fail | failed | Sistema | Oferece fallback. |
| generated | expire | expired | Job/storage | Link temporário. |
Permissões
| Permission key | Quem recebe por padrão | Ação protegida | Auditoria |
|---|---|---|---|
| share.generatePublic | Público/autenticado | Card de conteúdo público | Não |
| share.generateOfficial | Gestor contextual | Templates oficiais | Sim leve |
| share.generatePlayer | Próprio jogador/público conforme privacy | Perfil jogador | Não |
Fluxos funcionais
Resultado
- Carrega PublicMatchDto.
- Verifica status validated ou inclui badge aguardando/contestado.
- Escolhe formato.
- Renderiza placar, escudos, times, contexto e assinatura.
- Permite compartilhar imagem ou fallback.
Escalação
- Gestor usa MatchReport/lineup permitido.
- MVP usa lista de titulares e banco opcional.
- Nomes convidados respeitam visibilidade.
Perfil de jogador
- Verifica privacy.
- Usa foto/avatar, nome, posição, time e stats públicas.
- Inclui link do perfil.
Falha de geração
- Captura erro técnico.
- Mantém preview/dados.
- Oferece texto formatado e link.
Casos-limite e erros
| Cenário | Comportamento esperado | Código/estado |
|---|---|---|
| Logo do time ausente | Usar placeholder neutro com iniciais | — |
| Nome longo | Aplicar regras de truncamento/escala | CARD_CONTENT_OVERFLOW |
| Resultado contestado | Badge e texto neutro | SOURCE_CONTESTED |
| Perfil privado | Bloquear | CARD_NOT_ALLOWED |
| Canvas/view capture falha | Fallback texto+link | CARD_GENERATION_FAILED |
Privacidade e exposição pública
- Somente DTOs públicos entram no template.
- Telefone/endereço privado, saldo e valores nunca entram.
- Convidado não confirmado pode ser omitido ou mostrado apenas pelo nome permitido no contexto.
Notificações e auditoria
- Não gera notificação comum.
- Card oficial pode ser associado a post/campanha com auditoria separada.
API relacionada
| Método | Rota | Acesso | Finalidade |
|---|---|---|---|
| POST | /api/v1/shareable-cards | Público/contextual | Criar config |
| GET | /api/v1/shareable-cards/:id | Público/contextual | Detalhe |
| POST | /api/v1/shareable-cards/:id/generate | Contextual | Gerar server-side futuro |
| GET | /api/v1/shareable-cards/templates | Público | Templates |
| GET | /api/v1/shareable-cards/options | Contextual | Opções permitidas |
Contratos compartilhados
- ShareableCardType
- ShareableCardFormat
- ShareableCardDto
- CreateShareableCardRequest/Response
- ShareableCardSourceDto
- ShareFallbackDto
Requisitos de UX
- Preview em tela dedicada com escolha de formato.
- Sem editor livre; apenas opções controladas como fundo/variação quando disponíveis.
- Safe areas e legibilidade em tela pequena.
- Botões compartilhar, salvar imagem quando suportado e copiar texto/link.
Comportamento dos mocks
- Todos os tipos prioritários.
- Long names, no logo, contested, private, generation failure.
- Assets determinísticos.
Critérios de aceite
- Três formatos.
- Marca obrigatória.
- Fallback sempre.
- Sem dado privado/sponsor.
- Resultado status correto.
- Template por props.
Testes obrigatórios
- Privacy.
- Format dimensions.
- Overflow.
- Fallback.
- Source status.
- Template mapping.
Pós-MVP
- Vídeo, premium, sponsor moderado, identidade avançada e geração server-side.
- Cards celebrativos de aniversário de jogador, time ou torcida e marco de campanha, gerados como sugestão privada e publicados somente após aprovação explícita no preview.
- Aniversários usam
America/Sao_Paulo; as fontes são data de nascimento do jogador e data de fundação de time/torcida. - A idade aparece somente quando permitida no painel de privacidade, mas sua ocultação não impede a sugestão do card.
- Registro configurável de marcos inicialmente limitado a 5 vitórias validadas na campanha, 100º jogo validado e entrada no top 3 de qualquer ranking canônico disponível.
Decisões registradas
- Cards são motor central de viralização.
- Escalação MVP usa lista.
- Marca pequena obrigatória.
- Patrocínio em cards fica pós-MVP.
- Card celebrativo não é publicação automática; aprovação explícita em notificação acionável é invariante do fluxo pós-MVP.
Machine summary
spec: SPEC-DOMAIN-SHARE-001
domain: Cards compartilháveis
must_preserve:
- Card nunca expõe dado privado.
- Marca RaizFC é obrigatória no MVP.
- Time/jogador/conteúdo é protagonista; plataforma é assinatura.
- Patrocínio não aparece no card no MVP.
- Resultado contestado não pode ser apresentado como definitivo.
- Perfil privado não gera card público.
- Template não busca dados diretamente; recebe props/DTO.
- Todo card possui link de destino quando aplicável.
touches:
- contracts
- mocks
- api
- frontend
- backend
- tests
- documentation