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

depends_on: SPEC-DOMAIN-TERRITORY-001, SPEC-DOMAIN-PERMISSION-001

used_by: IS-MVP-01.7, IS-MVP-13.2, IS-MVP-13.3

Serviços e prestadores

Presença pública para empresas/equipes/profissionais do ecossistema, com contato externo, portfólio e vínculos a eventos.

Objetivo e limites

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

Incluído no MVP

• Service gerenciável.
• Tipos arbitragem, foto/vídeo, design/mídia, uniformes, artigos e genérico.
• Zero ou vários providers.
• Provider cadastrado ou não cadastrado.
• Portfólio/catálogo simples.
• Contato externo; sem contratação interna.
• Vínculo a partidas/eventos.

Fora do MVP

• Marketplace.
• Pagamento/escrow.
• Avaliações.
• Agenda/reserva.
• Comissões.

Atores e responsabilidades

Ator	Responsabilidade
Visitante	Pesquisa serviço e entra em contato externamente.
Gestor de serviço	Administra página, providers e portfólio.
Prestador cadastrado	Aceita vínculo que afeta perfil público.
Gestor de partida/campeonato	Vincula serviço/provider ao evento.
Operação	Trata reivindicação, anonimização e denúncias.

Conceitos canônicos

Service

Entidade pública/gerenciável.

Provider

Pessoa/profissional vinculado.

Showcase Item

Item de portfólio ou catálogo.

Event Link

Relação com partida/campeonato/evento.

Unclaimed Profile

Provider não cadastrado representado com dados mínimos.

Invariantes

• Criador de Service vira primary_owner.
• Service não possui wallet/sponsors no MVP.
• Provider cadastrado aceita vínculo antes de afetar perfil público.
• Provider não cadastrado não expõe documento/contato privado.
• Contratação ocorre fora do RaizFC no MVP.
• Event link não implica pagamento ou recomendação da plataforma.
• Anonimização preserva vínculo operacional mínimo quando necessário.

Estados

Estado	Significado	Visibilidade/efeito
active	Disponível	Público.
inactive	Sem operação atual	Aviso.
abandoned	Sem gestão	Claim.
suspended	Bloqueado	Limitado.
closed	Encerrado	Histórico.
duplicated_merged	Unificado	Redirect.

Transições permitidas

Origem	Ação	Destino	Autoridade	Efeitos
—	create	active	Autenticado	Owner.
active	deactivate	inactive	Owner/operação	Aviso.
active/inactive	mark_abandoned	abandoned	Operação	Claim.
abandoned	approve_claim	active	Operação	Owner.
any	merge	duplicated_merged	Operação	Redirect.

Permissões

Permission key	Quem recebe por padrão	Ação protegida	Auditoria
service.editProfile	Admin/Owner	Editar	Sim
service.manageProviders	Admin/Owner	Vincular providers	Sim
service.manageShowcase	Media/Admin	Portfólio	Sim
service.manageEventLinks	Events/Admin	Vínculos	Sim
service.manageManagers	Admin/Owner	Acessos	Sim

Fluxos funcionais

Criação

1. Usuário escolhe tipo, nome, distrito, descrição e contato.
2. Sistema verifica duplicidade.
3. Cria active e owner.

Vínculo de provider cadastrado

1. Gestor busca usuário/provider.
2. Cria requested.
3. Provider aceita/rejeita.
4. Aceite cria approved e pode aparecer publicamente.

Provider não cadastrado

1. Gestor registra nome de exibição e dados privados mínimos.
2. Provider aparece apenas no contexto permitido.
3. Pessoa pode solicitar revisão, claim ou anonimização.

Vínculo a evento

1. Gestor da partida solicita serviço/provider.
2. Parte responsável aprova/rejeita.
3. Approved aparece na página pública do evento conforme visibilidade.

Casos-limite e erros

Cenário	Comportamento esperado	Código/estado
Provider já vinculado	Evitar duplicidade	PROVIDER_LINK_EXISTS
Provider rejeita	Não publicar vínculo	PROVIDER_LINK_REJECTED
Service suspenso	Bloquear novos links	SERVICE_SUSPENDED
Solicitação de privacidade	Ocultar enquanto revisa quando necessário	PRIVACY_REQUEST_RECEIVED
Tipo incompatível	Permitir generic ou exigir ajuste	INVALID_SERVICE_TYPE

Privacidade e exposição pública

• CPF/documento nunca público.
• Contatos externos são publicados apenas quando autorizados.
• Provider não cadastrado pode pedir anonimização.
• Event link público mostra função/nome permitido, não dados privados.

Notificações e auditoria

• Convite/resposta de provider.
• Solicitação de event link.
• Claim/privacidade/denúncia.
• Mudanças de gestores.

API relacionada

Método	Rota	Acesso	Finalidade
POST	/api/v1/services	Autenticado	Criar
GET	/api/v1/services/:slug	Público	Página
PATCH	/api/v1/services/:id	service.editProfile	Editar
POST	/api/v1/services/:id/providers	service.manageProviders	Vincular
POST	/api/v1/provider-links/:id/respond	Provider	Responder
POST	/api/v1/services/:id/showcase	service.manageShowcase	Portfólio
POST	/api/v1/event-service-links	Contextual	Solicitar vínculo
POST	/api/v1/event-service-links/:id/respond	Contextual	Responder

Contratos compartilhados

• ServiceEntity
• PublicServiceDto
• ServiceManagementDto
• ServiceType
• ProviderDto
• ProviderLinkDto
• ShowcaseItemDto
• EventServiceLinkDto
• CreateServiceRequest

Requisitos de UX

• Página pública destaca tipo, território, portfólio, contato e eventos recentes.
• CTA é “Entrar em contato”, não “Contratar”.
• Perfil não reivindicado exibe caminho de revisão/anonimização.
• Gestão separa providers, portfólio e eventos.

Comportamento dos mocks

• Services de tipos variados.
• Providers registered/unregistered.
• Links requested/approved/rejected/contested.
• Privacy request.

Critérios de aceite

• Sem intermediação de contratação.
• Provider cadastrado aceita vínculo.
• Documento privado.
• Service gerenciável sem wallet.
• Event links auditáveis.

Testes obrigatórios

• Criação/duplicidade.
• Provider lifecycle.
• Privacy.
• Event link permissions.
• Public DTO.

Pós-MVP

• Marketplace, agenda, avaliações, pagamentos e comissões.

Decisões registradas

• Service pode representar empresa/equipe/loja/profissional.
• Provider é pessoa vinculada.
• Contato externo resolve o MVP.

Machine summary

spec: SPEC-DOMAIN-SERVICE-001
domain: Serviços e prestadores
must_preserve:
  - Criador de Service vira primary_owner.
  - Service não possui wallet/sponsors no MVP.
  - Provider cadastrado aceita vínculo antes de afetar perfil público.
  - Provider não cadastrado não expõe documento/contato privado.
  - Contratação ocorre fora do RaizFC no MVP.
  - Event link não implica pagamento ou recomendação da plataforma.
  - Anonimização preserva vínculo operacional mínimo quando necessário.
touches:
  - contracts
  - mocks
  - api
  - frontend
  - backend
  - tests
  - documentation