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

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

used_by: IS-MVP-01.2, IS-MVP-05.1, IS-MVP-05.2, IS-MVP-05.3

Jogadores

Perfil esportivo de um usuário, com vínculos, histórico, estatísticas e controles de privacidade.

Objetivo e limites

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

Incluído no MVP

• Ativação opcional do papel player.
• Um perfil principal por usuário.
• Posição, pé dominante, foto, bio curta e status.
• Vínculos ativos, convidados e ex-times.
• Stats de jogos, gols, assistências e cartões.
• Status “livre” e agenda exposta opt-in.
• Confirmação de histórico de convidado.

Fora do MVP

• Vídeos avançados.
• Avaliações/scouting.
• Agentes e contratos.
• Múltiplos perfis esportivos.

Atores e responsabilidades

Ator	Responsabilidade
Visitante	Vê perfil público conforme privacidade.
Jogador	Edita perfil, privacidade, disponibilidade e responde convites.
Gestor de time	Convida e consulta perfil público.
Gestor de campeonato	Consulta elegibilidade e inscrições.
Operação	Trata reivindicação/privacidade de convidados.

Conceitos canônicos

PlayerProfile

Extensão esportiva da conta.

AvailabilityStatus

available, active, inactive ou retired.

Guest Confirmation

Aprovação para associar participação criada antes da conta.

Public Stats

Somente dados derivados de partidas validadas e permitidos pela privacidade.

Invariantes

• Um usuário possui no máximo um PlayerProfile principal.
• Perfil pode existir incompleto, mas deve sinalizar campos faltantes.
• Stats públicas usam apenas partidas validadas.
• Guest não confirmado não cria histórico público pessoal.
• Jogador controla exibição de contatos, ex-times, times atuais, stats e disponibilidade.
• CPF/documentos nunca são públicos.
• Jogador pode encerrar vínculo ativo, preservando histórico.

Estados

Estado	Significado	Visibilidade/efeito
available	Livre e disponível	Pode expor agenda opt-in.
active	Atuando	Pode estar ligado a múltiplas categorias/times conforme regras.
inactive	Sem atividade atual	Histórico preservado.
retired	Aposentado	Sem convites ativos por padrão.

Transições permitidas

Origem	Ação	Destino	Autoridade	Efeitos
—	activate_profile	inactive/available	Usuário	Cria perfil possivelmente incompleto.
inactive	set_available	available	Jogador	Exibe disponibilidade se permitido.
available	accept_team_link	active	Jogador	Ativa vínculo.
active	set_inactive	inactive	Jogador	Não encerra automaticamente vínculos.
any	retire	retired	Jogador	Bloqueia novos convites por padrão.

Permissões

Permission key	Quem recebe por padrão	Ação protegida	Auditoria
player.editOwnProfile	Próprio jogador	Editar dados	Sim em campos sensíveis
player.managePrivacy	Próprio jogador	Privacidade	Sim
player.respondInvites	Próprio jogador	Aceitar/rejeitar	Sim
player.confirmGuestHistory	Próprio jogador	Associar histórico	Sim

Fluxos funcionais

Ativação

1. Usuário autenticado ativa papel player.
2. Sistema cria perfil com status e completeness.
3. Usuário preenche apelido esportivo, posições e privacidade.
4. Perfil público só mostra campos permitidos.

Aceite de convite

1. Jogador recebe convite com time e categorias.
2. Abre detalhes e aceita ou rejeita.
3. Aceite ativa TeamPlayerLink e notifica gestores.
4. Rejeição não aparece publicamente.

Confirmação de convidado

1. Jogador encontra participações potencialmente correspondentes.
2. Visualiza time, partida e nome usado.
3. Confirma uma por vez.
4. Sistema associa stats elegíveis e mantém audit trail.
5. Contestação envia solicitação ao suporte.

Casos-limite e erros

Cenário	Comportamento esperado	Código/estado
Perfil privado	Busca e página retornam somente resumo permitido ou 404 público conforme configuração	PLAYER_PRIVATE
Convite expirado	Não aceitar	INVITATION_EXPIRED
Participação já atribuída	Bloquear duplicidade	GUEST_HISTORY_ALREADY_CLAIMED
Aposentado recebe convite	Bloquear ou exigir mudança de status	PLAYER_RETIRED
Stats de partida contestada	Não consolidar até resolução	STATS_PENDING_VALIDATION

Privacidade e exposição pública

• Contatos, agenda, ex-times, times atuais e stats possuem toggles independentes.
• Nome de exibição pode diferir do nome da conta.
• Documento de convidado é privado e acessível somente a operação autorizada.
• Busca não retorna jogador com perfil público desativado.

Notificações e auditoria

• Convites de time.
• Encerramento de vínculo.
• Participações convidadas para confirmar.
• Retificação que altera stats.
• Mudanças de privacidade registradas em auditoria.

API relacionada

Método	Rota	Acesso	Finalidade
POST	/api/v1/players/activate	Autenticado	Ativar
GET	/api/v1/players/me	Jogador	Painel próprio
PATCH	/api/v1/players/me	Jogador	Editar
PATCH	/api/v1/players/me/privacy	Jogador	Privacidade
GET	/api/v1/players/:slug	Público	Perfil
GET	/api/v1/players/me/team-links	Jogador	Vínculos ativos/ex-times
GET	/api/v1/players/me/invites	Jogador	Convites
POST	/api/v1/team-player-links/:linkId/respond	Jogador	Aceitar/rejeitar (IS-MVP-05.2; rota compartilhada com SPEC-API-TEAM-TORCIDA-001, mesmo recurso do endpoint de encerrar vínculo — ver nota abaixo)
POST	/api/v1/team-player-links/:linkId/end	Jogador (vínculo ativo) ou team.manageSquad	Encerrar vínculo (IS-MVP-05.2; mesma rota)
GET	/api/v1/players/me/guest-confirmations	Jogador	Pendências
POST	/api/v1/players/me/guest-confirmations/:id/confirm	Jogador	Confirmar
GET	/api/v1/players/:id/stats	Público	Stats

IS-MVP-05.2: aceitar/rejeitar convite e encerrar vínculo reutilizam o recurso team-player-links já parcialmente implementado por IS-MVP-04.4 (SPEC-API-TEAM-TORCIDA-001), em vez de duplicar a mutação sob /players/me/invites/:id/.... accept aciona a transição accept_team_link (→ active) a partir de available/inactive/active; apenas retired é bloqueado explicitamente (PLAYER_RETIRED).

Contratos compartilhados

• PlayerProfileEntity
• PublicPlayerDto
• PlayerPrivateDto
• PlayerPrivacyDto
• PlayerStatsDto
• ActivatePlayerRequest/Response
• RespondTeamInviteRequest
• GuestConfirmationDto

Requisitos de UX

• Perfil público é vitrine esportiva, não rede social de influencer.
• Painel próprio mostra completude, convites, vínculos, confirmações e privacidade.
• Stats podem ser filtradas por time, categoria, campeonato e período.
• Status “livre” só aparece se explicitamente público.

Comportamento dos mocks

• Perfis completos, incompletos, privados, available e retired.
• Convites pending/expired.
• Guest confirmations confirmáveis e contestadas.
• Stats alteradas somente por partidas validadas.

Critérios de aceite

• Um perfil por usuário.
• Privacidade aplicada em busca, página e cards.
• Aceite de convite ativa link.
• Guest confirmation não duplica histórico.
• Stats contestadas não consolidam.

Testes obrigatórios

• Ativação idempotente.
• Privacidade por campo.
• Busca pública.
• Convites.
• Encerramento de vínculo.
• Confirmação e disputa de guest.
• Stats validadas.

Pós-MVP

• Vídeos e highlights.
• Scouting e avaliações.
• Agenda avançada por raio.
• Portfólio premium.

Decisões registradas

• Jogador é papel de usuário, não entidade gerenciável.
• Perfil incompleto é permitido com aviso.
• Disponibilidade e agenda são opt-in.
• Guest conta para time/partida, mas não para histórico pessoal até confirmação.

Machine summary

spec: SPEC-DOMAIN-PLAYER-001
domain: Jogadores
must_preserve:
  - Um usuário possui no máximo um PlayerProfile principal.
  - Perfil pode existir incompleto, mas deve sinalizar campos faltantes.
  - Stats públicas usam apenas partidas validadas.
  - Guest não confirmado não cria histórico público pessoal.
  - Jogador controla exibição de contatos, ex-times, times atuais, stats e disponibilidade.
  - CPF/documentos nunca são públicos.
  - Jogador pode encerrar vínculo ativo, preservando histórico.
touches:
  - contracts
  - mocks
  - api
  - frontend
  - backend
  - tests
  - documentation