Status: Approved · v2 · SPEC-API-MANAGEMENT-001

depends_on: SPEC-DOMAIN-PERMISSION-001, SPEC-API-OVERVIEW-001

used_by: IS-MVP-04.6, IS-MVP-08.3, IS-MVP-15.2

API de gestão, permissões, auditoria e assets

Infraestrutura transversal para memberships, roles, overrides, owner transfer e uploads seguros.

Princípios e padrões

• Base path /api/v1; JSON UTF-8; chaves em camelCase.
• Toda resposta usa ApiResponse<T> com ok, data|error e meta contendo requestId e timestamp.
• IDs são strings opacas; datas são ISO-8601 UTC; dinheiro é inteiro em centavos com moeda BRL.
• Listas usam page e pageSize no MVP; default 20, máximo 100; metadados ficam em meta.pagination.
• Endpoints públicos usam DTOs públicos específicos; entidades internas, memberships, saldos e dados privados nunca vazam.
• Erros de domínio são estáveis e acionáveis; stack traces e detalhes internos não são retornados.
• Alterações sensíveis usam Idempotency-Key, confirmação recente quando necessário e audit log.
• Uploads usam fluxo presigned; o backend valida propósito, MIME, tamanho e ownership antes de confirmar o asset.

Endpoints

Método	Rota	Acesso	Request	Response	Regras principais
GET	/management/my-entities	Autenticado	ManagedEntitiesQuery	ManagedEntitiesResponse	Agrupa team/torcida/championship/field/service.
GET	/management/:entityType/:entityId/managers	manageManagers/viewManagers	—	ManagersResponse	Role, overrides e status autorizados.
POST	/management/:entityType/:entityId/managers/invite	manageManagers	InviteManagerRequest	ManagerInviteResponse	Até limite.
POST	/management/invites/:inviteId/respond	Usuário alvo	RespondManagerInviteRequest	ManagementMembershipResponse	Accept/reject.
PATCH	/management/:entityType/:entityId/managers/:membershipId	manageManagers	UpdateManagerAccessRequest	ManagementMembershipResponse	Role + overrides.
DELETE	/management/:entityType/:entityId/managers/:membershipId	manageManagers	RemoveManagerRequest	OperationResponse	Não remove owner/último full.
POST	/management/:entityType/:entityId/transfer-primary-owner	primary_owner	TransferOwnerRequest	TransferOwnerResponse	Auth recente e confirmação.
GET	/permissions/catalog	Autenticado	entityType	PermissionCatalogResponse	Keys/labels/grupos.
POST	/permissions/check	Autenticado	PermissionCheckRequest	PermissionCheckResponse	Uso diagnóstico; não substitui guard.
GET	/management/:entityType/:entityId/audit-logs	viewAudit	AuditQuery	AuditLogsResponse	Privado e paginado.
POST	/uploads/presign	Autenticado	CreateUploadIntentRequest	CreateUploadIntentResponse	Purpose/entity ownership.
POST	/uploads/:assetId/confirm	Autenticado	ConfirmUploadRequest	AssetResponse	Verifica object metadata.
DELETE	/assets/:assetId	Asset owner/permission	DeleteAssetRequest	OperationResponse	Soft delete/detach policy.

Autenticação e autorização

• Um primary_owner por entidade.
• Permission positiva efetiva = role grants + manual grants − manual revokes.
• Acesso sempre revalidado no momento da ação.
• Uploads vinculados a purpose/entity e permission.

Erros de domínio

Código	HTTP	Quando ocorre	Ação esperada no cliente
PRIMARY_OWNER_REQUIRED	409	Operação deixaria sem owner	Transferir.
LAST_FULL_MANAGER	409	Remoção deixaria risco configurado	Revisar.
MANAGEMENT_INVITE_EXPIRED	410	Invite expirado	Novo invite.
UNKNOWN_PERMISSION	422	Key inválida para entity type	Usar catálogo.
UPLOAD_TYPE_NOT_ALLOWED	422	MIME/purpose inválido	Trocar arquivo.
UPLOAD_TOO_LARGE	413	Tamanho excede purpose	Comprimir.
ASSET_OWNERSHIP_MISMATCH	403	Asset de outro contexto	Bloquear.

Idempotência e concorrência

• Invite, transfer owner e upload confirmation idempotentes.
• Membership update usa version para evitar sobrescrita.

Auditoria e efeitos colaterais

• Toda mudança de acesso/owner e asset attach/delete auditada.
• Invites geram notifications.

Exemplos

accessUpdate

{
  "role": "media_manager",
  "grantPermissions": [
    "team.manageIdentity"
  ],
  "revokePermissions": [
    "team.publishPosts"
  ],
  "version": 3
}

presign

{
  "purpose": "team_logo",
  "entity": {
    "type": "team",
    "id": "team_001"
  },
  "fileName": "escudo.png",
  "mimeType": "image/png",
  "sizeBytes": 483210
}

Mocks

• Roles e permissions fixtures completas.
• Revoked membership muda comportamento imediatamente.
• Uploads fake retornam URL local segura.

Testes obrigatórios

• Owner invariants.
• Permission merge.
• Revocation immediate.
• Invite lifecycle.
• Upload MIME/size/ownership.
• Audit privacy.

Critérios de aceite

• Todas entidades gerenciáveis cobertas.
• Jogador excluído de ManageableEntityType.
• UI consegue explicar access sem confiar no check endpoint.

Machine summary

spec: SPEC-API-MANAGEMENT-001
api_group: API de gestão, permissões, auditoria e assets
base_path: /api/v1
response_envelope: ApiResponse<T>
ids: string
dates: ISO-8601
money: integer_cents