Referencia de Configuración: EntityConfig

Esta es la referencia completa de todas las propiedades disponibles en EntityConfig. El archivo de configuración es el corazón del sistema de entidades y define completamente su comportamiento.

Estructura General

interface EntityConfig {
  // 1. BASIC IDENTIFICATION
  slug: string
  enabled: boolean
  names: { singular: string; plural: string }
  icon: LucideIcon
  
  // 2. ACCESS AND SCOPE CONFIGURATION
  access: { public: boolean; api: boolean; metadata: boolean; shared?: boolean }
  
  // 3. UI/UX FEATURES
  ui: { dashboard: {...}; public: {...}; features: {...} }
  
  // 4. PERMISSIONS SYSTEM
  permissions: { read: UserRole[]; create: UserRole[]; update: UserRole[]; delete: UserRole[] }
  
  // 5. INTERNATIONALIZATION
  i18n: { fallbackLocale: SupportedLocale; loaders: Record<SupportedLocale, TranslationLoader> }
  
  // FIELDS
  fields: EntityField[]
  
  // OPTIONAL
  childEntities?: ChildEntityConfig
  idStrategy?: { type: 'uuid' | 'serial'; autoGenerate?: boolean }
  isCore?: boolean
  source?: 'core' | 'theme' | 'plugin'
}

---

1. Identificación Básica

slug (required)

El slug es la única fuente de verdad y define todos los nombres derivados automáticamente.

Tipo: string

Uso:

• URLs: /dashboard/{slug}
• API endpoints: /api/v1/{slug}
• Tabla de BD: {slug}
• Tabla de metadata: {slug}_metas
• Namespace i18n: {slug}

Convenciones:

• Usar minúsculas
• Plural (ej: tasks, products, users)
• Separar con guiones si es necesario (ej: blog-posts)

{
  slug: 'tasks'
  // Deriva automáticamente:
  // - tableName: 'tasks'
  // - metaTableName: 'tasks_metas'
  // - apiPath: '/api/v1/tasks'
  // - i18nNamespace: 'tasks'
}

enabled (required)

Controla si la entidad está activa o no en el sistema.

Tipo: boolean

Efecto:

• true: Entidad funcional, aparece en navegación, APIs disponibles
• false: Entidad deshabilitada, no aparece, APIs retornan 404

{
  enabled: true  // Entidad activa
}

names (required)

Nombres legibles para mostrar en la UI.

Tipo: { singular: string; plural: string }

Uso:

• singular: Títulos de formularios, detalles ("Edit Task", "New Product")
• plural: Listas, navegación ("Tasks", "All Products")

{
  names: {
    singular: 'task',      // "Create task", "Edit task"
    plural: 'Tasks'        // "All Tasks", "Tasks List"
  }
}

icon (required)

Icono de Lucide React para la UI.

Tipo: LucideIcon

Uso:

• Menú de navegación
• Breadcrumbs
• Headers de página
• Quick-create dropdown

import { CheckSquare, ShoppingBag, Users, Package } from 'lucide-react'

{
  icon: CheckSquare  // Icono de check para tasks
}

Iconos recomendados por tipo:

• Tasks/Todos: CheckSquare, ListTodo
• Products: ShoppingBag, Package
• Users/Clients: Users, UserCircle
• Projects: Folder, Briefcase
• Documents: FileText, File

---

2. Control de Acceso y Alcance

access (required)

Define el alcance y disponibilidad de la entidad.

Tipo: { public: boolean; api: boolean; metadata: boolean; shared?: boolean }

access.public

¿Es accesible sin autenticación?

Tipo: boolean

Comportamiento:

• true: Usuarios anónimos pueden leer (requiere RLS apropiado)
• false: Solo usuarios autenticados

{
  access: {
    public: false  // Solo usuarios autenticados
  }
}

Nota: Si es true, debes configurar policies RLS para anon role en PostgreSQL.

access.api

¿Tiene API externa con API keys?

Tipo: boolean

Comportamiento:

• true: Endpoints disponibles con autenticación vía API key
• false: Solo autenticación por sesión

{
  access: {
    api: true  // API externa disponible
  }
}

access.metadata

¿Soporta sistema de metadata?

Tipo: boolean

Comportamiento:

• true: Crea tabla {slug}_metas automáticamente
• false: Sin soporte de metadata

{
  access: {
    metadata: true  // Tabla tasks_metas disponible
  }
}

Beneficios:

• Campos dinámicos sin migración
• Datos extensibles por usuario
• Schema flexible

access.shared

¿Compartida entre usuarios?

Tipo: boolean | undefined

Comportamiento:

• false o undefined: Cada usuario ve solo sus registros (filtro userId)
• true: Todos los usuarios ven todos los registros (sin filtro userId)

{
  access: {
    shared: false  // CASE 1: Solo mis tareas (default)
  }
}

{
  access: {
    shared: true   // CASE 2: Todas las tareas del workspace
  }
}

Casos de uso:

• shared: false → Tareas personales, productos del usuario
• shared: true → Categorías globales, configuraciones del sistema

---

3. Características de UI/UX

ui (required)

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

Tipo: { dashboard: {...}; public: {...}; features: {...} }

ui.dashboard

Configuración para el área del dashboard.

Tipo: { showInMenu: boolean; showInTopbar: boolean }

{
  ui: {
    dashboard: {
      showInMenu: true,      // Aparece en menú lateral
      showInTopbar: true     // Aparece en quick-create dropdown
    }
  }
}

showInMenu:

• true: Item visible en navegación principal
• false: Sin entrada en menú (útil para entidades internas)

showInTopbar:

• true: Botón rápido de creación en el header
• false: Sin quick-create

ui.public

Configuración para páginas públicas.

Tipo: { hasArchivePage: boolean; hasSinglePage: boolean }

{
  ui: {
    public: {
      hasArchivePage: true,   // Página /blog/posts
      hasSinglePage: true     // Página /blog/posts/[slug]
    }
  }
}

hasArchivePage:

• true: Genera listado público
• false: Sin página de listado

hasSinglePage:

• true: Genera página de detalle público
• false: Sin página de detalle

Casos de uso:

• Blog posts: Ambas true
• Tasks privadas: Ambas false
• Portfolio projects: hasArchivePage: true, hasSinglePage: true

ui.features

Features funcionales de la entidad.

Tipo:

{
  searchable: boolean
  sortable: boolean
  filterable: boolean
  bulkOperations: boolean
  importExport: boolean
}

{
  ui: {
    features: {
      searchable: true,       // Incluida en búsqueda global
      sortable: true,         // Permite ordenar en tablas
      filterable: true,       // Permite filtrar en tablas
      bulkOperations: true,   // Operaciones en lote (delete múltiple, etc.)
      importExport: false     // Import/Export CSV
    }
  }
}

searchable:

• Incluye la entidad en la búsqueda global del dashboard
• Busca en campos con api.searchable: true

sortable:

• Habilita ordenamiento en listas
• Funciona con campos api.sortable: true

filterable:

• Habilita filtros en listas
• Genera filtros automáticos por tipo de campo

bulkOperations:

• Checkbox de selección múltiple
• Acciones en lote (eliminar, exportar, etc.)

importExport:

• Botones de import/export CSV
• Mapeo automático de campos

---

4. Sistema de Permisos

permissions (required)

Define qué roles pueden realizar qué acciones.

Tipo:

{
  read: UserRole[]
  create: UserRole[]
  update: UserRole[]
  delete: UserRole[]
}

UserRole: 'admin' | 'colaborator' | 'member' | 'user'

{
  permissions: {
    read: ['admin', 'colaborator', 'member'],    // Todos pueden ver
    create: ['admin', 'colaborator', 'member'],  // Todos pueden crear
    update: ['admin', 'colaborator', 'member'],  // Todos pueden editar
    delete: ['admin', 'colaborator']             // Solo admin y colaborator pueden eliminar
  }
}

Roles disponibles:

Rol	Descripción	Nivel de Acceso
admin	Administrador	Total
colaborator	Colaborador	Alto
member	Miembro	Medio
user	Usuario estándar	Básico

Validación:

• Aplicada automáticamente en APIs
• Verificada en componentes UI
• Integrada con RLS en base de datos

Ejemplos por escenario:

// Entidad pública de lectura, restringida de escritura
{
  permissions: {
    read: ['admin', 'colaborator', 'member', 'user'],
    create: ['admin'],
    update: ['admin'],
    delete: ['admin']
  }
}

// Entidad colaborativa
{
  permissions: {
    read: ['admin', 'colaborator', 'member'],
    create: ['admin', 'colaborator', 'member'],
    update: ['admin', 'colaborator', 'member'],
    delete: ['admin', 'colaborator']
  }
}

// Entidad solo admin
{
  permissions: {
    read: ['admin'],
    create: ['admin'],
    update: ['admin'],
    delete: ['admin']
  }
}

---

5. Internacionalización

i18n (required)

Configuración de traducciones multiidioma.

Tipo:

{
  fallbackLocale: SupportedLocale
  loaders: Record<SupportedLocale, TranslationLoader>
}

SupportedLocale: 'en' | 'es'

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

fallbackLocale:

• Idioma por defecto si la traducción no existe
• Usualmente 'en'

loaders:

• Funciones dinámicas que cargan archivos JSON
• Lazy loading para performance
• Un loader por idioma soportado

Estructura de archivos de traducción:

{
  "name": "Task",
  "pluralName": "Tasks",
  "description": "Manage your tasks",
  "actions": {
    "create": "Create Task",
    "edit": "Edit Task",
    "delete": "Delete Task",
    "view": "View Task"
  },
  "fields": {
    "title": "Task Title",
    "description": "Description",
    "status": "Status",
    "priority": "Priority"
  },
  "messages": {
    "created": "Task created successfully",
    "updated": "Task updated successfully",
    "deleted": "Task deleted successfully"
  }
}

---

6. Campos (Fields)

fields (required)

Array de definiciones de campos de la entidad.

Tipo: EntityField[]

Ver Field Types para documentación completa de tipos de campos.

{
  fields: [
    {
      name: 'title',
      type: 'text',
      required: true,
      display: {
        label: 'Title',
        description: 'Task title',
        placeholder: 'Enter title...',
        showInList: true,
        showInDetail: true,
        showInForm: true,
        order: 1,
        columnWidth: 12
      },
      api: {
        searchable: true,
        sortable: true,
        readOnly: false
      }
    }
    // ... más campos
  ]
}

Propiedades de EntityField:

Propiedad	Tipo	Requerido	Descripción
name	string	✅	Nombre del campo (columna en BD)
type	EntityFieldType	✅	Tipo de dato
required	boolean	✅	Campo obligatorio
defaultValue	any	❌	Valor por defecto
validation	ZodSchema	❌	Schema de validación Zod
display	FieldDisplay	✅	Configuración de UI
api	FieldAPI	✅	Configuración de API
options	FieldOption[]	❌	Opciones (para select/multiselect)
relation	RelationConfig	❌	Configuración de relación

---

7. Propiedades Opcionales

childEntities

Configuración de entidades hijas.

Tipo: ChildEntityConfig | undefined

Ver Child Entities para documentación completa.

{
  childEntities: {
    'comments': {
      table: 'task_comments',
      fields: [...],
      showInParentView: true,
      hasOwnRoutes: false,
      display: {...}
    }
  }
}

idStrategy

Estrategia de generación de IDs.

Tipo: { type: 'uuid' | 'serial'; autoGenerate?: boolean } | undefined

{
  idStrategy: {
    type: 'uuid',           // UUID (default) o serial
    autoGenerate: true      // Auto-generar (default: true)
  }
}

Opciones:

• uuid: UUID v4 aleatorio (recomendado)
• serial: Integer auto-incrementado

Casos de uso:

• uuid: Para datos distribuidos, APIs públicas, seguridad
• serial: Para IDs secuenciales legibles (ej: Order #1234)

isCore

Indica si es una entidad del sistema core.

Tipo: boolean | undefined

{
  isCore: true  // Entidad fundamental del sistema
}

Efecto:

• Entidades core no pueden ser sobrescritas por themes/plugins
• Proteción contra modificaciones accidentales

source

Origen de la entidad.

Tipo: 'core' | 'theme' | 'plugin' | undefined

{
  source: 'theme'  // Definida en el tema actual
}

Valores:

• core: Sistema base
• theme: Tema activo
• plugin: Plugin específico

---

Derivaciones Automáticas del Slug

El sistema deriva automáticamente varios nombres a partir del slug:

slug: 'tasks'

// Deriva:
// ↓
tableName: 'tasks'
metaTableName: 'tasks_metas'
apiPath: '/api/v1/tasks'
i18nNamespace: 'tasks'
foreignKey: 'entityId' (genérico para todas las entidades en metadata)

No necesitas configurar:

• Nombres de tablas
• Rutas de API
• Namespaces de traducción
• Foreign keys en metadata

---

Ejemplo Completo Comentado

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

export const taskEntityConfig: EntityConfig = {
  // 1. IDENTIFICACIÓN BÁSICA
  slug: 'tasks',           // → Deriva tableName, apiPath, etc.
  enabled: true,           // Entidad activa
  names: {
    singular: 'task',      // UI singular
    plural: 'Tasks'        // UI plural
  },
  icon: CheckSquare,       // Icono Lucide
  
  // 2. CONTROL DE ACCESO
  access: {
    public: false,         // Solo autenticados
    api: true,             // API externa disponible
    metadata: true,        // Soporta metadata
    shared: false          // Cada usuario ve sus tareas
  },
  
  // 3. UI/UX
  ui: {
    dashboard: {
      showInMenu: true,    // En menú lateral
      showInTopbar: true   // Quick-create
    },
    public: {
      hasArchivePage: false,  // Sin listado público
      hasSinglePage: false    // Sin detalle público
    },
    features: {
      searchable: true,    // En búsqueda global
      sortable: true,      // Permite ordenar
      filterable: true,    // Permite filtrar
      bulkOperations: true, // Operaciones lote
      importExport: false  // Sin import/export
    }
  },
  
  // 4. PERMISOS
  permissions: {
    read: ['admin', 'colaborator', 'member'],
    create: ['admin', 'colaborator', 'member'],
    update: ['admin', 'colaborator', 'member'],
    delete: ['admin', 'colaborator', 'member']
  },
  
  // 5. I18N
  i18n: {
    fallbackLocale: 'en',
    loaders: {
      es: () => import('./messages/es.json'),
      en: () => import('./messages/en.json')
    }
  },
  
  // CAMPOS (importados)
  fields: taskFields,
  
  // OPCIONALES
  idStrategy: {
    type: 'uuid',
    autoGenerate: true
  },
  source: 'theme'
}

---

Quick Reference: Propiedades por Caso de Uso

Entidad Privada (ej: Tasks personales)

{
  access: { public: false, shared: false },
  ui: { public: { hasArchivePage: false, hasSinglePage: false } },
  permissions: { read: ['admin', 'colaborator', 'member'] }
}

Entidad Compartida (ej: Team Wiki)

{
  access: { public: false, shared: true },
  ui: { public: { hasArchivePage: false, hasSinglePage: false } },
  permissions: { read: ['admin', 'colaborator', 'member'] }
}

Entidad Pública (ej: Blog Posts)

{
  access: { public: true, shared: true },
  ui: { public: { hasArchivePage: true, hasSinglePage: true } },
  permissions: { 
    read: ['admin', 'colaborator', 'member', 'user'],
    create: ['admin', 'colaborator']
  }
}

Entidad Solo Admin (ej: System Settings)

{
  access: { public: false, shared: true },
  ui: { dashboard: { showInMenu: false }, public: { ... } },
  permissions: {
    read: ['admin'],
    create: ['admin'],
    update: ['admin'],
    delete: ['admin']
  }
}

---

Próximos Pasos

1. Field Types - Tipos de campo disponibles
2. Relationships - Conectar entidades
3. Child Entities - Relaciones padre-hijo
4. Permissions - Sistema de permisos en detalle

---

💡 Tip: Usa la configuración de tasks en contents/themes/default/entities/tasks/tasks.config.ts como referencia para ver una implementación completa.