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

depends_on: SPEC-DOMAIN-AUTH-001

used_by: IS-MVP-04.6, IS-MVP-08.3, IS-MVP-14.3, IS-MVP-16.1

Gestão e permissões

Modelo de memberships, funções fixas, permissões positivas e responsabilidade principal por entidade.

Objetivo e limites

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

Incluído no MVP

• Entidades team, torcida, championship, field e service.
• Um primary_owner.
• Roles fixas e overrides manuais por usuário.
• Permissões positivas somadas.
• Convite e aceite.
• Máximo recomendado de 10 gestores.
• Audit log de ações sensíveis.

Fora do MVP

• Co-owners.
• Policies dinâmicas.
• Roles customizáveis salvas.
• Herança entre entidades.
• ABAC completo.

Atores e responsabilidades

Ator	Responsabilidade
Responsável principal	Controle total e propriedade.
Administrador	Gestão ampla, exceto ações exclusivas.
Gestores especializados	Financeiro, mídia, esportivo, elenco, eventos.
Visualizador	Leitura de gestão.
Convidado de gestão	Aceita/rejeita membership.
Operação	Recuperação e auditoria excepcional.

Conceitos canônicos

ManagementMembership

Relação user-entity com role e overrides.

ManagementRole

Template fixo de permissões.

PermissionKey

Ação granular, como team.manageSquad.

Primary Owner

Membership exclusiva e obrigatória.

Override

Adição ou remoção manual de permission key.

Invariantes

• Toda entidade gerenciável ativa possui exatamente um primary_owner.
• Primary owner possui todas as permissions e não pode ser negado por override.
• Membership pending não concede acesso.
• Permissões são avaliadas no backend.
• Usuário pode gerir múltiplas entidades.
• Jogador não é ManageableEntityType.
• Último full-access não deve ser removido sem confirmação e owner preservado.
• Convite expira e é idempotente.
• Ações exclusivas do owner não podem ser delegadas no MVP.

Estados

Estado	Significado	Visibilidade/efeito
pending	Convite enviado	Sem acesso.
active	Membership ativa	Acesso por role/overrides.
rejected	Convite rejeitado	Sem acesso.
expired	Prazo encerrado	Sem acesso.
revoked	Acesso removido	Histórico preservado.

Transições permitidas

Origem	Ação	Destino	Autoridade	Efeitos
—	invite	pending	Manager autorizado	Notifica convidado.
pending	accept	active	Convidado	Concede acesso.
pending	reject	rejected	Convidado	Registra.
pending	expire	expired	Job	Encerra.
active	update_role	active	Manager autorizado	Recalcula permissions.
active	revoke	revoked	Manager autorizado	Revoga imediatamente.
active owner	transfer_ownership	active new owner + active/revoked old	Primary owner	Transação atômica.

Permissões

Permission key	Quem recebe por padrão	Ação protegida	Auditoria
management.view	Viewer+	Abrir gestão	Não
management.manageManagers	Admin/Owner	Convidar/editar/remover	Sim
management.viewAudit	Admin/Owner e roles permitidas	Audit logs	Não
management.transferOwnership	Owner	Transferir ownership	Sim
management.deleteEntity	Owner	Excluir/encerrar conforme domínio	Sim

Fluxos funcionais

Convite

1. Gestor informa e-mail/contato ou seleciona usuário.
2. Escolhe role e optional overrides.
3. Sistema valida limite e permission.
4. Cria pending com expiração.
5. Usuário aceita e membership vira active.

Cálculo de permissão

1. Carrega active membership.
2. Se owner, concede tudo.
3. Caso contrário, carrega role template.
4. Soma grants manuais.
5. Remove denies manuais permitidos.
6. Valida status da entidade e contexto do recurso.

Transferência de ownership

1. Owner escolhe gestor active ou convida novo.
2. Confirma ação crítica.
3. Backend revalida autenticação recente.
4. Em transação, promove novo owner e rebaixa/revoga anterior conforme opção.
5. Registra auditoria e notifica todos.

Casos-limite e erros

Cenário	Comportamento esperado	Código/estado
Sem membership	Negar	PERMISSION_REQUIRED
Membership pending	Negar	MANAGEMENT_INVITE_PENDING
Remover owner	Bloquear	PRIMARY_OWNER_REQUIRED
11º gestor	Avisar/bloquear conforme limite configurado	MANAGER_LIMIT_REACHED
Override inválido para entidade	Rejeitar	INVALID_PERMISSION_KEY
Convite duplicado	Retornar existente ativo/pending	MANAGEMENT_INVITE_EXISTS

Privacidade e exposição pública

• DTO público nunca inclui memberships/permissions.
• Lista de gestores é privada, salvo nomes públicos definidos pela entidade.
• Audit log só aparece a usuários autorizados.
• Convite por e-mail não expõe existência de conta para terceiros.

Notificações e auditoria

• Convite, aceite, rejeição e expiração.
• Mudança de role/overrides.
• Revogação.
• Transferência de ownership.
• Ações críticas produzem AuditLog com actor, entity, action, before/after e requestId.

API relacionada

Método	Rota	Acesso	Finalidade
GET	/api/v1/management/my-entities	Autenticado	Entidades geridas
GET	/api/v1/management/:type/:id/managers	management.manageManagers/view	Listar
POST	/api/v1/management/:type/:id/managers/invite	management.manageManagers	Convidar
POST	/api/v1/management/invites/:id/respond	Convidado	Responder
PATCH	/api/v1/management/:type/:id/managers/:membershipId	management.manageManagers	Editar
DELETE	/api/v1/management/:type/:id/managers/:membershipId	management.manageManagers	Revogar
POST	/api/v1/management/:type/:id/transfer-primary-owner	Owner	Transferir
POST	/api/v1/permissions/check	Autenticado	Checar permission
GET	/api/v1/management/:type/:id/audit-logs	Permissão	Auditoria

Contratos compartilhados

• ManageableEntityType
• ManagementMembershipDto
• ManagementRole
• PermissionKey
• PermissionOverrideDto
• InviteManagerRequest
• TransferPrimaryOwnerRequest
• PermissionCheckResponse
• AuditLogDto

Requisitos de UX

• Minha Gestão lista entidades agrupadas por tipo; não vira dashboard geral pesado.
• Ações sem permission ficam visíveis e desabilitadas quando ajudam descoberta.
• Editor de role mostra resumo legível, não lista crua de keys por padrão.
• Ownership tem confirmação extra e explica irreversibilidade.

Comportamento dos mocks

• Usuário com múltiplas memberships.
• Roles e overrides.
• Convites pending/expired.
• Revogação imediata.
• Owner transfer in-memory.

Critérios de aceite

• Backend é autoridade.
• Owner único e obrigatório.
• Roles fixas com overrides.
• Convite exige aceite.
• Jogador não é gerenciável.
• Audit log em ações críticas.

Testes obrigatórios

• Permission resolution.
• Overrides.
• Invite lifecycle.
• Manager limit.
• Owner transfer atomic.
• Revoke.
• Status da entidade.

Pós-MVP

• Co-owners.
• Roles customizadas.
• Policies condicionais.
• Delegação temporária.

Decisões registradas

• Modelo inspirado em GitHub: funções fixas e ajustes manuais.
• Permissões positivas somam; restrições via override.
• Máximo recomendado 10.
• Um primary owner por entidade.

Machine summary

spec: SPEC-DOMAIN-PERMISSION-001
domain: Gestão e permissões
must_preserve:
  - Toda entidade gerenciável ativa possui exatamente um primary_owner.
  - Primary owner possui todas as permissions e não pode ser negado por override.
  - Membership pending não concede acesso.
  - Permissões são avaliadas no backend.
  - Usuário pode gerir múltiplas entidades.
  - Jogador não é ManageableEntityType.
  - Último full-access não deve ser removido sem confirmação e owner preservado.
  - Convite expira e é idempotente.
touches:
  - contracts
  - mocks
  - api
  - frontend
  - backend
  - tests
  - documentation