Status: Approved · v2 · SPEC-DOMAIN-TORCIDA-001

depends_on: SPEC-DOMAIN-TEAM-001, SPEC-DOMAIN-AUTH-001

used_by: IS-MVP-01.5, IS-MVP-08.1, IS-MVP-08.2

Torcidas

Entidade pública e gerenciável vinculada a um time, com membros, governança, carteira e patrocínio.

Objetivo e limites

Esta especificação define o comportamento canônico do domínio Torcidas no RaizFC. Ela deve ser consultada antes de alterar contratos, mocks, endpoints, telas, permissões ou Increment Specifications relacionados.

Incluído no MVP

• Criação vinculada a um time.
• Aprovação obrigatória pelo time.
• Página pública, gestão e membros.
• Modos open, approval_required e invite_only.
• Wallet, apoio, até três sponsors e transferências com time.

Fora do MVP

• Critérios automáticos complexos.
• Mensalidades.
• Votação interna avançada.
• Eventos e venda de ingressos.

Atores e responsabilidades

Ator	Responsabilidade
Visitante	Lê página e patrocinadores.
Torcedor	Segue, solicita entrada, apoia e compartilha.
Membro	Participa conforme regras da torcida.
Gestor da torcida	Administra identidade, membros, carteira e posts.
Gestor do time	Aprova a existência da torcida.
Operação	Modera denúncias e disputas.

Conceitos canônicos

Torcida

Permanece em português no modelo técnico.

TorcidaTeamLink

Relação de aprovação e vigência com o time.

Membership

Relação do usuário com a torcida; seguir não equivale a ser membro.

JoinMode

Política de entrada.

Invariantes

• Toda torcida pertence a um único time no MVP.
• Torcida só opera plenamente após aprovação do time.
• Criador vira primary_owner.
• Membro ativo segue a torcida automaticamente.
• Wallet só transfere para/de seu time vinculado.
• Torcida tem no máximo três sponsors ativos/reservados.
• Rejeição pelo time não apaga o registro; mantém histórico de decisão.

Estados

Estado	Significado	Visibilidade/efeito
pending_team_approval	Aguardando time	Página limitada, sem operação financeira.
approved	Ativa e aprovada	Página e gestão completas.
rejected	Rejeitada	Pode ser corrigida/reapresentada conforme regra.
suspended	Suspensa	Ações bloqueadas.
ended	Vínculo encerrado	Histórico preservado.

Transições permitidas

Origem	Ação	Destino	Autoridade	Efeitos
—	create	pending_team_approval	Usuário autenticado	Cria owner e wallet bloqueada.
pending_team_approval	approve	approved	Gestor do time	Libera membros, apoio e sponsors.
pending_team_approval	reject	rejected	Gestor do time	Registra motivo.
rejected	resubmit	pending_team_approval	Primary owner	Reenvia após ajustes.
approved	suspend	suspended	Time/operação conforme caso	Bloqueia ações.
approved/suspended	end	ended	Owners/operação	Preserva histórico.

Permissões

Permission key	Quem recebe por padrão	Ação protegida	Auditoria
torcida.editProfile	Admin/Media	Editar página	Sim
torcida.manageMembers	Members/Admin	Aprovar/remover membros	Sim
torcida.managePosts	Media/Admin	Publicar	Sim
torcida.manageWallet	Financial/Admin	Carteira e transferências	Sim
torcida.manageSponsors	Financial/Admin	Patrocínios	Sim
torcida.manageManagers	Admin/Primary owner	Acessos	Sim
torcida.transferOwnership	Primary owner	Transferir ownership	Sim

Fluxos funcionais

Criação e aprovação

1. Usuário escolhe time, nome, distrito e joinMode.
2. Sistema verifica duplicidade e mesmo distrito.
3. Torcida nasce pending_team_approval.
4. Time recebe pendência.
5. Aprovação libera página completa e carteira.

Entrada open

1. Usuário autenticado toca Entrar.
2. Membership active é criado.
3. Follow é garantido.

Entrada por aprovação

1. Pedido pending é criado.
2. Gestores recebem notificação.
3. Aprovar ativa membership; rejeitar registra decisão.

Transferência com time

1. Gestor financeiro escolhe direção e valor.
2. Backend valida vínculo approved, saldo e lotes.
3. Movimentações espelhadas são criadas sem taxa.
4. Ambas as entidades recebem notificação.

Casos-limite e erros

Cenário	Comportamento esperado	Código/estado
Time rejeita	Manter rejected e motivo	TORCIDA_REJECTED
Usuário já membro	Retornar estado atual sem duplicar	ALREADY_MEMBER
Torcida não aprovada tenta receber apoio	Bloquear checkout	TORCIDA_NOT_APPROVED
Transferência para outro time	Rejeitar	INVALID_TRANSFER_TARGET
Último owner tenta sair	Bloquear	PRIMARY_OWNER_REQUIRED

Privacidade e exposição pública

• Lista pública de membros pode ser agregada ou limitada; memberships privadas não são expostas.
• Extrato e saldo são privados.
• Apoiadores públicos sem valor.
• Contatos seguem configuração de visibilidade.

Notificações e auditoria

• Pedido de aprovação ao time.
• Pedido/decisão de entrada.
• Convites de membro e gestão.
• Créditos, transfers e sponsors.
• Suspensão e encerramento.

API relacionada

Método	Rota	Acesso	Finalidade
POST	/api/v1/torcidas	Autenticado	Criar
GET	/api/v1/torcidas/:slug	Público	Página
PATCH	/api/v1/torcidas/:id	torcida.editProfile	Editar
POST	/api/v1/torcidas/:id/join	Autenticado	Entrar/solicitar
GET	/api/v1/torcidas/:id/members	Público/gestão	Listar
POST	/api/v1/torcidas/:id/members/:memberId/approve	torcida.manageMembers	Aprovar
POST	/api/v1/torcidas/:id/invites	torcida.manageMembers	Convidar
POST	/api/v1/teams/:id/torcidas/:torcidaId/approve	team permission	Aprovar vínculo
GET	/api/v1/torcidas/:id/management-summary	Gestão	Resumo

Contratos compartilhados

• TorcidaEntity
• PublicTorcidaDto
• TorcidaManagementDto
• CreateTorcidaRequest
• TorcidaMembershipDto
• TorcidaJoinMode
• TorcidaTeamLinkStatus

Requisitos de UX

• Página mostra time vinculado, identidade, membros públicos, posts, apoio, sponsors e território.
• Estado pending/rejected mostra explicação ao owner e não simula entidade plenamente ativa.
• Gestão inclui membros, publicações, carteira, sponsors, identidade, permissões e configurações.

Comportamento dos mocks

• Torcidas pending, approved e rejected.
• Join open e approval_required alteram estado.
• Transferência in-memory com saldo e erro de insuficiência.

Critérios de aceite

• Time precisa aprovar.
• Membro ativo segue automaticamente.
• Wallet bloqueada antes da aprovação.
• Transferências apenas com time vinculado.
• JoinMode respeitado.

Testes obrigatórios

• Criação/duplicidade.
• Aprovação/rejeição/resubmit.
• Entrada por modos.
• Membership e follow.
• Transferência e saldo.
• Permissões.

Pós-MVP

• Critérios automáticos.
• Votações.
• Mensalidades.
• Eventos próprios.

Decisões registradas

• Torcida é entidade própria, não simples lista do time.
• Várias torcidas por time são permitidas.
• Aprovação do time é obrigatória.
• Torcida possui wallet e sponsors.

Machine summary

spec: SPEC-DOMAIN-TORCIDA-001
domain: Torcidas
must_preserve:
  - Toda torcida pertence a um único time no MVP.
  - Torcida só opera plenamente após aprovação do time.
  - Criador vira primary_owner.
  - Membro ativo segue a torcida automaticamente.
  - Wallet só transfere para/de seu time vinculado.
  - Torcida tem no máximo três sponsors ativos/reservados.
  - Rejeição pelo time não apaga o registro; mantém histórico de decisão.
touches:
  - contracts
  - mocks
  - api
  - frontend
  - backend
  - tests
  - documentation