forlogic-core 1.5.5 → 1.6.1

package/README.md

@@ -1,8 +1,8 @@
 # 🧱 Projeto atual
 
-**Schema padrão:** `central`
+**Schema padrão:** `processes`
 
-> **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'`.
+> **Nota sobre schemas:** Temos o schema padrão, 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'`.
 
 ---
 
@@ -40,10 +40,412 @@ CREATE INDEX idx_table_user ON schema.table(id_user);
 
 ---
 
+## 📝 CONVENÇÕES DE NOMENCLATURA
+
+### ⚠️ PADRÕES OBRIGATÓRIOS
+
+**Foreign Keys (Chaves Estrangeiras):**
+```typescript
+// ❌ ERRADO
+process_id: string
+user_id: string
+
+// ✅ CORRETO - Sempre prefixo id_
+id_process: string
+id_user: string
+```
+
+**Booleans:**
+```typescript
+// ❌ ERRADO
+active: boolean
+removed: boolean
+
+// ✅ CORRETO - Sempre prefixo is_
+is_active: boolean
+is_removed: boolean
+```
+
+**Timestamps:**
+```typescript
+// ❌ ERRADO
+creation_date: string
+update_time: string
+
+// ✅ CORRETO - Sempre sufixo _at
+created_at: string
+updated_at: string
+deleted_at: string
+```
+
+---
+
+## 🚫 ÍNDICES: ABSOLUTAMENTE PROIBIDO CRIAR AUTOMATICAMENTE
+
+### ⚠️ REGRA DE OURO
+**NUNCA, EM HIPÓTESE ALGUMA, criar índices automaticamente em migrations!**
+
+### 🤔 Por Quê?
+1. **Custo**: Índices ocupam espaço em disco e custam dinheiro
+2. **Performance de Escrita**: Cada índice adiciona overhead em INSERTs/UPDATEs
+3. **Otimização Prematura**: 99% dos índices criados "por precaução" nunca são usados
+4. **Manutenção**: Índices desnecessários dificultam manutenção e análise de queries
+
+### ❌ Casos PROIBIDOS (mesmo que pareçam "boas práticas")
+```sql
+-- ❌ PROIBIDO: Índice em FK "porque é boa prática"
+CREATE INDEX idx_subprocess_process ON subprocesses(id_process);
+
+-- ❌ PROIBIDO: Índice em campo de busca "porque pode ser útil"
+CREATE INDEX idx_process_title ON processes(title);
+
+-- ❌ PROIBIDO: Índice composto "por precaução"
+CREATE INDEX idx_deliverable_status ON deliverables(id_subprocess, is_completed);
+```
+
+### ✅ Quando Criar Índices?
+
+**APENAS** quando:
+1. ✅ **Solicitado explicitamente** pelo usuário
+2. ✅ **Análise de performance** comprovou necessidade (EXPLAIN ANALYZE)
+3. ✅ **Aprovação prévia** do usuário para incluir na migration
+
+### 📋 Checklist OBRIGATÓRIO Antes de Qualquer Migration
+```markdown
+- [ ] A migration NÃO contém NENHUM `CREATE INDEX`?
+- [ ] Se contém, o usuário solicitou EXPLICITAMENTE?
+- [ ] Se contém, foi feita análise de performance (EXPLAIN ANALYZE)?
+- [ ] Se contém, o usuário APROVOU adicionar à migration?
+```
+
+### 🔧 Processo Correto Para Criar Índices
+1. **Usuário solicita** OU problemas de performance são detectados
+2. **Rodar EXPLAIN ANALYZE** para confirmar necessidade
+3. **Perguntar ao usuário**: "Posso criar o índice X na coluna Y? Isso vai melhorar a query Z mas adiciona overhead."
+4. **Aguardar aprovação** do usuário
+5. **Criar migration separada** apenas com os índices aprovados
+
+### 📝 Template de Migration de Índices (quando aprovado)
+```sql
+-- Migration: [TIMESTAMP]_add_performance_indexes.sql
+-- Aprovado em: [DATA] 
+-- Justificativa: [RAZÃO ESPECÍFICA]
+
+CREATE INDEX idx_processes_title ON processes.processes(title);
+-- Melhora busca por título em 80% (EXPLAIN ANALYZE anexo)
+```
+
+---
+
+## 🚫 USAR forlogic-core - NÃO DUPLICAR CÓDIGO
+
+### ⚠️ ARQUIVOS PROIBIDOS DE CRIAR LOCALMENTE
+
+**NUNCA crie estes arquivos localmente:**
+```typescript
+// ❌ PROIBIDO - Usar da lib
+src/lib/utils.ts          // cn() já existe no forlogic-core
+src/components/ui/dialog.tsx
+src/components/ui/button.tsx
+src/components/ui/card.tsx
+src/components/ui/input.tsx
+// ... e TODOS os outros componentes UI
+```
+
+### ✅ Imports Corretos
+
+**Utils (cn):**
+```typescript
+// ❌ ERRADO
+import { cn } from '@/lib/utils'
+
+// ✅ CORRETO
+import { cn } from 'forlogic-core'
+```
+
+**Componentes UI:**
+```typescript
+// ❌ ERRADO
+import { Dialog } from '@/components/ui/dialog'
+import { Button } from '@/components/ui/button'
+
+// ✅ CORRETO
+import { Dialog, DialogContent, DialogTitle, DialogHeader } from 'forlogic-core'
+import { Button } from 'forlogic-core'
+```
+
+### 📋 Checklist Antes de Criar Novo Arquivo
+```markdown
+- [ ] Este componente/util JÁ existe no forlogic-core?
+- [ ] Verifiquei a lista de exports disponíveis abaixo?
+- [ ] Se existe, estou usando o import correto da lib?
+```
+
+### 📦 Componentes e Utils Disponíveis no forlogic-core
+
+**🎨 Componentes UI:**
+```typescript
+// Formulários
+Button, Input, Textarea, Label, Select, SelectContent, 
+SelectItem, SelectTrigger, SelectValue, Checkbox, RadioGroup, 
+RadioGroupItem, Switch
+
+// Layout
+Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle
+Dialog, DialogContent, DialogDescription, DialogFooter, DialogHeader, 
+DialogTitle, DialogTrigger
+Sheet, SheetContent, SheetDescription, SheetHeader, SheetTitle
+Separator, ScrollArea
+
+// Navegação
+Tabs, TabsContent, TabsList, TabsTrigger
+Accordion, AccordionContent, AccordionItem, AccordionTrigger
+DropdownMenu, DropdownMenuContent, DropdownMenuItem
+
+// Feedback
+Alert, AlertDescription, AlertTitle
+Toast, useToast
+Progress
+Badge
+Tooltip, TooltipContent, TooltipProvider, TooltipTrigger
+
+// Tabelas
+Table, TableBody, TableCell, TableHead, TableHeader, TableRow
+```
+
+**🛠️ Utils e Hooks:**
+```typescript
+// Utils
+cn                        // Merge classes Tailwind
+formatDate, formatDatetime // Formatação de datas
+
+// Auth
+useAuth                   // Hook de autenticação
+ProtectedRoute           // Componente de rota protegida
+
+// Qualiex
+useQualiexUsers          // Hook de usuários
+QualiexUserField         // Campo de seleção de usuário
+
+// Supabase
+getSupabaseClient        // Cliente Supabase configurado
+TokenManager             // Gerenciamento de tokens
+
+// Services
+createSimpleService      // Criar service CRUD
+createCrudPage           // Criar página CRUD
+generateCrudConfig       // Gerar config CRUD
+createSimpleSaveHandler  // Handler de save
+
+// Errors
+errorService             // Service de erros
+```
+
+### 🔍 Como Verificar Exports Disponíveis
+
+Se não tiver certeza se algo existe no forlogic-core:
+1. Abra `node_modules/forlogic-core/package.json`
+2. Verifique os exports disponíveis
+3. Em caso de dúvida, pergunte ao usuário antes de criar localmente
+
+---
+
+### 🔽 COMPONENTES AVANÇADOS
+
+#### EntitySelect - Dropdown Genérico com Busca
+
+**Quando usar?**
+
+Use o `EntitySelect` para criar dropdowns com busca e ordenação para qualquer entidade do sistema:
+- ✅ Seleção de processos, departamentos, categorias, etc
+- ✅ Busca em tempo real
+- ✅ Ordenação alfabética automática
+- ✅ Estados de loading e erro inclusos
+
+**Uso Básico:**
+
+```typescript
+import { EntitySelect } from 'forlogic-core';
+import { useProcesses } from './processService';
+
+function MyForm() {
+  const { data: processes = [], isLoading, error } = useProcesses();
+  const [selectedId, setSelectedId] = useState('');
+
+  return (
+    <EntitySelect
+      value={selectedId}
+      onChange={setSelectedId}
+      items={processes}
+      isLoading={isLoading}
+      error={error}
+      getItemValue={(process) => process.id}
+      getItemLabel={(process) => process.title}
+      placeholder="Selecionar processo"
+      searchPlaceholder="Buscar processo..."
+    />
+  );
+}
+```
+
+**Props do EntitySelect:**
+
+| Prop | Tipo | Obrigatório | Descrição |
+|------|------|-------------|-----------|
+| `items` | `T[]` | ✅ | Array de itens para seleção |
+| `getItemValue` | `(item: T) => string` | ✅ | Função que retorna o valor único do item (ex: `id`) |
+| `getItemLabel` | `(item: T) => string` | ✅ | Função que retorna o texto exibido |
+| `value` | `string` | ❌ | Valor selecionado |
+| `onChange` | `(value: string) => void` | ❌ | Callback quando valor muda |
+| `isLoading` | `boolean` | ❌ | Mostra skeleton durante carregamento |
+| `error` | `Error \| null` | ❌ | Mostra mensagem de erro |
+| `placeholder` | `string` | ❌ | Placeholder do select (padrão: "Selecionar...") |
+| `searchPlaceholder` | `string` | ❌ | Placeholder da busca (padrão: "Buscar...") |
+| `emptyMessage` | `string` | ❌ | Mensagem quando não há itens |
+| `noResultsMessage` | `string` | ❌ | Mensagem quando busca não encontra resultados |
+| `sortItems` | `(a: T, b: T) => number` | ❌ | Função customizada de ordenação (padrão: alfabético) |
+| `disabled` | `boolean` | ❌ | Desabilita o select |
+| `className` | `string` | ❌ | Classes CSS adicionais |
+
+**Ordenação Customizada:**
+
+Por padrão, itens são ordenados alfabeticamente pelo `label`. Para customizar:
+
+```typescript
+<EntitySelect
+  items={employees}
+  getItemValue={(e) => e.id}
+  getItemLabel={(e) => `${e.name} - ${e.department}`}
+  sortItems={(a, b) => {
+    // Ordenar por departamento, depois por nome
+    if (a.department !== b.department) {
+      return a.department.localeCompare(b.department);
+    }
+    return a.name.localeCompare(b.name);
+  }}
+/>
+```
+
+**Integração com React Hook Form:**
+
+```typescript
+import { useForm } from 'react-hook-form';
+import { EntitySelect } from 'forlogic-core';
+
+function MyForm() {
+  const { control } = useForm();
+  const { data: categories = [] } = useCategories();
+
+  return (
+    <FormField
+      control={control}
+      name="category_id"
+      render={({ field }) => (
+        <FormItem>
+          <FormLabel>Categoria</FormLabel>
+          <FormControl>
+            <EntitySelect
+              value={field.value}
+              onChange={field.onChange}
+              items={categories}
+              getItemValue={(c) => c.id}
+              getItemLabel={(c) => c.name}
+              placeholder="Selecionar categoria"
+            />
+          </FormControl>
+          <FormMessage />
+        </FormItem>
+      )}
+    />
+  );
+}
+```
+
+**Usando em Formulários CRUD:**
+
+Para usar o `EntitySelect` em formulários CRUD gerados automaticamente, você precisa criar um componente wrapper e registrá-lo no `BaseForm.tsx`:
+
+```typescript
+// 1. Criar wrapper do EntitySelect
+// src/components/ProcessSelect.tsx
+import { EntitySelect } from 'forlogic-core';
+import { useProcesses } from '@/processes/processService';
+
+export function ProcessSelect({ value, onChange, disabled }: any) {
+  const { data: processes = [], isLoading, error } = useProcesses();
+  
+  return (
+    <EntitySelect
+      value={value}
+      onChange={onChange}
+      items={processes}
+      isLoading={isLoading}
+      error={error}
+      getItemValue={(p) => p.id}
+      getItemLabel={(p) => p.title}
+      disabled={disabled}
+      placeholder="Selecionar processo"
+    />
+  );
+}
+
+// 2. Registrar no BaseForm.tsx (lib/crud/components/BaseForm.tsx)
+// Adicionar no switch case do renderField:
+case 'process-select':
+  return <ProcessSelect {...commonFieldProps} />;
+
+// 3. Usar na configuração do formulário
+{
+  name: 'id_process',
+  label: 'Processo',
+  type: 'process-select' as const,
+  required: true
+}
+```
+
+**Exemplo Completo:**
+
+```typescript
+// src/departments/DepartmentSelect.tsx
+import { EntitySelect } from 'forlogic-core';
+import { useDepartments } from './departmentService';
+
+interface DepartmentSelectProps {
+  value?: string;
+  onChange?: (value: string) => void;
+  disabled?: boolean;
+  className?: string;
+}
+
+export function DepartmentSelect(props: DepartmentSelectProps) {
+  const { data: departments = [], isLoading, error } = useDepartments();
+  
+  return (
+    <EntitySelect
+      {...props}
+      items={departments}
+      isLoading={isLoading}
+      error={error}
+      getItemValue={(dept) => dept.id}
+      getItemLabel={(dept) => dept.name}
+      placeholder="Selecionar departamento"
+      searchPlaceholder="Buscar departamento..."
+      emptyMessage="Nenhum departamento cadastrado"
+      noResultsMessage="Nenhum departamento encontrado com esse nome"
+    />
+  );
+}
+```
+
+---
+
 ### ✅ CHECKLIST (antes de implementar)
 
 - [ ] Schema `schema` especificado em queries e service?
 - [ ] RLS usando `alias` (nunca `id_user`)?
+- [ ] **Nomenclatura correta**: `id_<entity>`, `is_<bool>`, `<action>_at`?
+- [ ] **Migration SEM índices** (ou aprovados pelo usuário)?
+- [ ] **Imports do forlogic-core** (não criar utils.ts ou ui/* localmente)?
 - [ ] Preservar `item.id` no update?
 - [ ] Config gerado com `useMemo()`?
 - [ ] `<Outlet />` no componente pai?