Matriz de Permissões e Controle de Acesso (RBAC & ABAC)

Esta documentação resume a visão geral de quem pode o quê dentro da aplicação, tanto a nível global (Plataforma) quanto a nível de comunidade (Multi-tenant).

---

🏆 Visão Geral de Níveis de Acesso

Nível / Papel	Escopo	Descrição
Superuser / Staff (is_staff=True)	Global (Plataforma)	Acesso total ao Painel Admin Global (apps/admin e /admin/). Pode gerenciar qualquer usuário, ativar/desativar contas e conceder acesso staff.
Community Admin (Role.ADMIN)	Comunidade	Dono/Administrador da comunidade. Possui controle total de configurações, estrutura de espaços e gestão de membros da sua comunidade.
Community Moderator (Role.MODERATOR)	Comunidade	Moderador da comunidade. Pode apagar posts/comentários de terceiros e mutar/banir membros comuns.
Space Moderator (SpaceModerator)	Espaço Específico	Membro com privilégio de moderação de conteúdo restrito a um determinado Espaço (ex: canal "Design").
Visitante / Deslogado (AnonymousUser)	Público	Usuário não autenticado. Possui acesso público ao catálogo de cursos (/courses), aos detalhes do curso (/courses/$courseId), e à degustação de aulas gratuitas (free_lesson). Aulas trancadas e ações privadas redirecionam para o funil de vendas (Login/Cadastro/Checkout).
Regular Member (Role.MEMBER)	Comunidade	Membro comum da comunidade. Pode ler, publicar e interagir nos espaços em que tem acesso.
Muted Member (muted_until > now)	Comunidade	Membro temporariamente silenciado. Pode ler conteúdos, mas todas as ações de escrita (posts/comentários) são bloqueadas.
Banned Member (Status.BANNED)	Comunidade	Membro banido. Bloqueado de qualquer acesso na comunidade.

---

📊 Matriz Detalhada de Permissões por Funcionalidade

1. Painel Admin Global (apps/admin)

Ação	Membro	Moderador	Admin Comunidade	Staff Global (is_staff)
Acessar /users e Painel Admin	❌	❌	❌	✅
Ver lista de todos os usuários	❌	❌	❌	✅
Ativar / Desativar conta de usuário	❌	❌	❌	✅
Tornar usuário Admin Global (is_staff)	❌	❌	❌	✅
Excluir conta de usuário da plataforma	❌	❌	❌	✅

---

2. Gestão de Comunidade e Membros

Ação	Membro	Moderador	Admin Comunidade	Staff Global
Alterar Nome/Branding da Comunidade	❌	❌	✅	✅
Mutar / Desmutar Membro Comum (MEMBER)	❌	✅	✅	✅
Banir / Desbanir Membro Comum (MEMBER)	❌	✅	✅	✅
Mutar / Banir outro Moderador ou Admin	❌	❌	✅	✅
Promover Membro a Moderador / Admin	❌	❌	✅	✅
Mutar / Banir a si mesmo	❌	❌	❌	❌

---

3. Estrutura de Espaços e Containers

Ação	Membro	Moderador	Admin Comunidade	Staff Global
Criar / Editar / Deletar Espaços (Spaces)	❌	✅	✅	✅
Criar / Editar / Deletar Grupos de Espaços	❌	✅	✅	✅
Definir Moderadores de Espaço (SpaceModerator)	❌	❌	✅	✅
Acessar Espaços Privados (Membros permitidos)	❌ (a menos que convidado)	❌ (a menos que convidado)	✅	✅

---

4. Conteúdo (Posts, Comentários e Reações)

Ação	Membro Ativo	Membro Mutado	Moderador de Espaço	Moderador Comunidade	Admin
Ler conteúdos em Espaço acessível	✅	✅	✅	✅	✅
Criar novo Post / Comentário	✅	❌ (403 Muted)	✅	✅	✅
Editar / Deletar o PRÓPRIO conteúdo	✅	❌ (403 Muted)	✅	✅	✅
Deletar conteúdo DE TERCEIROS	❌	❌	✅ (no seu espaço)	✅	✅
Trancar Post (Bloquear novos comentários)	❌	❌	✅ (no seu espaço)	✅	✅
Comentar em Post Trancado	❌	❌	✅ (no seu espaço)	✅	✅

---

5. Cursos e Degustação Pública (Funil de Vendas)

Ação	Visitante (Deslogado)	Membro Sem Curso	Aluno / Comprador	Staff / Admin
Acessar Catálogo /courses e Detalhes do Curso	✅	✅	✅	✅
Ver lista completa de aulas e estrutura de seções	✅	✅	✅	✅
Assistir Aulas Liberadas / Gratuitas (free_lesson)	✅	✅	✅	✅
Assistir Aulas Fechadas / Pagas	❌ (Exibe Funil/Paywall)	❌ (Exibe Paywall)	✅	✅
Marcar Progresso de Aula (LessonProgress)	❌ (Redireciona Login)	✅	✅	✅
Fazer Checkout / Comprar Curso	✅ (Redireciona Login/Reg)	✅	✅	✅
Baixar Anexos de Aulas Gratuitas (free_lesson)	✅ (PDF Carimbado como Visitante)	✅ (PDF Carimbado com Dados do Membro)	✅ (PDF Carimbado com Dados do Membro)	✅
Baixar Anexos de Aulas Fechadas/Pagas	❌ (403 Bloqueado)	❌ (403 Exibe Paywall)	✅ (PDF Carimbado com Nome/E-mail/ID)	✅

---

🔎 Onde essas regras estão implementadas no código Backend?

Boas práticas (sempre seguir): conteúdo de Space nunca é liberado só por visible_to. Todo endpoint que retorna conteúdo deve usar um gate de acesso — accessible_to, _resolve_accessible_space, ou visible_content_qs + resolve_accessible_object. A guarda estrutural StructuralAccessGuardTests falha o build se isso for violado (ver regra 0 do CLAUDE.md e ADR-0010).

1. backend/apps/communities/permissions.py:

   • RequiresActiveMembership: Bloqueia membros BANNED.
   • CanModerateMembership: Valida quem pode banir/mutar quem.

2. backend/apps/spaces/permissions.py:

   • HasSpaceAccess: Valida acesso a espaços públicos/privados.
   • IsAuthorOrModerator: Valida edição/deleção de posts e comentários.
   • IsAdminOrModeratorForWrite: Valida criação/edição de estrutura de espaços.
   • IsNotMuted: Bloqueia ações de escrita de membros mutados.
   • visible_content_qs(membership, model) + resolve_accessible_object(membership, qs, pk): gates de conteúdo por objeto (404 para invisível/cross-community, 403 para visível-mas-inacessível). Usar em todo lookup de conteúdo.

3. backend/apps/headless/views.py — BFF headless:

   • _resolve_accessible_space(membership, space_id): gate de space único (404/403).
   • <Modelo>.objects.accessible_to(membership): queries cross-space fail-closed.
   • Permissions reutilizadas do /v1: IsAuthorOrModerator, IsAdminOrModerator, IsNotMuted, IsNotLocked (ex.: convites — invitation_links listar/criar/deletar é só admin/moderador).
   • CourseLessonDetailView: única allowlist — serve o stub locked=True (sem conteúdo) para quem não tem acesso.

4. backend/apps/media/security.py e LessonAttachmentDownloadView:

   • Bloqueio de acesso direto ao bucket S3/MinIO via get_presigned_download_url.
   • Injeção dinâmica de marca d'água anti-pirataria (apply_pdf_watermark) em arquivos PDF com Nome, E-mail, ID e Data/Hora do usuário.

5. Testes que impõem as regras (CI):

   • backend/apps/headless/tests/test_visibility_contracts.py — contrato de visibilidade/accesso (outsider/insider).
   • backend/apps/headless/tests/test_headless_access_regressions.py::StructuralAccessGuardTests — varredura de código-fonte que falha se um get_object_or_404 de modelo de conteúdo aparecer sem gate.