🛠️ Sistema de Gestión de Servicios Informáticos

Una plataforma web diseñada para la Sección de Servicios Informáticos de una institución, con el fin de registrar, asignar, controlar y documentar los servicios técnicos solicitados por las distintas dependencias.

📋 Tabla de Contenido

1. Visión General
2. Funcionalidades Principales
3. Roles del Sistema
4. Stack Tecnológico
5. Reglas de Negocio y Estados
6. Arquitectura y Entornos
7. Seguridad, Auditoría y Respaldo
8. Instalación Rápida
9. Hoja de Ruta
10. Limitaciones Conocidas
11. Licencia y Soporte

---

🌟 Visión General

El sistema centraliza el ciclo de vida completo de un servicio técnico, abarcando:

• Recepción multicanal (llamadas, WhatsApp, correo, presenciales).
• Asignación de técnicos mediante manifestación de interés o asignación directa del operador.
• Seguimiento de tareas técnicas, tiempos y soluciones.
• Aceptación final por el responsable de la dependencia solicitante.
• Generación de reportes operativos y analíticos.

---

🚀 Funcionalidades Principales

1. Gestión de Servicios

• Registro con codificación automática (ej. SRV-2026-0001).
• Priorización (Alta, Media, Baja).
• Vinculación con funcionario solicitante y dependencia.
• Motivos de cancelación documentados.

2. Asignación y Flujo de Atención

• Los técnicos manifiestan interés en un servicio desde el tablero.
• El operador confirma al técnico asignado.
• Asignación directa del operador disponible.

3. Tablero Kanban Interactivo

• 3 columnas: Pendientes, En proceso, Finalizados.
• Drag & drop con validación en backend.
• Tarjetas con código, prioridad, técnico, tiempo transcurrido, alertas de SLA.
• Filtros por técnico, dependencia, prioridad, fecha.
• Actualizaciones en tiempo real (WebSockets).

4. Tareas y Categorías

• Múltiples tareas técnicas por servicio.
• Cada tarea registra: categoría, subcategoría, descripción, tiempo, resultado.
• Seeders con catálogo inicial (contraseñas, redes, mantenimiento, etc.).

5. Notificaciones WhatsApp

• Integración desacoplada (capa NotificationChannel).
• Colas de Laravel con reintentos exponenciales.
• Registro de cada intento (éxito/fallo).
• Log de notificaciones consultable.

6. Archivos Adjuntos

• Imágenes, PDF, escaneos, evidencias.
• Niveles de visibilidad (público, interno, restringido).
• Control de tamaño y tipo MIME.

7. Reportes y Dashboard

• KPIs: tiempo promedio de respuesta/resolución, % de aceptación, carga por técnico.
• Gráficos: tendencia mensual, por dependencia, por prioridad, por medio de recepción.
• Exportación: PDF y Excel con filtros aplicados.

8. Control de Tiempos

• Tiempos automáticos: recepción, asignación, inicio, pausa, fin.
• Tiempo efectivo descontando pausas.
• Tiempo total del servicio.
• Auditoría de correcciones manuales.

9. Visto Bueno

• Proceso de aceptación/rechazo por el responsable de la dependencia.
• Observaciones registradas.
• Reapertura al estado "En proceso" si es rechazado.

---

👥 Roles del Sistema

Rol	Capacidades principales
Administrador	Acceso total, gestión de usuarios, configuración del sistema, reportes.
Operador	Registrar servicios, asignar técnicos, gestionar estados, reportes operativos.
Técnico	Ver pendientes, manifestar interés, registrar tareas/avances, finalizar servicios.
Funcionario	Registrar solicitudes propias, consultar estado, dar visto bueno (si es responsable).

---

🧰 Stack Tecnológico

Capa	Tecnología
Backend	Laravel 11 (PHP 8.2+)
Frontend declarativo	Livewire 3 (formularios, filtros, CRUDs)
Frontend interactivo	Vue.js 3 (Tablero Kanban, drag & drop)
Estilos	Tailwind CSS 3
Base de Datos	MySQL 8
Cache/Colas	Redis
WebSockets	Laravel Reverb (tiempo real en Kanban)
Infraestructura	Docker + Docker Compose + Dev Containers
Reportes	DomPDF (PDF) + Maatwebsite/Excel (XLSX)
Testing	Pest / PHPUnit
Calidad de código	Laravel Pint (PHP) + ESLint + Prettier (JS)

---

📐 Reglas de Negocio y Estados

Estados del Servicio

estado	asignado_id	Estado Visible
0	NULL	Pendiente
0	funcionario_id	En proceso
1	funcionario_id	Finalizado (técnico)
2	*	Cancelado

El visto bueno del responsable es independiente del estado técnico.

Transiciones Permitidas

• Pendiente → En proceso (al asignar técnico)
• En proceso → Finalizado (al cerrar el técnico)
• Pendiente/En proceso → Cancelado (solo operador/admin con motivo)
• Finalizado → Aceptado/Rechazado (por responsable de la dependencia)

---

🏗️ Arquitectura y Entornos

• Monolito modular Laravel con módulos por dominio (Services, Employees, Notifications, etc.).
• Frontend híbrido: Livewire en paneles administrativos, Vue.js en componentes de alta interactividad.
• Entornos separados: local, testing, production con sus propios .env.
• Docker Compose con servicios: app, web (Nginx), mysql, redis, queue, scheduler, mailpit, adminer.

---

🔐 Seguridad, Auditoría y Respaldo

• Autenticación robusta con Laravel Fortify/Breeze.
• Autorización mediante spatie/laravel-permission y Policies (ServicePolicy, EmployeePolicy, etc.).
• Validaciones en backend (no se confía en el frontend).
• Auditoría polimórfica (audit_logs) para cambios críticos.
• Protección CSRF, rate limiting y headers seguros.
• Backups automáticos de base de datos y archivos.
• Cifrado de datos sensibles y variables de entorno.

---

⚙️ Instalación Rápida

# 1. Clonar el repositorio
git clone <url-del-repositorio>
cd vibetest

# 2. Levantar contenedores
docker compose up -d --build

# 3. Instalar dependencias y migrar
composer install
npm install
npm run build
php artisan key:generate
php artisan migrate --seed
php artisan storage:link
php artisan queue:work

Más detalles en plan/plan-implementacion.md y plan/devcontainer-setup.md.

---

🗺️ Hoja de Ruta (Roadmap)

Fase	Duración	Entregable
1	1 sem	Setup + Auth
2	1 sem	Modelos institucionales
3	2 sem	Servicios core
4	2 sem	Kanban + Dashboard
5	1 sem	Tareas y categorías
6	1 sem	Historial y auditoría
7	1 sem	WhatsApp
8	1 sem	Archivos adjuntos
9	1 sem	Reportes
10	1 sem	QA + Despliegue

Ver plan/plan-implementacion.md para el detalle completo.

---

⚠️ Limitaciones Conocidas

• La API de WhatsApp requiere un proveedor externo (Twilio, Meta Cloud API) configurado en .env.
• El tiempo real depende de la disponibilidad de Laravel Reverb o Pusher.
• Los reportes predictivos (IA) están planificados para v2.
• Sin app móvil nativa (la interfaz web es completamente responsiva).

---

📄 Licencia y Soporte

Software propietario de uso institucional. Soporte interno a través del equipo de desarrollo.