service_manager/docs/database-schema.md

Modelo de Datos - ServiceManagerWeb

Resumen del Esquema

El sistema utiliza PostgreSQL con un diseño multi-tenant donde cada cliente (tenant) tiene sus datos aislados pero comparte la misma estructura de base de datos.

Dominios Principales

1. TENANTS - Multi-tenancy

• tenants: Organizaciones cliente
• Cada tenant tiene configuraciones propias (usuarios max, storage, tipos de archivo)

2. AUTH - Autenticación y Autorización

• users: Usuarios del sistema (internos y clientes)
• refresh_tokens: Tokens de refresco para JWT
• Roles: ADMIN, SUPPORT_MANAGER, AGENT, AUDITOR, CLIENT_ADMIN, CLIENT_USER
• Soporte para 2FA (TOTP) opcional para staff interno

3. TICKETS - Core del Negocio

• tickets: Tickets de soporte principales
• ticket_categories: Categorías personalizables por tenant
• affected_systems: Sistemas afectados por tenant
• ticket_comments: Conversación en tickets
• ticket_attachments: Archivos adjuntos
• ticket_status_history: Historial de cambios de estado

Estados de ticket: NEW → TRIAGE → IN_PROGRESS → WAITING_CUSTOMER → RESOLVED → CLOSED Prioridades: LOW, MEDIUM, HIGH, URGENT

4. NOTIFICATIONS - Comunicaciones

• email_templates: Templates personalizables por tenant
• notification_logs: Historial de emails enviados
• Soporte para variables dinámicas en templates

5. AUDIT - Bitácora y Compliance

• audit_logs: Registro completo de acciones
• Tracking con correlation_id para requests
• Almacena cambios antes/después en JSON

Características Técnicas

Índices Estratégicos

• Optimizados para queries por tenant
• Indices compuestos para búsquedas frecuentes
• Índices en campos de fecha para reportes

Constraints y Validación

• CHECK constraints para valores enum
• Foreign keys con CASCADE apropiados
• UNIQUE constraints compuestos (tenant_id + campo)

Triggers Automáticos

• updated_at se actualiza automáticamente
• Preparado para audit logging automático

Multi-tenancy

• Todos los datos principales tienen tenant_id
• Aislamiento a nivel de aplicación
• Configuraciones por tenant (SLA, categorías, etc.)

Numeración de Tickets

Formato: TKT-YYYY-NNNNNN (ej: TKT-2026-000001)

• Único por tenant
• Año incluido para fácil organización
• 6 dígitos con ceros a la izquierda

SLA Tracking

• sla_response_due: Tiempo límite para primera respuesta
• sla_resolution_due: Tiempo límite para resolución
• first_response_at: Timestamp de primera respuesta
• Configurables por categoría

Almacenamiento de Archivos

• Metadata en BD, archivos en filesystem/S3
• Checksums MD5 y SHA256 para integridad
• Validación de tipos MIME
• Límites de tamaño por tenant

Datos Iniciales

El schema incluye:

• Tenant demo para desarrollo
• Usuario admin por defecto
• Categorías base (Soporte Técnico, Consulta Comercial, Incidente Crítico)
• Sistemas base (Plataforma Web, API, Base de Datos)
• Templates de email básicos

Escalabilidad

• Preparado para sharding por tenant_id
• Partitioning por fecha en audit_logs
• Índices optimizados para paginación
• Soft deletes donde aplique