forlogic-core 1.6.12 → 1.7.0

package/dist/README.md

@@ -220,6 +220,7 @@ Table, TableBody, TableCell, TableHead, TableHeader, TableRow
 // Utils
 cn                        // Merge classes Tailwind
 formatDate, formatDatetime // Formatação de datas
+handleExternalLink       // Helper para links externos
 
 // Auth
 useAuth                   // Hook de autenticação
@@ -237,7 +238,6 @@ TokenManager             // Gerenciamento de tokens
 createSimpleService      // Criar service CRUD
 createCrudPage           // Criar página CRUD
 generateCrudConfig       // Gerar config CRUD
-createSimpleSaveHandler  // Handler de save
 
 // Errors
 errorService             // Service de erros
@@ -455,6 +455,222 @@ export function DepartmentSelect(props: DepartmentSelectProps) {
 
 ---
 
+## 🏗️ ARQUITETURA CRUD
+
+O sistema CRUD do forlogic-core segue uma arquitetura em camadas que separa responsabilidades e facilita manutenção:
+
+```mermaid
+graph TD
+    A[types.ts<br/>Interfaces TypeScript] --> B[Service.ts<br/>createSimpleService]
+    B --> C[useCrudHook<br/>React Query]
+    C --> D[Page.tsx<br/>Componente Principal]
+    D --> E[createCrudPage<br/>Gerador de CRUD]
+    E --> F[CrudTable<br/>Tabela]
+    E --> G[BaseForm<br/>Formulário]
+    E --> H[BulkActionBar<br/>Ações em Massa]
+    
+    I[(Supabase DB)] -.->|RLS + Soft Delete| B
+    J[Qualiex API] -.->|responsible_name| B
+    
+    style A fill:#e1f5ff
+    style B fill:#fff4e1
+    style C fill:#ffe1f5
+    style D fill:#e1ffe1
+    style E fill:#f5e1ff
+    style F fill:#ffe1e1
+    style G fill:#ffe1e1
+    style H fill:#ffe1e1
+```
+
+### **📁 Estrutura de Pastas Obrigatória**
+
+```
+src/
+├── examples/                    # 📁 Módulo completo
+│   ├── example.ts              # 🔷 Types (Entity + Payloads)
+│   ├── ExampleService.ts       # ⚙️ Service (createSimpleService)
+│   ├── ExamplesPage.tsx        # 🎨 Página CRUD
+│   └── components/             # 📦 Componentes específicos (opcional)
+│       └── ExampleSelect.tsx
+```
+
+### **✅ Checklist de Implementação**
+
+```
+✅ OBRIGATÓRIOS:
+  □ types.ts - Definir Example extends BaseEntity com campos explícitos
+  □ types.ts - Usar Omit<> e Partial<> para CreatePayload e UpdatePayload
+  □ Service.ts - Usar createSimpleService<Example, CreatePayload, UpdatePayload>
+  □ Service.ts - Configurar tableName, entityName, searchFields
+  □ Page.tsx - Chamar useExamplesCrud() DENTRO do componente
+  □ Page.tsx - Usar useMemo() para columns, formSections, config
+  □ Page.tsx - Usar manager.save() ao invés de createSimpleSaveHandler
+
+🔧 OPCIONAIS:
+  □ Filtros customizados (backend via additionalFilters recomendado)
+  □ onToggleStatus para ativar/desativar
+  □ Renderização customizada nas colunas
+  □ Campos de formulário customizados
+```
+
+### **🔄 Fluxo de Dados**
+
+1. **types.ts**: Define interfaces TypeScript (Entity, CreatePayload, UpdatePayload)
+2. **Service.ts**: Gera service com `createSimpleService` (métodos CRUD + hook)
+3. **useCrudHook**: Hook React Query que gerencia estado, cache, loading
+4. **Page.tsx**: Componente que usa o hook e define configuração visual
+5. **createCrudPage**: Gera componente de página completo (tabela + formulário)
+6. **UI Components**: Renderiza CrudTable, CrudForm, BulkActionBar, etc.
+
+### **🔐 Integrações Automáticas**
+
+- 🔒 **RLS (Row Level Security)**: Filtra por `alias`
+- 🗑️ **Soft Delete**: Marca `is_removed = true` ao invés de deletar
+- 👤 **Qualiex Enrichment**: Adiciona `responsible_name` aos registros
+- 🔍 **Busca Global**: Header com busca automática integrada ao CRUD
+
+---
+
+## 🔍 Busca Global no Header
+
+O `AppHeader` inclui uma barra de busca integrada que funciona automaticamente com o sistema CRUD.
+
+### **Como Funciona:**
+
+1. **Ativação Automática**: A busca aparece automaticamente em páginas CRUD quando `isSearchVisible = true` no AuthContext
+2. **Debounce**: Usa delay de 500ms (configurável via `SEARCH_CONFIG.debounceDelay`) para evitar queries excessivas
+3. **URL Sync**: Mantém o termo de busca sincronizado na URL (`?search=termo`)
+4. **Reset de Paginação**: Ao buscar, reseta automaticamente para página 1
+5. **Botão Refresh**: Atualiza os dados da página atual
+
+### **Ativar Busca em uma Página:**
+
+```typescript
+// No AuthContext ou componente pai
+const [isSearchVisible, setIsSearchVisible] = useState(true);
+```
+
+### **Integração com CRUD:**
+
+O hook `useCrud` já lê automaticamente o parâmetro `search` da URL:
+
+```typescript
+// lib/crud/hooks/useCrud.ts
+const [searchParams] = useSearchParams();
+const searchTerm = searchParams.get('search') || '';
+
+// A busca é aplicada automaticamente nos searchFields configurados no service
+```
+
+### **Configurar Campos de Busca:**
+
+```typescript
+// src/examples/ExampleService.ts
+export const { service, useCrudHook } = createSimpleService<Example>({
+  tableName: 'examples',
+  entityName: 'exemplo',
+  schemaName: 'central',
+  searchFields: ['title', 'description', 'tags'], // 🔍 Campos pesquisáveis
+});
+```
+
+### **Customizar Placeholder:**
+
+O placeholder da busca se adapta automaticamente à rota. Para customizar:
+
+```tsx
+// AppHeader.tsx - Modificação direta (afeta todas as rotas)
+<Input
+  placeholder={location.pathname === '/wiki' ? "Buscar artigos..." : "Buscar..."}
+/>
+
+// OU usar metadata (recomendado para páginas específicas)
+import { usePageMetadataContext } from 'forlogic-core';
+
+export default function MyPage() {
+  const { setMetadata } = usePageMetadataContext();
+  
+  useEffect(() => {
+    setMetadata({
+      title: 'Meus Itens',
+      subtitle: 'Gerencie seus itens',
+      // Futura feature: searchPlaceholder: 'Buscar por nome...'
+    });
+  }, []);
+}
+```
+
+### **Configuração Avançada:**
+
+```typescript
+// lib/config/index.ts
+export const SEARCH_CONFIG = {
+  debounceDelay: 500, // ms - ajuste conforme necessidade
+} as const;
+```
+
+**Quando aumentar o delay:**
+- ✅ Muitos usuários simultâneos (reduz carga no servidor)
+- ✅ Campos de busca muito amplos (muitos registros)
+- ✅ Backend com rate limiting
+
+**Quando reduzir o delay:**
+- ✅ Poucos registros (resposta instantânea)
+- ✅ Busca crítica para UX (feedback imediato)
+
+### **Controle Programático:**
+
+```typescript
+// Limpar busca programaticamente
+import { useSearchParams } from 'react-router-dom';
+
+const [searchParams, setSearchParams] = useSearchParams();
+
+const clearSearch = () => {
+  const newParams = new URLSearchParams(searchParams);
+  newParams.delete('search');
+  newParams.delete('page');
+  setSearchParams(newParams);
+};
+
+// Definir busca programaticamente
+const setSearch = (term: string) => {
+  const newParams = new URLSearchParams(searchParams);
+  newParams.set('search', term);
+  newParams.set('page', '1'); // Reset para primeira página
+  setSearchParams(newParams);
+};
+```
+
+### **Refresh Manual:**
+
+O botão de refresh chama a função `refreshData` do AuthContext:
+
+```typescript
+// Implementar no seu AuthContext
+const refreshData = useCallback(() => {
+  queryClient.invalidateQueries(); // Invalida cache do React Query
+  toast.success('Dados atualizados');
+}, [queryClient]);
+```
+
+### **Arquitetura da Busca:**
+
+```mermaid
+graph LR
+    A[Usuário digita] --> B[useState local]
+    B --> C[useDebounce 500ms]
+    C --> D[URL ?search=termo]
+    D --> E[useCrud lê URL]
+    E --> F[Supabase Query]
+    F --> G[Resultados filtrados]
+    
+    style C fill:#d4f4dd
+    style F fill:#ffd4d4
+```
+
+---
+
 ## 🚀 QUICK START - Criar CRUD Completo
 
 ### **1️⃣ Type**
@@ -491,24 +707,27 @@ export const { service: processService, useCrudHook: useProcesses } =
   });
 ```
 
-### **3️⃣ Save Handler**
+### **3️⃣ Save Handler (Integrado ao useCrud)**
 ```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
-  });
-};
+export default function ProcessesPage() {
+  const manager = useProcesses();
+
+  const handleSave = (data: any) => {
+    manager.save(data, (d) => ({
+      title: d.title,
+      description: d.description || null,
+      status: d.status || 'draft'
+    }));
+  };
+
+  // O método save() automaticamente:
+  // ✅ Detecta se é CREATE (sem id) ou UPDATE (com id)
+  // ✅ Injeta o alias no CREATE
+  // ✅ Chama createEntity ou updateEntity
+  // ✅ Fecha o modal automaticamente após sucesso
+}
 ```
 
 ### **4️⃣ Config (com useMemo)**
@@ -571,6 +790,282 @@ function ProcessLayout() {
 
 ---
 
+## 🔄 GUIA DE MIGRAÇÃO - v2.0
+
+Se você tem projetos usando versões antigas do `forlogic-core`, siga este guia para atualizar.
+
+### **📦 Atualizar Versão**
+
+```bash
+npm install forlogic-core@latest
+```
+
+---
+
+### **1️⃣ Migração de Tipos (Breaking Change)**
+
+#### **❌ ANTES (Versão Antiga):**
+```typescript
+import { 
+  ContentEntity, 
+  VisualEntity, 
+  UserRelatedEntity, 
+  ActivableEntity,
+  FormEntity 
+} from 'forlogic-core';
+
+export interface Example extends 
+  ContentEntity,
+  VisualEntity,
+  UserRelatedEntity,
+  ActivableEntity,
+  FormEntity {}
+
+export interface CreateExamplePayload {
+  title: string;
+  description?: string | null;
+  alias: string;  // ⚠️ Obrigatório manualmente
+  color?: string;
+  icon_name?: string;
+  id_user?: string | null;
+  is_actived?: boolean;
+  url_field?: string | null;
+  date_field?: string | null;
+}
+
+export interface UpdateExamplePayload extends Partial<CreateExamplePayload> {
+  title: string;  // Override
+}
+```
+
+#### **✅ DEPOIS (Nova API):**
+```typescript
+import { BaseEntity } from 'forlogic-core';
+
+export interface Example extends BaseEntity {
+  title: string;
+  description?: string | null;
+  color?: string;
+  icon_name?: string;
+  id_user?: string | null;
+  responsible_name?: string;
+  url_field?: string | null;
+  date_field?: string | null;
+  // is_actived agora vem de BaseEntity!
+}
+
+export type CreateExamplePayload = Omit<
+  Example, 
+  keyof BaseEntity | 'responsible_name'
+>;
+
+export type UpdateExamplePayload = Partial<CreateExamplePayload>;
+```
+
+**📝 Mudanças:**
+- ❌ **REMOVIDO**: Helper interfaces (`ContentEntity`, `VisualEntity`, etc)
+- ✅ **NOVO**: Apenas `BaseEntity` + campos explícitos
+- ✅ **NOVO**: `is_actived` agora é campo padrão de `BaseEntity`
+- ✅ **NOVO**: Use `Omit<>` e `Partial<>` para Payloads
+
+---
+
+### **2️⃣ Migração de Save Handler (Breaking Change)**
+
+#### **❌ ANTES (createSimpleSaveHandler):**
+```typescript
+import { createSimpleSaveHandler, useAuth } from 'forlogic-core';
+
+const { alias: currentAlias } = useAuth();
+
+const handleSave = createSimpleSaveHandler(
+  manager,
+  // createTransform
+  (data) => ({
+    title: data.title,
+    description: data.description || null,
+    alias: currentAlias  // ⚠️ Injetar manualmente
+  }),
+  // updateTransform
+  (data) => ({
+    title: data.title,
+    description: data.description || null
+  })
+);
+```
+
+#### **✅ DEPOIS (manager.save):**
+```typescript
+const handleSave = (data: any) => {
+  manager.save(data, (d) => ({
+    title: d.title,
+    description: d.description || null
+  }));
+};
+
+// O método save() faz automaticamente:
+// ✅ Detecta CREATE vs UPDATE (baseado em data.id)
+// ✅ Injeta alias no CREATE
+// ✅ Fecha modal após sucesso
+```
+
+**📝 Mudanças:**
+- ❌ **REMOVIDO**: `createSimpleSaveHandler`
+- ❌ **REMOVIDO**: Import de `useAuth` para pegar `alias`
+- ✅ **NOVO**: `manager.save(data, transform)`
+- ✅ **NOVO**: Alias injetado automaticamente
+
+---
+
+### **3️⃣ Migração de Campos de Formulário**
+
+#### **❌ ANTES (Tipos Múltiplos):**
+```typescript
+{
+  name: 'id_user',
+  label: 'Responsável',
+  type: 'simple-qualiex-user-field',  // OU 'single-responsible-select'
+  required: true
+}
+```
+
+#### **✅ DEPOIS (Tipo Unificado):**
+```typescript
+{
+  name: 'id_user',
+  label: 'Responsável',
+  type: 'user-select',
+  mode: 'single',  // OU 'multiple'
+  required: true
+}
+```
+
+**📝 Mudanças:**
+- ❌ **REMOVIDO**: `'simple-qualiex-user-field'`, `'single-responsible-select'`
+- ✅ **NOVO**: Apenas `'user-select'` com parâmetro `mode`
+
+---
+
+### **4️⃣ Migração de Imports**
+
+#### **❌ ANTES:**
+```typescript
+import { createSimpleSaveHandler } from 'forlogic-core';
+import { ContentEntity, VisualEntity, ... } from 'forlogic-core';
+```
+
+#### **✅ DEPOIS:**
+```typescript
+// createSimpleSaveHandler removido (usar manager.save)
+import { BaseEntity } from 'forlogic-core';
+import { handleExternalLink } from 'forlogic-core';  // NOVO helper
+```
+
+**📝 Mudanças:**
+- ❌ **REMOVIDO**: `createSimpleSaveHandler`
+- ❌ **REMOVIDO**: Helper interfaces de tipos
+- ✅ **NOVO**: `handleExternalLink` (helper de links externos)
+
+---
+
+### **5️⃣ Migração de Filtros Customizados**
+
+#### **❌ ANTES (Filtro Frontend):**
+```typescript
+const [statusFilter, setStatusFilter] = useState('active');
+
+const filteredEntities = useMemo(() => {
+  return manager.entities.filter(e => 
+    statusFilter === 'all' ? true : e.is_actived
+  );
+}, [manager.entities, statusFilter]);
+
+const filteredManager = useMemo(() => ({
+  ...manager,
+  entities: filteredEntities
+}), [manager, filteredEntities]);
+
+// Passar filteredManager para createCrudPage
+```
+
+#### **✅ DEPOIS (Filtro Backend - Recomendado):**
+```typescript
+const [statusFilter, setStatusFilter] = useState<boolean | 'all'>(true);
+
+// Passar filtro direto para o hook
+const manager = useExamplesCrud(
+  statusFilter === 'all' ? {} : { is_actived: statusFilter }
+);
+
+// Passar manager original (já vem filtrado)
+const CrudPage = createCrudPage({ manager, config, onSave });
+```
+
+**📝 Mudanças:**
+- ✅ **RECOMENDADO**: Filtro aplicado no backend (melhor performance)
+- ✅ **NOVO**: Hook aceita `additionalFilters` como parâmetro
+- ❌ **EVITAR**: Filtro frontend (só para casos complexos)
+
+---
+
+### **6️⃣ Checklist de Migração**
+
+Use este checklist para validar que seu projeto foi migrado corretamente:
+
+#### **Types (`example.ts`):**
+- [ ] Removido imports de helper interfaces (`ContentEntity`, `VisualEntity`, etc)
+- [ ] Interface principal agora estende apenas `BaseEntity`
+- [ ] Campos explícitos declarados na interface
+- [ ] `CreatePayload` usa `Omit<Example, keyof BaseEntity | 'responsible_name'>`
+- [ ] `UpdatePayload` usa `Partial<CreatePayload>`
+- [ ] Removido `alias: string` do `CreatePayload`
+- [ ] Removido interfaces/types não usados (`ExampleFilters`, `ExampleSortField`, `ExampleInsert`, `ExampleUpdate`)
+
+#### **Service (`ExampleService.ts`):**
+- [ ] Nenhuma mudança necessária (API permanece igual)
+
+#### **Page (`ExamplesPage.tsx`):**
+- [ ] Removido import de `createSimpleSaveHandler`
+- [ ] Removido import de `useAuth` (se usado apenas para alias)
+- [ ] Substituído `createSimpleSaveHandler` por `manager.save()`
+- [ ] Campos de formulário tipo `'user-select'` ao invés de tipos antigos
+- [ ] Filtros usando backend (`useExamplesCrud(filters)`) quando possível
+- [ ] Substituído lógica de links externos por `handleExternalLink` helper
+
+#### **Testes:**
+- [ ] Build sem erros TypeScript (`npm run build`)
+- [ ] Página carrega sem erros
+- [ ] Criar novo item funciona (alias injetado corretamente)
+- [ ] Editar item funciona
+- [ ] Deletar item funciona
+- [ ] Filtros funcionam corretamente
+- [ ] Paginação funciona
+- [ ] Busca funciona
+
+---
+
+### **7️⃣ Exemplo Completo de Migração**
+
+**Ver arquivo `src/examples/ExamplesPage.tsx` do projeto para exemplo 100% atualizado.**
+
+---
+
+### **❓ Problemas na Migração?**
+
+#### **Erro: "Property 'save' does not exist on type..."**
+- ✅ **Solução**: Atualize `forlogic-core` para versão mais recente
+- ✅ **Comando**: `npm install forlogic-core@latest`
+
+#### **Erro: "Cannot find module 'ContentEntity'"**
+- ✅ **Solução**: Remova imports de helper interfaces e use `BaseEntity`
+- ✅ **Ver**: Seção "1️⃣ Migração de Tipos" acima
+
+#### **Erro: "alias is required but not provided"**
+- ✅ **Solução**: Use `manager.save()` ao invés de `createEntity` direto
+- ✅ **Ver**: Seção "2️⃣ Migração de Save Handler" acima
+
+---
+
 ## 🎯 AÇÕES EM LOTE (Bulk Actions)
 
 O sistema CRUD suporta seleção múltipla e ações em lote usando checkboxes.
@@ -728,69 +1223,1068 @@ export function ProcessesPage() {
 
 ---
 
-### 🔗 Integração Qualiex (opcional)
+## 🎓 TUTORIAL COMPLETO: CRUD de Examples (Copy-Paste Ready)
 
-**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)
-```
+Este tutorial mostra como criar um CRUD completo usando o módulo **Examples** como referência. É um exemplo funcional 100% que você pode copiar e adaptar.
+
+### **Passo 1: Criar Types (`src/examples/example.ts`)**
 
-**Componentes prontos:**
 ```typescript
-import { QualiexUserField, QualiexResponsibleSelectField } from 'forlogic-core';
+// ============= EXAMPLE MODULE TYPES =============
+import { 
+  ContentEntity,      // title, description
+  VisualEntity,       // color, icon_name
+  UserRelatedEntity,  // id_user, responsible_name
+  ActivableEntity,    // is_actived
+  FormEntity,         // url_field, date_field
+  FilterState, 
+  EntitySortField 
+} from 'forlogic-core';
 
-// Select de usuários Qualiex
-<QualiexResponsibleSelectField 
-  value={form.watch('id_user')}
-  onChange={(userId) => form.setValue('id_user', userId)}
-/>
+/**
+ * Example - Entidade completa de exemplo
+ * 
+ * ✅ Campos Customizados:
+ * - title, description (conteúdo)
+ * - color, icon_name (visual)
+ * - id_user, responsible_name (usuário - enriquecido via Qualiex)
+ * - url_field, date_field (formulário)
+ * 
+ * 🔒 Campos Herdados de BaseEntity (automáticos):
+ * - id: string
+ * - alias: string
+ * - company_id: string
+ * - is_actived: boolean
+ * - is_removed: boolean
+ * - created_at: string
+ * - updated_at: string
+ */
+export interface Example extends BaseEntity {
+  title: string;
+  description?: string | null;
+  color?: string;
+  icon_name?: string;
+  id_user?: string | null;
+  responsible_name?: string;  // Enriquecido via Qualiex
+  url_field?: string | null;
+  date_field?: string | null;
+}
+
+/**
+ * CreateExamplePayload - Dados para CRIAR novo registro
+ * 
+ * ⚠️ IMPORTANTE:
+ * - Campo `alias` é injetado AUTOMATICAMENTE pelo manager.save()
+ * - Campos opcionais devem ter `| null`
+ * - NÃO incluir id, created_at, updated_at (gerados automaticamente)
+ */
+export type CreateExamplePayload = Omit<
+  Example, 
+  keyof BaseEntity | 'responsible_name'
+>;
+
+/**
+ * UpdateExamplePayload - Dados para ATUALIZAR registro existente
+ * 
+ * 📝 Pattern:
+ * - Todos os campos são opcionais (Partial)
+ */
+export type UpdateExamplePayload = Partial<CreateExamplePayload>;
 ```
 
-**Componentes em formulários CRUD:**
+**📖 Explicação Detalhada:**
+- **Composição de Interfaces:** Ao invés de redefinir campos, herda de interfaces prontas da lib
+- **`alias` no CreatePayload:** RLS do Supabase precisa desse campo para funcionar
+- **`Partial<>` no UpdatePayload:** Permite updates parciais (só manda os campos que mudaram)
+- **Campos `| null`:** Importante para sincronizar com Supabase (que aceita NULL)
+
+---
+
+### **Passo 2: Criar Service (`src/examples/ExampleService.ts`)**
+
 ```typescript
-// Para seleção de usuário
-{
-  name: 'responsible_id',
-  label: 'Responsável',
-  type: 'simple-qualiex-user-field' as const,
-  required: true
-}
+// ============= SIMPLIFIED SERVICE (MIGRATED) =============
 
-// Para seleção de responsável
-{
-  name: 'responsible_id',
-  label: 'Responsável',
-  type: 'single-responsible-select' as const,
-  required: true
-}
+import { createSimpleService } from 'forlogic-core';
+import type { Example, CreateExamplePayload, UpdateExamplePayload } from './example';
+
+/**
+ * ExampleService - Service CRUD completo gerado automaticamente
+ * 
+ * ✅ O que é gerado:
+ * - service.getAll(params)
+ * - service.getById(id)
+ * - service.create(data)
+ * - service.update(id, data)
+ * - service.delete(id)
+ * - useCrudHook() - Hook React Query integrado
+ * 
+ * 🔧 Configuração:
+ * - tableName: Nome da tabela no Supabase (schema: central)
+ * - entityName: Nome legível para toasts ("Exemplo criado com sucesso")
+ * - searchFields: Campos que serão pesquisados pelo filtro de busca
+ * - enableQualiexEnrichment: true → adiciona responsible_name automaticamente
+ * 
+ * 📊 Estrutura de Tabela Esperada (Supabase):
+ * CREATE TABLE central.examples (
+ *   id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+ *   alias TEXT NOT NULL,                -- ✅ Para RLS (obrigatório)
+ *   is_removed BOOLEAN DEFAULT false,   -- ✅ Para soft delete (obrigatório)
+ *   created_at TIMESTAMPTZ DEFAULT now(),
+ *   updated_at TIMESTAMPTZ DEFAULT now(),
+ *   title TEXT NOT NULL,
+ *   description TEXT,
+ *   id_user TEXT,
+ *   is_actived BOOLEAN DEFAULT true,
+ *   color TEXT,
+ *   icon_name TEXT,
+ *   url_field TEXT,
+ *   date_field DATE
+ * );
+ */
+export const { service: ExampleService, useCrudHook: useExamplesCrud } = 
+  createSimpleService<Example, CreateExamplePayload, UpdateExamplePayload>({
+    tableName: 'examples',              // 🗃️ Tabela no Supabase
+    entityName: 'Exemplo',              // 📣 Nome para mensagens
+    searchFields: ['title'],            // 🔍 Campos de busca textual
+    schemaName: 'central',              // 📂 Schema (default: 'central')
+    enableQualiexEnrichment: true       // 👤 Adiciona responsible_name
+  });
 ```
 
-**Componentes customizados:**
+**📖 Explicação Detalhada:**
+- **Uma linha, tudo pronto:** `createSimpleService` gera todo o boilerplate
+- **Soft delete automático:** `deleteEntity()` marca `is_removed = true`, não deleta fisicamente
+- **RLS automático:** Filtra por `alias` automaticamente
+- **Enrichment Qualiex:** Busca o `responsible_name` na API Qualiex e adiciona aos registros
 
-Você pode criar e usar componentes customizados nos formulários para necessidades específicas:
+---
+
+### **Passo 3: Criar Página (`src/examples/ExamplesPage.tsx`) - PARTE 1**
+
+#### **Imports e Configuração de Colunas**
 
 ```typescript
-// Exemplo de campo customizado
-{
-  name: 'custom_field',
-  label: 'Campo Customizado',
-  type: 'my-custom-component' as const,
-  required: true
-}
+// ============= EXAMPLES PAGE (MIGRATED TO NEW API) =============
+
+import { useExamplesCrud } from './ExampleService';
+import {
+  createCrudPage,
+  createSimpleSaveHandler,
+  formatDatetime,
+  useAuth,
+  type CrudColumn,
+  EntitySelect
+} from 'forlogic-core';
+import type { Example, CreateExamplePayload, UpdateExamplePayload } from './example';
+import { ExternalLink, Star } from 'lucide-react';
+import { toast } from 'sonner';
+import * as LucideIcons from 'lucide-react';
+import { useState, useMemo } from 'react';
+
+/**
+ * ⚠️ IMPORTANTE: Importar `cn` da lib, NÃO do utils local
+ * ❌ ERRADO: import { cn } from '@/lib/utils'
+ * ✅ CORRETO: import { cn } from 'forlogic-core'
+ */
 ```
 
-> **Nota:** Componentes customizados devem ser registrados no `BaseForm.tsx` para funcionarem corretamente nos formulários CRUD.
+---
+
+### **Passo 4: Configuração do Formulário**
 
-**⚠️ CRÍTICO:** Requests Qualiex exigem header `un-alias`:
 ```typescript
-// ✅ Já configurado no BaseService automaticamente
-headers: { 'un-alias': 'true' }
+/**
+ * 📝 CONFIGURAÇÃO DO FORMULÁRIO
+ * 
+ * Organizado em seções (formSections) com campos (fields).
+ * 
+ * Tipos de campos suportados:
+ * - 'text' - Input de texto simples
+ * - 'email' - Input de email com validação
+ * - 'textarea' - Área de texto grande
+ * - 'select' - Dropdown com options
+ * - 'color-picker' - Seletor de cor
+ * - 'icon-picker' - Seletor de ícone Lucide
+ * - 'user-select' - Seletor de usuário (com mode: 'single' | 'multiple')
+ * - 'custom' - Campo completamente customizado
+ * - 'group' - Agrupa campos horizontalmente
+ */
+const formSections = [{
+  id: 'general',
+  title: 'Informações Gerais',
+  fields: [
+    {
+      // 🎯 GROUP: Agrupa campos horizontalmente
+      type: 'group' as any,
+      name: 'title-group',
+      label: '',
+      layout: 'horizontal' as const,
+      className: 'grid grid-cols-1 sm:grid-cols-2 gap-6',
+      fields: [
+        {
+          name: 'title',
+          label: 'Título',
+          type: 'text' as const,
+          required: true,
+          placeholder: 'Digite o título do exemplo',
+        },
+        {
+          name: 'id_user',
+          label: 'Responsável',
+          type: 'user-select' as const,  // 👤 Campo unificado
+          mode: 'single',
+          required: true,
+          placeholder: 'Selecionar responsável',
+          defaultValue: '',
+        }
+      ],
+    },
+    {
+      name: 'url_field',
+      label: 'Link',
+      type: 'text' as const,
+      required: false,
+      placeholder: 'https://exemplo.com'
+    },
+    {
+      name: 'description',
+      label: 'Descrição',
+      type: 'textarea' as const,
+      required: false,
+      placeholder: 'Descrição detalhada do exemplo'
+    },
+    {
+      // 🎨 GROUP: Visual (cor + ícone)
+      type: 'group' as any,
+      name: 'visual-group',
+      label: 'Visual',
+      layout: 'horizontal' as const,
+      className: 'grid grid-cols-1 sm:grid-cols-2 gap-6',
+      fields: [
+        {
+          name: 'color',
+          label: 'Cor',
+          type: 'color-picker' as const,  // 🎨 Color picker da lib
+          required: false,
+          defaultValue: '#3b82f6'
+        },
+        {
+          name: 'icon_name',
+          label: 'Ícone',
+          type: 'icon-picker' as const,  // 🔷 Icon picker da lib
+          required: false,
+          defaultValue: 'Star'
+        }
+      ]
+    }
+  ],
+}];
 ```
 
 ---
 
+### **Passo 5: Componente Principal com Filtros**
+
+Ver código completo no arquivo `src/examples/ExamplesPage.tsx` do projeto.
+
+**Estrutura básica:**
+1. Hooks no topo
+2. Estados de filtros com `useState`
+3. Estados derivados com `useMemo`
+4. Manager customizado com `useMemo`
+5. Handlers (`handleToggleStatus`, `handleSave`)
+6. Criar página com `createCrudPage`
+
+---
+
+## 🎯 PADRÕES DE FILTROS CUSTOMIZADOS
+
+### **Pattern 1: Filtro de Status (Backend - Recomendado)**
+
+```typescript
+// ✅ PADRÃO BACKEND: Filtro aplicado na query SQL (melhor performance)
+
+// 1) Estado do filtro
+const [statusFilter, setStatusFilter] = useState<boolean | 'all'>(true);
+
+// 2) Passar filtro para o hook (aplica no backend)
+const manager = useExamplesCrud(
+  statusFilter === 'all' ? {} : { is_actived: statusFilter }
+);
+
+// 3) Componente do filtro
+const StatusFilter = () => (
+  <EntitySelect
+    value={String(statusFilter)}
+    onChange={(v) => setStatusFilter(v === 'all' ? 'all' : v === 'true')}
+    items={[
+      { id: 'true', name: 'Ativo' },
+      { id: 'false', name: 'Inativo' },
+      { id: 'all', name: '[Todos]' }
+    ]}
+    getItemValue={(item) => item.id}
+    getItemLabel={(item) => item.name}
+    placeholder="Status"
+    className="w-full sm:w-[180px]"
+  />
+);
+
+// 4) Usar em config.filters
+config: {
+  filters: [
+    { type: 'search' },
+    { type: 'custom', component: StatusFilter }
+  ]
+}
+
+// 5) Passar manager original (filtro já aplicado)
+const CrudPage = createCrudPage({
+  manager,  // ← Manager já vem filtrado do backend
+  config,
+  onSave
+});
+```
+
+### **Pattern 1B: Filtro de Status (Frontend - Casos Específicos)**
+
+```typescript
+// Use filtro frontend APENAS se:
+// ✅ Precisa combinar múltiplas propriedades (ex: status + tipo)
+// ✅ Lógica de filtro muito complexa para SQL
+// ❌ NÃO use para filtros simples (pior performance)
+
+const [statusFilter, setStatusFilter] = useState<boolean | 'all'>(true);
+
+const filteredEntities = useMemo(() => {
+  if (statusFilter === 'all') return manager.entities;
+  return manager.entities.filter(e => e.is_actived === statusFilter);
+}, [manager.entities, statusFilter]);
+
+const filteredManager = useMemo(() => ({
+  ...manager,
+  entities: filteredEntities,
+  pagination: {
+    ...manager.pagination,
+    totalItems: filteredEntities.length  // ⚠️ Atualizar contador
+  }
+}), [manager, filteredEntities]);
+```
+
+**📖 Explicação:**
+- **`useState`**: Armazena valor selecionado no filtro
+- **`useMemo` (filteredEntities)**: Evita re-filtrar a cada render
+- **`useMemo` (filteredManager)**: Evita re-criar objeto manager
+- **`EntitySelect`**: Componente de dropdown da lib
+- **`filteredManager`**: Manager modificado que createCrudPage vai usar
+
+---
+
+### **Pattern 2: Filtro de Departamento (Select Nativo)**
+
+```typescript
+// ✅ PADRÃO: Filtro por categoria/departamento
+
+const [deptFilter, setDeptFilter] = useState<string>('all');
+
+const filteredEntities = useMemo(() => {
+  if (deptFilter === 'all') return manager.entities;
+  return manager.entities.filter(e => e.department === deptFilter);
+}, [manager.entities, deptFilter]);
+
+const filteredManager = useMemo(() => ({
+  ...manager,
+  entities: filteredEntities
+}), [manager, filteredEntities]);
+
+const DepartmentFilter = () => (
+  <select 
+    value={deptFilter} 
+    onChange={(e) => setDeptFilter(e.target.value)}
+    className="px-3 py-2 border rounded-md"
+  >
+    <option value="all">Todos Departamentos</option>
+    <option value="HR">RH</option>
+    <option value="IT">TI</option>
+    <option value="Finance">Financeiro</option>
+  </select>
+);
+```
+
+---
+
+### **Pattern 3: Filtro de Data Range (Date Picker)**
+
+```typescript
+// ✅ PADRÃO: Filtro por intervalo de datas
+
+import { format, isAfter, isBefore, parseISO } from 'date-fns';
+
+const [dateRange, setDateRange] = useState<{ from?: Date; to?: Date }>({});
+
+const filteredEntities = useMemo(() => {
+  if (!dateRange.from && !dateRange.to) return manager.entities;
+  
+  return manager.entities.filter(e => {
+    const itemDate = parseISO(e.created_at);
+    if (dateRange.from && isBefore(itemDate, dateRange.from)) return false;
+    if (dateRange.to && isAfter(itemDate, dateRange.to)) return false;
+    return true;
+  });
+}, [manager.entities, dateRange]);
+
+const filteredManager = useMemo(() => ({
+  ...manager,
+  entities: filteredEntities
+}), [manager, filteredEntities]);
+```
+
+---
+
+## 🪝 HOOKS REACT NO CRUD
+
+| Hook | Quando Usar | Exemplo no CRUD | ⚠️ Evitar |
+|------|-------------|-----------------|-----------|
+| **useMemo** | Cálculos pesados que dependem de props/state | • Configuração de colunas<br>• Filtros derivados<br>• Manager customizado | Valores simples (strings, números) |
+| **useState** | Valores que mudam via interação do usuário | • Filtros customizados<br>• Modal open/close<br>• Seleção temporária | Estados derivados de outros estados |
+| **useCallback** | Funções que são passadas como props e dependem de state | • Handlers que dependem de filtros<br>• Callbacks de child components | Handlers simples sem dependências |
+| **useEffect** | Side effects (fetch, subscriptions) | • Fetch inicial de dados (já feito pelo manager)<br>• Sincronização externa | Cálculos ou transformações de dados |
+
+### **📖 Exemplos Práticos**
+
+```typescript
+// ✅ CORRETO: useMemo para config (evita re-render do formulário)
+const config = useMemo(() => ({
+  columns: [...],
+  formSections: [...]
+}), []);
+
+// ❌ ERRADO: sem useMemo (re-cria objeto a cada render)
+const config = {
+  columns: [...],
+  formSections: [...]
+};
+
+// ✅ CORRETO: useState para filtro
+const [statusFilter, setStatusFilter] = useState('active');
+
+// ❌ ERRADO: useMemo para valor que muda via interação
+const statusFilter = useMemo(() => 'active', []); // Não faz sentido!
+
+// ✅ CORRETO: useMemo para estado derivado
+const filteredEntities = useMemo(() => 
+  manager.entities.filter(e => e.is_actived),
+  [manager.entities]
+);
+
+// ❌ ERRADO: recalcula a cada render (lento)
+const filteredEntities = manager.entities.filter(e => e.is_actived);
+```
+
+---
+
+## ❌ ERROS COMUNS E SOLUÇÕES
+
+### **Erro 1: Importar `cn` do lugar errado**
+
+```typescript
+// ❌ SINTOMA: Classes CSS não aplicam
+// ❌ CAUSA: import { cn } from '@/lib/utils'
+import { cn } from '@/lib/utils';
+
+// ✅ SOLUÇÃO: Importar da lib
+import { cn } from 'forlogic-core';
+```
+
+---
+
+### **Erro 2: Esquecer `useMemo` no config**
+
+```typescript
+// ❌ SINTOMA: Formulário fecha/reabre sozinho, re-renders infinitos
+// ❌ CAUSA: Config recriado a cada render
+const config = { 
+  columns: exampleColumns, 
+  formSections 
+};
+
+// ✅ SOLUÇÃO: Envolver em useMemo
+const config = useMemo(() => ({ 
+  columns: exampleColumns, 
+  formSections 
+}), []);
+```
+
+---
+
+### **Erro 3: Passar `entities` ao invés de `manager`**
+
+```typescript
+// ❌ SINTOMA: TypeError: manager.createEntity is not a function
+// ❌ CAUSA: Passou array direto
+const CrudPage = createCrudPage({ 
+  manager: manager.entities,  // ← Errado!
+  config 
+});
+
+// ✅ SOLUÇÃO: Passar manager completo
+const CrudPage = createCrudPage({ 
+  manager,  // ← Correto!
+  config 
+});
+```
+
+---
+
+### **Erro 4: Filtro sem `useMemo`**
+
+```typescript
+// ❌ SINTOMA: Performance ruim, travamentos
+// ❌ CAUSA: Recalcula filtro a cada render
+const filteredEntities = manager.entities.filter(e => e.is_actived);
+
+// ✅ SOLUÇÃO: Envolver em useMemo
+const filteredEntities = useMemo(() => 
+  manager.entities.filter(e => e.is_actived),
+  [manager.entities]
+);
+```
+
+---
+
+### **Erro 5: Esquecer de usar `manager.save()`**
+
+```typescript
+// ❌ SINTOMA: Erro de RLS no Supabase, registro não é criado
+// ❌ CAUSA: Usar createEntity/updateEntity direto sem alias
+manager.createEntity({ 
+  title: data.title,
+  email: data.email
+  // ← Falta alias!
+});
+
+// ✅ SOLUÇÃO: Usar manager.save() que injeta alias automaticamente
+const handleSave = (data: any) => {
+  manager.save(data, (d) => ({
+    title: d.title,
+    email: d.email
+  }));
+  // O save() detecta CREATE vs UPDATE e injeta alias automaticamente
+};
+```
+
+---
+
+### **Erro 6: Chamar hooks fora do componente**
+
+```typescript
+// ❌ SINTOMA: Error: Hooks can only be called inside of the body of a function component
+// ❌ CAUSA: Hook chamado fora do componente
+const manager = useExamplesCrud();  // ← Fora do componente!
+
+export const ExamplesPage = () => {
+  return <CrudPage />;
+};
+
+// ✅ SOLUÇÃO: Chamar hooks DENTRO do componente
+export const ExamplesPage = () => {
+  const manager = useExamplesCrud();  // ← Dentro do componente!
+  return <CrudPage />;
+};
+```
+
+---
+
+## 🎨 PERSONALIZAÇÃO AVANÇADA
+
+### **1. Renderização Customizada de Colunas**
+
+```typescript
+// Exemplo 1: Badge de status com cores
+{
+  key: 'status',
+  header: 'Status',
+  render: (item) => (
+    <span className={`px-2 py-1 rounded-full text-xs ${
+      item.status === 'completed' ? 'bg-green-100 text-green-800' :
+      item.status === 'pending' ? 'bg-yellow-100 text-yellow-800' :
+      'bg-gray-100 text-gray-800'
+    }`}>
+      {item.status}
+    </span>
+  )
+}
+
+// Exemplo 2: Link externo
+{
+  key: 'website',
+  header: 'Site',
+  render: (item) => (
+    <a 
+      href={item.website} 
+      target="_blank" 
+      rel="noopener noreferrer"
+      className="text-blue-600 hover:underline"
+    >
+      Visitar
+    </a>
+  )
+}
+
+// Exemplo 3: Ícone colorido
+{
+  key: 'priority',
+  header: 'Prioridade',
+  render: (item) => {
+    const icons = { high: '🔴', medium: '🟡', low: '🟢' };
+    return <span>{icons[item.priority]}</span>;
+  }
+}
+```
+
+---
+
+### **2. Campos de Formulário Customizados**
+
+```typescript
+// Exemplo: Campo customizado com EntitySelect
+{
+  name: 'category_id',
+  label: 'Categoria',
+  type: 'custom' as const,
+  component: (props) => {
+    const { data: categories } = useCategoriesCrud();
+    return (
+      <EntitySelect
+        {...props}
+        items={categories}
+        getItemValue={(item) => item.id}
+        getItemLabel={(item) => item.name}
+        placeholder="Selecionar categoria"
+      />
+    );
+  }
+}
+```
+
+---
+
+### **3. Ações Customizadas na Linha**
+
+```typescript
+// Adicionar botão "Duplicar" nas ações da linha
+const customActions = (item: Example) => [
+  {
+    label: 'Duplicar',
+    icon: Copy,
+    onClick: () => {
+      const newItem = { ...item, id: undefined, title: `${item.title} (cópia)` };
+      manager.createEntity(newItem);
+    }
+  }
+];
+
+// Passar para createCrudPage
+const CrudPage = createCrudPage({
+  manager,
+  config: {
+    ...config,
+    customRowActions: customActions
+  }
+});
+```
+
+---
+
+### 🔗 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 (modo unificado)
+{
+  name: 'responsible_id',
+  label: 'Responsável',
+  type: 'user-select' as const,
+  mode: 'single',  // ou 'multiple'
+  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' }
+```
+
+---
+
+## 📍 PLACES - Locais e Sublocais
+
+O módulo **Places** permite gerenciar a hierarquia de locais e sublocais da organização, integrando com a API Qualiex.
+
+### 🔌 Imports Disponíveis
+
+```typescript
+// Tipos
+import type { Place, SubPlace } from 'forlogic-core';
+
+// Serviço
+import { placeService, PlaceService } from 'forlogic-core';
+
+// Componente de Página Pronta
+import { PlacesPage } from 'forlogic-core';
+```
+
+### 📋 Estrutura dos Dados
+
+```typescript
+interface Place {
+  id: string;
+  placeId: string;           // ID único do local no Qualiex
+  name: string;              // Nome do local
+  companyId: string;         // ID da empresa
+  usersIds: string[];        // Array de IDs de usuários vinculados
+  subPlaces?: SubPlace[];    // Sublocais (hierarquia)
+  parentId?: string | null;  // ID do local pai (se for sublocalizado)
+  isActive: boolean;         // Status do local
+  createdAt: string;
+  updatedAt: string;
+}
+
+interface SubPlace {
+  id: string;
+  placeId: string;
+  name: string;
+  parentId: string;
+  usersIds: string[];
+  isActive: boolean;
+  subPlaces?: SubPlace[];    // Recursivo - permite múltiplos níveis
+}
+```
+
+### 🎯 Como Obter Places
+
+#### Método 1 (Recomendado): Hook com React Query
+
+```typescript
+import { useQuery } from '@tanstack/react-query';
+import { useAuth, placeService } from 'forlogic-core';
+
+function MyComponent() {
+  const { alias } = useAuth();
+  
+  const { data: places = [], isLoading, error } = useQuery({
+    queryKey: ['places', alias],
+    queryFn: () => placeService.getPlaces(alias),
+    enabled: !!alias,
+    staleTime: 5 * 60 * 1000 // Cache de 5 minutos
+  });
+
+  if (isLoading) return <LoadingState />;
+  if (error) return <div>Erro ao carregar locais</div>;
+
+  return (
+    <div>
+      {places.map(place => (
+        <div key={place.id}>{place.name}</div>
+      ))}
+    </div>
+  );
+}
+```
+
+#### Método 2: Hook Customizado Reutilizável
+
+```typescript
+// src/hooks/usePlaces.ts
+import { useQuery } from '@tanstack/react-query';
+import { useAuth, placeService } from 'forlogic-core';
+
+export function usePlaces() {
+  const { alias } = useAuth();
+  
+  return useQuery({
+    queryKey: ['places', alias],
+    queryFn: () => placeService.getPlaces(alias),
+    enabled: !!alias,
+    staleTime: 5 * 60 * 1000 // Cache de 5 minutos
+  });
+}
+
+// Usar no componente
+const { data: places = [], isLoading } = usePlaces();
+```
+
+#### Método 3: Chamada Direta (Service)
+
+```typescript
+// Para casos especiais (não recomendado para components)
+const places = await placeService.getPlaces('my-alias');
+```
+
+### 🏠 Usando PlacesPage Pronta
+
+```typescript
+// App.tsx ou routes
+import { PlacesPage } from 'forlogic-core';
+
+<Route path="/places" element={<PlacesPage />} />
+```
+
+### 🔗 Integrando Places em Módulos CRUD
+
+#### Cenário A: PlaceSelect em Formulários
+
+```typescript
+// src/components/PlaceSelect.tsx
+import { EntitySelect } from 'forlogic-core';
+import { usePlaces } from '@/hooks/usePlaces';
+import { useMemo } from 'react';
+
+export function PlaceSelect({ value, onChange, disabled }: {
+  value?: string;
+  onChange: (value: string) => void;
+  disabled?: boolean;
+}) {
+  const { data: places = [], isLoading } = usePlaces();
+  
+  // Achatar hierarquia para o select
+  const flatPlaces = useMemo(() => {
+    const flatten = (items: Place[], level = 0): any[] => {
+      return items.flatMap(place => [
+        { ...place, level },
+        ...flatten(place.subPlaces || [], level + 1)
+      ]);
+    };
+    return flatten(places);
+  }, [places]);
+  
+  return (
+    <EntitySelect
+      value={value}
+      onChange={onChange}
+      items={flatPlaces}
+      isLoading={isLoading}
+      getItemValue={(p) => p.placeId}
+      getItemLabel={(p) => `${'  '.repeat(p.level)}${p.name}`}
+      disabled={disabled}
+      placeholder="Selecionar local"
+    />
+  );
+}
+
+// Usar no CRUD config
+{
+  key: 'place_id',
+  label: 'Local',
+  type: 'custom',
+  component: PlaceSelect,
+  required: true
+}
+```
+
+#### Cenário B: Filtrar Dados por Place
+
+```typescript
+// Service com filtro de placeId
+const { service, useCrudHook } = createSimpleService({
+  tableName: 'my_table',
+  schemaName: 'central',
+  additionalFilters: [
+    { field: 'place_id', operator: 'eq', value: selectedPlaceId }
+  ]
+});
+```
+
+#### Cenário C: Exibir Nome do Local em Tabelas
+
+```typescript
+// Hook para buscar nome do place
+function usePlaceName(placeId: string) {
+  const { data: places = [] } = usePlaces();
+  
+  return useMemo(() => {
+    const findPlace = (items: Place[]): Place | undefined => {
+      for (const place of items) {
+        if (place.placeId === placeId) return place;
+        if (place.subPlaces) {
+          const found = findPlace(place.subPlaces);
+          if (found) return found;
+        }
+      }
+    };
+    return findPlace(places)?.name || 'Local não encontrado';
+  }, [places, placeId]);
+}
+
+// Usar na coluna da tabela
+{
+  key: 'place_id',
+  header: 'Local',
+  render: (item) => {
+    const placeName = usePlaceName(item.place_id);
+    return <span>{placeName}</span>;
+  }
+}
+```
+
+### 🔑 Acessando placeId/placeName dos Tokens
+
+**⚠️ IMPORTANTE:** `placeId` e `placeName` **NÃO** vêm diretamente dos tokens JWT. Eles são obtidos da **API Qualiex**.
+
+```typescript
+// ❌ ERRADO - Não existe no token
+const { placeId } = useAuth(); // undefined
+
+// ✅ CORRETO - Buscar da API Qualiex
+const { data: places } = usePlaces();
+const userPlace = places.find(p => p.usersIds.includes(userId));
+const placeId = userPlace?.placeId;
+const placeName = userPlace?.name;
+```
+
+**Fluxo de dados:**
+1. Token JWT contém `alias` e `companyId`
+2. `placeService.getPlaces(alias)` busca os Places da API Qualiex
+3. Cada `Place` contém `usersIds` (array de IDs de usuários)
+4. Relacionar usuário logado com seu Place através de `usersIds`
+
+### 🌳 Navegação Hierárquica (Tree View)
+
+```typescript
+function PlaceTree({ places, level = 0 }: {
+  places: Place[];
+  level?: number;
+}) {
+  return (
+    <div>
+      {places.map(place => (
+        <div key={place.id}>
+          <div style={{ paddingLeft: `${level * 20}px` }}>
+            📍 {place.name} ({place.usersIds.length} usuários)
+            {!place.isActive && <Badge variant="secondary">Inativo</Badge>}
+          </div>
+          {place.subPlaces && place.subPlaces.length > 0 && (
+            <PlaceTree places={place.subPlaces} level={level + 1} />
+          )}
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+### 🛠️ Troubleshooting
+
+| Erro | Causa | Solução |
+|------|-------|---------|
+| `CompanyId não encontrado no token` | Token não validado corretamente | Verificar edge function `validate-token` |
+| `Alias da unidade é obrigatório` | `alias` não disponível no `useAuth()` | Aguardar carregamento do auth com `isLoading` |
+| `Token Qualiex não encontrado` | Variável de ambiente faltando | Verificar `VITE_QUALIEX_API_URL` no `.env` |
+| Places retorna array vazio `[]` | Empresa sem places cadastrados | Verificar cadastro no Qualiex admin |
+| Hierarquia quebrada | `parentId` incorreto nos dados | Verificar integridade dos dados na API Qualiex |
+
+### 📦 Exemplo Completo: Dashboard por Local
+
+```typescript
+import { usePlaces } from '@/hooks/usePlaces';
+import { Card, CardHeader, CardTitle, CardContent } from 'forlogic-core';
+
+function PlacesDashboard() {
+  const { data: places = [], isLoading } = usePlaces();
+  const { data: metrics = [] } = useQuery({
+    queryKey: ['metrics'],
+    queryFn: fetchMetrics
+  });
+
+  if (isLoading) return <LoadingState />;
+
+  return (
+    <div className="grid gap-4 md:grid-cols-2 lg:grid-cols-3">
+      {places.map(place => {
+        const placeMetrics = metrics.filter(m => m.place_id === place.placeId);
+        
+        return (
+          <Card key={place.id}>
+            <CardHeader>
+              <CardTitle>{place.name}</CardTitle>
+            </CardHeader>
+            <CardContent>
+              <div className="space-y-2">
+                <p className="text-sm">
+                  👥 Usuários: <strong>{place.usersIds.length}</strong>
+                </p>
+                <p className="text-sm">
+                  📊 Registros: <strong>{placeMetrics.length}</strong>
+                </p>
+                <p className="text-sm">
+                  📍 Sublocais: <strong>{place.subPlaces?.length || 0}</strong>
+                </p>
+              </div>
+            </CardContent>
+          </Card>
+        );
+      })}
+    </div>
+  );
+}
+```
+
+### ✅ Checklist de Implementação
+
+- [ ] `VITE_QUALIEX_API_URL` configurada no `.env`
+- [ ] Edge function `validate-token` retorna `company_id` corretamente
+- [ ] `alias` disponível no `useAuth()`
+- [ ] Hook `usePlaces()` criado e testado
+- [ ] `PlaceSelect` component criado (se necessário)
+- [ ] Tratamento de erro quando places vazio
+- [ ] Cache configurado no React Query (`staleTime`)
+- [ ] Hierarquia renderizada corretamente (se usar tree view)
+
+### 📚 Referências
+
+- **Tipos:** `lib/qualiex/places/types.ts`
+- **Service:** `lib/qualiex/places/PlaceService.ts`
+- **Componente:** `lib/qualiex/places/PlacesPage.tsx`
+- **Exports:** `lib/modular.ts` e `lib/exports/integrations.ts`
+- **Token Manager:** `lib/auth/services/TokenManager.ts`
+
+---
+
 ## 🗃️ MIGRATIONS + RLS
 
 ### Template SQL Completo