Initial commit

docs/database-schema.md

@@ -0,0 +1,96 @@
+# 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