forlogic-core 1.7.7 → 1.8.1

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'`.
 
@@ -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,35 +616,238 @@ 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,
+  }
+];
 ```
 
-**Rich Text Editor:**
+**Exemplo 2: Select de Usuários do Qualiex**
 
 ```typescript
-{
-  name: 'content',
-  type: 'custom',
-  component: RichTextEditor,
-  componentProps: {
-    toolbar: ['bold', 'italic', 'link']
+// 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
+    }
   }
+];
+```
+
+**Exemplo 3: MultiSelect de Treinamentos Anuais**
+
+```typescript
+// 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
@@ -1393,400 +1638,454 @@ userFieldsMapping: [
 
 ---
 
-### 🏢 Sistema de Gestores de Locais (Qualiex)
+### 🏢 Places - Hierarquia de Locais com Gerenciamento de Acessos
 
-Componentes reutilizáveis para gerenciamento de gestores e membros de locais/sublocais integrados com a API Qualiex.
+Sistema completo para visualização hierárquica de locais e gerenciamento configurável de acessos (gestores e membros).
 
-> **⚠️ IMPORTANTE:** Esta funcionalidade requer configuração de tabela no banco de dados do projeto consumidor. A biblioteca fornece os componentes, mas **você deve criar e configurar a tabela e o serviço** no seu projeto.
-
----
-
-#### 📦 Importação
+#### 📦 Importações
 
 ```typescript
-import {
-  PlaceManagerButton,
-  PlaceManagerBadge,
-  ManagerSelectionDialog,
-  usePlaceManagers,
-  PlaceManagerService,
-  type PlaceManagerServiceConfig,
-  type PlaceManager
-} from 'forlogic-core';
-```
+// Componentes
+import { PlacesList, PlaceCard, ManageAccessModal } from 'forlogic-core/places';
 
----
+// Service
+import { placeService } from 'forlogic-core/places';
 
-#### 🔧 Configuração Inicial (OBRIGATÓRIO)
+// Types
+import type { Place, PlacesListProps, PlaceCardProps, ManageAccessModalProps } from 'forlogic-core/places';
 
-##### **Passo 1: Criar a Tabela no Supabase**
+// Ou importação completa
+import { PlacesList, placeService } from 'forlogic-core';
+```
 
-A biblioteca espera uma tabela com a seguinte estrutura:
+#### 📋 Tipos de Dados
 
-```sql
-CREATE TABLE IF NOT EXISTS public.place_managers (
-  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
-  alias text NOT NULL,
-  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(),
-  
-  -- Constraint: Um usuário não pode ter múltiplas funções no mesmo local
-  UNIQUE (alias, place_id, user_id)
-);
+```typescript
+interface Place {
+  id: string;
+  name: string;
+  usersCount?: number;
+  hasChild?: boolean;
+  isActive?: boolean;
+  parentId?: string;
+  parentName?: string;
+  subPlaces?: Place[];
+}
+```
 
--- Índices para performance
-CREATE INDEX idx_place_managers_alias_place ON public.place_managers(alias, place_id);
-CREATE INDEX idx_place_managers_user ON public.place_managers(user_id);
+#### 🎯 Uso Básico - Apenas Visualização
 
--- RLS Policies (exemplo - ajustar conforme necessidade)
-ALTER TABLE public.place_managers ENABLE ROW LEVEL SECURITY;
+```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;
 
-CREATE POLICY "Users view own alias managers"
-  ON public.place_managers FOR SELECT
-  USING (((SELECT auth.jwt()) ->> 'alias'::text) = alias);
+  const { data: places = [], isLoading } = useQuery({
+    queryKey: ['places', alias, companyId],
+    queryFn: () => placeService.getPlaces(alias!, companyId!),
+    enabled: !!alias && !!companyId,
+  });
 
-CREATE POLICY "Users manage own alias managers"
-  ON public.place_managers FOR ALL
-  USING (((SELECT auth.jwt()) ->> 'alias'::text) = alias);
+  return <PlacesList places={places} isLoading={isLoading} />;
+}
 ```
 
-> 💡 **Dica:** Você pode usar um nome de tabela e schema diferentes, basta configurar no próximo passo.
+> **💡 Neste modo**, o `PlacesList` apenas renderiza a hierarquia visual. O botão "Gerenciar Acessos" não aparece.
 
 ---
 
-##### **Passo 2: Criar o Serviço no Seu Projeto**
-
-Crie um arquivo de serviço customizado no seu projeto:
+#### 🔐 Uso Avançado - Com Gerenciamento de Acessos
 
 ```typescript
-// src/services/placeManagerService.ts
-import { PlaceManagerService } from 'forlogic-core';
-
-export const placeManagerService = new PlaceManagerService({
-  tableName: 'place_managers',  // 🔧 Nome da sua tabela
-  schemaName: 'public'          // 🔧 Nome do schema
-});
+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;
+  };
+}
 ```
 
-**Configurações disponíveis:**
-
-| Propriedade  | Tipo     | Padrão             | Descrição                      |
-| ------------ | -------- | ------------------ | ------------------------------ |
-| `tableName`  | `string` | `'place_managers'` | Nome da tabela no Supabase     |
-| `schemaName` | `string` | `'public'`         | Nome do schema (geralmente 'public') |
+**Exemplo Completo:**
 
----
+```typescript
+import { PlacesList, Card } from 'forlogic-core';
+import { useAuth, placeService } from 'forlogic-core';
+import { useQuery } from '@tanstack/react-query';
 
-#### 🎨 Componentes
+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,
+  });
 
-##### **PlaceManagerButton**
+  // Buscar gestores e membros atuais (implementação do módulo)
+  const { data: accessData = [] } = useQuery({
+    queryKey: ['placeAccess'],
+    queryFn: () => myAccessService.getAllAccess(),
+  });
 
-Botão dropdown com ações de gerenciamento (trocar gestor, remover gestor).
+  // Callbacks de gerenciamento
+  const handleMakeManager = async (userId: string, placeId: string) => {
+    await myAccessService.setManager(placeId, userId);
+    queryClient.invalidateQueries(['placeAccess']);
+  };
 
-```tsx
-import { PlaceManagerButton } from 'forlogic-core';
-import { placeManagerService } from '@/services/placeManagerService';
+  const handleMakeMembers = async (userIds: string[], placeId: string) => {
+    await myAccessService.addMembers(placeId, userIds);
+    queryClient.invalidateQueries(['placeAccess']);
+  };
 
-<PlaceManagerButton
-  placeId="abc-123"
-  placeName="Matriz São Paulo"
-  service={placeManagerService}  // ⚠️ OBRIGATÓRIO
-/>
-```
+  const getCurrentManagerId = (placeId: string) => {
+    return accessData.find(a => a.placeId === placeId && a.role === 'manager')?.userId;
+  };
 
-**Props:**
+  const getCurrentMemberIds = (placeId: string) => {
+    return accessData.filter(a => a.placeId === placeId && a.role === 'member').map(a => a.userId);
+  };
 
-| Prop        | Tipo                   | Obrigatório | Descrição                        |
-| ----------- | ---------------------- | ----------- | -------------------------------- |
-| `placeId`   | `string`               | ✅          | ID do local                      |
-| `placeName` | `string`               | ✅          | Nome do local (para exibição)    |
-| `service`   | `PlaceManagerService`  | ✅          | Instância do serviço configurado |
+  return (
+    <Card className="p-6">
+      <PlacesList
+        places={places}
+        isLoading={isLoading}
+        manageAccessConfig={{
+          onMakeManager: handleMakeManager,
+          onMakeMembers: handleMakeMembers,
+          getCurrentManagerId,
+          getCurrentMemberIds
+        }}
+      />
+    </Card>
+  );
+}
+```
 
 ---
 
-##### **PlaceManagerBadge**
+#### 🎨 Componentes Individuais
 
-Badge visual que mostra "Gestor" ou "Gestores" com contador de usuários.
+##### PlacesList
 
-```tsx
-import { PlaceManagerBadge } from 'forlogic-core';
-import { placeManagerService } from '@/services/placeManagerService';
-
-<PlaceManagerBadge
-  placeId="abc-123"
-  userCount={15}
-  service={placeManagerService}  // ⚠️ OBRIGATÓRIO
-/>
-```
+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)
 
-| Prop        | Tipo                  | Obrigatório | Descrição                        |
-| ----------- | --------------------- | ----------- | -------------------------------- |
-| `placeId`   | `string`              | ✅          | ID do local                      |
-| `userCount` | `number`              | ✅          | Total de usuários do local       |
-| `service`   | `PlaceManagerService` | ✅          | Instância do serviço configurado |
-
-**Estados visuais:**
+##### PlaceCard
 
-- **"Gestor"** - Quando há 1 gestor definido
-- **"Gestores"** - Quando não há gestor definido (apenas membros)
+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)
 
-##### **ManagerSelectionDialog**
+##### ManageAccessModal
 
-Diálogo completo para seleção de gestores e membros com busca integrada.
+Modal para gerenciamento de acessos ao local.
 
-```tsx
-import { ManagerSelectionDialog } from 'forlogic-core';
-
-<ManagerSelectionDialog
-  open={showDialog}
-  onOpenChange={setShowDialog}
-  onSelectManager={(user) => handleSelectManager(user)}
-  onSelectMember={(user) => handleAddMember(user)}
-  currentManagerId={manager?.user_id}
-  currentMemberIds={members.map(m => m.user_id)}
-  placeName="Matriz São Paulo"
-  isLoading={false}
-/>
+```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[];
+}
 ```
 
-**Props:**
-
-| Prop               | Tipo                          | Obrigatório | Descrição                             |
-| ------------------ | ----------------------------- | ----------- | ------------------------------------- |
-| `open`             | `boolean`                     | ✅          | Controla visibilidade                 |
-| `onOpenChange`     | `(open: boolean) => void`     | ✅          | Callback de mudança de estado         |
-| `onSelectManager`  | `(user: QualiexUser) => void` | ✅          | Callback ao selecionar gestor         |
-| `onSelectMember`   | `(user: QualiexUser) => void` | ✅          | Callback ao adicionar membro          |
-| `currentManagerId` | `string`                      | ❌          | ID do gestor atual                    |
-| `currentMemberIds` | `string[]`                    | ❌          | IDs dos membros atuais                |
-| `placeName`        | `string`                      | ✅          | Nome do local (para exibição)         |
-| `isLoading`        | `boolean`                     | ❌          | Estado de loading externo (opcional)  |
+**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
 
 ---
 
-#### 🔧 Hook: usePlaceManagers
-
-Hook React Query para gerenciar gestores e membros de um local.
+#### 🔧 Service - placeService
 
 ```typescript
-import { usePlaceManagers } from 'forlogic-core';
-import { placeManagerService } from '@/services/placeManagerService';
+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`
 
-const {
-  managers,          // PlaceManager[] - Todos (gestor + membros)
-  manager,           // PlaceManager | undefined - Apenas o gestor
-  members,           // PlaceManager[] - Apenas membros
-  isLoading,         // boolean - Carregando dados iniciais
-  setManager,        // (user: QualiexUser) => void
-  addMember,         // (user: QualiexUser) => void
-  remove,            // (userId: string) => void
-  isSettingManager,  // boolean - Carregando mutação de gestor
-  isAddingMember,    // boolean - Carregando mutação de membro
-  isRemoving         // boolean - Carregando mutação de remoção
-} = usePlaceManagers(placeId, placeManagerService);
+**Exemplo:**
+```typescript
+const places = await placeService.getPlaces('my-alias', 'company-123');
 ```
 
-**Parâmetros:**
+---
 
-| Parâmetro | Tipo                  | Obrigatório | Descrição                                  |
-| --------- | --------------------- | ----------- | ------------------------------------------ |
-| `placeId` | `string`              | ✅          | ID do local                                |
-| `service` | `PlaceManagerService` | ✅          | Instância do serviço configurado           |
-| `enabled` | `boolean`             | ❌          | Habilitar/desabilitar query (default: `true`) |
+#### 🎯 Regras de Negócio
 
-**Retorno:**
+> **⚠️ Importante:** O módulo fornece apenas a INTERFACE. A lógica de persistência deve ser implementada pelo projeto consumidor.
 
-| Propriedade        | Tipo                          | Descrição                                      |
-| ------------------ | ----------------------------- | ---------------------------------------------- |
-| `managers`         | `PlaceManager[]`              | Todos os usuários (gestor + membros)           |
-| `manager`          | `PlaceManager \| undefined`   | Apenas o gestor (se existir)                   |
-| `members`          | `PlaceManager[]`              | Apenas membros (sem o gestor)                  |
-| `isLoading`        | `boolean`                     | Carregando dados iniciais                      |
-| `setManager`       | `(user: QualiexUser) => void` | Define novo gestor (remove anterior)           |
-| `addMember`        | `(user: QualiexUser) => void` | Adiciona membro ao local                       |
-| `remove`           | `(userId: string) => void`    | Remove usuário (gestor ou membro)              |
-| `isSettingManager` | `boolean`                     | Estado da mutação de definir gestor            |
-| `isAddingMember`   | `boolean`                     | Estado da mutação de adicionar membro          |
-| `isRemoving`       | `boolean`                     | Estado da mutação de remover                   |
+**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
 
 ---
 
-#### 🔧 Service: PlaceManagerService
+#### 🗄️ Estrutura de Banco Sugerida (Supabase)
 
-Classe para operações de banco de dados relacionadas a gestores de locais.
+```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)
+);
 
-##### **Instanciação Customizada**
+CREATE INDEX idx_place_access_place ON public.place_access(place_id);
+CREATE INDEX idx_place_access_user ON public.place_access(user_id);
 
-```typescript
-import { PlaceManagerService } from 'forlogic-core';
+-- RLS Policies
+ALTER TABLE public.place_access ENABLE ROW LEVEL SECURITY;
 
-// Configuração padrão (tabela 'place_managers' no schema 'public')
-const defaultService = new PlaceManagerService();
+CREATE POLICY "Users can view place access"
+  ON public.place_access FOR SELECT
+  USING (true);
 
-// Configuração customizada
-const customService = new PlaceManagerService({
-  tableName: 'gestores_locais',
-  schemaName: 'gestao'
-});
+CREATE POLICY "Authenticated users can manage place access"
+  ON public.place_access FOR ALL
+  USING (auth.role() = 'authenticated');
 ```
 
-##### **Métodos Disponíveis**
+---
+
+#### 💡 Exemplo Completo de Implementação
+
+**1. Service de Acesso (`src/places/services/PlaceAccessService.ts`):**
 
 ```typescript
-// Buscar gestores e membros de um local
-const managers = await placeManagerService.getPlaceManagers(
-  alias: string,
-  placeId: string
-);
-// Retorna: PlaceManager[]
+import { getSupabaseClient } from 'forlogic-core';
 
-// Definir gestor (remove anterior automaticamente)
-await placeManagerService.setManager(
-  alias: string,
-  placeId: string,
-  user: QualiexUser
-);
-// Retorna: void
+class PlaceAccessService {
+  private supabase = getSupabaseClient();
 
-// Adicionar membro
-await placeManagerService.addMember(
-  alias: string,
-  placeId: string,
-  user: QualiexUser
-);
-// Retorna: void
+  async getAllAccess() {
+    const { data, error } = await this.supabase
+      .from('place_access')
+      .select('*');
+    
+    if (error) throw error;
+    return data;
+  }
 
-// Remover usuário (gestor ou membro)
-await placeManagerService.removePlaceUser(
-  alias: string,
-  placeId: string,
-  userId: string
-);
-// Retorna: void
-```
+  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;
+  }
 
-#### 📘 Tipos
+  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'
+        }))
+      );
 
-```typescript
-interface PlaceManager {
-  id: string;
-  alias: string;
-  place_id: string;
-  user_id: string;
-  user_name: string;
-  user_email: string;
-  role: 'manager' | 'member';
-  created_at: string;
-  updated_at: string;
+    if (error) throw error;
+  }
 }
 
-interface PlaceManagerServiceConfig {
-  tableName?: string;   // Default: 'place_managers'
-  schemaName?: string;  // Default: 'public'
-}
+export const placeAccessService = new PlaceAccessService();
 ```
 
----
+**2. Hook Customizado (`src/places/hooks/usePlaceAccess.ts`):**
 
-#### 🎯 Regras de Negócio
+```typescript
+import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
+import { placeAccessService } from '../services/PlaceAccessService';
+import { useToast } from 'forlogic-core';
+import type { QualiexUser } 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 ao mesmo local
-3. ✅ **Ordenação alfabética**: Usuários sempre ordenados por nome
-4. ✅ **Busca inteligente**: Filtra por nome ou email do usuário
-5. ✅ **Integração Qualiex**: Utiliza `useQualiexUsers` para listar usuários
+export function usePlaceAccess() {
+  const queryClient = useQueryClient();
+  const { toast } = useToast();
 
----
+  const { data: accessData = [] } = useQuery({
+    queryKey: ['placeAccess'],
+    queryFn: () => placeAccessService.getAllAccess(),
+  });
 
-#### 💡 Exemplo Completo
+  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' 
+      });
+    }
+  });
 
-```tsx
-// 1. Criar serviço (src/services/placeManagerService.ts)
-import { PlaceManagerService } from 'forlogic-core';
+  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' 
+      });
+    }
+  });
 
-export const placeManagerService = new PlaceManagerService({
-  tableName: 'place_managers',
-  schemaName: 'public'
-});
+  return {
+    accessData,
+    setManager: setManagerMutation.mutateAsync,
+    addMembers: addMembersMutation.mutateAsync,
+  };
+}
+```
 
-// 2. Usar nos componentes (src/places/PlaceTreeItem.tsx)
-import { PlaceManagerButton, PlaceManagerBadge } from 'forlogic-core';
-import { placeManagerService } from '@/services/placeManagerService';
+**3. Página Final (`src/places/PlacesPage.tsx`):**
 
-function PlaceTreeItem({ place }) {
-  return (
-    <div className="flex items-center gap-3">
-      <span>{place.name}</span>
-      
-      {/* Badge com contador */}
-      <PlaceManagerBadge 
-        placeId={place.id} 
-        userCount={place.usersIds.length}
-        service={placeManagerService}
-      />
-      
-      {/* Botão de ações */}
-      <PlaceManagerButton 
-        placeId={place.id}
-        placeName={place.name}
-        service={placeManagerService}
-      />
-    </div>
-  );
-}
+```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';
+
+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,
+  });
 
-// 3. Uso avançado com hook (src/places/PlaceDetailsPage.tsx)
-import { usePlaceManagers } from 'forlogic-core';
-import { placeManagerService } from '@/services/placeManagerService';
+  const { accessData, setManager, addMembers } = usePlaceAccess();
+  const { data: users = [] } = useQualiexUsers();
 
-function PlaceDetailsPage({ placeId }) {
-  const {
-    manager,
-    members,
-    setManager,
-    addMember,
-    remove,
-    isLoading
-  } = usePlaceManagers(placeId, placeManagerService);
+  const handleMakeManager = async (userId: string, placeId: string) => {
+    const user = users.find(u => u.userId === userId);
+    if (user) {
+      await setManager({ placeId, user });
+    }
+  };
+
+  const handleMakeMembers = async (userIds: string[], placeId: string) => {
+    const selectedUsers = users.filter(u => userIds.includes(u.userId!));
+    await addMembers({ placeId, users: selectedUsers });
+  };
+
+  const getCurrentManagerId = (placeId: string) => {
+    return accessData.find(a => a.place_id === placeId && a.role === 'manager')?.user_id;
+  };
 
-  if (isLoading) return <LoadingState />;
+  const getCurrentMemberIds = (placeId: string) => {
+    return accessData
+      .filter(a => a.place_id === placeId && a.role === 'member')
+      .map(a => a.user_id);
+  };
 
   return (
-    <div>
-      <h2>Gestor Atual</h2>
-      {manager ? (
-        <div>
-          <p>{manager.user_name}</p>
-          <Button onClick={() => remove(manager.user_id)}>
-            Remover Gestor
-          </Button>
-        </div>
-      ) : (
-        <p>Nenhum gestor definido</p>
-      )}
+    <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>
 
-      <h2>Membros ({members.length})</h2>
-      <ul>
-        {members.map(member => (
-          <li key={member.id}>
-            {member.user_name}
-            <Button onClick={() => remove(member.user_id)}>
-              Remover
-            </Button>
-          </li>
-        ))}
-      </ul>
+      <Card className="p-6">
+        <PlacesList
+          places={places}
+          isLoading={isLoading}
+          manageAccessConfig={{
+            onMakeManager: handleMakeManager,
+            onMakeMembers: handleMakeMembers,
+            getCurrentManagerId,
+            getCurrentMemberIds
+          }}
+        />
+      </Card>
     </div>
   );
 }
@@ -1794,45 +2093,41 @@ function PlaceDetailsPage({ placeId }) {
 
 ---
 
-#### 🔒 Segurança e RLS
+#### 🛠️ Troubleshooting
 
-**Recomendações de RLS Policies:**
-
-```sql
--- Permitir leitura para usuários do mesmo alias
-CREATE POLICY "Users view own alias managers"
-  ON public.place_managers FOR SELECT
-  USING (((SELECT auth.jwt()) ->> 'alias'::text) = alias);
-
--- Permitir gestão completa para usuários do mesmo alias
-CREATE POLICY "Users manage own alias managers"
-  ON public.place_managers FOR ALL
-  USING (((SELECT auth.jwt()) ->> 'alias'::text) = alias);
-```
-
-> ⚠️ **Importante:** Ajuste as policies conforme as regras de negócio do seu projeto.
+| 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 |
 
 ---
 
-#### ❓ Troubleshooting
+#### ✅ Checklist de Implementação
 
-**Erro: "relation 'place_managers' does not exist"**
-- ✅ Verifique se a tabela foi criada no Supabase
-- ✅ Confirme o nome correto da tabela e schema no `PlaceManagerService`
+- [ ] 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
 
-**Erro: "No rows returned"**
-- ✅ Verifique as RLS policies da tabela
-- ✅ Confirme que o usuário tem permissão para ler a tabela
-- ✅ Verifique se o `alias` está correto
+---
 
-**Componente não atualiza após adicionar/remover**
-- ✅ O hook usa React Query com invalidação automática de cache
-- ✅ Verifique se está usando a mesma instância do `service` em todos os componentes
+#### 📚 Referências
 
-**Dropdown não abre ou está vazio**
-- ✅ Verifique se a integração com Qualiex está configurada
-- ✅ Confirme que `useQualiexUsers` está retornando usuários
-- ✅ Verifique console do navegador para erros de API
+- **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`
 
 ---
 
@@ -4390,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
 
@@ -5246,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