forlogic-core 1.4.15 → 1.5.1

package/dist/docs/templates/permission-check-hook.tsx

@@ -0,0 +1,275 @@
+/**
+ * TEMPLATE: Hook de Verificação de Permissão
+ * 📚 Detalhes: Consulte docs/FOR_AI.md
+ */
+
+import { usePermissionQuery } from 'forlogic-core';
+import { useAuth } from 'forlogic-core';
+import { supabase } from '@/integrations/supabase/client';
+
+// ============= EXEMPLO 1: Verificação Simples =============
+
+/**
+ * Hook para verificar se o usuário tem acesso a uma funcionalidade específica
+ */
+export const useFeatureAccess = () => {
+  const { user, selectedUnit } = useAuth();
+
+  return usePermissionQuery({
+    key: 'feature-access',
+    enabled: !!user && !!selectedUnit,
+    checkFn: async () => {
+      const { data } = await supabase
+        .from('feature_permissions')
+        .select('has_access')
+        .eq('unit_alias', selectedUnit!.alias)
+        .eq('feature_name', 'my-feature')
+        .single();
+      
+      return data?.has_access || false;
+    },
+    staleTime: 30 * 60 * 1000,  // 30 minutos
+    gcTime: 35 * 60 * 1000
+  });
+};
+
+// ============= EXEMPLO 2: Verificação com Service =============
+
+/**
+ * Service para centralizar lógica de permissões
+ */
+class PermissionService {
+  async checkFeatureAccess(alias: string, feature: string): Promise<boolean> {
+    const { data, error } = await supabase
+      .rpc('check_feature_permission', {
+        p_alias: alias,
+        p_feature: feature
+      });
+
+    if (error) {
+      console.error('Permission check error:', error);
+      return false;
+    }
+
+    return data || false;
+  }
+}
+
+const permissionService = new PermissionService();
+
+/**
+ * Hook usando service
+ */
+export const useAdvancedFeatureAccess = (featureName: string) => {
+  const { user, selectedUnit } = useAuth();
+
+  return usePermissionQuery({
+    key: `feature-access-${featureName}`,
+    enabled: !!user && !!selectedUnit,
+    checkFn: () => permissionService.checkFeatureAccess(
+      selectedUnit!.alias,
+      featureName
+    ),
+    staleTime: 30 * 60 * 1000,
+    gcTime: 35 * 60 * 1000
+  });
+};
+
+// ============= EXEMPLO 3: Múltiplas Permissões =============
+
+/**
+ * Hook para verificar múltiplas permissões de uma vez
+ */
+export const useMultiplePermissions = (features: string[]) => {
+  const { user, selectedUnit } = useAuth();
+
+  return usePermissionQuery({
+    key: `multi-permissions-${features.join('-')}`,
+    enabled: !!user && !!selectedUnit && features.length > 0,
+    checkFn: async () => {
+      const { data } = await supabase
+        .from('feature_permissions')
+        .select('feature_name, has_access')
+        .eq('unit_alias', selectedUnit!.alias)
+        .in('feature_name', features);
+
+      // Retorna true se todas as features têm acesso
+      return data?.every(item => item.has_access) || false;
+    },
+    staleTime: 30 * 60 * 1000,
+    gcTime: 35 * 60 * 1000
+  });
+};
+
+// ============= USO NOS COMPONENTES =============
+
+/**
+ * Exemplo 1: Proteger componente inteiro
+ */
+function ProtectedComponent() {
+  const { data: hasAccess, isLoading } = useFeatureAccess();
+
+  if (isLoading) {
+    return <div>Verificando permissões...</div>;
+  }
+
+  if (!hasAccess) {
+    return <div>Acesso negado</div>;
+  }
+
+  return <div>Conteúdo protegido</div>;
+}
+
+/**
+ * Exemplo 2: Proteger ação específica
+ */
+function ComponentWithProtectedAction() {
+  const { data: hasAccess } = useFeatureAccess();
+
+  const handleSensitiveAction = () => {
+    if (!hasAccess) {
+      toast.error('Você não tem permissão para esta ação');
+      return;
+    }
+    
+    // Executar ação
+  };
+
+  return (
+    <button 
+      onClick={handleSensitiveAction}
+      disabled={!hasAccess}
+    >
+      Ação Sensível
+    </button>
+  );
+}
+
+/**
+ * Exemplo 3: Condicional na UI
+ */
+function ConditionalUI() {
+  const { data: hasAccess } = useFeatureAccess();
+
+  return (
+    <div>
+      <h1>Dashboard</h1>
+      
+      {/* Sempre visível */}
+      <div>Conteúdo público</div>
+      
+      {/* Condicional */}
+      {hasAccess && (
+        <div>Conteúdo exclusivo</div>
+      )}
+    </div>
+  );
+}
+
+// ============= INTEGRAÇÃO COM SIDEBAR =============
+
+import type { SidebarConfig } from 'forlogic-core';
+import { Settings, Package, Users } from 'lucide-react';
+
+/**
+ * Configuração da sidebar com itens condicionais
+ */
+export const sidebarConfig: SidebarConfig = {
+  appName: 'Minha Aplicação',
+  navigation: [
+    // Item sempre visível
+    {
+      label: 'Dashboard',
+      path: '/dashboard',
+      icon: Settings,
+    },
+    // Item condicional com hook
+    {
+      label: 'Gestão',
+      path: '/management',
+      icon: Package,
+      useAccessHook: useFeatureAccess  // Hook de verificação
+    },
+    // Outro item condicional
+    {
+      label: 'Usuários',
+      path: '/users',
+      icon: Users,
+      useAccessHook: () => useAdvancedFeatureAccess('users-management')
+    }
+  ]
+};
+
+// ============= CONFIGURAÇÃO DE CACHE =============
+
+/**
+ * Recomendações de tempo de cache por tipo de permissão
+ */
+
+// Permissões raramente alteradas (ex: roles, perfis)
+export const useRoleCheck = () => {
+  return usePermissionQuery({
+    // ...
+    staleTime: 30 * 60 * 1000,  // 30 minutos
+    gcTime: 60 * 60 * 1000      // 1 hora
+  });
+};
+
+// Permissões dinâmicas (ex: acesso temporário)
+export const useDynamicPermission = () => {
+  return usePermissionQuery({
+    // ...
+    staleTime: 5 * 60 * 1000,   // 5 minutos
+    gcTime: 10 * 60 * 1000      // 10 minutos
+  });
+};
+
+// Verificações críticas (ex: transações financeiras)
+export const useCriticalPermission = () => {
+  return usePermissionQuery({
+    // ...
+    staleTime: 0,               // Sem cache
+    gcTime: 0                   // Sem garbage collection
+  });
+};
+
+// ============= INVALIDAÇÃO MANUAL (RARAMENTE NECESSÁRIA) =============
+
+import { useQueryClient } from '@tanstack/react-query';
+
+/**
+ * Exemplo de invalidação manual (use apenas quando necessário)
+ */
+function AdminPanel() {
+  const queryClient = useQueryClient();
+
+  const handlePermissionUpdate = async () => {
+    // Atualizar permissão no backend
+    await updatePermission();
+    
+    // Invalidar cache específico
+    queryClient.invalidateQueries({
+      queryKey: ['permission', 'feature-access']
+    });
+  };
+
+  return <button onClick={handlePermissionUpdate}>Atualizar Permissão</button>;
+}
+
+// ============= BOAS PRÁTICAS =============
+
+/**
+ * ✅ FAÇA:
+ * - Use staleTime apropriado para cada tipo de permissão
+ * - Sempre habilite apenas quando user e selectedUnit existirem
+ * - Trate loading states nos componentes
+ * - Use keys descritivas e únicas
+ * - Centralize lógica em services quando complexa
+ * 
+ * ❌ NÃO FAÇA:
+ * - Não use staleTime muito longo para permissões críticas
+ * - Não esqueça de desabilitar quando dependências faltam
+ * - Não ignore estados de loading
+ * - Não invalidate manualmente sem necessidade (AuthContext já faz)
+ * - Não faça verificações síncronas de permissão
+ */

package/dist/docs/templates/qualiex-config.ts

@@ -0,0 +1,137 @@
+// ============= CONFIGURAÇÃO INICIAL QUALIEX =============
+// Copie este código para o arquivo principal da aplicação (main.tsx ou App.tsx)
+
+import { setQualiexConfig } from 'forlogic-core';
+
+// ============= 1. VARIÁVEIS DE AMBIENTE =============
+// Adicione no arquivo .env do projeto:
+/*
+VITE_QUALIEX_API_URL=https://common-v4-api.qualiex.com
+*/
+
+// Configuração da integração
+// Execute no início da aplicação (antes de renderizar componentes)
+
+export function setupQualiexIntegration() {
+  setQualiexConfig({
+    // Enriquecimento automático de entidades com responsible_name
+    enableUserEnrichment: true,
+    
+    // Habilitar API de usuários Qualiex
+    enableUsersApi: true,
+  });
+}
+
+// ============= 3. USO NO MAIN.TSX =============
+/*
+import { StrictMode } from 'react';
+import { createRoot } from 'react-dom/client';
+import { setupQualiexIntegration } from './config/qualiexConfig';
+import App from './App';
+
+// Configurar Qualiex ANTES de renderizar
+setupQualiexIntegration();
+
+createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <App />
+  </StrictMode>
+);
+*/
+
+// ============= 4. EXPLICAÇÃO DAS OPÇÕES =============
+
+/**
+ * enableUserEnrichment: boolean
+ * 
+ * Quando true, o QualiexEnrichmentService adiciona automaticamente
+ * o campo `responsible_name` às entidades que possuem `id_user`.
+ * 
+ * Exemplo:
+ * const tasks = await taskService.getAll();
+ * // Se enableUserEnrichment: true
+ * // tasks[0] = { id: '1', title: 'Tarefa', id_user: 'user-123', responsible_name: 'João Silva' }
+ */
+
+/**
+ * enableUsersApi: boolean
+ * 
+ * Quando true, habilita chamadas à API de usuários Qualiex.
+ * Necessário para usar useQualiexUsers e QualiexUserField.
+ * 
+ * Se false, useQualiexUsers não fará requisições.
+ */
+
+// ============= 5. EXEMPLO DE CONFIGURAÇÃO CONDICIONAL =============
+// Configure baseado no ambiente ou feature flags
+
+export function setupQualiexIntegrationConditional() {
+  const isProduction = import.meta.env.PROD;
+  const hasQualiexUrl = !!import.meta.env.VITE_QUALIEX_API_URL;
+
+  setQualiexConfig({
+    // Habilitar enriquecimento apenas em produção
+    enableUserEnrichment: isProduction && hasQualiexUrl,
+    
+    // Habilitar API sempre que URL estiver configurada
+    enableUsersApi: hasQualiexUrl,
+  });
+}
+
+// ============= 6. VALIDAÇÃO DA CONFIGURAÇÃO =============
+// Helper para validar se Qualiex está configurado corretamente
+
+export function validateQualiexSetup() {
+  const qualiexUrl = import.meta.env.VITE_QUALIEX_API_URL;
+
+  if (!qualiexUrl) {
+    console.warn(
+      '⚠️ VITE_QUALIEX_API_URL não configurado. ' +
+      'Integração Qualiex não funcionará.'
+    );
+    return false;
+  }
+
+  console.log('✅ Integração Qualiex configurada:', qualiexUrl);
+  return true;
+}
+
+// ============= 7. DESABILITAR INTEGRAÇÃO =============
+// Para desabilitar completamente a integração Qualiex
+
+export function disableQualiexIntegration() {
+  setQualiexConfig({
+    enableUserEnrichment: false,
+    enableUsersApi: false,
+  });
+}
+
+// ============= RESUMO =============
+/*
+PASSOS PARA CONFIGURAR:
+
+1. Adicionar no .env:
+   VITE_QUALIEX_API_URL=https://common-v4-api.qualiex.com
+
+2. No main.tsx, antes de renderizar:
+   import { setQualiexConfig } from 'forlogic-core';
+   
+   setQualiexConfig({
+     enableUserEnrichment: true,
+     enableUsersApi: true,
+   });
+
+3. Usar nos componentes:
+   import { QualiexUserField, useQualiexUsers } from 'forlogic-core';
+
+⚠️ IMPORTANTE:
+- setQualiexConfig deve ser chamado ANTES de usar componentes Qualiex
+- VITE_QUALIEX_API_URL deve existir no .env
+- A autenticação é feita automaticamente via TokenManager
+- O header un-alias é adicionado automaticamente
+
+✅ VERIFICAR SE ESTÁ FUNCIONANDO:
+- useQualiexUsers deve retornar lista de usuários
+- QualiexUserField deve mostrar loading e depois lista
+- Console não deve mostrar erros 401/403
+*/