Arquitectura de Base de Datos - CreaRack Pro v1.0.50

Última actualización: 03-04-2026 Versión de la aplicación: v1.0.50 Motor: PostgreSQL (16 en producción, 17 en desarrollo) ORM: Django 6.0.3 Total de modelos: 42 Total de migraciones: 112

1. Visión General

CreaRack Pro utiliza PostgreSQL como base de datos relacional principal, gestionada a través del ORM de Django 6. La aplicación está organizada en 7 apps Django, cada una con sus propios modelos y migraciones.

Distribución de Modelos por App

Configuración de Conexión

Desarrollo (config/settings/dev.py)

DATABASES = {
    "default": {
        "ENGINE": "django.db.backends.postgresql",
        "NAME": "crearack_pro",
        "USER": "crearack_user",
        "PASSWORD": "dev_password_123",
        "HOST": os.getenv("POSTGRES_HOST", "localhost"),  # 'db' en Docker
        "PORT": "5432",
        "OPTIONS": {"connect_timeout": 10},
        # Sin CONN_MAX_AGE (nueva conexión por request)
    }
}

Producción (config/settings/production.py)

DATABASES = {
    "default": {
        "ENGINE": "django.db.backends.postgresql",
        "NAME": os.getenv("POSTGRES_DB", "crearack_pro"),
        "USER": os.getenv("POSTGRES_USER", "crearack_user"),
        "PASSWORD": os.getenv("POSTGRES_PASSWORD"),
        "HOST": os.getenv("POSTGRES_HOST", "db"),
        "PORT": "5432",
        "CONN_MAX_AGE": 600,          # Reutilizar conexiones 10 min
        "CONN_HEALTH_CHECKS": True,   # Django 6: verificar conexión antes de reutilizar
        "OPTIONS": {"connect_timeout": 10},
    }
}

2. Configuración Docker

Desarrollo (compose.yml)

db:
  image: postgres:18-alpine
  container_name: crearack_db
  environment:
    POSTGRES_DB: crearack_pro
    POSTGRES_USER: crearack_user
    POSTGRES_PASSWORD: dev_password_123
  volumes:
    - pg_data:/var/lib/postgresql/data
  ports:
    - "5432:5432"
  healthcheck:
    test: ["CMD-SHELL", "pg_isready -U crearack_user -d crearack_pro"]
    interval: 5s
    timeout: 5s
    retries: 5

• Imagen: postgres:18-alpine
• max_connections: Por defecto PostgreSQL (100)
• Volumen: pg_data (Docker named volume)
• Red: crearack_internal (bridge)

Producción (compose.prod.yml)

db:
  image: postgres:18-alpine
  restart: unless-stopped
  command: >-
    postgres
    -c max_connections=200
    -c shared_buffers=256MB
    -c shared_preload_libraries=pg_stat_statements
    -c pg_stat_statements.track=all
  environment:
    POSTGRES_DB: ${POSTGRES_DB:-crearack_pro}
    POSTGRES_USER: ${POSTGRES_USER:-crearack_user}
    POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
  volumes:
    - pg_data_prod:/var/lib/postgresql/data

pgbouncer:
  image: edoburu/pgbouncer:latest
  environment:
    DATABASE_URL: postgres://...@db:5432/crearack_pro
    POOL_MODE: transaction
    DEFAULT_POOL_SIZE: 30
    MAX_CLIENT_CONN: 300
  depends_on:
    db: { condition: service_healthy }

• Imagen: postgres:18-alpine (migrado desde 16 el 04-04-2026)
• max_connections: 200 (bajado desde 500 gracias a pgbouncer)
• shared_buffers: 256MB
• pg_stat_statements: Activado (slow query tracking)
• pgbouncer: Transaction pooling, pool=30, max_client=300
• CONN_MAX_AGE: 0 en Django (obligatorio con pgbouncer transaction mode)
• Volumen: pg_data_prod (Docker named volume)
• Red: crearack_internal (bridge)
• Contenedor en Hetzner: crearack-pro-zcmvsl-db-1
• Monitoring: Huey task monitor_db_connections cada 5 min, alerta en SystemLog al 80%
• Backup verification: testzip() tras cada backup diario (3:30 AM)

3. Modelo Multi-Tenancy

CreaRack Pro implementa multi-tenancy con dos capas de aislamiento:

1. Capa aplicación (Django ORM): Todos los queries filtran por organization=org
2. Capa base de datos (PostgreSQL RLS): Políticas Row-Level Security como red de seguridad (v1.0.50)

Patrón de Aislamiento (ORM)

Organization (tenant raíz)
├── User (FK directa → organization)
├── Rack (FK directa → organization)
│   └── Device (FK indirecta vía rack.organization)
│       └── ConfigBackup (FK indirecta vía device.rack.organization)
├── Blueprint (FK directa → organization)
├── DeviceProfile (FK directa → organization)
├── MonitoringTarget (FK directa → organization)
├── AIInsight (FK directa → organization)
├── SignagePlayer (FK directa → organization)
├── AgentInstance (FK directa → organization)
├── Script (FK directa → organization)
├── StoredCredential (FK directa → organization)
├── SystemLog (FK directa → organization, nullable)
└── ScriptTemplate (FK directa → organization, nullable = global)

Modelos Globales (sin Organization FK)

Soft Delete

Los siguientes modelos implementan borrado lógico con campo deleted_at:

Métodos: soft_delete(), restore(), propiedad is_deleted.

PostgreSQL Row-Level Security (v1.0.50)

Migration: core/0017_rls_policies

RLS añade protección a nivel de base de datos. Si un bug en el ORM omite el filtro por organización, PostgreSQL bloquea el acceso.

Mecanismo: TenantRLSMiddleware ejecuta SET app.current_org_id por request. PostgreSQL aplica políticas USING (organization_id = current_setting('app.current_org_id')::int).

Cobertura: 35 tablas con políticas:

• 29 tablas strict (org NOT NULL): Solo filas de la organización del request
• 6 tablas nullable (Stencil, User, etc.): Filas propias + globales (org IS NULL)
• Bypass: Superusers (org_id=0), requests sin auth

Tablas con FK heredada (Device, ConfigBackup, BlueprintPlacement, etc.) no necesitan política propia — la integridad referencial protege automáticamente.

Tenant Lifecycle

4. Referencia de Modelos por App

4.1 App core

4.1.1 SaaSModule

Tabla: core_saasmodule

Registro de módulos de aplicación disponibles para suscripción.

Meta: ordering = ['sort_order', 'name']

4.1.2 Plan

Tabla: core_plan

Plan de suscripción que define módulos base para una organización.

M2M: modules → SaaSModule (through: core_plan_modules, related_name: plans)

Meta: ordering = ['sort_order']

Choices para slug: starter, pro, custom

4.1.3 Organization

Tabla: core_organization

Tenant SaaS. Todas las entidades pertenecen a una organización.

M2M: extra_modules → SaaSModule (through: core_organization_extra_modules, related_name: extra_organizations)

4.1.4 User

Tabla: core_user

Modelo de usuario custom que extiende AbstractUser de Django. Definido como AUTH_USER_MODEL = "core.User".

Constraints:

• UniqueConstraint(fields=['email'], condition=~Q(email=''), name='unique_email_when_set') — email único cuando no está vacío

4.1.5 SystemLog

Tabla: core_systemlog

Log de auditoría del sistema.

Indexes:

• (organization, -timestamp)
• (user, -timestamp)
• (level, -timestamp)

Meta: ordering = ['-timestamp']

4.1.6 ScriptTemplate

Tabla: core_scripttemplate

Plantillas de scripts de configuración de red reutilizables.

Constraints: unique_together = ('name', 'organization')

4.1.7 ImpersonationLog

Tabla: core_impersonationlog

Log de auditoría para sesiones de impersonación de superusuario.

Meta: ordering = ['-started_at']

4.1.8 ModulePermission

Tabla: core_modulepermission

Permisos granulares por usuario (override sobre el rol).

4.1.9 TemporaryAccess

Tabla: core_temporaryaccess

Elevación temporal de permisos con tiempo limitado.

Meta: ordering = ['-granted_at']

4.1.10 StoredCredential

Tabla: core_storedcredential

Almacenamiento cifrado (Fernet AES) de credenciales SNMP/SSH/HTTP.

Constraints: unique_together = ('name', 'organization')

Cifrado: Los campos sensibles (community, auth_key, priv_key, ssh_password, enable_password, http_password) se cifran con Fernet AES via CredentialManager. El método get_section(section_name) descifra bajo demanda.

4.1.11 LoginLog

Tabla: core_loginlog

Registro de cada intento de login (exitoso y fallido).

Indexes:

• (user, -timestamp)
• (success, -timestamp)
• (ip_address, -timestamp)

Meta: ordering = ['-timestamp']

4.2 App racks

4.2.1 BoxCategory

Tabla: racks_boxcategory

Categorías para dispositivos.

Constraints: unique_together = ('name', 'organization')

4.2.2 RackGroup

Tabla: racks_rackgroup

Agrupación lógica de racks (ej: ‘Data Center A’, ‘Row 1’). También utilizado por DeviceProfile, SignagePlayer y Device como grupo genérico.

Constraints: unique_together = ('name', 'organization')

4.2.3 Stencil

Tabla: racks_stencil

Plantillas de dispositivos (device templates) para el editor de racks.

4.2.4 Rack

Tabla: racks_rack

Rack/armario de servidor.

M2M: groups → RackGroup (through: racks_rack_groups, related_name: racks)

4.2.5 Device

Tabla: racks_device

Dispositivo dentro de un rack.

M2M: groups → RackGroup (through: racks_device_groups, related_name: devices)

4.2.6 ConfigBackup

Tabla: racks_configbackup

Backups de configuración de dispositivos de red.

Indexes:

• (device, -created_at)
• (rack, -created_at)

Meta: ordering = ['-created_at']

4.3 App blueprints

4.3.1 Blueprint

Tabla: blueprints_blueprint

Mapa de canvas infinito (plano o topología).

4.3.2 BlueprintPlacement

Tabla: blueprints_blueprintplacement

Posición de un rack sobre un plano.

Constraints: unique_together = ('blueprint', 'rack')

4.3.3 MapAnnotation

Tabla: blueprints_mapannotation

Paredes, texto, zonas en el mapa.

4.3.4 AIPrompt

Tabla: blueprints_aiprompt

Prompts de AI Brain guardados (sistema Save As).

Constraints: unique_together = [('organization', 'name')]

Meta: ordering = ['-updated_at']

4.4 App network

4.4.1 VendorProfile

Tabla: vendor_profiles (custom db_table)

Base de datos centralizada de vendors de red. Scope global (no per-organization).

Meta: ordering = ['priority', 'display_name']

4.4.2 CustomMib

Tabla: custom_mibs (custom db_table)

MIBs custom subidos por usuarios para enriquecer Deep Discovery.

Constraints: unique_together = [['vendor_profile', 'module_name']]

Meta: ordering = ['-uploaded_at']

4.4.3 DeviceProfile

Tabla: device_profiles (custom db_table)

Perfil completo de dispositivo de red descubierto via Auto-Provision Tool.

M2M: groups → RackGroup (through auto, related_name: device_profiles)

Constraints: unique_together = [['organization', 'ip_address']]

Indexes:

• (organization, ip_address)
• (vendor, model)
• (confidence_score)
• (discovered_at)

Meta: ordering = ['-confidence_score', '-discovered_at']

4.4.4 PortConnection

Tabla: port_connections (custom db_table)

Mapeo de puertos de dispositivo a DeviceProfiles o Devices (switch-to-switch, etc.). Exactamente UNO de profile o connected_device debe estar presente (XOR constraint).

Constraints:

• unique_together = [('device', 'port_key')]
• CheckConstraint: (profile NOT NULL AND connected_device NULL) OR (profile NULL AND connected_device NOT NULL) — nombre: port_conn_one_target
• UniqueConstraint(fields=['connected_device', 'connected_port_key'], condition=Q(connected_port_key__gt='')) — nombre: port_conn_unique_dest_port

Indexes: (organization)

4.5 App monitoring

4.5.1 MonitoringTarget

Tabla: monitoring_monitoringtarget

Dispositivo o IP a monitorear.

Constraints: unique_together = ['organization', 'ip_address'] — el target es 1:1 por host y org. El campo scope fue eliminado (Ficha Central F4, migración monitoring/0025): la pertenencia a las páginas Wireless/UPS/Signage la decide DeviceProfile.assigned_page, no el target.

Meta: ordering = ['name'] · index (organization, enabled) (idx_target_org_enabled)

4.5.2 MetricSample

Tabla: monitoring_metricsample

Muestra individual de métrica (histórico). Nota: Candidato a eliminación futura — la mayoría de métricas se almacenan en VictoriaMetrics, pero este modelo aún tiene 38+ referencias activas.

Indexes:

• (target, metric_type, -timestamp)
• (timestamp)

Meta: ordering = ['-timestamp']

4.5.3 MonitoringAlert

Tabla: monitoring_monitoringalert

Configuración de alertas (per-device o global).

Meta: ordering = ['name']

4.5.4 AlertEvent

Tabla: monitoring_alertevent

Historial de alertas disparadas.

Meta: ordering = ['-triggered_at']

4.5.5 AggregatedMetric

Tabla: monitoring_aggregatedmetric

Métricas agregadas por hora para consultas históricas eficientes.

Constraints: unique_together = ['target', 'hour', 'metric_type']

Indexes: (target, metric_type, -hour)

Meta: ordering = ['-hour']

4.5.6 AIInsight

Tabla: monitoring_aiinsight

Diagnóstico AI generado por CreaRack Network Sentinel (CNS).

Constraints:

• UniqueConstraint(fields=['organization', 'case_number'], name='unique_case_number_per_org')

Indexes:

• (organization, status)
• (target, -created_at)

Meta: ordering = ['-created_at']

4.5.7 AIInsightAuditLog

Tabla: monitoring_aiinsightauditlog

Log de auditoría para cada acción sobre un insight.

Meta: ordering = ['-created_at']

4.5.8 InsightConversation

Tabla: monitoring_insightconversation

Conversación Q&A para un AI Insight (interacciones Explain).

Meta: ordering = ['created_at']

4.5.9 SLAPolicy

Tabla: monitoring_slapolicy

Políticas SLA configurables por nivel de riesgo.

Constraints: unique_together = ['organization', 'risk_level']

4.5.10 NotificationChannel

Tabla: monitoring_notificationchannel

Canal de notificación (webhook, email, Slack, Teams).

4.5.11 NotificationLog

Tabla: monitoring_notificationlog

Log de notificaciones enviadas.

Meta: ordering = ['-created_at']

4.5.12 EscalationPolicy

Tabla: monitoring_escalationpolicy

Política de escalamiento multi-nivel por nivel de riesgo.

4.5.13 EscalationLevel

Tabla: monitoring_escalationlevel

Paso individual dentro de una política de escalamiento.

Constraints: unique_together = ['policy', 'level']

Meta: ordering = ['level']

4.5.14 IncidentGroup

Tabla: monitoring_incidentgroup

Agrupa insights relacionados con la misma causa raíz.

Meta: ordering = ['-created_at']

4.5.15 MaintenanceWindow

Tabla: monitoring_maintenancewindow

Ventana de mantenimiento para suprimir creación de insights.

M2M: targets → MonitoringTarget (related_name: maintenance_windows) — vacío = todos los targets

Meta: ordering = ['-start_at']

4.5.16 KnownIssue

Tabla: monitoring_knownissue

Issue conocido con resolución documentada.

Meta: ordering = ['-occurrence_count']

4.5.17 InsightLink

Tabla: monitoring_insightlink

Link manual entre dos insights relacionados.

Constraints: unique_together = ['source', 'target']

4.5.18 Runbook

Tabla: monitoring_runbook

Librería de procedimientos de remediación.

Meta: ordering = ['-usage_count']

4.5.19 RecurringPattern

Tabla: monitoring_recurringpattern

Patrón de incidentes recurrentes detectado para alertas proactivas.

Meta: ordering = ['-confidence']

4.6 App signage

4.6.1 SignageVendorAdapter

Tabla: signage_signagevendoradapter

Configuración de adaptador vendor-specific para comunicación con dispositivos de signage. Scope global (sin FK a Organization).

Meta: ordering = ['name']

4.6.2 SignagePlayer

Tabla: signage_signageplayer

Reproductor/player de signage físico vinculado a network discovery.

M2M: groups → RackGroup (related_name: signage_players)

Constraints: unique_together = ['organization', 'device_profile']

Meta: ordering = ['display_name']

4.6.3 SignageOperation

Tabla: signage_signageoperation

Log de auditoría de operaciones de signage con rollback.

Meta: ordering = ['-created_at']

Auto-purge: Mantiene últimas 50 por organización.

4.6.4 MediaAsset

Tabla: signage_mediaasset

Contenido multimedia subido para playlists de digital signage.

Meta: ordering = ['-created_at']

4.6.5 Playlist

Tabla: signage_playlist

Colección ordenada de media assets con timing y transiciones.

Meta: ordering = ['-updated_at']

Auto-purge: Elimina auto-playlists >24h (mantiene 20 más recientes).

4.6.6 Schedule

Tabla: signage_schedule

Reglas basadas en tiempo para mapear playlists a franjas horarias.

Meta: ordering = ['name']

4.6.7 ClientProject

Tabla: signage_clientproject

Proyecto de cliente que agrupa dispositivos, contenido, playlists y schedules.

M2M:

• devices → DeviceProfile (related_name: client_projects)
• playlists → Playlist (related_name: client_projects)

Meta: ordering = ['name']

4.6.8 PlaybackLog

Tabla: signage_playbacklog

Proof-of-play: registro de lo que se mostró, cuándo y por cuánto tiempo.

Indexes:

• (organization, -started_at)
• (player, -started_at)

Meta: ordering = ['-started_at']

4.6.9 ContentDeployment

Tabla: signage_contentdeployment

Tracking de despliegue de playlists/schedules a players.

M2M: players → SignagePlayer (related_name: deployments)

Meta: ordering = ['-created_at']

4.6.10 ClientShareLink

Tabla: signage_clientsharelink

Link de acceso basado en token para clientes externos del portal de signage.

M2M:

• players → SignagePlayer (related_name: share_links)
• playlists → Playlist (related_name: share_links)
• schedules → Schedule (related_name: share_links)

Meta: ordering = ['-created_at']

4.6.11 PortalChangeLog

Tabla: signage_portalchangelog

Audit trail y cola de cambios pendientes del portal de clientes.

Indexes: (status, -created_at)

Meta: ordering = ['-created_at']

4.7 App terminal

4.7.1 Script

Tabla: terminal_script

Scripts de comandos de red.

4.7.2 AgentInstance

Tabla: terminal_agentinstance

Representa una instalación del Local Agent conectada al SaaS. Soporta roles Primary/Secondary para failover de Sentinel Mode.

Indexes:

• (organization, role)
• (organization, status)

Meta: ordering = ['-connected_at']

5. Diagrama de Relaciones entre Entidades

┌─────────────────────────────────────────────────────────────────────┐
│                         CORE (Tenant Root)                          │
│                                                                     │
│  ┌──────────┐    ┌──────────────┐    ┌──────┐                      │
│  │ SaaSModule│◄──M2M──┤     Plan      │    │      │                │
│  └──────────┘    └──────┬───────┘    │      │                      │
│       ▲                  │FK          │      │                      │
│       │M2M          ┌────▼────────┐  │      │                      │
│       └─────────────┤Organization  │◄─┘      │                      │
│                     └──┬──┬──┬────┘          │                      │
│                        │  │  │               │                      │
│     ┌──────────────────┘  │  └──────────┐    │                      │
│     │FK                   │FK            │FK  │                      │
│  ┌──▼──┐  ┌──────────┐   │  ┌───────────▼─┐ │  ┌──────────────┐   │
│  │User  │  │SystemLog  │   │  │StoredCred   │ │  │ LoginLog     │   │
│  └──┬───┘  └──────────┘   │  └─────────────┘ │  └──────────────┘   │
│     │                      │                   │                     │
│     │1:1                   │                   │                     │
│  ┌──▼──────────────┐      │                   │                     │
│  │ModulePermission  │      │                   │                     │
│  └─────────────────┘      │                   │                     │
└───────────────────────────┼───────────────────┼─────────────────────┘
                            │                   │
┌───────────────────────────┼───────────────────┼─────────────────────┐
│                      RACKS │                   │                     │
│                            │                   │                     │
│  ┌──────────┐    ┌────────▼──┐    ┌──────────▼──┐                  │
│  │RackGroup  │◄──M2M──┤   Rack     │    │  Stencil    │            │
│  └────┬─────┘    └──┬────────┘    └─────────────┘                  │
│       │              │FK                                            │
│       │M2M     ┌─────▼────┐    ┌──────────────┐                    │
│       └────────┤  Device   ├───►ConfigBackup   │                    │
│                └─────┬─────┘    └──────────────┘                    │
│                      │FK                                            │
└──────────────────────┼──────────────────────────────────────────────┘
                       │
┌──────────────────────┼──────────────────────────────────────────────┐
│                BLUEPRINTS                                            │
│                       │                                             │
│  ┌──────────┐   ┌────▼────────────────┐    ┌──────────────┐        │
│  │AIPrompt   │   │BlueprintPlacement   │    │MapAnnotation  │       │
│  └──────────┘   └────┬────────────────┘    └──────┬───────┘        │
│                      │FK                          │FK               │
│                 ┌────▼───────┐                    │                  │
│                 │ Blueprint   │◄───────────────────┘                 │
│                 └────────────┘                                       │
└─────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────┐
│                        NETWORK                                       │
│                                                                     │
│  ┌──────────────┐    ┌───────────────┐    ┌──────────────┐          │
│  │VendorProfile  │◄──FK──┤  CustomMib    │    │PortConnection │     │
│  └──────────────┘    └───────────────┘    └──────────────┘          │
│                                                                     │
│  ┌──────────────────────────────┐                                   │
│  │       DeviceProfile           │                                  │
│  │  FK → Organization            │                                  │
│  │  FK → MonitoringTarget (opt)  │                                  │
│  │  FK → Device (opt)            │                                  │
│  │  M2M → RackGroup              │                                  │
│  └──────────────────────────────┘                                   │
└─────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────┐
│                       MONITORING                                     │
│                                                                     │
│  ┌────────────────┐    ┌──────────────┐    ┌──────────────┐         │
│  │MonitoringTarget │◄──FK──┤MetricSample  │    │AggregatedMetric│   │
│  └───────┬────────┘    └──────────────┘    └──────────────┘         │
│          │FK                                                        │
│          │         ┌──────────────────┐                              │
│          ├────────►│  AIInsight        │◄──FK── IncidentGroup       │
│          │         │  FK → KnownIssue  │◄──FK── Runbook             │
│          │         └────────┬─────────┘                             │
│          │                  │FK                                      │
│          │    ┌─────────────┼──────────────┐                        │
│          │    │             │              │                         │
│          │  AuditLog  Conversation  InsightLink                     │
│          │                                                          │
│          │    ┌───────────────┐    ┌──────────────────┐             │
│          ├───►│MonitoringAlert │───►│   AlertEvent      │           │
│          │    └───────────────┘    └──────────────────┘             │
│          │                                                          │
│  ┌───────┴───────────────────────────────────────────┐              │
│  │ ITSM: SLAPolicy, NotificationChannel,            │              │
│  │       EscalationPolicy → EscalationLevel,         │              │
│  │       MaintenanceWindow (M2M targets),            │              │
│  │       KnownIssue, Runbook, RecurringPattern       │              │
│  └───────────────────────────────────────────────────┘              │
└─────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────┐
│                        SIGNAGE                                       │
│                                                                     │
│  ┌────────────────────┐    ┌────────────────┐                       │
│  │SignageVendorAdapter │    │  MediaAsset     │                      │
│  │  (global)           │    └───────┬────────┘                      │
│  └────────┬───────────┘            │FK                              │
│           │FK                      │                                │
│  ┌────────▼───────────┐    ┌──────▼─────────┐    ┌──────────┐      │
│  │  SignagePlayer      │◄──M2M──┤ContentDeployment│    │ Schedule │  │
│  │  FK → Playlist      │    └────────────────┘    └──────────┘      │
│  │  FK → Schedule      │                                            │
│  └────────┬───────────┘    ┌──────────┐                             │
│           │FK              │ Playlist  │                             │
│  ┌────────▼────────┐      └──────────┘                              │
│  │SignageOperation  │                                                │
│  │PlaybackLog       │      ┌──────────────────┐                     │
│  └─────────────────┘      │ClientShareLink    │                     │
│                           │  M2M → Players    │                     │
│  ┌──────────────┐         │  M2M → Playlists  │                     │
│  │ClientProject  │         │  M2M → Schedules  │                    │
│  │ M2M → Devices │         └────────┬─────────┘                     │
│  │ M2M → Playlists│                │FK                              │
│  └──────────────┘         ┌────────▼─────────┐                      │
│                           │PortalChangeLog    │                      │
│                           └──────────────────┘                       │
└─────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────┐
│                        TERMINAL                                      │
│                                                                     │
│  ┌──────────┐    ┌───────────────┐                                  │
│  │  Script   │    │AgentInstance   │                                 │
│  │  FK→Org   │    │  FK→Org        │                                │
│  │  FK→User  │    │  unique agent_id│                               │
│  └──────────┘    └───────────────┘                                  │
└─────────────────────────────────────────────────────────────────────┘

6. Patrones de Diseño Clave

6.1 Soft Delete (deleted_at)

Tres modelos implementan borrado lógico: Organization, Rack y Blueprint. Cada uno tiene:

• Campo deleted_at (DateTimeField, nullable)
• Métodos soft_delete() y restore()
• Propiedad is_deleted
• Los queries regulares no filtran automáticamente por deleted_at — el filtrado se hace en las vistas/API

6.2 Campos JSON

El uso de JSONField es extensivo para datos semi-estructurados:

Nota: Device.model_data y Device.management_config usan TextField con JSON manual (legacy) en lugar de JSONField nativo de PostgreSQL.

6.3 Cifrado Fernet (AES-128-CBC)

El modelo StoredCredential almacena credenciales sensibles cifradas con Fernet (basado en AES-128-CBC + HMAC-SHA256). Implementado via core.security.credential_manager.CredentialManager.

Campos cifrados:

• community (SNMP v2c)
• auth_key, priv_key (SNMPv3)
• ssh_password, enable_password (SSH)
• http_password (HTTP)

Adicionalmente, Device.management_config puede contener valores cifrados con Fernet (detectados por el prefijo gAAAA).

6.4 Audit Logging

El sistema tiene múltiples capas de auditoría:

6.5 ArrayField (PostgreSQL-specific)

Los siguientes campos usan ArrayField de django.contrib.postgres:

6.6 Tablas con db_table Custom

El resto de modelos usan el naming convention de Django: {app_label}_{model_name_lower}.

7. Resumen de Migraciones

RunPython notables (data migrations):

• Seed de VendorProfiles para ~40 vendors de red (network)
• Seed de 9 UPS vendor profiles (network 0040)
• Seed de 12 SignageVendorAdapters (signage)
• Seed de SaaSModules y Plans (core)

8. Backup y Restore

Documentación detallada: Documentation/admin/BACKUP_RESTORE.md

Backup PostgreSQL

# Desarrollo
docker compose exec db pg_dump -U crearack_user crearack_pro > backup.sql

# Producción
ssh root@crearack.com "docker exec crearack-pro-zcmvsl-db-1 \
  pg_dump -U crearack_user crearack_pro" > backup_prod.sql

Restore

# Desarrollo
docker compose exec -T db psql -U crearack_user crearack_pro < backup.sql

# Producción (con precaución)
cat backup.sql | ssh root@crearack.com "docker exec -i crearack-pro-zcmvsl-db-1 \
  psql -U crearack_user crearack_pro"

Backup via Django (con remapeo de IDs)

La app incluye endpoints de backup/restore nativos que manejan:

• Exportación de modelos seleccionados a JSON
• Remapeo de IDs al importar (evita colisiones)
• Preservación de relaciones (FKs, M2M, cables)

9. Notas de Rendimiento

Conexiones

Incidente de Saturación (01-04-2026)

El modo Sentinel con 268 targets saturó max_connections=100 tras reconexión post-downtime de 5 días. Solución temporal: subir a 500. Solución definitiva pendiente: pgbouncer como connection pooler en modo transaction.

Cuellos de Botella Conocidos

1. MetricSample: Tabla de alto volumen (38+ referencias activas). Candidata a eliminación cuando se migre completamente a VictoriaMetrics.
2. DeviceProfile: Modelo muy ancho (~50 campos) con múltiples JSONFields grandes (interfaces, deep_snmp_data, raw_snmp_data). Considerar partición o archivado de raw data.
3. PlaybackLog / SignageOperation: Tablas de alto volumen con auto-purge (50 ops, 24h playlists).
4. Sin pgbouncer: Cada worker de Daphne/Huey abre conexiones independientes a PostgreSQL.

Mejoras Pendientes

• pgbouncer: Connection pooler en modo transaction entre Django y PostgreSQL
• Sentinel batch status: Agrupar device status updates en bulk POST
• Migration squash: 44 migraciones en network/ — diferido a v2.0.0 por riesgo
• MetricSample cleanup: Eliminar cuando VictoriaMetrics cubra todas las referencias

Mantenido por: Claude (Anthropic) + Equipo CreaRack

Véase también

• [[crearack-tech—architecture—pg18-migration-plan]]
• [[crearack-tech—admin—cache-and-database]]
• [[crearack-tech—guides—database-admin-guide]]
• [[decision—20260315—postgres-18-pgbouncer]]
• [[decision—20260201—conn-max-age-daphne]]
• [[concept—saas—multi-tenancy]]
• [[decision—20260101—django-ninja-vs-drf]]