Ajuste rotas, Menus, Layout, Permissãoes UserRoleGuard

src/composables/useAuth.js

@@ -1,3 +1,50 @@
+/**
+ * ---------------------------------------------------------
+ * useAuth()
+ * ---------------------------------------------------------
+ *
+ * Stack do projeto:
+ * - Vue 3 (Composition API)
+ * - PrimeVue (UI)
+ * - Supabase (Auth + Database)
+ *
+ * Responsabilidade:
+ * Camada global de AUTENTICAÇÃO baseada no Supabase.
+ *
+ * O que este composable faz:
+ * - Obtém a sessão atual do Supabase (auth.getSession)
+ * - Mantém o estado reativo do usuário autenticado
+ * - Escuta mudanças de autenticação (login, logout, refresh de token)
+ * - Expõe apenas a identidade do usuário (user)
+ *
+ * O que ele NÃO faz:
+ * - Não controla permissões
+ * - Não valida roles
+ * - Não decide acesso a telas ou botões
+ * - Não aplica regras de plano (Free/Pro)
+ *
+ * Conceito arquitetural:
+ * Este arquivo trata apenas de IDENTIDADE (Auth).
+ *
+ * Auth  → "Quem é o usuário autenticado?"
+ * AuthZ → "O que esse usuário pode acessar ou executar?"
+ *
+ * A AUTORIZAÇÃO deve ser tratada em outra camada,
+ * como por exemplo:
+ * - useAuthz()
+ * - tenantStore (membership.role)
+ * - entitlementsStore (features do plano)
+ *
+ * Observação importante:
+ * O role do usuário NÃO vem do Supabase Auth.
+ * Ele é definido na tabela de membership (multi-tenant).
+ *
+ * Portanto:
+ * Nunca utilizar apenas `user` para controle de acesso.
+ *
+ * Esse composable é apenas a base de identidade do sistema.
+ */
+ 
 import { ref, onMounted } from 'vue'
 import { supabase } from '@/lib/supabase/client'