forlogic-core 1.7.6 → 1.8.0

package/README.md

@@ -1,6 +1,6 @@
 # 🧱 Projeto atual
 
-**Schema padrão:** `central`
+**Schema padrão:** `common`
 
 > **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'`.
 
@@ -208,7 +208,7 @@ import { Button } from 'forlogic-core'
 // Formulários
 Button, Input, Textarea, Label, Select, SelectContent,
 SelectItem, SelectTrigger, SelectValue, Checkbox, RadioGroup,
-RadioGroupItem, Switch
+RadioGroupItem, Switch, CreatableCombobox
 
 // Layout
 Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle
@@ -466,6 +466,48 @@ export function DepartmentSelect(props: DepartmentSelectProps) {
 
 O `BaseForm` suporta campos totalmente customizados através do tipo `'custom'`, permitindo usar **qualquer componente React** como campo de formulário.
 
+#### ⚠️ IMPORTANTE: Como Usar Corretamente
+
+**❌ ERRADO - Usar tipo customizado sem configurar:**
+```typescript
+// ❌ ISSO NÃO VAI FUNCIONAR!
+{
+  name: 'annual_training_ids',
+  label: 'Treinamentos Anuais',
+  type: 'annual-training-multi-select', // ❌ BaseForm não conhece esse tipo
+}
+
+// E passar customComponents na página:
+<BaseForm
+  customComponents={{
+    'annual-training-multi-select': AnnualTrainingMultiSelect // ❌ Ignorado!
+  }}
+/>
+```
+
+**✅ CORRETO - Usar type: 'custom' com component:**
+```typescript
+import { AnnualTrainingMultiSelect } from './components/AnnualTrainingMultiSelect';
+
+{
+  name: 'annual_training_ids',
+  label: 'Treinamentos Anuais',
+  type: 'custom', // ✅ Tipo reconhecido pelo BaseForm
+  component: AnnualTrainingMultiSelect, // ✅ Componente passado diretamente
+  required: true,
+  componentProps: { // ✅ Props adicionais (opcional)
+    placeholder: 'Selecionar treinamentos...'
+  }
+}
+```
+
+#### 🔑 Pontos Críticos
+
+1. **Use sempre `type: 'custom'`** - É o único tipo que o BaseForm reconhece para componentes customizados
+2. **Passe o `component` diretamente** - Não existe prop `customComponents` no BaseForm
+3. **Importe o componente** - Deve ser importado no arquivo onde você define os campos
+4. **Interface obrigatória** - Seu componente DEVE aceitar: `value`, `onChange`, `disabled`, `error`
+
 #### Interface do Componente Customizado
 
 Todo campo customizado deve seguir esta interface:
@@ -574,30 +616,576 @@ const formFields: FormField[] = [
 - ✅ **Flexibilidade** - Props extras via `componentProps`
 - ✅ **Reatividade** - `updateField` e `onValueChange` funcionam corretamente
 
-#### Exemplos Adicionais
+#### Exemplos Práticos Completos
 
-**MultiSelect com Busca:**
+**Exemplo 1: MultiSelect de Objetivos Estratégicos**
 
 ```typescript
-{
-  name: 'categories',
-  type: 'custom',
-  component: MultiSelectField,
-  componentProps: {
-    options: categories,
-    searchable: true
+// 1. Criar o componente customizado
+// src/components/StrategicObjectivesMultiSelect.tsx
+import { Label, Badge } from 'forlogic-core';
+import { useStrategicObjectives } from '@/hooks/useStrategicObjectives';
+
+interface Props {
+  value: string[];
+  onChange: (value: string[]) => void;
+  disabled?: boolean;
+  error?: string;
+}
+
+export function StrategicObjectivesMultiSelect({ 
+  value = [], 
+  onChange, 
+  disabled, 
+  error 
+}: Props) {
+  const { data: objectives = [], isLoading } = useStrategicObjectives();
+
+  const toggleObjective = (id: string) => {
+    if (disabled) return;
+    const newValue = value.includes(id)
+      ? value.filter(v => v !== id)
+      : [...value, id];
+    onChange(newValue);
+  };
+
+  if (isLoading) return <div>Carregando...</div>;
+
+  return (
+    <div className="space-y-2">
+      <Label>Objetivos Estratégicos</Label>
+      <div className="flex flex-wrap gap-2">
+        {objectives.map(obj => (
+          <Badge
+            key={obj.id}
+            variant={value.includes(obj.id) ? 'default' : 'outline'}
+            className="cursor-pointer"
+            onClick={() => toggleObjective(obj.id)}
+          >
+            {obj.name}
+          </Badge>
+        ))}
+      </div>
+      {error && <p className="text-sm text-destructive">{error}</p>}
+    </div>
+  );
+}
+
+// 2. Usar no formulário - CORRETO ✅
+import { StrategicObjectivesMultiSelect } from '@/components/StrategicObjectivesMultiSelect';
+
+const formFields: FormField[] = [
+  {
+    name: 'strategic_objective_ids',
+    label: '',
+    type: 'custom', // ✅
+    component: StrategicObjectivesMultiSelect, // ✅
+    required: true,
   }
+];
+```
+
+**Exemplo 2: Select de Usuários do Qualiex**
+
+```typescript
+// 1. Componente customizado
+// src/components/QualiexUserSelect.tsx
+import { EntitySelect } from 'forlogic-core';
+import { useQualiexUsers } from '@/hooks/useQualiexUsers';
+
+interface Props {
+  value: string;
+  onChange: (value: string) => void;
+  disabled?: boolean;
+  error?: string;
+  placeId?: string; // Filtrar por local
 }
+
+export function QualiexUserSelect({ 
+  value, 
+  onChange, 
+  disabled, 
+  error,
+  placeId 
+}: Props) {
+  const { data: users = [], isLoading } = useQualiexUsers({ placeId });
+
+  return (
+    <div className="space-y-2">
+      <EntitySelect
+        value={value}
+        onChange={onChange}
+        items={users}
+        isLoading={isLoading}
+        disabled={disabled}
+        getItemValue={(u) => u.id}
+        getItemLabel={(u) => `${u.name} - ${u.email}`}
+        placeholder="Selecionar usuário..."
+        searchPlaceholder="Buscar usuário..."
+      />
+      {error && <p className="text-sm text-destructive">{error}</p>}
+    </div>
+  );
+}
+
+// 2. Usar no formulário - CORRETO ✅
+import { QualiexUserSelect } from '@/components/QualiexUserSelect';
+
+const formFields: FormField[] = [
+  {
+    name: 'id_responsible',
+    label: 'Responsável',
+    type: 'custom', // ✅
+    component: QualiexUserSelect, // ✅
+    required: true,
+    componentProps: {
+      placeId: currentPlaceId // Props extras
+    }
+  }
+];
 ```
 
-**Rich Text Editor:**
+**Exemplo 3: MultiSelect de Treinamentos Anuais**
 
 ```typescript
-{
-  name: 'content',
-  type: 'custom',
-  component: RichTextEditor,
-  componentProps: {
+// 1. Componente customizado
+// src/training/components/AnnualTrainingMultiSelect.tsx
+import { Checkbox, Label } from 'forlogic-core';
+import { useAnnualTrainings } from '@/hooks/useAnnualTrainings';
+
+interface Props {
+  value: string[];
+  onChange: (value: string[]) => void;
+  disabled?: boolean;
+  error?: string;
+  year?: number;
+}
+
+export function AnnualTrainingMultiSelect({ 
+  value = [], 
+  onChange, 
+  disabled, 
+  error,
+  year 
+}: Props) {
+  const { data: trainings = [], isLoading } = useAnnualTrainings(year);
+
+  const toggleTraining = (id: string) => {
+    if (disabled) return;
+    const newValue = value.includes(id)
+      ? value.filter(v => v !== id)
+      : [...value, id];
+    onChange(newValue);
+  };
+
+  if (isLoading) return <div>Carregando treinamentos...</div>;
+
+  return (
+    <div className="space-y-2">
+      <Label>Treinamentos Anuais {year && `(${year})`}</Label>
+      <div className="space-y-2 max-h-60 overflow-y-auto border rounded-md p-3">
+        {trainings.map(training => (
+          <div key={training.id} className="flex items-center gap-2">
+            <Checkbox
+              id={`training-${training.id}`}
+              checked={value.includes(training.id)}
+              onCheckedChange={() => toggleTraining(training.id)}
+              disabled={disabled}
+            />
+            <Label 
+              htmlFor={`training-${training.id}`}
+              className="font-normal cursor-pointer"
+            >
+              {training.title}
+            </Label>
+          </div>
+        ))}
+      </div>
+      {error && <p className="text-sm text-destructive">{error}</p>}
+    </div>
+  );
+}
+
+// 2. Usar no formulário - CORRETO ✅
+import { AnnualTrainingMultiSelect } from '@/training/components/AnnualTrainingMultiSelect';
+
+const formFields: FormField[] = [
+  {
+    name: 'annual_training_ids',
+    label: '',
+    type: 'custom', // ✅
+    component: AnnualTrainingMultiSelect, // ✅
+    required: true,
+    componentProps: {
+      year: 2025 // Props extras
+    },
+    validation: (value) => {
+      if (!value?.length) return 'Selecione pelo menos um treinamento';
+    }
+  }
+];
+```
+
+#### ❌ Erros Comuns e Soluções
+
+| Erro | Causa | Solução |
+|------|-------|---------|
+| Campo aparece como input text | Tipo customizado não reconhecido | Use `type: 'custom'` em vez de `type: 'meu-campo-custom'` |
+| "customComponents is not used" | Passando prop que não existe | Remova `customComponents` e use `component` direto no field |
+| "component is not defined" | Esqueceu de importar | Importe o componente no arquivo de fields |
+| Campo não recebe props | componentProps ignorado | Verifique se seu componente aceita as props via `...props` |
+| onChange não funciona | Componente não chama onChange | Certifique-se de chamar `onChange(novoValor)` |
+
+#### 📋 Checklist de Implementação
+
+Ao criar um campo customizado, verifique:
+
+- [ ] Componente aceita `value`, `onChange`, `disabled`, `error`
+- [ ] `type: 'custom'` está configurado
+- [ ] `component: SeuComponente` está passado
+- [ ] Componente está importado no arquivo de fields
+- [ ] `onChange` é chamado quando valor muda
+- [ ] `error` é exibido quando presente
+- [ ] `disabled` desabilita interações
+
+---
+
+### 🎯 Campo Creatable Select
+
+O `CreatableCombobox` permite que usuários **selecionem de opções existentes OU criem novos itens inline** sem sair do formulário.
+
+#### Quando Usar?
+
+- ✅ Seleção de tags, categorias, labels
+- ✅ Campos onde usuários podem precisar criar valores rapidamente
+- ✅ Dropdowns com centenas de opções (busca rápida)
+- ✅ Single ou múltipla seleção
+
+#### Uso Básico no BaseForm
+
+```typescript
+import { createCrudPage } from 'forlogic-core';
+import { TagService } from './tagService';
+
+const formFields: FormSection[] = [
+  {
+    id: 'basic',
+    title: 'Informações',
+    fields: [
+      {
+        name: 'tags',
+        label: 'Tags',
+        type: 'creatable-select',
+        mode: 'multiple',
+        placeholder: 'Selecionar ou criar tags...',
+        options: tagsOptions, // [{ label: 'React', value: '1' }, ...]
+        onCreate: async (tagName) => {
+          // Criar tag no backend
+          const newTag = await TagService.create({ name: tagName });
+          // Atualizar lista de opções (refetch)
+          refetchTags();
+          return newTag.id; // Retorna ID para seleção automática
+        },
+        createLabel: (term) => `Criar "${term}"`,
+        required: true
+      },
+      {
+        name: 'category',
+        label: 'Categoria',
+        type: 'creatable-select',
+        mode: 'single',
+        placeholder: 'Selecionar categoria...',
+        options: categoriesOptions,
+        onCreate: async (categoryName) => {
+          const newCat = await CategoryService.create({ name: categoryName });
+          refetchCategories();
+          return newCat.id;
+        }
+      }
+    ]
+  }
+];
+```
+
+#### Props do Campo
+
+| Prop                  | Tipo                                       | Padrão                  | Descrição                                            |
+| --------------------- | ------------------------------------------ | ----------------------- | ---------------------------------------------------- |
+| `type`                | `'creatable-select'`                       | -                       | Tipo do campo (obrigatório)                          |
+| `mode`                | `'single' \| 'multiple'`                   | `'single'`              | Seleção única ou múltipla                            |
+| `options`             | `Array<{ label: string; value: string }>`  | `[]`                    | Opções existentes para seleção                       |
+| `onCreate`            | `(searchTerm: string) => Promise<string>`  | -                       | Callback para criar novo item (retorna ID)           |
+| `placeholder`         | `string`                                   | `'Selecionar...'`       | Texto quando nenhum item selecionado                 |
+| `searchPlaceholder`   | `string`                                   | `'Buscar...'`           | Texto da busca interna                               |
+| `createLabel`         | `(term: string) => string`                 | `'Criar "{term}"'`      | Função para gerar label do botão criar               |
+| `emptyMessage`        | `string`                                   | `'Nenhum item encontrado.'` | Mensagem quando não há opções                    |
+
+#### Exemplo Completo com React Query
+
+```typescript
+import { useQuery, useQueryClient } from '@tanstack/react-query';
+import { createCrudPage } from 'forlogic-core';
+import { TagService } from './tagService';
+
+function TagsPage() {
+  const queryClient = useQueryClient();
+  
+  // Buscar tags existentes
+  const { data: tags = [], isLoading } = useQuery({
+    queryKey: ['tags'],
+    queryFn: () => TagService.getAll()
+  });
+
+  // Converter para formato do CreatableCombobox
+  const tagsOptions = tags.map(tag => ({
+    label: tag.name,
+    value: tag.id
+  }));
+
+  const formFields: FormSection[] = [
+    {
+      id: 'article',
+      title: 'Artigo',
+      fields: [
+        {
+          name: 'title',
+          label: 'Título',
+          type: 'text',
+          required: true
+        },
+        {
+          name: 'tags',
+          label: 'Tags',
+          type: 'creatable-select',
+          mode: 'multiple',
+          options: tagsOptions,
+          onCreate: async (tagName) => {
+            // Validar nome
+            if (tagName.trim().length < 2) {
+              throw new Error('Nome deve ter ao menos 2 caracteres');
+            }
+            
+            // Criar no backend
+            const newTag = await TagService.create({ 
+              name: tagName.trim() 
+            });
+            
+            // Invalidar cache para refetch automático
+            queryClient.invalidateQueries({ queryKey: ['tags'] });
+            
+            // Retornar ID para seleção automática
+            return newTag.id;
+          },
+          placeholder: 'Selecionar tags...',
+          searchPlaceholder: 'Buscar ou criar tag...',
+          createLabel: (term) => `✨ Criar tag "${term}"`,
+          required: true
+        }
+      ]
+    }
+  ];
+
+  return createCrudPage({
+    // ... config do CRUD
+    formFields
+  });
+}
+```
+
+#### Uso Standalone (Fora do BaseForm)
+
+```typescript
+import { CreatableCombobox } from 'forlogic-core/ui';
+import { useState } from 'react';
+
+function MyComponent() {
+  const [selectedTags, setSelectedTags] = useState<string[]>([]);
+  
+  const tagsOptions = [
+    { label: 'React', value: '1' },
+    { label: 'TypeScript', value: '2' },
+    { label: 'Node.js', value: '3' }
+  ];
+
+  return (
+    <CreatableCombobox
+      mode="multiple"
+      value={selectedTags}
+      onChange={setSelectedTags}
+      options={tagsOptions}
+      onCreate={async (tagName) => {
+        const response = await fetch('/api/tags', {
+          method: 'POST',
+          body: JSON.stringify({ name: tagName })
+        });
+        const newTag = await response.json();
+        return newTag.id;
+      }}
+      placeholder="Selecionar tags..."
+      createLabel={(term) => `Criar "${term}"`}
+    />
+  );
+}
+```
+
+#### Interface TypeScript
+
+```typescript
+interface CreatableComboboxProps {
+  // Dados
+  options: Array<{ label: string; value: string }>;
+  value?: string | string[];
+  
+  // Eventos
+  onChange: (value: string | string[]) => void;
+  onCreate?: (searchTerm: string) => Promise<string | void>;
+  
+  // Config
+  placeholder?: string;
+  searchPlaceholder?: string;
+  createLabel?: (term: string) => string;
+  emptyMessage?: string;
+  
+  // Estado
+  disabled?: boolean;
+  error?: string;
+  isLoading?: boolean;
+  
+  // UI
+  className?: string;
+  mode?: 'single' | 'multiple';
+}
+```
+
+#### Fluxo de Criação
+
+```mermaid
+graph TD
+    A[Usuário digita 'Design'] --> B{Termo existe?}
+    B -->|Sim| C[Mostra opção existente]
+    B -->|Não| D[Mostra botão 'Criar Design']
+    D --> E[Usuário clica em criar]
+    E --> F[onCreate chamado]
+    F --> G{Retornou ID?}
+    G -->|Sim| H[Adiciona à seleção automaticamente]
+    G -->|Não| I[Apenas fecha dropdown]
+    H --> J[queryClient.invalidateQueries atualiza lista]
+    C --> K[Usuário seleciona]
+    K --> L[onChange chamado]
+```
+
+#### Estados Visuais
+
+**Campo Vazio (Single):**
+```
+┌────────────────────────────────┐
+│  Selecionar categoria...    ▼ │
+└────────────────────────────────┘
+```
+
+**Campo com Múltiplos Selecionados:**
+```
+┌────────────────────────────────┐
+│  [React ✕] [TypeScript ✕]  ▼  │
+└────────────────────────────────┘
+```
+
+**Dropdown com Busca (Termo Não Existe):**
+```
+┌────────────────────────────────┐
+│  🔍 design                     │
+├────────────────────────────────┤
+│  ┏━━━━━━━━━━━━━━━━━━━━━━━━━┓ │
+│  ┃  ✨ Criar "design"        ┃ │ <- Botão azul
+│  ┗━━━━━━━━━━━━━━━━━━━━━━━━━┛ │
+└────────────────────────────────┘
+```
+
+**Dropdown com Opções Existentes:**
+```
+┌────────────────────────────────┐
+│  🔍 react                      │
+├────────────────────────────────┤
+│  ✓ React                       │ <- Selecionado
+│    React Native                │
+│    React Query                 │
+└────────────────────────────────┘
+```
+
+#### Boas Práticas
+
+1. **Sempre retornar o ID no onCreate:**
+   - Permite seleção automática do item criado
+   - Evita usuário ter que procurar o item recém-criado
+
+2. **Invalidar cache após criar:**
+   - Use `queryClient.invalidateQueries()` para refetch automático
+   - Garante que lista de opções está sempre atualizada
+
+3. **Validação no onCreate:**
+   - Valide o nome antes de criar
+   - Lance erro amigável se inválido
+   - Use `toast.error()` para feedback visual
+
+4. **Loading states:**
+   - Passe `isLoading` durante fetch inicial de opções
+   - `onCreate` já mostra loading interno automaticamente
+
+5. **Modo apropriado:**
+   - `single`: Categoria, Status, Tipo
+   - `multiple`: Tags, Skills, Departamentos
+
+#### Troubleshooting
+
+**Problema:** Opções não atualizam após criar
+```typescript
+// ❌ ERRADO - Não invalida cache
+onCreate: async (name) => {
+  await TagService.create({ name });
+  return newTag.id;
+}
+
+// ✅ CORRETO - Invalida cache
+onCreate: async (name) => {
+  const newTag = await TagService.create({ name });
+  queryClient.invalidateQueries({ queryKey: ['tags'] });
+  return newTag.id;
+}
+```
+
+**Problema:** Dropdown fica transparente
+```css
+/* Adicionar ao CSS global se necessário */
+.popover-content {
+  background-color: white;
+  z-index: 9999;
+}
+```
+
+**Problema:** onCreate não retorna ID
+```typescript
+// ✅ Sempre retornar o ID para seleção automática
+onCreate: async (name) => {
+  const response = await TagService.create({ name });
+  return response.id; // <- IMPORTANTE
+}
+```
+
+---
+
+#### Integração com FormField Types
+
+O tipo `'creatable-select'` está disponível para uso direto no `FormField`:
+
+```typescript
+type FormFieldType = 
+  | 'text' 
+  | 'textarea' 
+  | 'select' 
+  | 'creatable-select'  // <- Novo tipo
+  | 'checkbox' 
+  | 'radio' 
+  | 'date'
     toolbar: ['bold', 'italic', 'link'],
     minHeight: 200
   }
@@ -1038,128 +1626,466 @@ userFieldsMapping: [
 ]
 ```
 
-✅ **BOM**: Usar sufixos distintos
+✅ **BOM**: Usar sufixos distintos
+
+```typescript
+// ✅ Campos de saída únicos
+userFieldsMapping: [
+  { idField: 'created_by_id', nameField: 'created_by_name' },
+  { idField: 'updated_by_id', nameField: 'updated_by_name' },
+]
+```
+
+---
+
+### 🏢 Places - Hierarquia de Locais com Gerenciamento de Acessos
+
+Sistema completo para visualização hierárquica de locais e gerenciamento configurável de acessos (gestores e membros).
+
+#### 📦 Importações
+
+```typescript
+// Componentes
+import { PlacesList, PlaceCard, ManageAccessModal } from 'forlogic-core/places';
+
+// Service
+import { placeService } from 'forlogic-core/places';
+
+// Types
+import type { Place, PlacesListProps, PlaceCardProps, ManageAccessModalProps } from 'forlogic-core/places';
+
+// Ou importação completa
+import { PlacesList, placeService } from 'forlogic-core';
+```
+
+#### 📋 Tipos de Dados
+
+```typescript
+interface Place {
+  id: string;
+  name: string;
+  usersCount?: number;
+  hasChild?: boolean;
+  isActive?: boolean;
+  parentId?: string;
+  parentName?: string;
+  subPlaces?: Place[];
+}
+```
+
+#### 🎯 Uso Básico - Apenas Visualização
+
+```typescript
+import { PlacesList } from 'forlogic-core';
+import { useAuth, placeService } from 'forlogic-core';
+import { useQuery } from '@tanstack/react-query';
+
+function MyPlacesPage() {
+  const { alias } = useAuth();
+  const tokenData = TokenManager.extractTokenData();
+  const companyId = tokenData?.companyId;
+
+  const { data: places = [], isLoading } = useQuery({
+    queryKey: ['places', alias, companyId],
+    queryFn: () => placeService.getPlaces(alias!, companyId!),
+    enabled: !!alias && !!companyId,
+  });
+
+  return <PlacesList places={places} isLoading={isLoading} />;
+}
+```
+
+> **💡 Neste modo**, o `PlacesList` apenas renderiza a hierarquia visual. O botão "Gerenciar Acessos" não aparece.
+
+---
+
+#### 🔐 Uso Avançado - Com Gerenciamento de Acessos
+
+```typescript
+interface PlacesListProps {
+  places: Place[];
+  isLoading: boolean;
+  manageAccessConfig?: {
+    onMakeManager?: (userId: string, placeId: string) => void | Promise<void>;
+    onMakeMembers?: (userIds: string[], placeId: string) => void | Promise<void>;
+    getCurrentManagerId?: (placeId: string) => string | undefined;
+    getCurrentMemberIds?: (placeId: string) => string[] | undefined;
+  };
+}
+```
+
+**Exemplo Completo:**
+
+```typescript
+import { PlacesList, Card } from 'forlogic-core';
+import { useAuth, placeService } from 'forlogic-core';
+import { useQuery } from '@tanstack/react-query';
+
+function MyPlacesPageWithManagement() {
+  const { alias } = useAuth();
+  const tokenData = TokenManager.extractTokenData();
+  const companyId = tokenData?.companyId;
+  
+  // Buscar places
+  const { data: places = [], isLoading } = useQuery({
+    queryKey: ['places', alias, companyId],
+    queryFn: () => placeService.getPlaces(alias!, companyId!),
+    enabled: !!alias && !!companyId,
+  });
+
+  // Buscar gestores e membros atuais (implementação do módulo)
+  const { data: accessData = [] } = useQuery({
+    queryKey: ['placeAccess'],
+    queryFn: () => myAccessService.getAllAccess(),
+  });
+
+  // Callbacks de gerenciamento
+  const handleMakeManager = async (userId: string, placeId: string) => {
+    await myAccessService.setManager(placeId, userId);
+    queryClient.invalidateQueries(['placeAccess']);
+  };
+
+  const handleMakeMembers = async (userIds: string[], placeId: string) => {
+    await myAccessService.addMembers(placeId, userIds);
+    queryClient.invalidateQueries(['placeAccess']);
+  };
+
+  const getCurrentManagerId = (placeId: string) => {
+    return accessData.find(a => a.placeId === placeId && a.role === 'manager')?.userId;
+  };
+
+  const getCurrentMemberIds = (placeId: string) => {
+    return accessData.filter(a => a.placeId === placeId && a.role === 'member').map(a => a.userId);
+  };
+
+  return (
+    <Card className="p-6">
+      <PlacesList
+        places={places}
+        isLoading={isLoading}
+        manageAccessConfig={{
+          onMakeManager: handleMakeManager,
+          onMakeMembers: handleMakeMembers,
+          getCurrentManagerId,
+          getCurrentMemberIds
+        }}
+      />
+    </Card>
+  );
+}
+```
+
+---
+
+#### 🎨 Componentes Individuais
+
+##### PlacesList
+
+Componente principal que renderiza a lista hierárquica de locais.
+
+**Props:**
+- `places: Place[]` - Array de locais (hierarquia já construída)
+- `isLoading: boolean` - Estado de carregamento
+- `manageAccessConfig?: object` - Callbacks de gerenciamento (opcional)
+
+##### PlaceCard
+
+Componente individual de local com suporte a colapso de sublocais.
+
+**Props:**
+- `place: Place` - Dados do local
+- `level?: number` - Nível hierárquico (controla indentação)
+- `manageAccessConfig?: object` - Callbacks (propagado recursivamente)
+
+##### ManageAccessModal
+
+Modal para gerenciamento de acessos ao local.
+
+```typescript
+interface ManageAccessModalProps {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  placeId: string;
+  placeName: string;
+  onMakeManager?: (userId: string, placeId: string) => void | Promise<void>;
+  onMakeMembers?: (userIds: string[], placeId: string) => void | Promise<void>;
+  currentManagerId?: string;
+  currentMemberIds?: string[];
+}
+```
+
+**Funcionalidades:**
+- Lista todos os usuários do alias (via `useQualiexUsers`)
+- Busca por nome ou email
+- Ordenação alfabética
+- Seleção múltipla de usuários
+- Regras automáticas:
+  * 1 usuário selecionado: mostra "Tornar Gestor" + "Tornar Membro"
+  * 2+ usuários selecionados: mostra apenas "Tornar Membros"
+  * 0 usuários selecionados: botões desabilitados
+
+---
+
+#### 🔧 Service - placeService
+
+```typescript
+async getPlaces(alias: string, companyId: string): Promise<Place[]>
+```
+
+Busca locais da API Qualiex e constrói hierarquia automaticamente.
+
+**Características:**
+- Suporta renovação automática de token (via QualiexErrorInterceptor)
+- Constrói hierarquia baseada em `parentId`
+- Tratamento de erros com `errorService`
 
+**Exemplo:**
 ```typescript
-// ✅ Campos de saída únicos
-userFieldsMapping: [
-  { idField: 'created_by_id', nameField: 'created_by_name' },
-  { idField: 'updated_by_id', nameField: 'updated_by_name' },
-]
+const places = await placeService.getPlaces('my-alias', 'company-123');
 ```
 
 ---
 
-### 🏢 Sistema de Gestores de Locais (Qualiex)
+#### 🎯 Regras de Negócio
 
-Componentes para gerenciamento de gestores e membros de locais/sublocais integrados com a API Qualiex.
+> **⚠️ Importante:** O módulo fornece apenas a INTERFACE. A lógica de persistência deve ser implementada pelo projeto consumidor.
 
-#### Importação
+**Regras sugeridas:**
+1. **Um gestor por local** - Ao atribuir novo gestor, remover o anterior
+2. **Múltiplos membros por local** - Sem limite
+3. **Usuário não pode ser gestor e membro simultaneamente** do mesmo local
+4. **Validar permissões** antes de salvar
 
-```typescript
-import {
-  PlaceManagerButton,
-  PlaceManagerBadge,
-  ManagerSelectionDialog,
-  usePlaceManagers,
-  PlaceManagerService,
-  type PlaceManager
-} from 'forlogic-core';
-```
+---
 
-#### Componentes
+#### 🗄️ Estrutura de Banco Sugerida (Supabase)
 
-**PlaceManagerButton** - Botão dropdown com ações de gerenciamento:
+```sql
+CREATE TABLE IF NOT EXISTS public.place_access (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  place_id text NOT NULL,
+  user_id text NOT NULL,
+  user_name text NOT NULL,
+  user_email text NOT NULL,
+  role text NOT NULL CHECK (role IN ('manager', 'member')),
+  created_at timestamptz DEFAULT now(),
+  updated_at timestamptz DEFAULT now(),
+  UNIQUE (place_id, user_id)
+);
 
-```tsx
-<PlaceManagerButton
-  placeId="abc-123"
-  placeName="Matriz São Paulo"
-  serviceConfig={{ tableName: 'place_managers' }}
-/>
-```
+CREATE INDEX idx_place_access_place ON public.place_access(place_id);
+CREATE INDEX idx_place_access_user ON public.place_access(user_id);
 
-**PlaceManagerBadge** - Badge visual com contador de gestores:
+-- RLS Policies
+ALTER TABLE public.place_access ENABLE ROW LEVEL SECURITY;
 
-```tsx
-<PlaceManagerBadge
-  placeId="abc-123"
-  userCount={15}
-/>
+CREATE POLICY "Users can view place access"
+  ON public.place_access FOR SELECT
+  USING (true);
+
+CREATE POLICY "Authenticated users can manage place access"
+  ON public.place_access FOR ALL
+  USING (auth.role() = 'authenticated');
 ```
 
-**ManagerSelectionDialog** - Diálogo completo de seleção:
+---
 
-```tsx
-<ManagerSelectionDialog
-  open={showDialog}
-  onOpenChange={setShowDialog}
-  onSelectManager={(user) => console.log('Gestor:', user)}
-  onSelectMember={(user) => console.log('Membro:', user)}
-  currentManagerId={manager?.user_id}
-  currentMemberIds={members.map(m => m.user_id)}
-  placeName="Matriz São Paulo"
-/>
-```
+#### 💡 Exemplo Completo de Implementação
 
-#### Hook: usePlaceManagers
+**1. Service de Acesso (`src/places/services/PlaceAccessService.ts`):**
 
 ```typescript
-const {
-  managers,      // Todos (gestor + membros)
-  manager,       // Apenas o gestor
-  members,       // Apenas membros
-  setManager,    // (user: QualiexUser) => void
-  addMember,     // (user: QualiexUser) => void
-  remove,        // (userId: string) => void
-  isLoading
-} = usePlaceManagers(placeId);
+import { getSupabaseClient } from 'forlogic-core';
+
+class PlaceAccessService {
+  private supabase = getSupabaseClient();
+
+  async getAllAccess() {
+    const { data, error } = await this.supabase
+      .from('place_access')
+      .select('*');
+    
+    if (error) throw error;
+    return data;
+  }
+
+  async setManager(placeId: string, userId: string, userName: string, userEmail: string) {
+    // Remover gestor anterior
+    await this.supabase
+      .from('place_access')
+      .delete()
+      .eq('place_id', placeId)
+      .eq('role', 'manager');
+
+    // Adicionar novo gestor
+    const { error } = await this.supabase
+      .from('place_access')
+      .insert({
+        place_id: placeId,
+        user_id: userId,
+        user_name: userName,
+        user_email: userEmail,
+        role: 'manager'
+      });
+
+    if (error) throw error;
+  }
+
+  async addMembers(
+    placeId: string, 
+    users: Array<{userId: string, userName: string, userEmail: string}>
+  ) {
+    const { error } = await this.supabase
+      .from('place_access')
+      .upsert(
+        users.map(user => ({
+          place_id: placeId,
+          user_id: user.userId,
+          user_name: user.userName,
+          user_email: user.userEmail,
+          role: 'member'
+        }))
+      );
+
+    if (error) throw error;
+  }
+}
+
+export const placeAccessService = new PlaceAccessService();
 ```
 
-#### Service: PlaceManagerService
+**2. Hook Customizado (`src/places/hooks/usePlaceAccess.ts`):**
 
 ```typescript
-import { PlaceManagerService } from 'forlogic-core';
+import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
+import { placeAccessService } from '../services/PlaceAccessService';
+import { useToast } from 'forlogic-core';
+import type { QualiexUser } from 'forlogic-core';
 
-// Instância customizada
-const service = new PlaceManagerService({
-  tableName: 'my_place_managers',
-  schemaName: 'custom_schema'
-});
+export function usePlaceAccess() {
+  const queryClient = useQueryClient();
+  const { toast } = useToast();
+
+  const { data: accessData = [] } = useQuery({
+    queryKey: ['placeAccess'],
+    queryFn: () => placeAccessService.getAllAccess(),
+  });
+
+  const setManagerMutation = useMutation({
+    mutationFn: ({ placeId, user }: { placeId: string; user: QualiexUser }) =>
+      placeAccessService.setManager(
+        placeId, 
+        user.userId!, 
+        user.userName!, 
+        user.userEmail!
+      ),
+    onSuccess: () => {
+      queryClient.invalidateQueries(['placeAccess']);
+      toast({ title: 'Gestor definido com sucesso' });
+    },
+    onError: () => {
+      toast({ 
+        title: 'Erro ao definir gestor', 
+        variant: 'destructive' 
+      });
+    }
+  });
+
+  const addMembersMutation = useMutation({
+    mutationFn: ({ placeId, users }: { placeId: string; users: QualiexUser[] }) =>
+      placeAccessService.addMembers(
+        placeId,
+        users.map(u => ({ 
+          userId: u.userId!, 
+          userName: u.userName!, 
+          userEmail: u.userEmail! 
+        }))
+      ),
+    onSuccess: () => {
+      queryClient.invalidateQueries(['placeAccess']);
+      toast({ title: 'Membros adicionados com sucesso' });
+    },
+    onError: () => {
+      toast({ 
+        title: 'Erro ao adicionar membros', 
+        variant: 'destructive' 
+      });
+    }
+  });
 
-// Métodos disponíveis
-await service.getPlaceManagers(alias, placeId);
-await service.setManager(alias, placeId, user);
-await service.addMember(alias, placeId, user);
-await service.removePlaceUser(alias, placeId, userId);
+  return {
+    accessData,
+    setManager: setManagerMutation.mutateAsync,
+    addMembers: addMembersMutation.mutateAsync,
+  };
+}
 ```
 
-> ⚠️ A configuração do banco de dados (tabelas, RLS policies) deve ser feita no projeto consumidor.
+**3. Página Final (`src/places/PlacesPage.tsx`):**
 
-#### Regras de Negócio
+```typescript
+import { useQuery } from '@tanstack/react-query';
+import { useAuth, TokenManager, placeService, PlacesList, Card } from 'forlogic-core';
+import { usePlaceAccess } from './hooks/usePlaceAccess';
+import { useQualiexUsers } from 'forlogic-core';
 
-1. **Um gestor por local** - Ao definir novo gestor, o anterior é removido automaticamente
-2. **Membros ilimitados** - Múltiplos membros podem ser adicionados
-3. **Ordenação alfabética** - Sempre ordenado por nome
-4. **Busca inteligente** - Filtra por nome ou email
+export function PlacesPage() {
+  const { alias } = useAuth();
+  const tokenData = TokenManager.extractTokenData();
+  const companyId = tokenData?.companyId;
+  
+  const { data: places = [], isLoading } = useQuery({
+    queryKey: ['places', alias, companyId],
+    queryFn: () => placeService.getPlaces(alias!, companyId!),
+    enabled: !!alias && !!companyId,
+  });
 
-#### Exemplo Completo
+  const { accessData, setManager, addMembers } = usePlaceAccess();
+  const { data: users = [] } = useQualiexUsers();
 
-```tsx
-function PlaceTreeItem({ place }) {
-  return (
-    <div className="flex items-center gap-3">
-      <span>{place.name}</span>
+  const handleMakeManager = async (userId: string, placeId: string) => {
+    const user = users.find(u => u.userId === userId);
+    if (user) {
+      await setManager({ placeId, user });
+    }
+  };
 
-      <PlaceManagerBadge
-        placeId={place.id}
-        userCount={place.usersIds.length}
-      />
+  const handleMakeMembers = async (userIds: string[], placeId: string) => {
+    const selectedUsers = users.filter(u => userIds.includes(u.userId!));
+    await addMembers({ placeId, users: selectedUsers });
+  };
 
-      <PlaceManagerButton
-        placeId={place.id}
-        placeName={place.name}
-      />
+  const getCurrentManagerId = (placeId: string) => {
+    return accessData.find(a => a.place_id === placeId && a.role === 'manager')?.user_id;
+  };
+
+  const getCurrentMemberIds = (placeId: string) => {
+    return accessData
+      .filter(a => a.place_id === placeId && a.role === 'member')
+      .map(a => a.user_id);
+  };
+
+  return (
+    <div className="container mx-auto py-6 space-y-6">
+      <div className="flex flex-col gap-2">
+        <h1 className="text-3xl font-bold tracking-tight">Locais</h1>
+        <p className="text-muted-foreground">
+          Visualização hierárquica de locais e gestão de acessos
+        </p>
+      </div>
+
+      <Card className="p-6">
+        <PlacesList
+          places={places}
+          isLoading={isLoading}
+          manageAccessConfig={{
+            onMakeManager: handleMakeManager,
+            onMakeMembers: handleMakeMembers,
+            getCurrentManagerId,
+            getCurrentMemberIds
+          }}
+        />
+      </Card>
     </div>
   );
 }
@@ -1167,6 +2093,44 @@ function PlaceTreeItem({ place }) {
 
 ---
 
+#### 🛠️ Troubleshooting
+
+| Problema | Causa | Solução |
+|----------|-------|---------|
+| Botão "Gerenciar Acessos" não aparece | `manageAccessConfig` não fornecido | Passar objeto `manageAccessConfig` para `PlacesList` |
+| Lista de usuários vazia no modal | `useQualiexUsers` não retorna dados | Verificar token e configuração de alias |
+| Erro ao salvar gestor/membro | Callbacks não implementados | Implementar `onMakeManager` e `onMakeMembers` |
+| Hierarquia não exibe sublocais | Dados sem `parentId` correto | Verificar estrutura retornada pela API Qualiex |
+| Modal não abre | Estado `open` não controlado | Verificar se `ActionMenu` está funcionando |
+
+---
+
+#### ✅ Checklist de Implementação
+
+- [ ] Importar componentes do `forlogic-core/places`
+- [ ] Criar tabela `place_access` no Supabase (ou equivalente)
+- [ ] Implementar `PlaceAccessService` com métodos CRUD
+- [ ] Criar hook `usePlaceAccess` com React Query
+- [ ] Configurar `manageAccessConfig` na página
+- [ ] Testar seleção de gestor (apenas 1 usuário)
+- [ ] Testar seleção de membros (múltiplos usuários)
+- [ ] Implementar regra de "remover gestor anterior"
+- [ ] Adicionar toast de sucesso/erro
+- [ ] Testar busca de usuários no modal
+- [ ] Validar ordenação alfabética
+
+---
+
+#### 📚 Referências
+
+- **Componentes:** `lib/places/components/`
+- **Service:** `lib/places/services/PlaceService.ts`
+- **Types:** `lib/places/types.ts`
+- **Exports:** `lib/places/index.ts`
+- **Exemplo completo:** `src/places/PlacesPage.tsx`
+
+---
+
 ### ✅ CHECKLIST (antes de implementar)
 
 - [ ] Schema `schema` especificado em queries e service?
@@ -1734,35 +2698,356 @@ export default function ProcessesPage() {
 }
 ```
 
-#### **Integração com Bulk Actions:**
+#### **Integração com Bulk Actions:**
+
+```typescript
+customActions: [
+  {
+    label: 'Exportar Selecionados',
+    icon: Download,
+    variant: 'outline',
+    action: () => {
+      if (manager.selectedIds.length === 0) {
+        toast({ title: 'Selecione pelo menos um item', variant: 'destructive' });
+        return;
+      }
+      
+      const selectedItems = manager.entities.filter(
+        item => manager.selectedIds.includes(item.id)
+      );
+      exportToCSV(selectedItems);
+    }
+  }
+]
+```
+
+**Boas Práticas:**
+- ✅ Use `useMemo` para evitar recriação em cada render
+- ✅ Use `variant="outline"` para ações secundárias
+- ✅ Use ícones do `lucide-react` para consistência visual
+- ✅ Mostre feedback (loading, toasts) para ações assíncronas
+- ❌ Evite muitas ações (máximo 3-4 para não poluir a UI)
+
+---
+
+### **🔍 TUTORIAL COMPLETO: FILTROS E EXPORTAÇÃO**
+
+Este tutorial mostra como implementar filtros customizados e botão de exportação em páginas CRUD.
+
+---
+
+#### **📋 Cenário: Página de Exemplos com Filtro de Status e Exportação**
+
+Vamos criar uma página que:
+1. ✅ Filtra exemplos por status (Ativo/Inativo/Todos)
+2. ✅ Exporta todos os dados para CSV (não apenas da página atual)
+3. ✅ Mantém filtros aplicados ao exportar
+
+---
+
+#### **Passo 1: Configurar o Service**
+
+```typescript
+// src/examples/ExampleService.ts
+import { createSimpleService } from 'forlogic-core';
+import type { Example, CreateExamplePayload, UpdateExamplePayload } from './example';
+
+export const { service: ExampleService, useCrudHook: useExamplesCrud } = 
+  createSimpleService<Example, CreateExamplePayload, UpdateExamplePayload>({
+    tableName: 'examples',
+    entityName: 'Exemplo',
+    searchFields: ['title', 'description'],
+    schemaName: 'central',
+    enableQualiexEnrichment: true
+  });
+```
+
+**✅ Por que exportar o `service`?**
+- Permite chamar `ExampleService.getAll()` diretamente para exportação
+- Busca todos os registros sem depender do manager paginado
+
+---
+
+#### **Passo 2: Criar Componente de Filtro**
+
+```typescript
+// src/examples/ExamplesPage.tsx
+
+// 1️⃣ Estado do filtro (padrão: true = apenas Ativos)
+const [statusFilter, setStatusFilter] = useState<boolean | 'all'>(true);
+
+// 2️⃣ Manager com filtro aplicado no backend
+const manager = useExamplesCrud(
+  statusFilter === 'all' ? {} : { is_actived: statusFilter }
+);
+
+// 3️⃣ Componente de filtro customizado
+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]"
+  />
+);
+```
+
+**📝 Como funciona:**
+- `statusFilter` controla o estado do filtro
+- `useExamplesCrud` recebe `{ is_actived: true }` como filtro backend
+- Backend retorna apenas registros com `is_actived = true`
+- Paginação mostra total correto (ex: "1-10 de 43 itens")
+
+---
+
+#### **Passo 3: Implementar Exportação para CSV**
+
+```typescript
+// src/examples/ExamplesPage.tsx
+import { Download } from 'lucide-react';
+import { useToast, formatDatetime } from 'forlogic-core';
+import { ExampleService } from './ExampleService';
+
+export const ExamplesPage = () => {
+  const { toast } = useToast();
+  const [statusFilter, setStatusFilter] = useState<boolean | 'all'>(true);
+  const manager = useExamplesCrud(
+    statusFilter === 'all' ? {} : { is_actived: statusFilter }
+  );
+
+  // 🚀 Função de exportação (busca TODOS os itens)
+  const handleExport = async () => {
+    try {
+      // 1️⃣ Mostrar feedback
+      toast({
+        title: 'Exportando...',
+        description: 'Buscando todos os registros'
+      });
+
+      // 2️⃣ Buscar TODOS os registros (limite alto)
+      const filters = statusFilter === 'all' ? {} : { is_actived: statusFilter };
+      const allData = await ExampleService.getAll({
+        search: manager.searchTerm, // Manter busca atual
+        limit: 10000, // Limite alto para buscar tudo
+        page: 1,
+        ...filters // Aplicar filtros de status
+      });
+
+      // 3️⃣ Validar dados
+      if (!allData.data || allData.data.length === 0) {
+        toast({
+          variant: 'destructive',
+          title: 'Nenhum dado disponível',
+          description: 'Não há dados para exportar'
+        });
+        return;
+      }
+
+      // 4️⃣ Definir cabeçalhos do CSV
+      const headers = [
+        'Título',
+        'Responsável',
+        'Status',
+        'Link',
+        'Descrição',
+        'Cor',
+        'Ícone',
+        'Atualizado em'
+      ];
+      
+      // 5️⃣ Mapear dados para linhas CSV
+      const rows = allData.data.map((item: Example) => [
+        item.title || '',
+        item.responsible_name || '',
+        item.is_actived ? 'Ativo' : 'Inativo',
+        item.url_field || '',
+        item.description || '',
+        item.color || '',
+        item.icon_name || '',
+        formatDatetime(item.updated_at)
+      ]);
+
+      // 6️⃣ Criar conteúdo CSV
+      const csvContent = [
+        headers.join(','),
+        ...rows.map(row => 
+          row.map(cell => `"${String(cell).replace(/"/g, '""')}"`).join(',')
+        )
+      ].join('\n');
+
+      // 7️⃣ Criar blob e fazer download
+      const blob = new Blob(['\ufeff' + csvContent], { 
+        type: 'text/csv;charset=utf-8;' 
+      });
+      const link = document.createElement('a');
+      const url = URL.createObjectURL(blob);
+      link.setAttribute('href', url);
+      link.setAttribute('download', `exemplos_${new Date().toISOString().split('T')[0]}.csv`);
+      link.style.visibility = 'hidden';
+      document.body.appendChild(link);
+      link.click();
+      document.body.removeChild(link);
+
+      // 8️⃣ Feedback de sucesso
+      toast({
+        title: 'Exportação concluída',
+        description: `${allData.data.length} registros exportados com sucesso`
+      });
+    } catch (error) {
+      console.error('Erro ao exportar:', error);
+      toast({
+        variant: 'destructive',
+        title: 'Erro na exportação',
+        description: 'Não foi possível exportar os dados'
+      });
+    }
+  };
+
+  // Restante do código...
+};
+```
+
+**⚠️ IMPORTANTE:**
+- `ExampleService.getAll()` busca TODOS os registros (não só da página)
+- Limite de 10.000 itens - ajuste se necessário
+- `\ufeff` adiciona BOM para Unicode (acentos no Excel)
+- Escape de aspas duplas: `""` dentro do CSV
+
+---
+
+#### **Passo 4: Configurar `customActions` e `filters`**
+
+```typescript
+// src/examples/ExamplesPage.tsx
+
+const CrudPage = createCrudPage({
+  manager,
+  config: {
+    entityName: 'exemplo',
+    entityNamePlural: 'exemplos',
+    columns: exampleColumns,
+    formSections,
+    
+    // ✅ Filtros na barra superior
+    filters: [
+      { type: 'search' }, // Busca padrão
+      { type: 'custom', component: StatusFilter } // Filtro customizado
+    ],
+    
+    // ✅ Botão de exportar na barra de ações
+    customActions: [
+      {
+        label: 'Exportar',
+        icon: Download as any,
+        variant: 'outline' as const,
+        action: handleExport
+      }
+    ],
+    
+    enableBulkActions: true
+  },
+  onSave: handleSave,
+  onToggleStatus: handleToggleStatus
+});
+```
+
+---
+
+#### **🎯 Tipos de Filtros Disponíveis**
+
+##### **1. Filtro de Busca (Search)**
+```typescript
+filters: [
+  { type: 'search' } // Busca automática nos searchFields do service
+]
+```
+
+##### **2. Filtro Select Nativo**
+```typescript
+filters: [
+  {
+    type: 'select',
+    placeholder: 'Status',
+    value: statusFilter,
+    onChange: setStatusFilter,
+    options: [
+      { value: 'all', label: '[Todos]' },
+      { value: 'active', label: 'Ativo' },
+      { value: 'inactive', label: 'Inativo' }
+    ]
+  }
+]
+```
+
+##### **3. Filtro Customizado (Recomendado)**
+```typescript
+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"
+  />
+);
+
+filters: [
+  { type: 'custom', component: StatusFilter }
+]
+```
+
+---
 
-```typescript
-customActions: [
-  {
-    label: 'Exportar Selecionados',
-    icon: Download,
-    variant: 'outline',
-    action: () => {
-      if (manager.selectedIds.length === 0) {
-        toast({ title: 'Selecione pelo menos um item', variant: 'destructive' });
-        return;
-      }
-      
-      const selectedItems = manager.entities.filter(
-        item => manager.selectedIds.includes(item.id)
-      );
-      exportToCSV(selectedItems);
-    }
-  }
-]
+#### **📊 Resultado Visual**
+
+**Barra de Ações:**
+```
+[ + Novo ] [ 🔽 Exportar ]   [ 🔍 Buscar... ] [ Status: Ativo ▼ ]
 ```
 
-**Boas Práticas:**
-- ✅ Use `useMemo` para evitar recriação em cada render
-- ✅ Use `variant="outline"` para ações secundárias
-- ✅ Use ícones do `lucide-react` para consistência visual
-- ✅ Mostre feedback (loading, toasts) para ações assíncronas
-- ❌ Evite muitas ações (máximo 3-4 para não poluir a UI)
+**Ao clicar em "Exportar":**
+1. ✅ Toast: "Exportando... Buscando todos os registros"
+2. ✅ Download automático: `exemplos_2025-01-21.csv`
+3. ✅ Toast: "43 registros exportados com sucesso"
+
+**Conteúdo do CSV:**
+```csv
+Título,Responsável,Status,Link,Descrição,Cor,Ícone,Atualizado em
+"Exemplo 1","João Silva","Ativo","https://...","Descrição exemplo","#3b82f6","Star","21/01/2025 14:30"
+"Exemplo 2","Maria Santos","Inativo","","Outro exemplo","#f59e0b","Heart","20/01/2025 09:15"
+```
+
+---
+
+#### **🔥 Boas Práticas**
+
+**✅ FAZER:**
+- Exportar via `service.getAll()` para buscar todos os registros
+- Aplicar mesmos filtros na exportação
+- Escapar aspas duplas: `cell.replace(/"/g, '""')`
+- Adicionar BOM Unicode: `\ufeff` para acentos
+- Mostrar feedback (toast) durante exportação
+- Usar `async/await` para exportação
+
+**❌ NÃO FAZER:**
+- Exportar apenas `manager.entities` (só dados da página atual)
+- Ignorar filtros aplicados ao exportar
+- Esquecer de tratar erros
+- Exportar sem feedback visual
+
+---
 
 ---
 
@@ -3400,339 +4685,6 @@ 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
 
@@ -4256,6 +5208,195 @@ const columns: CrudColumn<MyEntity>[] = [
 
 ---
 
+## 📧 ENVIO DE EMAILS
+
+O `forlogic-core` fornece um serviço padronizado para envio de emails usando templates cadastrados no banco de dados.
+
+### **Como Funciona**
+
+1. **Template no banco**: Cadastre templates na tabela `common.email_templates` com variáveis usando `{{variableName}}`
+2. **Envio via código**: Use `emailService.sendEmail()` passando o código do template e as variáveis
+3. **Edge Function**: Automaticamente busca o template, substitui as variáveis e envia via SMTP
+4. **Logs**: Registra todos os envios em `common.email_logs`
+
+### **Uso Básico**
+
+```typescript
+import { emailService } from 'forlogic-core';
+
+// Enviar email de boas-vindas
+await emailService.sendEmail({
+  templateCode: 'WELCOME',
+  to: 'usuario@exemplo.com',
+  variables: {
+    userName: 'João Silva',
+    activationLink: 'https://app.com/activate/abc123',
+    companyName: 'Minha Empresa'
+  }
+});
+
+// Enviar para múltiplos destinatários
+await emailService.sendEmail({
+  templateCode: 'NOTIFICATION',
+  to: ['usuario1@exemplo.com', 'usuario2@exemplo.com'],
+  variables: {
+    title: 'Novo documento disponível',
+    message: 'Um documento foi compartilhado com você',
+    actionUrl: 'https://app.com/docs/123',
+    actionLabel: 'Ver Documento'
+  },
+  cc: ['gestor@exemplo.com'],
+  replyTo: 'suporte@empresa.com'
+});
+```
+
+### **Parâmetros do emailService.sendEmail()**
+
+```typescript
+interface SendEmailParams {
+  templateCode: string;      // Código do template no banco (ex: 'WELCOME')
+  to: string | string[];      // Email(s) do(s) destinatário(s)
+  variables: Record<string, any>; // Variáveis para substituir no template
+  cc?: string[];             // Emails em cópia (opcional)
+  bcc?: string[];            // Emails em cópia oculta (opcional)
+  replyTo?: string;          // Email para resposta (opcional)
+}
+```
+
+### **Criando Templates no Banco**
+
+Os templates devem ser cadastrados na tabela `common.email_templates`:
+
+```sql
+INSERT INTO common.email_templates (
+  alias,
+  template_code,
+  template_name,
+  subject,
+  html_body,
+  is_active
+) VALUES (
+  'minha_empresa',
+  'WELCOME',
+  'Email de Boas-vindas',
+  'Bem-vindo, {{userName}}!',
+  '<h1>Olá, {{userName}}!</h1>
+   <p>Bem-vindo à {{companyName}}!</p>
+   <a href="{{activationLink}}">Ativar Conta</a>',
+  true
+);
+```
+
+### **Variáveis nos Templates**
+
+Use a sintaxe `{{variableName}}` tanto no subject quanto no html_body:
+
+```html
+<!-- Exemplo de template HTML -->
+<div style="font-family: Arial, sans-serif;">
+  <h1>Olá, {{userName}}!</h1>
+  <p>{{message}}</p>
+  
+  {{#if actionUrl}}
+  <a href="{{actionUrl}}" style="background: #0066cc; color: white; padding: 10px 20px;">
+    {{actionLabel}}
+  </a>
+  {{/if}}
+  
+  <p>Atenciosamente,<br>{{companyName}}</p>
+</div>
+```
+
+### **Tratamento de Erros**
+
+```typescript
+try {
+  await emailService.sendEmail({
+    templateCode: 'NOTIFICATION',
+    to: 'usuario@exemplo.com',
+    variables: { title: 'Teste', message: 'Mensagem' }
+  });
+  
+  toast.success('Email enviado com sucesso!');
+} catch (error) {
+  console.error('Erro ao enviar email:', error);
+  toast.error('Erro ao enviar email. Verifique as configurações SMTP.');
+}
+```
+
+### **Requisitos**
+
+1. **Edge Function**: A edge function `send-email` deve estar configurada
+2. **Secrets SMTP**: Configure as secrets no Supabase:
+   - `SMTP_HOST` - Servidor SMTP (ex: smtp.gmail.com)
+   - `SMTP_PORT` - Porta SMTP (ex: 587)
+   - `SMTP_USER` - Usuário SMTP
+   - `SMTP_PASSWORD` - Senha SMTP
+   - `SMTP_FROM` - Email remetente (ex: noreply@empresa.com)
+
+3. **Tabelas**: 
+   - `common.email_templates` - Armazena os templates
+   - `common.email_logs` - Registra os envios
+
+### **Exemplo Completo: Notificação de Mudança de Liderança**
+
+```typescript
+import { emailService } from 'forlogic-core';
+import { toast } from 'sonner';
+
+async function notifyLeadershipChange(
+  employeeEmail: string,
+  employeeName: string,
+  newLeaderName: string,
+  oldLeaderName?: string
+) {
+  try {
+    await emailService.sendEmail({
+      templateCode: 'LEADERSHIP_CHANGE',
+      to: employeeEmail,
+      variables: {
+        employeeName,
+        newLeaderName,
+        oldLeaderName: oldLeaderName || 'Nenhum líder anterior',
+        companyName: 'ForLogic',
+        changeDate: new Date().toLocaleDateString('pt-BR')
+      }
+    });
+    
+    console.log(`Email de mudança de liderança enviado para ${employeeName}`);
+  } catch (error) {
+    console.error('Erro ao enviar email de liderança:', error);
+    throw error;
+  }
+}
+
+// Uso
+await notifyLeadershipChange(
+  'joao@empresa.com',
+  'João Silva',
+  'Maria Santos',
+  'Pedro Costa'
+);
+```
+
+### **Boas Práticas**
+
+**✅ FAZER:**
+- Cadastrar todos os templates no banco com `is_active = true`
+- Usar nomes de variáveis descritivos (ex: `userName`, `actionUrl`)
+- Tratar erros de envio com try/catch
+- Validar emails antes de enviar
+- Logar envios importantes para auditoria
+
+**❌ NÃO FAZER:**
+- Hardcodar templates no código
+- Enviar sem validar variáveis obrigatórias
+- Ignorar erros de envio
+- Usar variáveis não declaradas no template
+- Enviar emails sem confirmação do usuário (quando necessário)
+
+---
+
 ## 📚 REFERÊNCIA RÁPIDA
 
 ### Imports Essenciais