forlogic-core 1.5.2 → 1.5.4

package/README.md

@@ -1,36 +1,628 @@
-# 🧱 Documentação exclusiva para este projeto
+# 🧱 Projeto atual
 
-> **Sistema empresarial com React + TypeScript + Supabase**
+**Schema padrão:** `central`
+
+> **Nota sobre schemas:** O schema padrão é `central`, mas módulos podem usar schemas diferentes quando necessário para organização ou isolamento de dados. Por exemplo, o módulo de treinamentos usa o schema `trainings`. Você pode especificar o schema no service usando `schemaName: 'nome_do_schema'`.
+
+---
+
+## 🤖 REGRAS CRÍTICAS
+
+### ⚠️ TOP 3 ERROS
+
+1. **ESQUECER SCHEMA**
+```typescript
+// ❌ ERRADO
+.from('table')
+
+// ✅ CORRETO
+.schema('schema').from('table')
+```
+
+2. **RLS COM `id` (sem alias)**
+```sql
+-- ❌ ERRADO
+CREATE POLICY "Users view own" ON schema.table
+FOR SELECT USING (id_user = auth.uid());
+
+-- ✅ CORRETO  
+CREATE POLICY "Users view own" ON schema.table
+FOR SELECT USING (alias = auth.uid());
+```
+
+3. **NÃO CRIAR ÍNDICES AUTOMATICAMENTE**
+```sql
+-- ❌ PROIBIDO criar índices sem aprovação
+CREATE INDEX idx_table_user ON schema.table(id_user);
+
+-- ✅ Apenas quando solicitado explicitamente
+```
+
+---
+
+### ✅ CHECKLIST (antes de implementar)
+
+- [ ] Schema `schema` especificado em queries e service?
+- [ ] RLS usando `alias` (nunca `id_user`)?
+- [ ] Preservar `item.id` no update?
+- [ ] Config gerado com `useMemo()`?
+- [ ] `<Outlet />` no componente pai?
+- [ ] Qualiex header `un-alias` configurado?
 
 ---
 
-## ⚙️ Configuração deste Projeto
+## 🚀 QUICK START - Criar CRUD Completo
+
+### **1️⃣ Type**
+```typescript
+// src/processes/process.ts
+export interface Process {
+  id: string;
+  id_user: string | null;
+  title: string;
+  description?: string;
+  status: 'draft' | 'active' | 'completed';
+  created_at?: string;
+  updated_at?: string;
+  deleted?: boolean;
+}
+
+export type ProcessInsert = Omit<Process, 'id' | 'created_at' | 'updated_at'>;
+export type ProcessUpdate = Partial<ProcessInsert>;
+```
+
+### **2️⃣ Service**
+```typescript
+// src/processes/processService.ts
+import { createSimpleService } from 'forlogic-core';
+import { Process, ProcessInsert, ProcessUpdate } from './process';
+
+export const { service: processService, useCrudHook: useProcesses } = 
+  createSimpleService<Process, ProcessInsert, ProcessUpdate>({
+    tableName: 'processes',
+    entityName: 'processo',
+    schemaName: 'central', // ⚠️ OBRIGATÓRIO
+    searchFields: ['title', 'description'],
+    enableQualiexEnrichment: true
+  });
+```
+
+### **3️⃣ Save Handler**
+```typescript
+// src/processes/ProcessesPage.tsx
+import { createSimpleSaveHandler } from 'forlogic-core';
+import { processService } from './processService';
+
+const handleSave = createSimpleSaveHandler({
+  service: processService,
+  entityName: 'processo'
+});
 
-### 🗄️ Schema do Banco
+// ⚠️ CRÍTICO: Preservar ID no update
+const handleUpdate = async (item: Process) => {
+  await handleSave({
+    ...item,
+    id: item.id // ⚠️ OBRIGATÓRIO para update
+  });
+};
+```
 
-Schema padrão deste projeto: **`central`**
+### **4️⃣ Config (com useMemo)**
+```typescript
+// src/processes/ProcessesPage.tsx
+import { useMemo } from 'react';
+import { generateCrudConfig } from 'forlogic-core';
 
-## 🤖 Instruções para IA (Lovable)
+export default function ProcessesPage() {
+  const crud = useProcesses();
 
-⚠️ **CONSULTAR SEMPRE antes de qualquer modificação:**
+  // ⚠️ OBRIGATÓRIO useMemo para evitar re-renders
+  const config = useMemo(() => 
+    generateCrudConfig<Process>({
+      entity: 'processo',
+      columns: [
+        { key: 'title', label: 'Título', type: 'text', required: true },
+        { key: 'status', label: 'Status', type: 'select', 
+          options: [
+            { value: 'draft', label: 'Rascunho' },
+            { value: 'active', label: 'Ativo' },
+            { value: 'completed', label: 'Concluído' }
+          ]
+        },
+        { key: 'description', label: 'Descrição', type: 'textarea' }
+      ]
+    }), 
+  []);
 
-1. **README.md da lib**: Acesse via `node_modules/forlogic-core/dist/README.md` - Instalação e Quick Start
-2. **AI_RULES.md**: Acesse via `node_modules/forlogic-core/dist/docs/AI_RULES.md` - **REGRAS CRÍTICAS**
-3. **Templates**: Acesse via `node_modules/forlogic-core/dist/docs/templates/` - Códigos prontos
-4. **Hub da Docs**: Acesse via `node_modules/forlogic-core/dist/docs/README.md` - Navegação completa
+  return createCrudPage({
+    config,
+    crud,
+    saveHandler: handleSave
+  });
+}
+```
 
-**NUNCA recriar:**
-- ❌ Integração Qualiex (já existe na lib)
-- ❌ Integração Supabase (já existe na lib)
-- ❌ Sistema CRUD (usar `createCrudPage` da lib)
-- ❌ Componentes base (importar de `forlogic-core`)
+### **5️⃣ Page + Outlet (preservar estado)**
+```typescript
+// src/App.tsx
+import { Outlet } from 'react-router-dom';
 
-**SEMPRE verificar:**
-- ✅ Schema padrão do projeto
-- ✅ Templates disponíveis antes de criar do zero
+function App() {
+  return (
+    <Routes>
+      <Route path="/processes" element={<ProcessLayout />}>
+        <Route index element={<ProcessesPage />} />
+        <Route path="new" element={<ProcessesPage />} />
+        <Route path=":id/edit" element={<ProcessesPage />} />
+      </Route>
+    </Routes>
+  );
+}
+
+// ⚠️ OBRIGATÓRIO: Outlet preserva estado
+function ProcessLayout() {
+  return <Outlet />; // Evita reload do componente
+}
+```
+
+---
+
+## 🎯 AÇÕES EM LOTE (Bulk Actions)
+
+O sistema CRUD suporta seleção múltipla e ações em lote usando checkboxes.
+
+### **Habilitar Bulk Actions**
+
+Adicione `enableBulkActions: true` na configuração:
+
+```typescript
+const config = useMemo((): CrudPageConfig<Process> => ({
+  entityName: "Processo",
+  entityNamePlural: "Processos",
+  enableBulkActions: true, // 🆕 Habilita checkboxes e ações em lote
+  columns: [...],
+  formSections: [...]
+}), []);
+```
+
+### **Ações Padrão Disponíveis**
+
+Quando `enableBulkActions: true`, as seguintes ações ficam disponíveis automaticamente:
+
+- ✅ **Deletar em lote**: Deleta múltiplos itens selecionados (usa a mesma função do delete individual)
+- ✅ **Checkbox "Selecionar Todos"**: No header da tabela para selecionar/deselecionar todos os itens da página
+- ✅ **Indicador Visual**: Linhas/cards selecionados têm background destacado
+- ✅ **Barra de Ações**: Aparece no topo quando há itens selecionados
+
+### **Ações Customizadas**
+
+Você pode adicionar ações customizadas além do delete padrão:
+
+```typescript
+import { Download, Archive } from 'lucide-react';
+import type { BulkAction } from 'forlogic-core';
+
+const config: CrudPageConfig<Process> = {
+  entityName: "Processo",
+  entityNamePlural: "Processos",
+  enableBulkActions: true,
+  bulkActions: [
+    {
+      label: "Exportar Selecionados",
+      icon: Download,
+      variant: "outline", // 'default' | 'destructive' | 'outline'
+      action: async (items) => {
+        // Sua lógica de exportação
+        const selectedItems = manager.entities.filter(
+          e => manager.selectedIds.includes(e.id)
+        );
+        await exportToExcel(selectedItems);
+      }
+    },
+    {
+      label: "Arquivar",
+      icon: Archive,
+      confirmMessage: "Tem certeza que deseja arquivar os itens selecionados?",
+      action: async (items) => {
+        const selectedItems = manager.entities.filter(
+          e => manager.selectedIds.includes(e.id)
+        );
+        await bulkArchive(selectedItems.map(i => i.id));
+      }
+    }
+  ],
+  columns: [...]
+};
+```
+
+### **Comportamento**
+
+**Desktop (Tabela):**
+- Checkbox na primeira coluna (50px de largura)
+- Checkbox no header para "Selecionar Todos"
+- Click na linha NÃO abre o form quando bulk actions está ativo (evita edição acidental)
+
+**Mobile (Cards):**
+- Checkbox no canto superior esquerdo de cada card
+- Mesmo comportamento de seleção que desktop
+
+**Barra de Ações:**
+- Aparece automaticamente quando há itens selecionados
+- Mostra quantidade de itens selecionados
+- Botão "Limpar" para deselecionar todos
+- Botões de ações (Delete + customizadas)
+
+### **Propriedades do Manager**
+
+Quando bulk actions está habilitado, o `manager` retornado pelo `useCrud` inclui:
+
+```typescript
+manager.selectedIds        // string[] - IDs dos itens selecionados
+manager.selectItem(id)     // Seleciona/desseleciona um item
+manager.selectAll()        // Seleciona/desseleciona todos
+manager.clearSelection()   // Limpa seleção
+manager.isAllSelected      // boolean - Todos selecionados?
+manager.bulkDelete(ids)    // Deleta múltiplos IDs
+manager.isBulkDeleting     // boolean - Loading do bulk delete
+```
+
+### **Exemplo Completo**
+
+```typescript
+// src/processes/ProcessesPage.tsx
+import { useMemo } from 'react';
+import { createCrudPage, createSimpleSaveHandler, type BulkAction } from 'forlogic-core';
+import { Download, Archive } from 'lucide-react';
+import { Process } from './process';
+import { useProcessCrud } from './processService';
+import { exportToExcel } from '@/utils/export';
+
+export function ProcessesPage() {
+  const manager = useProcessCrud();
+
+  const bulkActions: BulkAction<Process>[] = useMemo(() => [
+    {
+      label: "Exportar",
+      icon: Download,
+      variant: "outline",
+      action: async () => {
+        const selected = manager.entities.filter(
+          e => manager.selectedIds.includes(e.id)
+        );
+        await exportToExcel(selected);
+      }
+    }
+  ], [manager.entities, manager.selectedIds]);
+
+  const config = useMemo(() => ({
+    entityName: "Processo",
+    entityNamePlural: "Processos",
+    enableBulkActions: true,
+    bulkActions,
+    columns: [
+      { key: 'title', header: 'Título', sortable: true },
+      { key: 'status', header: 'Status', className: 'w-24 text-center' },
+    ],
+    formSections: [...]
+  }), [bulkActions]);
+
+  const handleSave = createSimpleSaveHandler(
+    manager,
+    (data) => ({ ...data }),
+    (data) => ({ ...data })
+  );
+
+  const CrudPage = createCrudPage({
+    manager,
+    config,
+    onSave: handleSave
+  });
+
+  return <CrudPage />;
+}
+```
+
+---
+
+### 🔗 Integração Qualiex (opcional)
+
+**Auto-enrichment** (já configurado no BaseService):
+```typescript
+// ✅ Automático - dados enriquecidos com nome do usuário
+const processes = await processService.getAll();
+// processes[0].usuario_nome = "João Silva" (se enableQualiexEnrichment: true)
+```
+
+**Componentes prontos:**
+```typescript
+import { QualiexUserField, QualiexResponsibleSelectField } from 'forlogic-core';
+
+// Select de usuários Qualiex
+<QualiexResponsibleSelectField 
+  value={form.watch('id_user')}
+  onChange={(userId) => form.setValue('id_user', userId)}
+/>
+```
+
+**Componentes em formulários CRUD:**
+```typescript
+// Para seleção de usuário
+{
+  name: 'responsible_id',
+  label: 'Responsável',
+  type: 'simple-qualiex-user-field' as const,
+  required: true
+}
+
+// Para seleção de responsável
+{
+  name: 'responsible_id',
+  label: 'Responsável',
+  type: 'single-responsible-select' as const,
+  required: true
+}
+```
+
+**Componentes customizados:**
+
+Você pode criar e usar componentes customizados nos formulários para necessidades específicas:
+
+```typescript
+// Exemplo de campo customizado
+{
+  name: 'custom_field',
+  label: 'Campo Customizado',
+  type: 'my-custom-component' as const,
+  required: true
+}
+```
+
+> **Nota:** Componentes customizados devem ser registrados no `BaseForm.tsx` para funcionarem corretamente nos formulários CRUD.
+
+**⚠️ CRÍTICO:** Requests Qualiex exigem header `un-alias`:
+```typescript
+// ✅ Já configurado no BaseService automaticamente
+headers: { 'un-alias': 'true' }
+```
+
+---
+
+## 🗃️ MIGRATIONS + RLS
+
+### Template SQL Completo
+```sql
+-- 1️⃣ Criar tabela
+CREATE TABLE central.processes (
+  id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
+  id_user UUID, -- ⚠️ NUNCA foreign key para auth.users
+  title TEXT NOT NULL,
+  description TEXT,
+  status TEXT DEFAULT 'draft',
+  created_at TIMESTAMPTZ DEFAULT now(),
+  updated_at TIMESTAMPTZ DEFAULT now(),
+  deleted BOOLEAN DEFAULT false
+);
+
+-- 2️⃣ Habilitar RLS
+ALTER TABLE central.processes ENABLE ROW LEVEL SECURITY;
+
+-- 3️⃣ Políticas RLS (usar 'alias', nunca 'id_user')
+CREATE POLICY "Users view own processes"
+ON central.processes FOR SELECT
+USING (alias = auth.uid()); -- ⚠️ 'alias', não 'id_user'
+
+CREATE POLICY "Users insert own processes"
+ON central.processes FOR INSERT
+WITH CHECK (alias = auth.uid());
+
+CREATE POLICY "Users update own processes"
+ON central.processes FOR UPDATE
+USING (alias = auth.uid());
+
+-- 4️⃣ Trigger updated_at
+CREATE TRIGGER set_updated_at
+BEFORE UPDATE ON central.processes
+FOR EACH ROW
+EXECUTE FUNCTION public.set_updated_at();
+
+-- 5️⃣ Índices (apenas se necessário)
+-- ⚠️ NÃO criar automaticamente - solicitar aprovação
+-- CREATE INDEX idx_processes_user ON central.processes(id_user);
+```
+
+### ❌ Sintaxes Proibidas RLS
+```sql
+-- NUNCA usar 'id' ou 'id_user' direto
+id_user = auth.uid()           -- ❌ ERRADO
+id = auth.uid()                 -- ❌ ERRADO
+
+-- SEMPRE usar 'alias'
+alias = auth.uid()              -- ✅ CORRETO
+```
+
+---
+
+## 🐛 TROUBLESHOOTING
+
+### 1️⃣ "relation does not exist"
+```typescript
+// Causa: Schema ausente
+.from('processes') // ❌
+
+// Solução:
+.from('processes', { schema: 'central' }) // ✅
+```
+
+### 2️⃣ RLS retorna vazio
+```sql
+-- Causa: Sintaxe incorreta
+USING (id_user = auth.uid()) -- ❌
+
+-- Solução:
+USING (alias = auth.uid())   -- ✅
+```
+
+### 3️⃣ Duplicação de registros
+```typescript
+// Causa: ID ausente no update
+await service.save({ title: 'Novo' }); // ❌ Cria duplicado
+
+// Solução: Preservar ID
+await service.save({ id: item.id, title: 'Novo' }); // ✅
+```
+
+### 4️⃣ Página recarrega ao editar
+```typescript
+// Causa: Config sem useMemo
+const config = generateCrudConfig(...); // ❌ Re-render infinito
+
+// Solução:
+const config = useMemo(() => generateCrudConfig(...), []); // ✅
+```
+
+### 5️⃣ Estado reseta ao navegar
+```typescript
+// Causa: Outlet ausente
+<Route path="/processes" element={<ProcessesPage />} /> // ❌
+
+// Solução: Layout com Outlet
+<Route path="/processes" element={<ProcessLayout />}>
+  <Route index element={<ProcessesPage />} />
+</Route>
+// ProcessLayout: return <Outlet />; // ✅
+```
+
+### 6️⃣ Qualiex retorna 401
+```typescript
+// Causa: Header ausente
+fetch(url); // ❌
+
+// Solução: Adicionar header
+fetch(url, { headers: { 'un-alias': 'true' } }); // ✅
+// (BaseService já faz automaticamente)
+```
+
+---
+
+## 📐 CONTROLE DE LARGURA DAS COLUNAS
+
+O `forlogic-core` oferece três formas de definir larguras de colunas nas tabelas CRUD:
+
+### **1️⃣ Via `className` (Recomendado)**
+Use classes do Tailwind para larguras fixas ou responsivas:
+```typescript
+const columns = [
+  {
+    key: 'status',
+    header: 'Status',
+    className: 'w-24 text-center', // Largura fixa: 96px
+  },
+  {
+    key: 'updated_at',
+    header: 'Atualizado em',
+    className: 'w-40 text-center whitespace-nowrap', // 160px, sem quebra
+  },
+];
+```
+
+### **2️⃣ Via `width` (Fixo em pixels)**
+Especifique largura fixa diretamente:
+```typescript
+{
+  key: 'order',
+  header: 'Ordem',
+  width: 60, // Largura fixa: 60px
+  className: 'text-center',
+}
+```
+
+### **3️⃣ Via `minWidth` + `weight` (Flexível)**
+Para colunas que crescem proporcionalmente:
+```typescript
+{
+  key: 'description',
+  header: 'Descrição',
+  minWidth: 200, // Mínimo: 200px
+  weight: 2, // 2x mais espaço que colunas padrão (weight: 1)
+}
+```
+
+### **⚠️ Importante**
+- A tabela usa `table-auto` para respeitar essas configurações
+- Para truncar textos longos, use: `className: "max-w-[200px] truncate"`
+- Combine `whitespace-nowrap` com largura fixa para evitar quebras
+
+### **📋 Exemplo Completo**
+```typescript
+const columns: CrudColumn<MyEntity>[] = [
+  {
+    key: 'order',
+    header: 'Ordem',
+    width: 60, // Fixo: 60px
+    className: 'text-center',
+  },
+  {
+    key: 'title',
+    header: 'Título',
+    minWidth: 200, // Mínimo: 200px, cresce conforme espaço disponível
+    weight: 3, // 3x mais espaço que colunas padrão
+  },
+  {
+    key: 'status',
+    header: 'Status',
+    className: 'w-24 text-center', // Tailwind: 96px
+  },
+  {
+    key: 'progress',
+    header: 'Nível & Progresso',
+    className: 'w-40 text-center', // Tailwind: 160px
+  },
+  {
+    key: 'updated_at',
+    header: 'Atualizado em',
+    className: 'w-40 text-center whitespace-nowrap', // 160px, sem quebra
+    render: (item) => formatDate(item.updated_at)
+  },
+];
+```
+
+---
+
+## 📚 REFERÊNCIA RÁPIDA
+
+### Imports Essenciais
+```typescript
+// CRUD
+import { 
+  createSimpleService, 
+  createCrudPage, 
+  generateCrudConfig,
+  createSimpleSaveHandler 
+} from 'forlogic-core';
+
+// UI
+import { Button, Input, Card, toast } from 'forlogic-core/ui';
+
+// Auth
+import { useAuth, ProtectedRoute } from 'forlogic-core';
+
+// Qualiex
+import { QualiexUserField, useQualiexUsers } from 'forlogic-core';
+```
+
+### Estrutura de Arquivos
+```
+src/
+├── processes/
+│   ├── process.ts              # Types
+│   ├── processService.ts       # Service + Hook
+│   └── ProcessesPage.tsx       # Page + Config
+```
 
 ---
 
 ## 📝 Licença
 
-MIT License - ForLogic © 2025
+MIT License - ForLogic © 2025
+
+**Última atualização:** 2025-10-05