Introducción al Sistema de Entidades

¿Qué es el Sistema de Entidades?

El sistema de entidades es una arquitectura config-driven inspirada en WordPress que permite crear, gestionar y mantener modelos de datos completos mediante archivos de configuración. En lugar de escribir código boilerplate para cada nueva funcionalidad, defines la estructura y comportamiento de tus entidades en archivos TypeScript, y el sistema genera automáticamente toda la infraestructura necesaria.

Filosofía: Configuración sobre Código

El Problema Tradicional

En el desarrollo web tradicional, crear una nueva entidad de datos requiere trabajo repetitivo en múltiples capas:

// ❌ Enfoque Tradicional: ~10 horas de desarrollo

// 1. Definir el modelo TypeScript (30 min)
interface Product {
  id: string
  name: string
  price: number
  // ... más campos
}

// 2. Crear endpoints API (2-3 horas)
// app/api/products/route.ts
// app/api/products/[id]/route.ts

// 3. Implementar componentes UI (3-4 horas)
// ProductList.tsx, ProductForm.tsx, ProductDetail.tsx

// 4. Agregar validación (1 hora)
// Schemas Zod manuales

// 5. Configurar permisos (1 hora)
// Lógica de autorización en cada endpoint

// 6. Integrar en navegación (30 min)
// Actualizar menús, rutas, etc.

// TOTAL: ~10 horas por entidad

La Solución: Config-Driven Entities

Con el sistema de entidades, todo esto se reduce a un archivo de configuración:

// ✅ Enfoque Config-Driven: ~15 minutos

import { CheckSquare } from 'lucide-react'
import type { EntityConfig } from '@/core/lib/entities/types'

export const productEntityConfig: EntityConfig = {
  // Identificación básica
  slug: 'products',
  enabled: true,
  names: {
    singular: 'product',
    plural: 'Products'
  },
  icon: CheckSquare,
  
  // Control de acceso
  access: {
    public: false,
    api: true,
    metadata: true,
    shared: false
  },
  
  // Configuración UI
  ui: {
    dashboard: {
      showInMenu: true,
      showInTopbar: true
    },
    public: {
      hasArchivePage: false,
      hasSinglePage: false
    },
    features: {
      searchable: true,
      sortable: true,
      filterable: true,
      bulkOperations: true,
      importExport: false
    }
  },
  
  // Permisos por rol
  permissions: {
    read: ['admin', 'colaborator', 'member'],
    create: ['admin', 'colaborator'],
    update: ['admin', 'colaborator'],
    delete: ['admin']
  },
  
  // Internacionalización
  i18n: {
    fallbackLocale: 'en',
    loaders: {
      es: () => import('./messages/es.json'),
      en: () => import('./messages/en.json')
    }
  },
  
  // Campos de la entidad
  fields: [
    {
      name: 'name',
      type: 'text',
      required: true,
      display: {
        label: 'Product Name',
        placeholder: 'Enter product name...',
        showInList: true,
        showInDetail: true,
        showInForm: true,
        order: 1,
        columnWidth: 12
      },
      api: {
        searchable: true,
        sortable: true,
        readOnly: false
      }
    },
    {
      name: 'price',
      type: 'number',
      required: true,
      display: {
        label: 'Price',
        placeholder: '0.00',
        showInList: true,
        showInDetail: true,
        showInForm: true,
        order: 2,
        columnWidth: 6
      },
      api: {
        searchable: false,
        sortable: true,
        readOnly: false
      }
    }
    // ... más campos
  ]
}

El sistema automáticamente genera:

• ✅ Endpoints API REST completos (/api/v1/products)
• ✅ Componentes UI reutilizables (lista, formulario, detalle)
• ✅ Validación de datos con Zod
• ✅ Sistema de permisos integrado
• ✅ Navegación dinámica en el dashboard
• ✅ Soporte de metadata para campos dinámicos
• ✅ Internacionalización completa
• ✅ Queries SQL optimizadas con RLS

Arquitectura: 5 Secciones Lógicas

El sistema está diseñado alrededor de 5 secciones lógicas que definen completamente una entidad:

1. Identificación Básica

Define el nombre, slug (URL) e icono de la entidad.

{
  slug: 'tasks',           // Single source of truth - deriva todo lo demás
  enabled: true,           // Entidad activa/inactiva
  names: {
    singular: 'task',      // Nombre singular
    plural: 'Tasks'        // Nombre plural
  },
  icon: CheckSquare        // Icono de Lucide React
}

Derivaciones Automáticas del Slug:

• tableName: tasks (nombre de tabla en BD)
• metaTableName: tasks_metas (tabla de metadata)
• apiPath: /api/v1/tasks (endpoint API)
• i18nNamespace: tasks (namespace de traducciones)

2. Control de Acceso y Alcance

Define quién puede acceder y cómo se comporta la entidad.

{
  access: {
    public: false,         // ¿Accesible sin autenticación?
    api: true,             // ¿Tiene API externa con API keys?
    metadata: true,        // ¿Soporta campos metadata dinámicos?
    shared: false          // ¿Compartida entre usuarios? (sin filtro userId)
  }
}

Casos de RLS (Row-Level Security):

• shared: false → Solo el usuario owner ve sus registros
• shared: true → Todos los usuarios autenticados ven todos los registros
• public: true → Usuarios anónimos pueden leer (con RLS apropiado)

3. Características de UI/UX

Controla cómo se muestra y comporta en la interfaz.

{
  ui: {
    dashboard: {
      showInMenu: true,      // Aparece en navegación del dashboard
      showInTopbar: true     // Aparece en quick-create dropdown
    },
    public: {
      hasArchivePage: false, // Tiene página pública de listado
      hasSinglePage: false   // Tiene página pública de detalle
    },
    features: {
      searchable: true,      // Incluida en búsqueda global
      sortable: true,        // Permite ordenar en listas
      filterable: true,      // Permite filtrar en listas
      bulkOperations: true,  // Operaciones en lote
      importExport: false    // Import/Export CSV
    }
  }
}

4. Sistema de Permisos

Define qué roles pueden realizar qué acciones.

{
  permissions: {
    read: ['admin', 'colaborator', 'member'],    // Quién puede ver
    create: ['admin', 'colaborator', 'member'],  // Quién puede crear
    update: ['admin', 'colaborator', 'member'],  // Quién puede editar
    delete: ['admin', 'colaborator']             // Quién puede eliminar
  }
}

Roles Disponibles:

• admin - Administrador con acceso total
• colaborator - Colaborador con permisos amplios
• member - Miembro con permisos básicos
• user - Usuario estándar

5. Internacionalización

Soporte multiidioma integrado.

{
  i18n: {
    fallbackLocale: 'en',  // Idioma por defecto
    loaders: {
      es: () => import('./messages/es.json'),
      en: () => import('./messages/en.json')
    }
  }
}

Características Principales

Config-Driven Development

• Una sola fuente de verdad: El archivo de configuración define TODO
• Cero boilerplate: No necesitas escribir código repetitivo
• Cambios instantáneos: Modifica la config y todo se actualiza automáticamente
• Type-safe: TypeScript garantiza consistencia en toda la app

Generación Automática

El sistema genera automáticamente:

1. APIs REST completas con autenticación dual (sesión + API key)
2. Componentes UI universales (EntityListWrapper, EntityFormWrapper, EntityDetailWrapper)
3. Validación de datos con Zod schemas
4. Queries SQL optimizadas con soporte RLS
5. Sistema de permisos integrado en cada operación
6. Navegación dinámica en el dashboard
7. Soporte de metadata para campos extensibles

Seguridad por Defecto

• Row-Level Security (RLS): Aislamiento de datos por usuario en PostgreSQL
• Validación automática: Todos los inputs son validados
• Permisos granulares: Control por rol en cada operación
• API Keys scoped: APIs externas con permisos configurables

Performance Optimizado

• Queries eficientes: SQL optimizado con índices automáticos
• Metadata en 1 query: Merge inteligente de datos principales + metadata
• Caching inteligente: Registry con pre-loading en el dashboard
• Componentes optimizados: Wrappers con manejo eficiente de estados

Casos de Uso Ideales

✅ Perfecto Para

• Entidades CRUD estándar: Productos, clientes, pedidos, tareas
• Admin panels: Gestión de usuarios, configuraciones
• Content management: Posts, páginas, media
• Business workflows: Tickets, proyectos, leads
• Multi-tenant apps: Datos aislados por usuario/organización

⚠️ Considerar Alternativas Para

• Lógica de negocio muy compleja: Mejor implementación custom
• Features en tiempo real: Chat, notificaciones live
• Visualizaciones complejas: Dashboards, analytics avanzados
• Procesamiento de archivos pesado: Conversiones, transformaciones

Métricas de Impacto

Métrica	Desarrollo Tradicional	Sistema de Entidades	Mejora
Tiempo por entidad	~10 horas	~15 minutos	40x más rápido
Líneas de código	~800 líneas	~50 líneas config	16x menos código
Archivos a crear	8-12 archivos	1 archivo config	8-12x menos archivos
Tiempo de testing	2-3 horas	15 minutos	8x más rápido
Mantenimiento	Alto (múltiples archivos)	Bajo (un solo archivo)	~80% menos esfuerzo
Consistencia	Manual (propensa a errores)	Automática (garantizada)	100% consistente

Ejemplo Real: Tasks Entity

El proyecto incluye una implementación completa de referencia en:

• Configuración: contents/themes/default/entities/tasks/tasks.config.ts
• Campos: contents/themes/default/entities/tasks/tasks.fields.ts
• Traducciones: contents/themes/default/entities/tasks/messages/
• UI en Dashboard: app/dashboard/(main)/tasks/

Esta entidad de tareas demuestra:

• Configuración completa de 5 secciones
• 15+ campos de diferentes tipos
• Relaciones con otras entidades (clients, users)
• Metadata para campos extensibles
• Permisos por rol
• UI completamente funcional

Próximos Pasos

1. Quick Start - Crea tu primera entidad en 15 minutos
2. Configuration Reference - Referencia completa de EntityConfig
3. Field Types - Todos los tipos de campo disponibles
4. Examples - Ejemplos completos listos para usar

Recursos Adicionales

• Tipos TypeScript: core/lib/entities/types.ts - Definiciones completas
• Registry System: core/lib/entities/registry.ts - Sistema central de registro
• Wrappers UI: core/components/entities/wrappers/ - Componentes reutilizables
• API Generator: core/lib/entities/api-generator.ts - Generación de endpoints

---

💡 Tip: El sistema de entidades está diseñado para ser incremental. Puedes empezar con una configuración básica y agregar características avanzadas gradualmente según las necesites.