Modelo de Datos

BoostAPI usa MySQL 8 con TypeORM. El esquema se sincroniza automaticamente (synchronize: true), con timezone forzado a UTC.

Diagrama de dominios

Entities (Empresas/Tenants)
    |
    +-- Users
    |     +-- Employees (por entidad)
    |     +-- Zauru Sessions (credenciales cifradas)
    |
    +-- Roles + Permissions
    |     +-- Role Permissions
    |     +-- Subscriptions (user/employee + role + entity)
    |           +-- Permission Overrides (ALLOW/DENY)
    |
    +-- Records (CRM Core)
    |     +-- Groups
    |     |     +-- Leads
    |     |     |     +-- Contacts
    |     |     |           +-- Contact Channels
    |     |     +-- Group Assignments (vendedor)
    |     |     +-- Group Purchase Summaries
    |     +-- Lead Assignments
    |     +-- Contact Assignments
    |     +-- Entity Channel Accounts
    |
    +-- Custom Fields
    |     +-- Custom Field Types
    |     +-- Custom Field Groups
    |     +-- Custom Fields + Options
    |     +-- Custom Field Values
    |
    +-- Opportunities (Kanban)
    |     +-- Opportunity States
    |     +-- Opportunity Events
    |     +-- Opportunity Funnels
    |     +-- Opportunity Orders
    |
    +-- Quotes
    |     +-- Quote Lines / Sections / Subsections
    |     +-- Quote States / Attachments
    |     +-- Quote Templates
    |     +-- Quote Public Decisions
    |
    +-- Orders
    |     +-- Order Lines
    |     +-- Automatic Numbers
    |
    +-- Interactions (Mensajeria)
    |     +-- Conversations
    |     +-- Message Index
    |     +-- Timeline Events
    |     +-- Workspace Notes
    |     +-- Routing (Queues + Filters)
    |     +-- Communications Config
    |
    +-- Agenda Events
    +-- Notifications + Recipients
    +-- Global Settings
    +-- Media Uploads

Tablas por dominio

Core – Multi-tenancy

Tabla	Descripcion	Relaciones clave
`entities`	Empresas/tenants. PK = Zauru entity ID	Padre de casi todo
`users`	Usuarios del CRM	email (unique), bcrypt password, zauru_id
`employees`	Empleados por entidad	user_id + entity_id

Autenticacion y RBAC

Tabla	Descripcion
`roles`	Roles por entidad. Flags: seller_role, allow_change_seller, read_chats
`subscriptions`	Vinculo usuario/empleado + rol + entidad. Unique por user+entity y employee+entity
`permissions`	Catalogo de permisos (44 codigos)
`role_permissions`	Permisos asignados a roles
`subscription_permission_overrides`	Overrides ALLOW/DENY por suscripcion
`zauru_user_sessions`	Sesiones Zauru cifradas (AES-256-CBC) por user+entity+client_kind

Records (CRM Core)

Tabla	Descripcion
`groups`	Agrupacion de leads. Filtrado por entity_id
`leads`	Leads/clientes. zauru_id null = lead puro, no-null = cliente sincronizado con Zauru
`contacts`	Contactos bajo leads
`contact_channels`	Canales de contacto: telefono, email, WhatsApp
`communication_channel_types`	Tipos de canal (whatsapp_api, etc.)
`entity_channel_accounts`	Cuentas de canal de la entidad
`group_assignments`	Asignacion vendedor -> grupo
`lead_assignments`	Asignacion vendedor -> lead
`contact_assignments`	Asignacion vendedor -> contacto
`group_purchase_summaries`	Cache de datos de compra

Campos personalizados

Tabla	Descripcion
`custom_field_types`	Tipos: texto, numero, fecha, select, media, etc.
`custom_field_groups`	Agrupaciones logicas de campos
`custom_fields`	Definiciones de campos con configuracion
`custom_field_options`	Opciones para campos tipo select/multi-select
`custom_field_values`	Valores guardados por entidad target (group/lead/contact)

Oportunidades (Kanban)

Tabla	Descripcion
`opportunities`	Oportunidades de venta
`opportunity_states`	Estados del funnel (personalizable por entidad)
`opportunity_events`	Historial de eventos de cada oportunidad
`opportunity_funnels`	Definiciones de funnels
`opportunity_orders`	Vinculacion oportunidad -> pedido

Cotizaciones

Tabla	Descripcion
`quotes`	Cotizaciones principales
`quote_lines`	Lineas de producto de la cotizacion
`quote_sections` / `quote_subsections`	Estructura de secciones
`quote_states`	Estados del ciclo de vida
`quote_attachments`	Archivos adjuntos (PDF, imagenes, videos, brochures)
`quote_rejection_reasons`	Razones de rechazo
`quote_public_decisions`	Decisiones del checkout publico
`quote_template_*`	5 tablas para el sistema de plantillas

Pedidos

Tabla	Descripcion
`orders`	Pedidos (se sincronizan con Zauru)
`order_lines`	Lineas de producto del pedido
`automatic_numbers`	Numeracion automatica
`automatic_number_types`	Tipos de numeracion

Interacciones (Mensajeria)

Tabla	Descripcion
`interaction_conversations`	Registro principal de conversacion
`interaction_event_inbox`	Cola de eventos entrantes
`interaction_message_index`	Indice local de mensajes
`interaction_timeline_event`	Timeline de la conversacion
`interaction_conversation_workspace_note`	Notas del vendedor/admin
`interaction_conversation_alias`	Alias de conversaciones
`interaction_conversation_relink`	Registros de re-vinculacion
`interaction_contact_channel_route`	Ruteo contacto -> canal
`interaction_communications_config`	Config de Communications por entidad
`contact_custom_field_assignment`	Campos personalizados en contactos de conversacion
`contact_required_field_policy`	Politicas de campos requeridos
`routing_queue`	Colas de routing
`routing_queue_member`	Miembros de colas
`routing_filter` / `routing_filter_rule`	Reglas de filtrado
`routing_rr_cursor`	Cursor round-robin

Otros

Tabla	Descripcion
`agenda_events`	Eventos de calendario
`media_uploads`	Registros de procesamiento de media (S3)
`notifications`	Notificaciones
`notification_recipients`	Destinatarios de notificaciones
`global_settings`	Definiciones de settings
`entity_global_settings`	Valores de settings por entidad
`external_catalog_caches`	Cache de datos de catalogo Zauru
`employee_payment_method_assignments`	Metodos de pago asignados a empleados
`employee_payment_term_assignments`	Terminos de pago asignados
`employee_supervisor_assignments`	Asignaciones de supervisores

Consideraciones importantes

No hay migraciones formales. TypeORM synchronize: true crea/actualiza tablas automaticamente. En produccion, esto significa que cambios de esquema se aplican al arrancar.
Los datos de Zauru NO se almacenan localmente (facturas, pagos, productos, stock). Se consultan en tiempo real via GraphQL/REST y se cachean en Pulpito.
Los leads se convierten en clientes cuando se les asigna un zauru_id. Esto significa que el lead se sincronizo con un payee de Zauru.
Las credenciales de Zauru estan cifradas en la tabla zauru_user_sessions usando AES-256-CBC con ZAURU_SESSION_ENCRYPTION_KEY.

Referencia privada: Ver BoostAPI/docs/domain-and-data-model.md para el modelo de datos detallado con diagramas y BoostAPI/src/*/entities/ para las definiciones exactas de TypeORM.