forlogic-core 1.6.3 → 1.6.5

package/README.md

@@ -906,6 +906,265 @@ fetch(url, { headers: { 'un-alias': 'true' } }); // ✅
 
 ---
 
+## 🔍 FILTROS NO BACKEND (Backend Filtering)
+
+### **Por que Filtros no Backend?**
+
+Filtrar dados no **backend** é a abordagem recomendada porque:
+- ✅ **Paginação correta**: Total de itens reflete os dados filtrados
+- ✅ **Performance**: Menos dados trafegados pela rede
+- ✅ **Escalabilidade**: Funciona com milhares de registros
+- ✅ **Ordenação**: Ordena apenas os dados filtrados
+
+### **Como Implementar Filtros no Backend**
+
+#### **1️⃣ Filtros Estáticos (via additionalFilters)**
+
+Para filtros simples e estáticos, use `additionalFilters` no service:
+
+```typescript
+// src/subprocesses/SubprocessService.ts
+import { createSimpleService } from 'forlogic-core';
+import { Subprocess, SubprocessInsert, SubprocessUpdate } from './types';
+
+export const { 
+  service: subprocessService, 
+  useCrudHook: baseUseCrudHook 
+} = createSimpleService<Subprocess, SubprocessInsert, SubprocessUpdate>({
+  tableName: 'subprocesses',
+  entityName: 'subprocesso',
+  schemaName: 'processes',
+  searchFields: ['title', 'description'],
+  enableQualiexEnrichment: true,
+  // Filtros estáticos aplicados sempre
+  additionalFilters: [
+    { field: 'is_removed', operator: 'eq', value: false }
+  ]
+});
+```
+
+#### **2️⃣ Filtros Dinâmicos (via Hook Customizado)**
+
+Para filtros dinâmicos controlados por URL ou estado, crie um hook wrapper:
+
+```typescript
+// src/subprocesses/SubprocessService.ts
+import { useMemo } from 'react';
+import { createSimpleService } from 'forlogic-core';
+
+// Service base
+export const { 
+  service: subprocessService, 
+  useCrudHook: baseUseCrudHook 
+} = createSimpleService<Subprocess, SubprocessInsert, SubprocessUpdate>({
+  tableName: 'subprocesses',
+  entityName: 'subprocesso',
+  schemaName: 'processes',
+  searchFields: ['title', 'description']
+});
+
+// Hook customizado que aceita filtros dinâmicos
+export function useSubprocessesCrud(filters?: {
+  is_actived?: boolean;
+  id_process?: string | 'none';
+}) {
+  // Transforma filtros em additionalFilters
+  const additionalFilters = useMemo(() => {
+    const filterList: any[] = [];
+    
+    // Filtro de status (ativo/inativo)
+    if (filters?.is_actived !== undefined) {
+      filterList.push({
+        field: 'is_actived',
+        operator: 'eq',
+        value: filters.is_actived
+      });
+    }
+    
+    // Filtro de processo (incluindo "sem processo")
+    if (filters?.id_process) {
+      if (filters.id_process === 'none') {
+        // Operador especial para NULL
+        filterList.push({
+          field: 'id_process',
+          operator: 'is_null'
+        });
+      } else {
+        filterList.push({
+          field: 'id_process',
+          operator: 'eq',
+          value: filters.id_process
+        });
+      }
+    }
+    
+    return filterList;
+  }, [filters?.is_actived, filters?.id_process]);
+  
+  // Chama hook base com filtros dinâmicos
+  return baseUseCrudHook({ additionalFilters });
+}
+```
+
+#### **3️⃣ Usar na Página com URL Search Params**
+
+```typescript
+// src/subprocesses/SubprocessesPage.tsx
+import { useSearchParams } from 'react-router-dom';
+import { useSubprocessesCrud } from './SubprocessService';
+
+export default function SubprocessesPage() {
+  const [searchParams, setSearchParams] = useSearchParams();
+  
+  // Ler filtros da URL
+  const filters = useMemo(() => ({
+    is_actived: searchParams.get('is_actived') === 'true',
+    id_process: searchParams.get('id_process') || undefined
+  }), [searchParams]);
+  
+  // Manager com filtros aplicados no backend
+  const manager = useSubprocessesCrud(filters);
+  
+  // Config com filtros de UI
+  const config = useMemo(() => generateCrudConfig<Subprocess>({
+    entityName: 'Subprocesso',
+    entityNamePlural: 'Subprocessos',
+    filters: [
+      {
+        type: 'custom',
+        component: StatusSelect,
+        props: {
+          value: searchParams.get('is_actived') || 'all',
+          onChange: (value: string) => {
+            if (value === 'all') {
+              searchParams.delete('is_actived');
+            } else {
+              searchParams.set('is_actived', value === 'active' ? 'true' : 'false');
+            }
+            setSearchParams(searchParams);
+          }
+        }
+      },
+      {
+        type: 'custom',
+        component: ProcessSelect,
+        props: {
+          value: searchParams.get('id_process') || 'all',
+          onChange: (value: string) => {
+            if (value === 'all') {
+              searchParams.delete('id_process');
+            } else {
+              searchParams.set('id_process', value);
+            }
+            setSearchParams(searchParams);
+          }
+        }
+      }
+    ],
+    columns: [...]
+  }), [searchParams]);
+  
+  return <CrudPage />;
+}
+```
+
+### **Operadores de Filtro Disponíveis**
+
+O `BaseService` suporta os seguintes operadores em `additionalFilters`:
+
+| Operador | Descrição | Exemplo |
+|----------|-----------|---------|
+| `eq` | Igual a | `{ field: 'status', operator: 'eq', value: 'active' }` |
+| `neq` | Diferente de | `{ field: 'status', operator: 'neq', value: 'archived' }` |
+| `gt` | Maior que | `{ field: 'price', operator: 'gt', value: 100 }` |
+| `gte` | Maior ou igual | `{ field: 'price', operator: 'gte', value: 100 }` |
+| `lt` | Menor que | `{ field: 'stock', operator: 'lt', value: 10 }` |
+| `lte` | Menor ou igual | `{ field: 'stock', operator: 'lte', value: 10 }` |
+| `in` | Em lista | `{ field: 'category', operator: 'in', value: ['A', 'B'] }` |
+| `contains` | Contém texto | `{ field: 'name', operator: 'contains', value: 'test' }` |
+| `is_null` | É nulo | `{ field: 'deleted_at', operator: 'is_null' }` |
+
+### **Exemplo Completo: Filtro de Status e Processo**
+
+```typescript
+// Hook com filtros dinâmicos
+export function useSubprocessesCrud(filters?: {
+  is_actived?: boolean;
+  id_process?: string | 'none';
+}) {
+  const additionalFilters = useMemo(() => {
+    const filterList: any[] = [];
+    
+    if (filters?.is_actived !== undefined) {
+      filterList.push({
+        field: 'is_actived',
+        operator: 'eq',
+        value: filters.is_actived
+      });
+    }
+    
+    if (filters?.id_process) {
+      if (filters.id_process === 'none') {
+        filterList.push({
+          field: 'id_process',
+          operator: 'is_null'
+        });
+      } else {
+        filterList.push({
+          field: 'id_process',
+          operator: 'eq',
+          value: filters.id_process
+        });
+      }
+    }
+    
+    return filterList;
+  }, [filters?.is_actived, filters?.id_process]);
+  
+  return baseUseCrudHook({ additionalFilters });
+}
+
+// Na página
+const filters = useMemo(() => ({
+  is_actived: searchParams.get('is_actived') === 'true',
+  id_process: searchParams.get('id_process') || undefined
+}), [searchParams]);
+
+const manager = useSubprocessesCrud(filters);
+
+// Resultado: Paginação mostra "1-10 de 43 itens" (correto!)
+// Backend retorna apenas os 43 subprocessos ativos
+```
+
+### **⚠️ Filtros Frontend vs Backend**
+
+**❌ Filtros no Frontend (EVITAR):**
+```typescript
+// Problema: Paginação incorreta
+const filteredEntities = useMemo(() => 
+  manager.entities.filter(e => e.is_actived), 
+  [manager.entities]
+);
+
+// manager.totalCount = 100 (total do backend)
+// filteredEntities.length = 43 (após filtro)
+// Paginação mostra "1-10 de 100 itens" ❌ ERRADO
+```
+
+**✅ Filtros no Backend (CORRETO):**
+```typescript
+// Backend retorna apenas dados filtrados
+const manager = useSubprocessesCrud({ 
+  is_actived: true 
+});
+
+// manager.totalCount = 43 (correto!)
+// manager.entities.length = 10 (página 1)
+// Paginação mostra "1-10 de 43 itens" ✅ CORRETO
+```
+
+---
+
 ## 📐 CONTROLE DE LARGURA DAS COLUNAS
 
 O `forlogic-core` oferece três formas de definir larguras de colunas nas tabelas CRUD:
@@ -1027,4 +1286,4 @@ src/
 
 MIT License - ForLogic © 2025
 
-**Última atualização:** 2025-10-05
+**Última atualização:** 2025-10-06

package/dist/README.md

@@ -906,6 +906,265 @@ fetch(url, { headers: { 'un-alias': 'true' } }); // ✅
 
 ---
 
+## 🔍 FILTROS NO BACKEND (Backend Filtering)
+
+### **Por que Filtros no Backend?**
+
+Filtrar dados no **backend** é a abordagem recomendada porque:
+- ✅ **Paginação correta**: Total de itens reflete os dados filtrados
+- ✅ **Performance**: Menos dados trafegados pela rede
+- ✅ **Escalabilidade**: Funciona com milhares de registros
+- ✅ **Ordenação**: Ordena apenas os dados filtrados
+
+### **Como Implementar Filtros no Backend**
+
+#### **1️⃣ Filtros Estáticos (via additionalFilters)**
+
+Para filtros simples e estáticos, use `additionalFilters` no service:
+
+```typescript
+// src/subprocesses/SubprocessService.ts
+import { createSimpleService } from 'forlogic-core';
+import { Subprocess, SubprocessInsert, SubprocessUpdate } from './types';
+
+export const { 
+  service: subprocessService, 
+  useCrudHook: baseUseCrudHook 
+} = createSimpleService<Subprocess, SubprocessInsert, SubprocessUpdate>({
+  tableName: 'subprocesses',
+  entityName: 'subprocesso',
+  schemaName: 'processes',
+  searchFields: ['title', 'description'],
+  enableQualiexEnrichment: true,
+  // Filtros estáticos aplicados sempre
+  additionalFilters: [
+    { field: 'is_removed', operator: 'eq', value: false }
+  ]
+});
+```
+
+#### **2️⃣ Filtros Dinâmicos (via Hook Customizado)**
+
+Para filtros dinâmicos controlados por URL ou estado, crie um hook wrapper:
+
+```typescript
+// src/subprocesses/SubprocessService.ts
+import { useMemo } from 'react';
+import { createSimpleService } from 'forlogic-core';
+
+// Service base
+export const { 
+  service: subprocessService, 
+  useCrudHook: baseUseCrudHook 
+} = createSimpleService<Subprocess, SubprocessInsert, SubprocessUpdate>({
+  tableName: 'subprocesses',
+  entityName: 'subprocesso',
+  schemaName: 'processes',
+  searchFields: ['title', 'description']
+});
+
+// Hook customizado que aceita filtros dinâmicos
+export function useSubprocessesCrud(filters?: {
+  is_actived?: boolean;
+  id_process?: string | 'none';
+}) {
+  // Transforma filtros em additionalFilters
+  const additionalFilters = useMemo(() => {
+    const filterList: any[] = [];
+    
+    // Filtro de status (ativo/inativo)
+    if (filters?.is_actived !== undefined) {
+      filterList.push({
+        field: 'is_actived',
+        operator: 'eq',
+        value: filters.is_actived
+      });
+    }
+    
+    // Filtro de processo (incluindo "sem processo")
+    if (filters?.id_process) {
+      if (filters.id_process === 'none') {
+        // Operador especial para NULL
+        filterList.push({
+          field: 'id_process',
+          operator: 'is_null'
+        });
+      } else {
+        filterList.push({
+          field: 'id_process',
+          operator: 'eq',
+          value: filters.id_process
+        });
+      }
+    }
+    
+    return filterList;
+  }, [filters?.is_actived, filters?.id_process]);
+  
+  // Chama hook base com filtros dinâmicos
+  return baseUseCrudHook({ additionalFilters });
+}
+```
+
+#### **3️⃣ Usar na Página com URL Search Params**
+
+```typescript
+// src/subprocesses/SubprocessesPage.tsx
+import { useSearchParams } from 'react-router-dom';
+import { useSubprocessesCrud } from './SubprocessService';
+
+export default function SubprocessesPage() {
+  const [searchParams, setSearchParams] = useSearchParams();
+  
+  // Ler filtros da URL
+  const filters = useMemo(() => ({
+    is_actived: searchParams.get('is_actived') === 'true',
+    id_process: searchParams.get('id_process') || undefined
+  }), [searchParams]);
+  
+  // Manager com filtros aplicados no backend
+  const manager = useSubprocessesCrud(filters);
+  
+  // Config com filtros de UI
+  const config = useMemo(() => generateCrudConfig<Subprocess>({
+    entityName: 'Subprocesso',
+    entityNamePlural: 'Subprocessos',
+    filters: [
+      {
+        type: 'custom',
+        component: StatusSelect,
+        props: {
+          value: searchParams.get('is_actived') || 'all',
+          onChange: (value: string) => {
+            if (value === 'all') {
+              searchParams.delete('is_actived');
+            } else {
+              searchParams.set('is_actived', value === 'active' ? 'true' : 'false');
+            }
+            setSearchParams(searchParams);
+          }
+        }
+      },
+      {
+        type: 'custom',
+        component: ProcessSelect,
+        props: {
+          value: searchParams.get('id_process') || 'all',
+          onChange: (value: string) => {
+            if (value === 'all') {
+              searchParams.delete('id_process');
+            } else {
+              searchParams.set('id_process', value);
+            }
+            setSearchParams(searchParams);
+          }
+        }
+      }
+    ],
+    columns: [...]
+  }), [searchParams]);
+  
+  return <CrudPage />;
+}
+```
+
+### **Operadores de Filtro Disponíveis**
+
+O `BaseService` suporta os seguintes operadores em `additionalFilters`:
+
+| Operador | Descrição | Exemplo |
+|----------|-----------|---------|
+| `eq` | Igual a | `{ field: 'status', operator: 'eq', value: 'active' }` |
+| `neq` | Diferente de | `{ field: 'status', operator: 'neq', value: 'archived' }` |
+| `gt` | Maior que | `{ field: 'price', operator: 'gt', value: 100 }` |
+| `gte` | Maior ou igual | `{ field: 'price', operator: 'gte', value: 100 }` |
+| `lt` | Menor que | `{ field: 'stock', operator: 'lt', value: 10 }` |
+| `lte` | Menor ou igual | `{ field: 'stock', operator: 'lte', value: 10 }` |
+| `in` | Em lista | `{ field: 'category', operator: 'in', value: ['A', 'B'] }` |
+| `contains` | Contém texto | `{ field: 'name', operator: 'contains', value: 'test' }` |
+| `is_null` | É nulo | `{ field: 'deleted_at', operator: 'is_null' }` |
+
+### **Exemplo Completo: Filtro de Status e Processo**
+
+```typescript
+// Hook com filtros dinâmicos
+export function useSubprocessesCrud(filters?: {
+  is_actived?: boolean;
+  id_process?: string | 'none';
+}) {
+  const additionalFilters = useMemo(() => {
+    const filterList: any[] = [];
+    
+    if (filters?.is_actived !== undefined) {
+      filterList.push({
+        field: 'is_actived',
+        operator: 'eq',
+        value: filters.is_actived
+      });
+    }
+    
+    if (filters?.id_process) {
+      if (filters.id_process === 'none') {
+        filterList.push({
+          field: 'id_process',
+          operator: 'is_null'
+        });
+      } else {
+        filterList.push({
+          field: 'id_process',
+          operator: 'eq',
+          value: filters.id_process
+        });
+      }
+    }
+    
+    return filterList;
+  }, [filters?.is_actived, filters?.id_process]);
+  
+  return baseUseCrudHook({ additionalFilters });
+}
+
+// Na página
+const filters = useMemo(() => ({
+  is_actived: searchParams.get('is_actived') === 'true',
+  id_process: searchParams.get('id_process') || undefined
+}), [searchParams]);
+
+const manager = useSubprocessesCrud(filters);
+
+// Resultado: Paginação mostra "1-10 de 43 itens" (correto!)
+// Backend retorna apenas os 43 subprocessos ativos
+```
+
+### **⚠️ Filtros Frontend vs Backend**
+
+**❌ Filtros no Frontend (EVITAR):**
+```typescript
+// Problema: Paginação incorreta
+const filteredEntities = useMemo(() => 
+  manager.entities.filter(e => e.is_actived), 
+  [manager.entities]
+);
+
+// manager.totalCount = 100 (total do backend)
+// filteredEntities.length = 43 (após filtro)
+// Paginação mostra "1-10 de 100 itens" ❌ ERRADO
+```
+
+**✅ Filtros no Backend (CORRETO):**
+```typescript
+// Backend retorna apenas dados filtrados
+const manager = useSubprocessesCrud({ 
+  is_actived: true 
+});
+
+// manager.totalCount = 43 (correto!)
+// manager.entities.length = 10 (página 1)
+// Paginação mostra "1-10 de 43 itens" ✅ CORRETO
+```
+
+---
+
 ## 📐 CONTROLE DE LARGURA DAS COLUNAS
 
 O `forlogic-core` oferece três formas de definir larguras de colunas nas tabelas CRUD:
@@ -1027,4 +1286,4 @@ src/
 
 MIT License - ForLogic © 2025
 
-**Última atualização:** 2025-10-05
+**Última atualização:** 2025-10-06