forlogic-core 1.5.0 → 1.5.2

package/dist/docs/TROUBLESHOOTING.md

@@ -0,0 +1,473 @@
+# 🚨 Troubleshooting - Soluções para Problemas Comuns
+
+Guia completo de solução de erros com a biblioteca ForLogic Core.
+
+---
+
+## 🔴 ERRO CRÍTICO: "isLoading is undefined" ou "manager is undefined"
+
+### Sintoma
+```
+TypeError: Cannot read properties of undefined (reading 'isLoading')
+TypeError: manager is undefined
+```
+
+### Causas
+1. **Ordem incorreta dos providers React**
+2. **Uso incorreto da API** (passar `service` ao invés de `manager` para `createCrudPage`)
+
+### ✅ Solução 1: Ordem Correta dos Providers
+
+A ordem dos providers é **CRÍTICA** para o funcionamento correto da biblioteca:
+
+```tsx
+// src/App.tsx - ORDEM CORRETA ✅
+import { ErrorBoundary } from 'forlogic-core';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { AuthProvider } from 'forlogic-core';
+import { BrowserRouter } from 'react-router-dom';
+
+const queryClient = new QueryClient();
+
+function App() {
+  return (
+    <ErrorBoundary>           {/* 1️⃣ PRIMEIRO */}
+      <QueryClientProvider client={queryClient}>  {/* 2️⃣ SEGUNDO */}
+        <AuthProvider>        {/* 3️⃣ TERCEIRO */}
+          <BrowserRouter>     {/* 4️⃣ QUARTO */}
+            {/* Suas rotas aqui */}
+          </BrowserRouter>
+        </AuthProvider>
+      </QueryClientProvider>
+    </ErrorBoundary>
+  );
+}
+```
+
+### ❌ Ordem Incorreta (Causa o Erro)
+```tsx
+// ❌ ERRADO - Causa "isLoading is undefined"
+<BrowserRouter>
+  <AuthProvider>
+    <QueryClientProvider client={queryClient}>
+      <ErrorBoundary>
+        {/* ... */}
+      </ErrorBoundary>
+    </QueryClientProvider>
+  </AuthProvider>
+</BrowserRouter>
+```
+
+### Por Que a Ordem Importa?
+
+1. **ErrorBoundary** precisa capturar erros de todos os providers
+2. **QueryClientProvider** precisa ter acesso ao contexto de auth para invalidar cache no logout
+3. **AuthProvider** depende do QueryClient para gerenciar estado de autenticação
+4. **BrowserRouter** precisa estar dentro dos providers para rotas funcionarem
+
+**Referência:** Ver "Quick Start → Seção 2" no [README.md](../README.md).
+
+### ✅ Solução 2: Use a API Corretamente
+
+`createCrudPage` SEMPRE espera `manager` (do `useCrudHook`), NUNCA `service` diretamente.
+
+#### ❌ ERRADO (Causa "isLoading is undefined"):
+```typescript
+const { service, useCrudHook } = createSimpleService<Entity>({ tableName: 'entities' });
+
+// ❌ ISTO NÃO FUNCIONA - createCrudPage não aceita service
+export const EntitiesPage = createCrudPage({ 
+  service,  // ❌ ERRADO - causa erro
+  config 
+});
+```
+
+#### ✅ CORRETO:
+```typescript
+const { service, useCrudHook } = createSimpleService<Entity>({ tableName: 'entities' });
+
+export const EntitiesPage = () => {
+  const manager = useCrudHook(); // ✅ Chamar hook dentro do componente
+
+  const handleSave = createSimpleSaveHandler(manager, createFn, updateFn);
+
+  const CrudPageComponent = createCrudPage({
+    manager, // ✅ Passar manager, NÃO service
+    config: {
+      entityName: 'Entity',
+      entityNamePlural: 'Entities',
+      columns: [...],
+      formSections: [...]
+    },
+    onSave: handleSave
+  });
+
+  return <CrudPageComponent />;
+};
+```
+
+**Referência:** Ver [AI_RULES.md](AI_RULES.md) → Regra #2 ou [templates/basic-crud-page.tsx](templates/basic-crud-page.tsx).
+
+**Por que isso acontece:**
+- `createCrudPage` internamente usa `manager.isLoading`, `manager.data`, etc.
+- Se você passa `service` ao invés de `manager`, essas propriedades não existem
+- Você DEVE chamar `useCrudHook()` dentro de um componente React para obter o `manager`
+
+---
+
+## 🔄 Cache Não Funciona / Queries Não Invalidam
+
+### Sintomas
+- Dados não atualizam ao trocar de unidade
+- Cache não limpa no logout
+- Dados antigos aparecem após login
+
+### Causa
+`QueryClientProvider` não tem acesso ao `AuthProvider` devido à ordem incorreta.
+
+### ✅ Solução
+Seguir a [ordem correta dos providers](#-solução-1-ordem-correta-dos-providers) acima.
+
+---
+
+## 🔐 LoginPage/CallbackPage Não Funcionam
+
+### Sintomas
+- Redirecionamento infinito
+- Página em branco
+- Erro "Cannot read properties of undefined"
+
+### Causas Comuns
+
+#### 1. Ordem Incorreta dos Providers ⚠️
+**Solução:** [Ver ordem correta](#-solução-1-ordem-correta-dos-providers)
+
+#### 2. Configuração de Rotas Incorreta
+```tsx
+// ❌ ERRADO
+<Route path="/auth/login" element={<LoginPage />} />
+<Route path="/auth/callback" element={<CallbackPage />} />
+
+// ✅ CORRETO
+<Route path="/login" element={<LoginPage />} />
+<Route path="/callback" element={<CallbackPage />} />
+```
+
+**Referência:** Ver [templates/app-layout.tsx](templates/app-layout.tsx) para estrutura completa de rotas de autenticação.
+
+#### 3. URLs Não Configuradas no Supabase
+Configure em: **Authentication → URL Configuration**
+- Site URL: `http://localhost:5173` (dev) ou `https://seudominio.com` (prod)
+- Redirect URLs: `http://localhost:5173/callback` e `https://seudominio.com/callback`
+
+#### 4. ProtectedRoute Envolvendo Páginas de Auth
+```tsx
+// ❌ ERRADO
+<Route path="/login" element={<ProtectedRoute><LoginPage /></ProtectedRoute>} />
+
+// ✅ CORRETO
+<Route path="/login" element={<LoginPage />} />
+```
+
+---
+
+## 📦 "Cannot find module 'forlogic-core'"
+
+### Sintoma
+```
+Error: Cannot find module 'forlogic-core'
+```
+
+### ✅ Solução
+```bash
+npm install forlogic-core
+```
+
+Verifique se está em `package.json`:
+```json
+{
+  "dependencies": {
+    "forlogic-core": "^x.x.x"
+  }
+}
+```
+
+---
+
+## 🔷 Erros de Tipo TypeScript
+
+### Sintoma
+```
+Type 'X' is not assignable to type 'Y'
+```
+
+### ✅ Solução: Use Named Imports
+```tsx
+// ❌ ERRADO
+import Button from 'forlogic-core';
+
+// ✅ CORRETO
+import { Button } from 'forlogic-core';
+```
+
+**Referência:** Ver [README.md](../README.md) → "Instalação".
+
+---
+
+## 📐 Sidebar Não Aparece
+
+### Causas Comuns
+
+#### 1. AppLayout Fora do AuthProvider
+```tsx
+// ❌ ERRADO
+<AppLayout>
+  <AuthProvider>
+    {/* ... */}
+  </AuthProvider>
+</AppLayout>
+
+// ✅ CORRETO
+<AuthProvider>
+  <AppLayout>
+    {/* ... */}
+  </AppLayout>
+</AuthProvider>
+```
+
+#### 2. sidebarConfig Não Passado
+```tsx
+// ❌ ERRADO
+<AppLayout>
+  <Routes>{/* ... */}</Routes>
+</AppLayout>
+
+// ✅ CORRETO
+import { sidebarConfig } from './config/sidebar';
+
+<AppLayout sidebarConfig={sidebarConfig}>
+  <Routes>{/* ... */}</Routes>
+</AppLayout>
+```
+
+**Referência:** Ver [templates/app-layout.tsx](templates/app-layout.tsx) para exemplo completo de layout.
+
+---
+
+## 📄 createCrudPage Não Renderiza
+
+### Sintomas
+- Página em branco
+- Erro de renderização
+
+### Causas Comuns
+
+#### 1. Service Mal Configurado
+```tsx
+// ❌ ERRADO - Falta generic type
+const service = createSimpleService('users');
+
+// ✅ CORRETO
+const service = createSimpleService<User>('users');
+```
+
+#### 2. Tipos de Campo Inconsistentes
+```tsx
+// ❌ ERRADO
+const config = generateCrudConfig<User>({
+  fields: {
+    age: { type: 'text' } // age é number, não text
+  }
+});
+
+// ✅ CORRETO
+const config = generateCrudConfig<User>({
+  fields: {
+    age: { type: 'number' }
+  }
+});
+```
+
+**Referência:** Ver [AI_RULES.md](AI_RULES.md) → Regra #2 e [templates/basic-crud-page.tsx](templates/basic-crud-page.tsx).
+
+---
+
+## 👤 useAuth Retorna null/undefined
+
+### Sintoma
+```tsx
+const { user } = useAuth(); // user é sempre null
+```
+
+### Causas Comuns
+
+#### 1. useAuth Fora do AuthProvider
+```tsx
+// ❌ ERRADO
+function App() {
+  const { user } = useAuth(); // ❌ Fora do AuthProvider
+  return <AuthProvider>{/* ... */}</AuthProvider>;
+}
+
+// ✅ CORRETO
+function AppContent() {
+  const { user } = useAuth(); // ✅ Dentro do AuthProvider
+  return <div>{user?.email}</div>;
+}
+
+function App() {
+  return (
+    <AuthProvider>
+      <AppContent />
+    </AuthProvider>
+  );
+}
+```
+
+#### 2. Ordem Incorreta dos Providers
+**Referência:** Ver [README.md](../README.md) → "Quick Start" → Seção 2 (Estrutura de Providers).
+
+---
+
+## 🔄 Update Cria Novo Registro ao Invés de Atualizar
+
+### Sintoma
+Ao editar e salvar um registro, é criado um novo registro ao invés de atualizar o existente.
+
+### Causa
+O `id` não está sendo preservado no payload de atualização.
+
+### ✅ Solução 1: Use createSimpleSaveHandler (Recomendado)
+
+```tsx
+import { createSimpleSaveHandler } from 'forlogic-core';
+
+const ExamplesPage = createCrudPage({
+  config,
+  service,
+  saveHandler: createSimpleSaveHandler(service), // ✅ Preserva ID automaticamente
+});
+```
+
+**O que `createSimpleSaveHandler` faz:**
+- ✅ Preserva o `id` no payload de update
+- ✅ Remove campos imutáveis (`alias`, `created_at`, etc.)
+- ✅ Trata update e insert corretamente
+
+### ✅ Solução 2: Handler Customizado Manual
+
+Se precisar de lógica customizada:
+
+```tsx
+const ExamplesPage = createCrudPage({
+  config,
+  service,
+  saveHandler: async (formData, editingItem) => {
+    // ✅ CRÍTICO: Preservar o ID
+    const dataToSave = editingItem?.id 
+      ? { ...formData, id: editingItem.id } // Update: inclui ID
+      : formData; // Insert: sem ID
+
+    // ✅ Remover campos imutáveis em updates
+    if (editingItem?.id) {
+      delete dataToSave.alias;
+      delete dataToSave.created_at;
+      delete dataToSave.updated_at;
+    }
+
+    // Sua lógica customizada aqui
+    await service.save(dataToSave);
+  },
+});
+```
+
+### ❌ Erros Comuns
+
+#### Erro 1: Remover o ID do payload
+```tsx
+// ❌ ERRADO - Remove o ID
+const dataToSave = { ...formData };
+delete dataToSave.id; // ❌ Causa criação de novo registro
+await service.save(dataToSave);
+```
+
+#### Erro 2: Enviar campos imutáveis em UPDATE
+```tsx
+// ❌ ERRADO - Envia alias em UPDATE
+const dataToSave = {
+  ...formData,
+  id: editingItem.id,
+  alias: formData.alias // ❌ Causa erro RLS se alias é imutável
+};
+```
+
+#### Erro 3: Não verificar se é update ou insert
+```tsx
+// ❌ ERRADO - Sempre inclui ID
+const dataToSave = { ...formData, id: editingItem?.id };
+await service.save(dataToSave); // ❌ Insert falha com ID null
+```
+
+### ✅ Checklist de Implementação Correta
+
+- [ ] Usar `createSimpleSaveHandler` (recomendado) OU
+- [ ] Handler customizado preserva `id` quando `editingItem?.id` existe
+- [ ] Campos imutáveis (`alias`, `created_at`) removidos em updates
+- [ ] Verificar `editingItem?.id` antes de incluir ID no payload
+- [ ] Não enviar `id: null` em inserts
+
+### 🐛 Debug
+
+Se ainda criar novos registros:
+
+1. **Console log do payload:**
+```tsx
+console.log('Payload:', dataToSave);
+console.log('EditingItem:', editingItem);
+```
+
+2. **Verificar se o ID está presente:**
+```tsx
+if (editingItem?.id) {
+  console.log('UPDATE - ID:', editingItem.id);
+} else {
+  console.log('INSERT - Sem ID');
+}
+```
+
+3. **Checar network tab:** Procurar pela requisição PATCH/POST e ver o body.
+
+---
+
+## 🔐 Violação de RLS Policy
+
+### Sintoma
+```
+Error: new row violates row-level security policy
+```
+
+### ✅ Solução
+Revise as políticas RLS no Supabase:
+1. Acesse **Authentication → Policies**
+2. Verifique se as políticas permitem a operação
+3. Teste com SQL Editor:
+```sql
+-- Testar insert
+INSERT INTO sua_tabela (campo) VALUES ('valor');
+
+-- Testar update
+UPDATE sua_tabela SET campo = 'novo_valor' WHERE id = 'uuid';
+```
+
+---
+
+## 📚 Recursos Adicionais
+
+- [README.md](../README.md) - Instalação e Quick Start
+- [AI_RULES.md](./AI_RULES.md) - Regras críticas para desenvolvimento com IA
+- [Templates](./templates/) - Códigos prontos
+- [Hub da Docs](./README.md) - Navegação completa
+
+---
+
+**💡 Dica:** Use Ctrl+F para buscar seu erro específico neste documento.