forlogic-core 1.5.2 → 1.5.3

package/dist/README.md

@@ -1,248 +1,471 @@
-# ForLogic Core
+# 🧱 Projeto atual
 
-> **Biblioteca empresarial com React + TypeScript + Supabase**  
-> Sistema CRUD completo, autenticação, integração Qualiex e componentes UI prontos.
+**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'`.
 
 ---
 
-## 📦 Instalação
+## 🤖 REGRAS CRÍTICAS
+
+### ⚠️ TOP 3 ERROS
+
+1. **ESQUECER SCHEMA**
+```typescript
+// ❌ ERRADO
+.from('table')
 
-```bash
-npm install forlogic-core
+// ✅ CORRETO
+.schema('schema').from('table')
 ```
 
-### Peer Dependencies
+2. **RLS COM `id` (sem alias)**
+```sql
+-- ❌ ERRADO
+CREATE POLICY "Users view own" ON schema.table
+FOR SELECT USING (id_user = auth.uid());
 
-A biblioteca requer as seguintes dependências (geralmente já presentes em projetos React):
+-- ✅ 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);
 
-```bash
-npm install react react-dom react-router-dom @tanstack/react-query
+-- ✅ Apenas quando solicitado explicitamente
 ```
 
 ---
 
-## 🚀 Quick Start
+### ✅ 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?
+
+---
+
+## 🚀 QUICK START - Criar CRUD Completo
 
-### 1. Configuração Inicial
+### **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;
+}
 
-```tsx
-// src/main.tsx
-import { setupQualiexCore } from 'forlogic-core';
-import 'forlogic-core/index.css';
+export type ProcessInsert = Omit<Process, 'id' | 'created_at' | 'updated_at'>;
+export type ProcessUpdate = Partial<ProcessInsert>;
+```
 
-setupQualiexCore({
-  supabaseUrl: import.meta.env.VITE_SUPABASE_URL,
-  supabaseAnonKey: import.meta.env.VITE_SUPABASE_ANON_KEY
+### **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'
 });
+
+// ⚠️ CRÍTICO: Preservar ID no update
+const handleUpdate = async (item: Process) => {
+  await handleSave({
+    ...item,
+    id: item.id // ⚠️ OBRIGATÓRIO para update
+  });
+};
 ```
 
-### 2. Estrutura de Providers
+### **4️⃣ Config (com useMemo)**
+```typescript
+// src/processes/ProcessesPage.tsx
+import { useMemo } from 'react';
+import { generateCrudConfig } from 'forlogic-core';
+
+export default function ProcessesPage() {
+  const crud = useProcesses();
+
+  // ⚠️ 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' }
+      ]
+    }), 
+  []);
+
+  return createCrudPage({
+    config,
+    crud,
+    saveHandler: handleSave
+  });
+}
+```
 
-```tsx
+### **5️⃣ Page + Outlet (preservar estado)**
+```typescript
 // src/App.tsx
-import { ErrorBoundary, QueryClientProvider, AuthProvider } from 'forlogic-core';
-import { BrowserRouter } from 'react-router-dom';
+import { Outlet } from 'react-router-dom';
 
 function App() {
   return (
-    <ErrorBoundary>
-      <QueryClientProvider client={queryClient}>
-        <AuthProvider>
-          <BrowserRouter>
-            {/* Suas rotas aqui */}
-          </BrowserRouter>
-        </AuthProvider>
-      </QueryClientProvider>
-    </ErrorBoundary>
+    <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
+}
+```
+
+---
+
+### 🔗 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)
 ```
 
-### 3. Criar uma Página CRUD Completa
+**Componentes prontos:**
+```typescript
+import { QualiexUserField, QualiexResponsibleSelectField } from 'forlogic-core';
 
-```tsx
-// src/employees/EmployeesPage.tsx
-import { createCrudPage, createSimpleService, useCrud } from 'forlogic-core';
+// Select de usuários Qualiex
+<QualiexResponsibleSelectField 
+  value={form.watch('id_user')}
+  onChange={(userId) => form.setValue('id_user', userId)}
+/>
+```
 
-// 1. Definir tipo
-interface Employee {
-  id?: string;
-  name: string;
-  email: string;
-  role: string;
+**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
 }
 
-// 2. Criar service
-const service = createSimpleService<Employee>('employees', { 
-  schemaName: 'central' // Usar schema do seu projeto
-});
+// Para seleção de responsável
+{
+  name: 'responsible_id',
+  label: 'Responsável',
+  type: 'single-responsible-select' as const,
+  required: true
+}
+```
 
-// 3. Criar hook
-const useEmployeesCrud = () => useCrud({ 
-  service, 
-  queryKey: 'employees' 
-});
+**Componentes customizados:**
 
-// 4. Configurar colunas e formulário
-const columns = [
-  { key: 'name', label: 'Nome' },
-  { key: 'email', label: 'Email' },
-  { key: 'role', label: 'Cargo' }
-];
+Você pode criar e usar componentes customizados nos formulários para necessidades específicas:
 
-const formSections = [
-  {
-    title: 'Dados do Funcionário',
-    fields: [
-      { name: 'name', label: 'Nome', type: 'text', required: true },
-      { name: 'email', label: 'Email', type: 'email', required: true },
-      { name: 'role', label: 'Cargo', type: 'text', required: true }
-    ]
-  }
-];
+```typescript
+// Exemplo de campo customizado
+{
+  name: 'custom_field',
+  label: 'Campo Customizado',
+  type: 'my-custom-component' as const,
+  required: true
+}
+```
 
-// 5. Exportar página
-export default createCrudPage({
-  useCrud: useEmployeesCrud,
-  columns,
-  formSections,
-  title: 'Funcionários'
-});
+> **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' }
 ```
 
 ---
 
-## 📚 Documentação Completa
+## 🗃️ 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);
+```
 
-A documentação detalhada está disponível em:
+### ❌ Sintaxes Proibidas RLS
+```sql
+-- NUNCA usar 'id' ou 'id_user' direto
+id_user = auth.uid()           -- ❌ ERRADO
+id = auth.uid()                 -- ❌ ERRADO
 
-- **[Regras para IA](dist/docs/AI_RULES.md)** - Checklist crítico para desenvolvimento assistido por IA
-- **[Troubleshooting](dist/docs/TROUBLESHOOTING.md)** - Soluções para problemas comuns
-- **[Templates Prontos](dist/docs/templates/)** - Códigos completos para copiar e usar
-- **[Navegação da Docs](dist/docs/README.md)** - Hub central da documentação
+-- SEMPRE usar 'alias'
+alias = auth.uid()              -- ✅ CORRETO
+```
 
 ---
 
-## 🎯 Recursos Principais
+## 🐛 TROUBLESHOOTING
 
-### ✅ Sistema CRUD Completo
-- Tabelas com paginação, filtros e ordenação
-- Formulários automáticos com validação
-- Cards responsivos para mobile
-- Ações em lote (deletar múltiplos)
+### 1️⃣ "relation does not exist"
+```typescript
+// Causa: Schema ausente
+.from('processes') // ❌
 
-### 🔐 Autenticação
-- Login/logout automático
-- Proteção de rotas
-- Integração com Supabase Auth
-- Gerenciamento de tokens
+// Solução:
+.from('processes', { schema: 'central' }) // ✅
+```
 
-### 🎨 Componentes UI
-- 50+ componentes prontos (shadcn/ui)
-- Design system completo
-- Dark mode nativo
-- Totalmente customizável
+### 2️⃣ RLS retorna vazio
+```sql
+-- Causa: Sintaxe incorreta
+USING (id_user = auth.uid()) -- ❌
 
-### 🔗 Integrações
-- **Qualiex**: Componentes para seleção de usuários
-- **Supabase**: Cliente configurado automaticamente
-- **React Query**: Cache e sincronização de dados
+-- Solução:
+USING (alias = auth.uid())   -- ✅
+```
 
----
+### 3️⃣ Duplicação de registros
+```typescript
+// Causa: ID ausente no update
+await service.save({ title: 'Novo' }); // ❌ Cria duplicado
 
-## 💡 Exemplo de Uso Completo
+// Solução: Preservar ID
+await service.save({ id: item.id, title: 'Novo' }); // ✅
+```
 
-```tsx
-import { 
-  createCrudPage, 
-  createSimpleService, 
-  useCrud,
-  QualiexUserField 
-} from 'forlogic-core';
+### 4️⃣ Página recarrega ao editar
+```typescript
+// Causa: Config sem useMemo
+const config = generateCrudConfig(...); // ❌ Re-render infinito
 
-interface Task {
-  id?: string;
-  title: string;
-  description: string;
-  responsible_id: string;
-  status: 'pending' | 'in_progress' | 'done';
-}
+// Solução:
+const config = useMemo(() => generateCrudConfig(...), []); // ✅
+```
 
-const service = createSimpleService<Task>('tasks', { 
-  schemaName: 'central' 
-});
+### 5️⃣ Estado reseta ao navegar
+```typescript
+// Causa: Outlet ausente
+<Route path="/processes" element={<ProcessesPage />} /> // ❌
 
-const useTasksCrud = () => useCrud({ service, queryKey: 'tasks' });
-
-export default createCrudPage({
-  useCrud: useTasksCrud,
-  columns: [
-    { key: 'title', label: 'Título' },
-    { key: 'status', label: 'Status' },
-  ],
-  formSections: [
-    {
-      title: 'Dados da Tarefa',
-      fields: [
-        { name: 'title', label: 'Título', type: 'text', required: true },
-        { name: 'description', label: 'Descrição', type: 'textarea' },
-        { 
-          name: 'responsible_id', 
-          label: 'Responsável', 
-          type: 'custom',
-          component: QualiexUserField 
-        },
-        { 
-          name: 'status', 
-          label: 'Status', 
-          type: 'select',
-          options: [
-            { value: 'pending', label: 'Pendente' },
-            { value: 'in_progress', label: 'Em Progresso' },
-            { value: 'done', label: 'Concluído' }
-          ]
-        }
-      ]
-    }
-  ],
-  title: 'Tarefas'
-});
+// 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)
 ```
 
 ---
 
-## 🔧 Configuração Avançada
+## 📐 CONTROLE DE LARGURA DAS COLUNAS
 
-### Import Modular (Tree-shaking)
+O `forlogic-core` oferece três formas de definir larguras de colunas nas tabelas CRUD:
 
-Para bundles menores, use imports específicos:
+### **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
+  },
+];
+```
 
-```tsx
-import { Button, Input, Card } from 'forlogic-core/modular';
+### **2️⃣ Via `width` (Fixo em pixels)**
+Especifique largura fixa diretamente:
+```typescript
+{
+  key: 'order',
+  header: 'Ordem',
+  width: 60, // Largura fixa: 60px
+  className: 'text-center',
+}
 ```
 
-### Customização de Tema
+### **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)
+}
+```
 
-Edite `index.css` no seu projeto:
+### **⚠️ 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
 
-```css
-:root {
-  --primary: 220 70% 50%;
-  --secondary: 210 40% 96.1%;
-  /* ... outros tokens */
-}
+### **📋 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)
+  },
+];
 ```
 
 ---
 
-## 📖 Links Úteis
+## 📚 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';
 
-- **GitHub**: [forlogic-core](https://github.com/forlogic/forlogic-core)
-- **NPM**: [forlogic-core](https://www.npmjs.com/package/forlogic-core)
-- **Suporte**: [Issues](https://github.com/forlogic/forlogic-core/issues)
+// 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
+
+**Última atualização:** 2025-10-05