forlogic-core 1.0.0

package/README.md

@@ -0,0 +1,1238 @@
+# 🧱 forlogic-core - Sistema CRUD Ultra-Simplificado
+
+> **Biblioteca modular React + TypeScript + Supabase para gestão empresarial com autenticação dupla JWT e integração Qualiex**
+
+[![npm version](https://badge.fury.io/js/%40qualiex%2Fcore.svg)](https://badge.fury.io/js/%40qualiex%2Fcore)
+[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
+[![React](https://img.shields.io/badge/React-18+-61dafb.svg)](https://reactjs.org/)
+
+---
+
+## 📦 Instalação
+
+```bash
+npm install forlogic-core
+```
+
+### Dependências Peer (Obrigatórias)
+
+```bash
+npm install react react-dom react-router-dom
+```
+
+### Configuração Inicial
+
+```tsx
+// main.tsx ou App.tsx
+import { setupQualiexCore } from 'forlogic-core';
+import 'forlogic-core/dist/styles/index.css';
+
+setupQualiexCore({
+  supabaseUrl: 'your-supabase-url',
+  supabaseKey: 'your-supabase-anon-key',
+  qualiexBaseUrl: 'your-qualiex-url'
+});
+```
+
+### Uso Básico
+
+```tsx
+import { CrudPage, useCrud } from 'forlogic-core';
+
+function MyPage() {
+  const crud = useCrud({
+    queryKey: 'my-entities',
+    service: MyService,
+    entityName: 'Item'
+  });
+  
+  return (
+    <CrudPage
+      manager={crud}
+      config={{ entityName: 'Item', entityNamePlural: 'Itens' }}
+      formSections={formConfig}
+      onSave={(data) => crud.createEntity(data)}
+    />
+  );
+}
+```
+
+---
+
+## 🚀 Stack Tecnológico
+
+| Tecnologia | Versão | Propósito |
+|------------|---------|-----------|
+| **React** | 18+ | Framework UI |
+| **TypeScript** | 5+ | Type Safety |
+| **Tailwind CSS** | 3+ | Styling System |
+| **Supabase** | 2+ | Backend BaaS |
+| **React Query** | 5+ | Estado e Cache |
+| **React Hook Form** | 7+ | Formulários |
+| **Zod** | 3+ | Validação |
+| **shadcn/ui** | Latest | Componentes Base |
+| **Radix UI** | Latest | Primitivos Acessíveis |
+
+---
+
+## 🏗️ Arquitetura do Projeto
+
+### Sistema de Importação Direta (Zero Barrel Exports)
+
+```
+forlogic-core/
+├── 🔐 auth/                          # Sistema de Autenticação
+│   ├── components/
+│   │   ├── ProtectedRoute.tsx        # Rota protegida por auth
+│   │   └── UserInfo.tsx              # Informações do usuário
+│   ├── contexts/
+│   │   └── AuthContext.tsx           # Context de autenticação
+│   ├── pages/
+│   │   └── CallbackPage.tsx          # Callback OAuth
+│   └── services/
+│       ├── AuthService.ts            # Lógica de autenticação
+│       └── TokenManager.ts           # Gestão de tokens JWT
+│
+├── 🗂️ crud/                          # Sistema CRUD Genérico
+│   ├── components/
+│   │   ├── ActionMenuItems.tsx       # Itens do menu de ações
+│   │   ├── BaseForm.tsx             # Formulário base configurável
+│   │   ├── CrudCards.tsx            # Cards responsivos para mobile
+│   │   ├── CrudForm.tsx             # Wrapper CRUD simples
+│   │   ├── CrudPage.tsx             # Página CRUD completa
+│   │   ├── CrudTable.tsx            # Tabela CRUD responsiva
+│   │   ├── FilterBar.tsx            # Barra de filtros e busca
+│   │   ├── TableFooter.tsx          # Rodapé com paginação
+│   │   └── TableRowActions.tsx      # Ações de linha da tabela
+│   └── hooks/
+│       ├── useCrud.ts               # Hook principal para CRUD
+│       └── useBaseForm.ts           # Hook para formulários
+│
+├── 🎨 components/                    # Componentes Globais
+│   ├── layout/
+│   │   ├── AppHeader.tsx            # Cabeçalho da aplicação
+│   │   └── AppSidebar.tsx           # Sidebar de navegação
+│   └── ui/                          # Componentes UI (shadcn/ui)
+│       ├── button.tsx               # Sistema de botões
+│       ├── card.tsx                 # Sistema de cards
+│       ├── form.tsx                 # Componentes de formulário
+│       ├── input.tsx                # Inputs customizados
+│       ├── table.tsx                # Tabelas responsivas
+│       ├── toast.tsx                # Notificações toast
+│       └── [50+ componentes]        # Biblioteca completa
+│
+├── 🔌 integrations/                  # Integrações Externas
+│   ├── supabase/
+│   │   ├── client.ts                # Cliente Supabase configurado
+│   │   └── types.ts                 # Tipos gerados automaticamente
+│   └── qualiex/
+│       ├── components/
+│       │   ├── QualiexUserField.tsx # Campo de usuário Qualiex
+│       │   └── QualiexResponsibleSelectField.tsx
+│       ├── services/
+│       │   └── qualiexApi.ts        # API client Qualiex
+│       ├── hooks/
+│       │   └── useQualiexUsers.ts   # Hook para usuários
+│       └── types/
+│           └── qualiexTypes.ts      # Tipos da API Qualiex
+│
+├── 🔧 services/                      # Serviços Base
+│   ├── BaseService.ts               # Service CRUD genérico
+│   ├── ErrorService.ts              # Tratamento de erros
+│   └── QualiexEnrichmentService.ts  # Enriquecimento de dados
+│
+├── 🧰 hooks/                         # Hooks Globais
+│   ├── useActiveModules.ts          # Módulos ativos
+│   ├── useDebounce.ts               # Debounce de busca
+│   ├── usePageTitle.ts              # Título da página
+│   └── use-toast.ts                 # Sistema de toast
+│
+├── 🛠️ utils/                         # Utilitários
+│   └── index.ts                     # Funções auxiliares
+│
+├── ⚙️ config/                        # Configurações
+│   └── index.ts                     # Config centralizada
+│
+└── 📄 types.ts                       # Tipos Globais
+```
+
+**✅ Princípios**: Imports diretos, componentes pequenos, zero over-engineering
+
+---
+
+## 🔐 Sistema de Autenticação Dupla
+
+### Arquitetura de Tokens JWT
+
+```mermaid
+sequenceDiagram
+    participant U as Usuário
+    participant Q as Qualiex OAuth
+    participant E as Edge Function
+    participant S as Supabase
+    participant A as App
+
+    U->>Q: Login OAuth
+    Q->>U: access_token + id_token
+    U->>E: validate-token(access_token)
+    E->>Q: Valida token
+    E->>S: Gera supabase_token
+    E->>U: supabase_token
+    U->>A: Login com 3 tokens
+```
+
+### Tokens Gerenciados
+
+| Token | Função | Storage | Duração |
+|-------|--------|---------|---------|
+| `access_token` | API Qualiex | localStorage | 1h |
+| `id_token` | Dados do usuário | localStorage | 1h |
+| `supabase_token` | Acesso RLS | localStorage | 1h |
+| `refresh_token` | Renovação | httpOnly cookie | 7d |
+
+### Edge Functions
+
+```
+supabase/functions/
+├── validate-token/          # Produção: Validação completa
+│   └── index.ts            # - Valida no Qualiex
+│                           # - Gera token Supabase
+│                           # - Retorna dados do usuário
+└── dev-tokens/             # Desenvolvimento: Tokens mock
+    └── index.ts            # - Bypass OAuth em dev
+                            # - Gera tokens válidos
+                            # - Acelera desenvolvimento
+```
+
+### Fluxo de Unidades/Empresas
+
+```tsx
+// Contexto de autenticação com multi-tenancy
+const { user, companies, selectedUnit, switchUnit } = useAuth();
+
+// Trocar entre empresas do usuário
+await switchUnit(companyAlias);
+```
+
+**🔒 Segurança**: RLS por alias + JWT claims + refresh automático
+
+---
+
+## 🗄️ Banco de Dados e RLS
+
+### Estrutura Padrão de Tabela
+
+```sql
+-- Tabela modelo compatível com o sistema
+CREATE TABLE schema_module.your_table (
+  -- 🔑 Campos obrigatórios do sistema
+  id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
+  alias TEXT NOT NULL,                    -- Multi-tenancy RLS
+  
+  -- 📝 Campos de negócio (personalizáveis)
+  title TEXT NOT NULL,
+  description TEXT,
+  url_field TEXT,
+  date_field TIMESTAMP WITH TIME ZONE,
+  color TEXT,
+  icon_name TEXT,
+  id_user TEXT,                          -- ID responsável (Qualiex)
+  
+  -- 🎛️ Campos de controle (obrigatórios)
+  is_actived BOOLEAN DEFAULT true,       -- Status ativo/inativo
+  is_removed BOOLEAN DEFAULT false,      -- Soft delete
+  created_at TIMESTAMP WITH TIME ZONE DEFAULT now(),
+  updated_at TIMESTAMP WITH TIME ZONE DEFAULT now()
+);
+
+-- 🔒 Trigger para updated_at
+CREATE TRIGGER update_your_table_updated_at
+  BEFORE UPDATE ON schema_module.your_table
+  FOR EACH ROW
+  EXECUTE FUNCTION schema_module.update_updated_at_column();
+```
+
+### Políticas RLS Multi-Tenant
+
+```sql
+-- 🔒 Habilitar Row Level Security
+ALTER TABLE schema_module.your_table ENABLE ROW LEVEL SECURITY;
+
+-- 👀 SELECT: Ver dados da empresa
+CREATE POLICY "Users can view company data" ON schema_module.your_table
+FOR SELECT USING (
+  ((SELECT auth.jwt()) ->> 'alias') = alias 
+);
+
+-- ➕ INSERT: Inserir com alias da empresa
+CREATE POLICY "Users can insert company data" ON schema_module.your_table
+FOR INSERT WITH CHECK (
+  ((SELECT auth.jwt()) ->> 'alias') = alias
+);
+
+-- ✏️ UPDATE: Atualizar dados da empresa
+CREATE POLICY "Users can update company data" ON schema_module.your_table
+FOR UPDATE USING (
+  ((SELECT auth.jwt()) ->> 'alias') = alias
+);
+
+-- ⚠️ IMPORTANTE: NÃO criar política DELETE 
+-- Sistema usa soft delete (is_removed = true)
+```
+
+### Template SQL Completo
+
+```sql
+-- Copie este template para criar novas tabelas
+\i 'docs/templates/rls-policies.sql'
+```
+
+**🛡️ Segurança**: Isolamento automático por empresa via RLS
+
+---
+
+## 🧠 Sistema CRUD Simplificado
+
+### BaseService - CRUD Automático
+
+```typescript
+// Criar service em 3 linhas
+import { createService } from 'forlogic-core';
+import type { MyEntity } from '@/types';
+
+export const MyService = createService<MyEntity>({
+  tableName: 'my_table',
+  searchFields: ['title', 'description'],  // Campos de busca
+  schemaName: 'schema_module',                   // Schema do banco
+  entityName: 'MinhaEntidade'              // Para enrichment Qualiex
+});
+
+// Pronto! Service com todas as operações CRUD:
+// - MyService.getAll() - Listar com paginação e busca
+// - MyService.create() - Criar com RLS automático
+// - MyService.update() - Atualizar com validação
+// - MyService.delete() - Soft delete (is_removed = true)
+```
+
+### Hook CRUD - Gerenciamento de Estado
+
+```tsx
+import { useCrud } from 'forlogic-core';
+
+function MyComponent() {
+  const manager = useCrud({
+    queryKey: 'my-entities',     // Cache key única
+    service: MyService,          // Service criado acima
+    entityName: 'Item',          // Nome singular
+    pageSize: 25                 // Itens por página (opcional)
+  });
+
+  // Estado disponível:
+  const {
+    entities,           // Dados da página atual
+    pagination,         // Info de paginação
+    isLoading,         // Estado de carregamento
+    searchTerm,        // Termo de busca atual
+    
+    // Operações:
+    createEntity,      // Criar novo
+    updateEntity,      // Atualizar existente
+    deleteEntity,      // Soft delete
+    refetch,          // Recarregar dados
+    handleSearch,     // Buscar (debounced)
+    handlePageChange, // Mudar página
+  } = manager;
+
+  return (
+    <div>
+      <input 
+        onChange={(e) => handleSearch(e.target.value)}
+        placeholder="Buscar..."
+      />
+      
+      {entities.map(item => (
+        <div key={item.id}>
+          <h3>{item.title}</h3>
+          <button onClick={() => deleteEntity(item.id)}>
+            Remover
+          </button>
+        </div>
+      ))}
+      
+      <button onClick={() => handlePageChange(pagination.currentPage + 1)}>
+        Próxima página
+      </button>
+    </div>
+  );
+}
+```
+
+**⚡ Performance**: React Query + debounce + paginação server-side
+
+---
+
+## 🎨 Sistema de Formulários
+
+### Configuração Declarativa
+
+```tsx
+// Definir formulário por configuração (zero JSX manual)
+const formSections = [
+  {
+    id: 'general',
+    title: 'Informações Gerais',
+    description: 'Dados principais do item',
+    fields: [
+      {
+        name: 'title',
+        label: 'Título',
+        type: 'text',
+        required: true,
+        placeholder: 'Digite o título...'
+      },
+      {
+        name: 'description',
+        label: 'Descrição',
+        type: 'textarea',
+        rows: 4
+      },
+      {
+        name: 'date_field',
+        label: 'Data',
+        type: 'date',
+        required: true
+      }
+    ]
+  },
+  {
+    id: 'advanced',
+    title: 'Configurações Avançadas',
+    condition: (formData) => formData.userType === 'admin', // Seção condicional
+    fields: [
+      {
+        name: 'color',
+        label: 'Cor do tema',
+        type: 'color-picker'
+      },
+      {
+        name: 'icon_name',
+        label: 'Ícone',
+        type: 'icon-picker'
+      },
+      {
+        name: 'id_user',
+        label: 'Responsável',
+        type: 'simple-qualiex-user-field'  // Campo integrado Qualiex
+      }
+    ]
+  }
+];
+```
+
+### Tipos de Campo Disponíveis
+
+#### 📝 Campos Básicos
+| Tipo | Descrição | Props Extras |
+|------|-----------|--------------|
+| `text` | Entrada de texto | `placeholder`, `maxLength` |
+| `textarea` | Área de texto | `rows`, `placeholder` |
+| `email` | E-mail com validação | `placeholder` |
+| `password` | Senha oculta | `placeholder` |
+| `number` | Número | `step`, `min`, `max` |
+| `date` | Data | `min`, `max` |
+| `datetime-local` | Data e hora | - |
+| `url` | URL com validação | `placeholder` |
+
+#### 🎯 Campos de Seleção
+| Tipo | Descrição | Props Extras |
+|------|-----------|--------------|
+| `select` | Seleção única | `options: [{label, value}]` |
+| `multiselect` | Seleção múltipla | `options`, `maxSelections` |
+| `checkbox` | Checkbox | `defaultValue: boolean` |
+| `radio` | Grupo de rádio | `options: [{label, value}]` |
+
+#### 🎨 Campos Visuais
+| Tipo | Descrição | Props Extras |
+|------|-----------|--------------|
+| `color` | Cor (input nativo) | - |
+| `color-picker` | Seletor de cores avançado | `presetColors` |
+| `icon-picker` | Seletor de ícones Lucide | `categories` |
+
+#### 🔌 Campos Integrados Qualiex
+| Tipo | Descrição | Props Extras |
+|------|-----------|--------------|
+| `simple-qualiex-user-field` | Usuário simples | - |
+| `user-select` | Seletor de usuário avançado | `multiple` |
+| `single-responsible-select` | Responsável único | - |
+
+#### 🔧 Campos Especiais
+| Tipo | Descrição | Props Extras |
+|------|-----------|--------------|
+| `group` | Agrupamento de campos | `fields: FormField[]` |
+| `divider` | Separador visual | `label` |
+
+### Recursos Avançados
+
+#### 💡 Campos Computados
+```tsx
+{
+  name: 'fullName',
+  label: 'Nome Completo',
+  type: 'text',
+  computedValue: (formData) => `${formData.firstName} ${formData.lastName}`,
+  disabled: true
+}
+```
+
+#### 🔗 Dependências entre Campos
+```tsx
+{
+  name: 'endDate',
+  label: 'Data Final',
+  type: 'date',
+  dependsOn: 'startDate',
+  validation: (value, formData) => {
+    if (value < formData.startDate) {
+      return 'Data final deve ser após a inicial';
+    }
+  }
+}
+```
+
+#### ✅ Validação Customizada
+```tsx
+{
+  name: 'cpf',
+  label: 'CPF',
+  type: 'text',
+  validation: {
+    pattern: /^\d{3}\.\d{3}\.\d{3}-\d{2}$/,
+    message: 'CPF deve estar no formato 000.000.000-00',
+    custom: (value) => {
+      if (!isValidCPF(value)) return 'CPF inválido';
+    }
+  }
+}
+```
+
+#### 🔄 Callbacks de Mudança
+```tsx
+{
+  name: 'category',
+  label: 'Categoria',
+  type: 'select',
+  options: categories,
+  onValueChange: (value, formData, setValue) => {
+    // Recarregar subcategorias baseado na categoria
+    loadSubcategories(value).then(subs => {
+      setValue('subcategory', null); // Reset subcategoria
+      // Atualizar opções de subcategoria
+    });
+  }
+}
+```
+
+---
+
+## 📊 Sistema de Tabelas e Cards
+
+### CrudPage - Página Completa
+
+```tsx
+import { CrudPage, useCrud } from 'forlogic-core';
+
+export function MyEntityPage() {
+  const manager = useCrud({
+    queryKey: 'my-entities',
+    service: MyService,
+    entityName: 'Item'
+  });
+  
+  const config = {
+    entityName: 'Item',
+    entityNamePlural: 'Itens',
+    description: 'Gerencie seus itens aqui',
+    
+    // Configuração da tabela
+    columns: [
+      { 
+        key: 'title', 
+        header: 'Título', 
+        sortable: true,
+        searchable: true 
+      },
+      { 
+        key: 'responsible_name', 
+        header: 'Responsável' 
+      },
+      { 
+        key: 'created_at', 
+        header: 'Criado em',
+        render: (item) => formatDate(item.created_at)
+      },
+      {
+        key: 'is_actived',
+        header: 'Status',
+        render: (item) => (
+          <Badge variant={item.is_actived ? 'success' : 'secondary'}>
+            {item.is_actived ? 'Ativo' : 'Inativo'}
+          </Badge>
+        )
+      }
+    ],
+    
+    // Configuração dos cards (mobile)
+    cardFields: [
+      {
+        key: 'title',
+        label: 'Título',
+        render: (value, item) => (
+          <h3 className="font-semibold text-lg">{value}</h3>
+        )
+      },
+      {
+        key: 'responsible_name',
+        label: 'Responsável',
+        render: (value) => value || 'Não definido'
+      }
+    ]
+  };
+
+  return (
+    <CrudPage
+      manager={manager}
+      config={config}
+      formSections={formSections}
+      onSave={(data) => manager.createEntity(data)}
+      
+      // Configurações opcionais
+      enableSearch={true}
+      enableFilters={true}
+      enableExport={true}
+      customActions={[
+        {
+          label: 'Ação Customizada',
+          icon: 'star',
+          onClick: (item) => console.log('Custom action', item)
+        }
+      ]}
+    />
+  );
+}
+```
+
+### Responsividade Automática
+
+- **Desktop (≥768px)**: Tabela completa com ordenação
+- **Mobile (<768px)**: Cards otimizados para toque
+- **Transição suave**: Mudança automática no breakpoint
+
+---
+
+## 🔌 Integração Qualiex
+
+### API de Usuários
+
+```tsx
+import { qualiexApi, useQualiexUsers } from 'forlogic-core';
+
+// Hook para buscar usuários
+function MyComponent() {
+  const { users, loading, error } = useQualiexUsers();
+  
+  return (
+    <select>
+      {users.map(user => (
+        <option key={user.userId} value={user.userId}>
+          {user.userName} ({user.userEmail})
+        </option>
+      ))}
+    </select>
+  );
+}
+
+// API direta
+const users = await qualiexApi.fetchUsers(alias, companyId);
+// Retorna: QualiexUser[] { userId, userName, userEmail }
+```
+
+### Enriquecimento Automático
+
+```typescript
+// Service com enrichment automático
+export const TaskService = createService<Task>({
+  tableName: 'tasks',
+  searchFields: ['title'],
+  entityName: 'Task' // Nome da entidade no Qualiex
+});
+
+// Dados enriquecidos automaticamente:
+// id_user "123" → responsible_name "João Silva"
+// Busca automática na API Qualiex quando necessário
+```
+
+---
+
+## 🎯 Exemplos Práticos
+
+### 1. CRUD de Produtos
+
+```tsx
+// types.ts
+export interface Product {
+  id: string;
+  alias: string;
+  name: string;
+  description?: string;
+  price: number;
+  category_id: string;
+  id_user: string;  // Responsável
+  is_actived: boolean;
+  is_removed: boolean;
+  created_at: string;
+  updated_at: string;
+  
+  // Campos enriquecidos
+  responsible_name?: string;
+  category_name?: string;
+}
+
+// ProductService.ts
+import { createService } from 'forlogic-core';
+
+export const ProductService = createService<Product>({
+  tableName: 'products',
+  searchFields: ['name', 'description'],
+  schemaName: 'schema_module',
+  entityName: 'Product'
+});
+
+// ProductsPage.tsx
+import { CrudPage, useCrud } from 'forlogic-core';
+
+export function ProductsPage() {
+  const manager = useCrud({
+    queryKey: 'products',
+    service: ProductService,
+    entityName: 'Produto'
+  });
+
+  const formSections = [
+    {
+      id: 'basic',
+      title: 'Informações Básicas',
+      fields: [
+        {
+          name: 'name',
+          label: 'Nome do Produto',
+          type: 'text',
+          required: true
+        },
+        {
+          name: 'description',
+          label: 'Descrição',
+          type: 'textarea',
+          rows: 3
+        },
+        {
+          name: 'price',
+          label: 'Preço',
+          type: 'number',
+          step: 0.01,
+          min: 0,
+          required: true
+        }
+      ]
+    },
+    {
+      id: 'management',
+      title: 'Gestão',
+      fields: [
+        {
+          name: 'category_id',
+          label: 'Categoria',
+          type: 'select',
+          options: categories,
+          required: true
+        },
+        {
+          name: 'id_user',
+          label: 'Responsável',
+          type: 'simple-qualiex-user-field',
+          required: true
+        }
+      ]
+    }
+  ];
+
+  const config = {
+    entityName: 'Produto',
+    entityNamePlural: 'Produtos',
+    columns: [
+      { key: 'name', header: 'Nome', sortable: true },
+      { key: 'category_name', header: 'Categoria' },
+      { key: 'price', header: 'Preço', render: (item) => `R$ ${item.price}` },
+      { key: 'responsible_name', header: 'Responsável' }
+    ]
+  };
+
+  return (
+    <CrudPage
+      manager={manager}
+      config={config}
+      formSections={formSections}
+      onSave={(data) => manager.createEntity(data)}
+    />
+  );
+}
+```
+
+### 2. Formulário de Contato Avançado
+
+```tsx
+import { BaseForm } from 'forlogic-core';
+
+export function ContactForm({ open, onClose, onSubmit }) {
+  const sections = [
+    {
+      id: 'personal',
+      title: 'Dados Pessoais',
+      fields: [
+        {
+          name: 'name',
+          label: 'Nome Completo',
+          type: 'text',
+          required: true
+        },
+        {
+          name: 'email',
+          label: 'E-mail',
+          type: 'email',
+          required: true,
+          validation: {
+            pattern: /^[^\s@]+@[^\s@]+\.[^\s@]+$/,
+            message: 'E-mail inválido'
+          }
+        },
+        {
+          name: 'phone',
+          label: 'Telefone',
+          type: 'text',
+          validation: {
+            custom: (value) => {
+              if (value && !isValidPhone(value)) {
+                return 'Telefone inválido';
+              }
+            }
+          }
+        }
+      ]
+    },
+    {
+      id: 'preferences',
+      title: 'Preferências',
+      fields: [
+        {
+          name: 'contactMethod',
+          label: 'Método de Contato Preferido',
+          type: 'select',
+          options: [
+            { label: 'E-mail', value: 'email' },
+            { label: 'Telefone', value: 'phone' },
+            { label: 'WhatsApp', value: 'whatsapp' }
+          ],
+          onValueChange: (value, formData, setValue) => {
+            if (value === 'whatsapp' && !formData.phone) {
+              // Foco automático no campo telefone
+              document.querySelector('[name="phone"]')?.focus();
+            }
+          }
+        },
+        {
+          name: 'newsletter',
+          label: 'Receber newsletter',
+          type: 'checkbox',
+          defaultValue: true
+        }
+      ]
+    }
+  ];
+
+  return (
+    <BaseForm
+      open={open}
+      title="Novo Contato"
+      sections={sections}
+      onSubmit={onSubmit}
+      onCancel={onClose}
+      submitText="Salvar Contato"
+    />
+  );
+}
+```
+
+---
+
+## 🔒 Segurança e Performance
+
+### Implementações de Segurança
+
+| Recurso | Implementação | Benefício |
+|---------|---------------|-----------|
+| **RLS Multi-tenant** | Política por `alias` | Isolamento total entre empresas |
+| **Soft Delete** | `is_removed = true` | Auditoria e recuperação |
+| **JWT Refresh** | Renovação automática | Sessões seguras |
+| **Input Validation** | Zod + client-side | Prevenção de dados inválidos |
+| **XSS Protection** | Sanitização automática | Prevenção de ataques |
+
+### Otimizações de Performance
+
+| Recurso | Configuração | Impacto |
+|---------|--------------|---------|
+| **React Query Cache** | 10 min | -80% requests |
+| **Search Debounce** | 500ms | -90% queries |
+| **Paginação Server** | 25 itens | Escalabilidade |
+| **Lazy Loading** | Componentes | Menor bundle |
+| **Bundle Splitting** | Por rota | Carregamento rápido |
+
+### Métricas Automáticas
+
+```typescript
+// Configuração de performance (opcional)
+setupQualiexCore({
+  // ... outras configs
+  performance: {
+    cacheTime: 10 * 60 * 1000,      // 10 minutos
+    staleTime: 5 * 60 * 1000,       // 5 minutos
+    debounceDelay: 500,             // 500ms
+    pageSize: 25,                   // 25 itens por página
+    enableMetrics: true             // Métricas automáticas
+  }
+});
+```
+
+---
+
+## 📚 Documentação Técnica
+
+### Estrutura de Dados
+
+```typescript
+// Tipos base do sistema
+export interface BaseEntity {
+  id: string;
+  alias: string;
+  is_actived: boolean;
+  is_removed: boolean;
+  created_at: string;
+  updated_at: string;
+}
+
+export interface PaginationInfo {
+  currentPage: number;
+  totalPages: number;
+  totalItems: number;
+  pageSize: number;
+  hasNext: boolean;
+  hasPrev: boolean;
+}
+
+export interface CrudManager<T> {
+  entities: T[];
+  pagination: PaginationInfo;
+  isLoading: boolean;
+  searchTerm: string;
+  createEntity: (data: Partial<T>) => Promise<void>;
+  updateEntity: (id: string, data: Partial<T>) => Promise<void>;
+  deleteEntity: (id: string) => Promise<void>;
+  refetch: () => void;
+  handleSearch: (term: string) => void;
+  handlePageChange: (page: number) => void;
+}
+```
+
+### Políticas RLS Template
+
+```sql
+-- Template completo para novas tabelas
+-- docs/templates/rls-policies.sql
+
+-- Criar tabela
+CREATE TABLE schema_module.{table_name} (
+  id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
+  alias TEXT NOT NULL,
+  
+  -- Campos customizados aqui
+  title TEXT NOT NULL,
+  description TEXT,
+  
+  -- Campos de controle
+  is_actived BOOLEAN DEFAULT true,
+  is_removed BOOLEAN DEFAULT false,
+  created_at TIMESTAMP WITH TIME ZONE DEFAULT now(),
+  updated_at TIMESTAMP WITH TIME ZONE DEFAULT now()
+);
+
+-- RLS
+ALTER TABLE schema_module.{table_name} ENABLE ROW LEVEL SECURITY;
+
+-- Políticas padrão
+CREATE POLICY "view_company_data" ON schema_module.{table_name}
+FOR SELECT USING (
+  ((SELECT auth.jwt()) ->> 'alias') = alias 
+  AND is_removed = false
+);
+
+CREATE POLICY "insert_company_data" ON schema_module.{table_name}
+FOR INSERT WITH CHECK (
+  ((SELECT auth.jwt()) ->> 'alias') = alias
+);
+
+CREATE POLICY "update_company_data" ON schema_module.{table_name}
+FOR UPDATE USING (
+  ((SELECT auth.jwt()) ->> 'alias') = alias
+);
+
+-- Trigger updated_at
+CREATE TRIGGER update_{table_name}_updated_at
+  BEFORE UPDATE ON schema_module.{table_name}
+  FOR EACH ROW
+  EXECUTE FUNCTION schema_module.update_updated_at_column();
+```
+
+### Edge Functions
+
+```typescript
+// validate-token/index.ts
+import { serve } from 'https://deno.land/std@0.168.0/http/server.ts';
+
+serve(async (req) => {
+  const { access_token } = await req.json();
+  
+  // Validar token no Qualiex
+  const userInfo = await validateWithQualiex(access_token);
+  
+  // Gerar token Supabase
+  const supabaseToken = await generateSupabaseToken(userInfo);
+  
+  return new Response(
+    JSON.stringify({
+      supabase_token: supabaseToken,
+      user: userInfo
+    }),
+    { headers: { 'Content-Type': 'application/json' } }
+  );
+});
+```
+
+---
+
+## 🚀 Guia de Migração
+
+### De Sistemas Legados
+
+```typescript
+// ANTES: Código manual complexo
+const [data, setData] = useState([]);
+const [loading, setLoading] = useState(false);
+const [search, setSearch] = useState('');
+
+useEffect(() => {
+  loadData();
+}, [search]);
+
+const loadData = async () => {
+  setLoading(true);
+  try {
+    const result = await api.getData({ search });
+    setData(result);
+  } finally {
+    setLoading(false);
+  }
+};
+
+// DEPOIS: Hook simplificado
+const manager = useCrud({
+  queryKey: 'my-data',
+  service: MyService,
+  entityName: 'Item'
+});
+
+// Pronto! Todas as funcionalidades automáticas
+```
+
+### Checklist de Migração
+
+- [ ] ✅ Criar tabela com estrutura padrão
+- [ ] ✅ Configurar políticas RLS
+- [ ] ✅ Criar service com `createService()`
+- [ ] ✅ Substituir código manual por `useCrud()`
+- [ ] ✅ Configurar formulários declarativos
+- [ ] ✅ Testar operações CRUD
+- [ ] ✅ Verificar responsividade
+- [ ] ✅ Configurar integração Qualiex (se necessário)
+
+---
+
+## 🛠️ Desenvolvimento
+
+### Comandos de Build
+
+```bash
+# Desenvolvimento da lib
+npm run dev
+
+# Build da biblioteca
+npm run build:lib
+# ou
+./build-and-publish.sh build
+
+# Publicar versão
+./build-and-publish.sh patch   # 1.0.0 → 1.0.1
+./build-and-publish.sh minor   # 1.0.0 → 1.1.0
+./build-and-publish.sh major   # 1.0.0 → 2.0.0
+
+# Teste de publicação
+./build-and-publish.sh dry-run
+```
+
+### Estrutura de Build
+
+```
+dist/                      # Saída da build
+├── index.js              # CommonJS
+├── index.esm.js          # ES Modules
+├── index.d.ts            # Types
+├── styles/
+│   └── index.css         # CSS incluído
+├── package.json          # Package da lib
+└── README.md             # Esta documentação
+```
+
+### Scripts Personalizados
+
+```javascript
+// scripts/build-lib.js - Build customizado
+// scripts/publish-lib.js - Publicação automatizada
+// build-and-publish.sh - Wrapper para comandos
+```
+
+---
+
+## 🎯 Princípios de Desenvolvimento
+
+### ✅ SEMPRE Fazer
+
+- **Imports diretos**: `import { Component } from 'forlogic-core'`
+- **Componentes pequenos**: Máximo 100 linhas
+- **RLS ativado**: Todas as tabelas com políticas
+- **Soft delete**: `is_removed = true`
+- **Props inline**: Evitar interfaces desnecessárias
+- **Configuração declarativa**: Formulários por config
+
+### ❌ NUNCA Fazer
+
+- Barrel exports (`index.ts` desnecessários)
+- Over-engineering (YAGNI)
+- DELETE físico no banco
+- Componentes monolíticos
+- Props drilling excessivo
+- Ignorar políticas RLS
+
+### 🔥 Filosofia
+
+> **"Máxima produtividade com mínima complexidade"**
+
+- ⚡ **Performance**: React Query + otimizações automáticas
+- 🔒 **Segurança**: RLS + JWT + validação
+- 📱 **Responsividade**: Mobile-first automático
+- 🔧 **DX**: Zero config, máxima simplicidade
+- 🎨 **Design**: Sistema consistente e acessível
+
+---
+
+## 📋 Troubleshooting
+
+### Problemas Comuns
+
+**❌ Erro: "RLS policy violation"**
+```sql
+-- Verificar se as políticas estão corretas
+SELECT schemaname, tablename, policyname 
+FROM pg_policies 
+WHERE tablename = 'your_table';
+```
+
+**❌ Erro: "Cannot read property of undefined"**
+```typescript
+// Verificar se o serviço foi configurado corretamente
+export const MyService = createService<MyEntity>({
+  tableName: 'correct_table_name',  // ← Verificar nome
+  schemaName: 'schema_module',            // ← Verificar schema
+  // ...
+});
+```
+
+**❌ Formulário não aparece**
+```tsx
+// Verificar se as seções estão configuradas
+const formSections = [
+  {
+    id: 'section1',           // ← ID obrigatório
+    title: 'Título',          // ← Título obrigatório
+    fields: [                 // ← Array de campos obrigatório
+      {
+        name: 'field1',       // ← Nome obrigatório
+        label: 'Label',       // ← Label obrigatório
+        type: 'text'          // ← Tipo obrigatório
+      }
+    ]
+  }
+];
+```
+
+### Debug Mode
+
+```typescript
+// Ativar logs detalhados
+setupQualiexCore({
+  // ... outras configs
+  debug: true  // Logs no console
+});
+```
+
+---
+
+## 📞 Suporte
+
+### Recursos
+
+- 📖 **Documentação**: Este README
+- 🔧 **Exemplos**: `/src/examples/`
+- 🐛 **Issues**: GitHub Issues
+- 💬 **Suporte**: Equipe ForLogic
+
+### Atualizações
+
+```bash
+# Verificar versão atual
+npm list forlogic-core
+
+# Atualizar para última versão
+npm update forlogic-core
+
+# Migração automática
+npx forlogic-core migrate
+```
+
+---
+
+## 📄 Licença
+
+MIT License - ForLogic © 2025
+
+---
+
+**✨ Sistema ultra-simplificado para máxima produtividade empresarial**
+
+*Arquitetura pensada para desenvolvedores que valorizam simplicidade, performance e segurança.*