forlogic-core 1.5.0 → 1.5.2

package/dist/docs/templates/qualiex-integration-example.tsx

@@ -0,0 +1,430 @@
+/**
+ * TEMPLATE: Integração Qualiex
+ * ⚠️ REGRAS: Consulte docs/AI_REFERENCE.md
+ * 📚 Detalhes: Consulte docs/QUALIEX_INTEGRATION.md
+ * ❌ NÃO criar implementação própria - usar da lib!
+ */
+
+// 1. Configuração inicial (main.tsx ou App.tsx)
+import { setQualiexConfig } from 'forlogic-core';
+
+// Habilitar integração Qualiex
+setQualiexConfig({
+  enableUserEnrichment: true, // Adicionar responsible_name às entidades
+  enableUsersApi: true,        // Habilitar API de usuários
+});
+
+// 2. Variável de ambiente (.env)
+// VITE_QUALIEX_API_URL=https://common-v4-api.qualiex.com
+
+// 3. Interface da entidade (src/tasks/task.ts)
+
+import { BaseEntity, ContentEntity, UserRelatedEntity } from 'forlogic-core';
+
+export interface Task extends ContentEntity, UserRelatedEntity {
+  // ContentEntity: title, description
+  // UserRelatedEntity: id_user, responsible_name
+  
+  status: 'pending' | 'in_progress' | 'completed';
+  due_date?: string | null;
+  priority?: 'low' | 'medium' | 'high';
+}
+
+export interface CreateTaskPayload {
+  title: string;
+  description?: string;
+  id_user: string;  // ID do usuário Qualiex
+  status: 'pending' | 'in_progress' | 'completed';
+  due_date?: string;
+  priority?: 'low' | 'medium' | 'high';
+  alias: string;
+}
+
+export interface UpdateTaskPayload {
+  title?: string;
+  description?: string;
+  id_user?: string;
+  status?: 'pending' | 'in_progress' | 'completed';
+  due_date?: string;
+  priority?: 'low' | 'medium' | 'high';
+}
+
+// ============= 4. SERVICE =============
+// src/tasks/taskService.ts
+
+import { createSimpleService } from 'forlogic-core';
+import { Task, CreateTaskPayload, UpdateTaskPayload } from './task';
+
+export const { service: taskService, useCrudHook: useTaskCrud } = 
+  createSimpleService<Task, CreateTaskPayload, UpdateTaskPayload>({
+    tableName: 'tasks',
+    entityName: 'Task',
+    searchFields: ['title', 'description'],
+    schemaName: 'YOUR_SCHEMA' // Use o schema do seu projeto (ex: 'central', 'trainings', 'public')
+  });
+
+// ============= 5. PÁGINA CRUD COM QUALIEX USER FIELD =============
+// src/tasks/TasksPage.tsx
+
+import { 
+  createCrudPage, 
+  createSimpleSaveHandler, 
+  QualiexUserField,
+  useAuth,
+  Badge,
+  type FormSection 
+} from 'forlogic-core';
+import { Calendar, User, CheckCircle } from 'lucide-react';
+import { Task } from './task';
+import { useTaskCrud } from './taskService';
+
+// Configuração das colunas
+const taskColumns = [
+  { 
+    key: 'title', 
+    header: 'Título',
+    sortable: true,
+    render: (item: Task) => (
+      <span className="font-medium">{item.title}</span>
+    )
+  },
+  { 
+    key: 'responsible_name', 
+    header: 'Responsável',
+    sortable: true,
+    render: (item: Task) => (
+      <div className="flex items-center gap-2">
+        <User className="h-4 w-4 text-muted-foreground" />
+        <span>{item.responsible_name || 'Sem responsável'}</span>
+      </div>
+    )
+  },
+  { 
+    key: 'status',
+    header: 'Status',
+    sortable: true,
+    render: (item: Task) => {
+      const statusConfig = {
+        pending: { label: 'Pendente', color: 'bg-yellow-100 text-yellow-800' },
+        in_progress: { label: 'Em Progresso', color: 'bg-blue-100 text-blue-800' },
+        completed: { label: 'Concluída', color: 'bg-green-100 text-green-800' }
+      };
+      const config = statusConfig[item.status];
+      
+      return (
+        <Badge className={config.color}>
+          {config.label}
+        </Badge>
+      );
+    }
+  },
+  { 
+    key: 'due_date', 
+    header: 'Prazo',
+    sortable: true,
+    render: (item: Task) => (
+      item.due_date ? (
+        <div className="flex items-center gap-2">
+          <Calendar className="h-4 w-4 text-muted-foreground" />
+          {new Date(item.due_date).toLocaleDateString('pt-BR')}
+        </div>
+      ) : (
+        <span className="text-muted-foreground">-</span>
+      )
+    )
+  },
+];
+
+// ✅ Seções do formulário com QualiexUserField
+const formSections: FormSection[] = [
+  {
+    id: 'main-info',
+    title: 'Informações Principais',
+    fields: [
+      {
+        name: 'title',
+        label: 'Título',
+        type: 'text',
+        required: true,
+        placeholder: 'Digite o título da tarefa',
+      },
+      {
+        name: 'description',
+        label: 'Descrição',
+        type: 'textarea',
+        placeholder: 'Descreva a tarefa...',
+      },
+      {
+        name: 'status',
+        label: 'Status',
+        type: 'select',
+        required: true,
+        options: [
+          { value: 'pending', label: 'Pendente' },
+          { value: 'in_progress', label: 'Em Progresso' },
+          { value: 'completed', label: 'Concluída' },
+        ],
+        defaultValue: 'pending',
+      },
+    ],
+  },
+  {
+    id: 'assignment',
+    title: 'Atribuição e Prazo',
+    fields: [
+      {
+        name: 'id_user',
+        label: 'Responsável',
+        type: 'custom',
+        required: true,
+        // ✅ USAR QualiexUserField para carregar usuários da API Qualiex
+        renderField: ({ value, onChange, error }) => (
+          <div className="space-y-1">
+            <QualiexUserField
+              value={value}
+              onChange={onChange}
+              placeholder="Selecione o responsável"
+            />
+            {error && (
+              <p className="text-sm text-destructive">{error}</p>
+            )}
+          </div>
+        )
+      },
+      {
+        name: 'due_date',
+        label: 'Prazo',
+        type: 'date',
+      },
+      {
+        name: 'priority',
+        label: 'Prioridade',
+        type: 'select',
+        options: [
+          { value: 'low', label: 'Baixa' },
+          { value: 'medium', label: 'Média' },
+          { value: 'high', label: 'Alta' },
+        ],
+        defaultValue: 'medium',
+      },
+    ],
+  },
+];
+
+// Componente da página
+export function TasksPage() {
+  const manager = useTaskCrud();
+  const { alias } = useAuth();
+
+  // Handler com transformações
+  const handleSave = createSimpleSaveHandler(
+    manager,
+    // CREATE transform
+    (data: any) => ({
+      ...data,
+      alias: alias || '',
+      status: data.status || 'pending',
+      priority: data.priority || 'medium',
+    }),
+    // UPDATE transform
+    (data: any) => {
+      const { alias: _, ...updateData } = data;
+      return updateData;
+    }
+  );
+
+  const CrudPage = createCrudPage({
+    manager,
+    config: {
+      entityName: 'Tarefa',
+      entityNamePlural: 'Tarefas',
+      columns: taskColumns,
+      formSections,
+      cardFields: [
+        { 
+          key: 'title', 
+          label: 'Título',
+          render: (item: Task) => (
+            <span className="font-semibold text-lg">{item.title}</span>
+          )
+        },
+        { 
+          key: 'responsible_name',
+          label: 'Responsável',
+          render: (item: Task) => (
+            <div className="flex items-center gap-2">
+              <User className="h-4 w-4" />
+              <span>{item.responsible_name || 'Sem responsável'}</span>
+            </div>
+          )
+        },
+        { 
+          key: 'status',
+          label: 'Status',
+          render: (item: Task) => {
+            const config = {
+              pending: { label: 'Pendente', color: 'bg-yellow-100' },
+              in_progress: { label: 'Em Progresso', color: 'bg-blue-100' },
+              completed: { label: 'Concluída', color: 'bg-green-100' }
+            };
+            return (
+              <Badge className={config[item.status].color}>
+                {config[item.status].label}
+              </Badge>
+            );
+          }
+        },
+      ]
+    },
+    onSave: handleSave
+  });
+
+  return <CrudPage />;
+}
+
+// ============= 6. USO DIRETO DO HOOK (OPCIONAL) =============
+// Exemplo de componente que usa useQualiexUsers diretamente
+
+import { useQualiexUsers } from 'forlogic-core';
+
+export function QualiexUsersDebug() {
+  const { data: users, isLoading, error } = useQualiexUsers();
+
+  if (isLoading) {
+    return <div>Carregando usuários...</div>;
+  }
+
+  if (error) {
+    return <div>Erro ao carregar: {error.message}</div>;
+  }
+
+  return (
+    <div>
+      <h3>Usuários Qualiex ({users?.length || 0})</h3>
+      <ul>
+        {users?.map(user => (
+          <li key={user.userId}>
+            {user.userName} - {user.userEmail}
+          </li>
+        ))}
+      </ul>
+    </div>
+  );
+}
+
+// ============= 7. USO DO SERVIÇO DE API (AVANÇADO) =============
+// Uso direto do qualiexApi para casos específicos
+
+import { qualiexApi } from 'forlogic-core';
+
+export async function fetchQualiexUserById(userId: string) {
+  try {
+    const user = await qualiexApi.fetchUserById(
+      userId,
+      'company-alias',
+      'company-id'
+    );
+    
+    if (user) {
+      console.log('Usuário encontrado:', user.userName);
+      return user;
+    }
+  } catch (error) {
+    console.error('Erro ao buscar usuário:', error);
+  }
+}
+
+// ============= 8. ENRIQUECIMENTO DE ENTIDADES (OPCIONAL) =============
+// Adicionar responsible_name automaticamente às entidades
+
+import { QualiexEnrichmentService } from 'forlogic-core';
+
+export async function enrichTasksWithResponsibles(tasks: Task[]) {
+  return QualiexEnrichmentService.enrichWithResponsibleNames(
+    tasks,
+    {
+      entityName: 'Task',
+      fallbackResponsibleText: 'Sem responsável'
+    }
+  );
+}
+
+// ============= 9. FORMULÁRIO CUSTOMIZADO (ALTERNATIVA) =============
+// Se precisar de controle total do formulário
+
+import { useForm, Controller } from 'react-hook-form';
+import { QualiexUserField, Button, Input, Textarea } from 'forlogic-core';
+
+interface CustomTaskFormData {
+  title: string;
+  description?: string;
+  id_user: string;
+}
+
+export function CustomTaskForm() {
+  const { control, register, handleSubmit } = useForm<CustomTaskFormData>();
+
+  const onSubmit = (data: CustomTaskFormData) => {
+    console.log('Dados do formulário:', data);
+    // Lógica de salvar
+  };
+
+  return (
+    <form onSubmit={handleSubmit(onSubmit)} className="space-y-4">
+      <div>
+        <label>Título</label>
+        <Input {...register('title', { required: true })} />
+      </div>
+
+      <div>
+        <label>Descrição</label>
+        <Textarea {...register('description')} />
+      </div>
+
+      <div>
+        <label>Responsável</label>
+        <Controller
+          control={control}
+          name="id_user"
+          rules={{ required: 'Responsável é obrigatório' }}
+          render={({ field, fieldState }) => (
+            <div className="space-y-1">
+              <QualiexUserField
+                value={field.value}
+                onChange={field.onChange}
+                placeholder="Selecione o responsável"
+              />
+              {fieldState.error && (
+                <p className="text-sm text-destructive">
+                  {fieldState.error.message}
+                </p>
+              )}
+            </div>
+          )}
+        />
+      </div>
+
+      <Button type="submit">Salvar Tarefa</Button>
+    </form>
+  );
+}
+
+// ============= RESUMO =============
+/*
+✅ O QUE A LIB FORNECE:
+- qualiexApi: Serviço de API com autenticação automática
+- useQualiexUsers: Hook React Query para buscar usuários
+- QualiexUserField: Componente UI pronto (loading, error, lista)
+- QualiexEnrichmentService: Enriquecimento de entidades com responsible_name
+
+❌ O QUE NÃO FAZER:
+- NÃO criar seu próprio serviço de API Qualiex
+- NÃO criar hook customizado useQualiexUsers
+- NÃO criar componente customizado de select de usuário
+
+✅ CHECKLIST:
+1. Adicionar VITE_QUALIEX_API_URL no .env
+2. Configurar setQualiexConfig({ enableUsersApi: true })
+3. Usar QualiexUserField nos formulários
+4. Importar de 'forlogic-core'
+*/

package/dist/docs/templates/quick-start-example.tsx

@@ -0,0 +1,96 @@
+/**
+ * QUICK START EXAMPLE - Complete CRUD in 5 minutes
+ * 
+ * This example shows how to create a complete CRUD interface
+ * with minimal code using the new simplified API.
+ */
+
+import React from 'react';
+import { createSimpleService, createCrudPage, generateCrudConfig } from 'forlogic-core';
+
+// 1. Define your entity type
+interface Product {
+  id: string;
+  name: string;
+  description: string;
+  price: number;
+  category: string;
+  active: boolean;
+  created_at: Date;
+}
+
+// 2. Create the service (one line!)
+const productService = createSimpleService<Product>({
+  tableName: 'products'
+});
+
+// 3. Generate CRUD configuration with smart defaults
+const productConfig = generateCrudConfig<Product>(
+  'Produtos',
+  {
+    name: '',
+    description: '',
+    price: 0,
+    category: '',
+    active: true,
+  },
+  {
+    // Override defaults as needed
+    columns: [
+      { key: 'name', label: 'Nome', type: 'text', required: true, searchable: true },
+      { key: 'description', label: 'Descrição', type: 'textarea' },
+      { key: 'price', label: 'Preço', type: 'number', required: true },
+      { 
+        key: 'category', 
+        label: 'Categoria', 
+        type: 'select',
+        options: [
+          { label: 'Eletrônicos', value: 'electronics' },
+          { label: 'Roupas', value: 'clothing' },
+          { label: 'Casa', value: 'home' }
+        ]
+      },
+      { key: 'active', label: 'Ativo', type: 'boolean' },
+    ]
+  }
+);
+
+// 4. Create the complete CRUD page (one line!)
+export const ProductsPage = createCrudPage({
+  service: productService,
+  config: productConfig,
+});
+
+// That's it! You now have:
+// ✅ Complete CRUD interface (list, create, edit, delete)
+// ✅ Search functionality
+// ✅ Form validation
+// ✅ Loading states
+// ✅ Error handling
+// ✅ Responsive design
+// ✅ Type safety
+
+// ALTERNATIVE: Even simpler with auto-generation
+// export const ProductsPageAuto = createCrudPage({
+//   service: createSimpleService<Product>({ tableName: 'products' }),
+//   config: generateCrudConfig('Produtos', { name: '', price: 0, active: true })
+// });
+
+/**
+ * COMPARISON: Old vs New
+ * 
+ * OLD WAY (100+ lines):
+ * - Create service class extending BaseService
+ * - Create form component with validation
+ * - Create table component with actions
+ * - Create page component tying everything together
+ * - Handle loading states manually
+ * - Handle error states manually
+ * 
+ * NEW WAY (20 lines):
+ * - Define entity type
+ * - Create service (1 line)
+ * - Generate config (1 function call)
+ * - Create page (1 line)
+ * - Everything else is automatic!
+ */

package/dist/docs/templates/rls-policies.sql

@@ -0,0 +1,80 @@
+-- =========================================
+-- TEMPLATES RLS POLICIES
+-- =========================================
+-- Templates prontos para usar em novas tabelas
+-- Adapte conforme necessário para cada caso
+
+-- =========================================
+-- 1. TEMPLATE PADRÃO: Tabela com Soft Delete
+-- =========================================
+-- Use este template para a maioria das tabelas
+/*
+-- Substituir:
+-- - schema_name: nome do schema (ex: central, public)
+-- - table_name: nome da tabela
+
+-- Habilitar RLS
+ALTER TABLE schema_name.table_name ENABLE ROW LEVEL SECURITY;
+
+-- SELECT: Ver apenas dados da empresa
+CREATE POLICY "Users can view company data" ON schema_name.table_name
+FOR SELECT USING (
+  ((SELECT auth.jwt()) ->> 'alias') = alias 
+);
+
+-- INSERT: Inserir apenas com alias da empresa do usuário
+CREATE POLICY "Users can insert company data" ON schema_name.table_name
+FOR INSERT WITH CHECK (
+  ((SELECT auth.jwt()) ->> 'alias') = alias
+);
+
+-- UPDATE: Atualizar apenas dados da empresa
+CREATE POLICY "Users can update company data" ON schema_name.table_name
+FOR UPDATE USING (
+  ((SELECT auth.jwt()) ->> 'alias') = alias
+);
+
+-- IMPORTANTE: NÃO criar política DELETE (soft delete usado)
+
+-- ⚠️ IMPORTANTE: NÃO criar índices automaticamente
+-- Índices devem ser criados APENAS quando explicitamente solicitado
+-- Criar índices desnecessários prejudica performance de INSERT/UPDATE/DELETE
+*/
+
+-- =========================================
+-- 2. EXEMPLO COMPLETO: Tabela de Produtos
+-- =========================================
+
+-- Criar tabela de exemplo
+CREATE TABLE central.products (
+  id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
+  alias TEXT NOT NULL,
+  name TEXT NOT NULL,
+  description TEXT,
+  price DECIMAL(10,2),
+  is_removed BOOLEAN DEFAULT false,
+  created_at TIMESTAMP WITH TIME ZONE DEFAULT now(),
+  updated_at TIMESTAMP WITH TIME ZONE DEFAULT now()
+);
+
+-- Habilitar RLS
+ALTER TABLE central.products ENABLE ROW LEVEL SECURITY;
+
+-- Políticas
+CREATE POLICY "Users can view company products" ON central.products
+FOR SELECT USING (
+  ((SELECT auth.jwt()) ->> 'alias') = alias 
+);
+
+CREATE POLICY "Users can insert company products" ON central.products
+FOR INSERT WITH CHECK (
+  ((SELECT auth.jwt()) ->> 'alias') = alias
+);
+
+CREATE POLICY "Users can update company products" ON central.products
+FOR UPDATE USING (
+  ((SELECT auth.jwt()) ->> 'alias') = alias
+);
+
+-- ⚠️ Nota: Índices NÃO foram criados (seguindo a regra de não criar automaticamente)
+-- Crie índices apenas quando necessário para otimizar queries específicas