# Sistema de Seguimiento Automático de Tiempo de Trabajo

## Descripción General

El sistema de ticketera ahora incluye **seguimiento automático del tiempo real** que cada técnico invierte trabajando en cada ticket. Este sistema registra automáticamente cuándo un técnico abre un ticket y cuánto tiempo permanece trabajando en él.

## ¿Por Qué es Importante?

### Beneficios del Seguimiento de Tiempo

✅ **Trazabilidad real**: Saber exactamente cuánto tiempo se invirtió en cada ticket  
✅ **Análisis de productividad**: Identificar qué tickets consumen más recursos  
✅ **Facturación precisa**: Cobrar a clientes basándose en tiempo real invertido  
✅ **Planificación mejorada**: Estimar mejor tiempos de resolución futuros  
✅ **Métricas de desempeño**: Evaluar eficiencia de técnicos objetivamente  

## ¿Cómo Funciona?

### 1. Inicio Automático de Sesión

Cuando un técnico, ingeniero, supervisor o administrador **abre un ticket** que está en estado "Abierto" o "En Progreso":

```
✅ El sistema AUTOMÁTICAMENTE:
├── Crea un registro de sesión de trabajo
├── Guarda la hora exacta de inicio
├── Comienza a contar el tiempo transcurrido
└── Muestra un cronómetro en tiempo real
```

**No requiere acción manual del técnico** - Es completamente automático.

### 2. Seguimiento en Tiempo Real

Mientras el técnico trabaja en el ticket:

```
⏱️ El sistema:
├── Muestra un cronómetro actualizado cada segundo
├── Envía "heartbeat" cada 30 segundos para mantener sesión activa
├── Registra el timestamp de la última actividad
└── Permite ver el tiempo transcurrido en la sesión actual
```

### 3. Cierre Automático de Sesión

La sesión se cierra automáticamente cuando:

```
🔒 Eventos que finalizan la sesión:
├── Usuario navega a otra página
├── Usuario cierra la pestaña del navegador
├── Usuario cierra el navegador
├── Sesión expira por inactividad
└── Usuario cierra sesión manualmente
```

El sistema calcula automáticamente la **duración total** en segundos.

### 4. Múltiples Sesiones

Un técnico puede abrir el mismo ticket **múltiples veces**:

```
Ticket #TK202510001:
├── Sesión 1: 30/10/2025 09:00 - 09:45 = 45 minutos
├── Sesión 2: 30/10/2025 14:00 - 14:30 = 30 minutos
├── Sesión 3: 31/10/2025 10:00 - 11:15 = 1h 15min
└── TOTAL: 2 horas 30 minutos
```

Cada sesión se registra por separado, pero el **tiempo total** se suma automáticamente.

## Interfaz de Usuario

### Vista del Ticket (Técnicos)

En la página de detalle del ticket, los técnicos ven:

#### Panel de "Tiempo de Trabajo"

```
╔══════════════════════════════════════╗
║  ⏰ Tiempo de Trabajo                ║
╠══════════════════════════════════════╣
║  Tiempo Total Invertido              ║
║  2h 30m                              ║
║                                      ║
║  ✅ Sesión activa                    ║
║  Iniciada: 10:00:00                  ║
║  Tiempo: 0h 15m 32s (en vivo)       ║
║                                      ║
║  ─────────────────────────           ║
║  Historial de Sesiones (3)          ║
║                                      ║
║  • Juan Pérez                        ║
║    30/10/2025 09:00 | 45m           ║
║                                      ║
║  • Juan Pérez                        ║
║    30/10/2025 14:00 | 30m           ║
║                                      ║
║  • Juan Pérez                        ║
║    31/10/2025 10:00 | 1h 15m        ║
╚══════════════════════════════════════╝
```

### Lista de Tickets

En la tabla de tickets, una nueva columna muestra el tiempo total:

| ID | Título | Prioridad | Estado | **Tiempo** | Fecha |
|----|--------|-----------|--------|------------|-------|
| TK001 | Error en login | Alta | En Progreso | **🕒 2h 30m** | 30/10 |
| TK002 | Actualizar logo | Media | Abierto | **🕒 45m** | 30/10 |
| TK003 | Bug en checkout | Crítica | Resuelto | **🕒 4h 15m** | 29/10 |

## Casos de Uso Reales

### Caso 1: Ticket Complejo

**Situación**: Un técnico necesita investigar un bug difícil de reproducir.

```
Día 1:
├── 09:00-09:30: Lectura inicial del ticket (30m)
├── 10:00-11:30: Investigación en logs (1h 30m)
└── 14:00-15:00: Pruebas de reproducción (1h)

Día 2:
├── 09:00-10:45: Desarrollo de fix (1h 45m)
└── 15:00-15:30: Testing y documentación (30m)

TOTAL REGISTRADO: 5h 15m
```

El sistema **suma automáticamente** todas las sesiones.

### Caso 2: Ticket con Múltiples Técnicos

**Situación**: Un ticket es escalado a un técnico senior.

```
Técnico Junior (María):
├── Sesión 1: 1h 30m (investigación inicial)
└── Total: 1h 30m

Técnico Senior (Carlos):
├── Sesión 1: 45m (revisión del trabajo de María)
├── Sesión 2: 2h 15m (resolución del problema)
└── Total: 3h

TIEMPO TOTAL DEL TICKET: 4h 30m
```

Cada técnico tiene su **tiempo individual registrado**, pero también se ve el **tiempo total** del ticket.

### Caso 3: Interrupciones

**Situación**: Un técnico es interrumpido por una llamada urgente.

```
Sesión del Ticket A:
├── 10:00: Abre ticket A (inicia cronómetro)
├── 10:45: Recibe llamada urgente, cierra pestaña
└── Sesión cerrada: 45 minutos registrados ✅

Sesión del Ticket B (urgente):
├── 10:45: Abre ticket B
├── 11:30: Resuelve ticket B
└── Sesión cerrada: 45 minutos registrados ✅

Regresa al Ticket A:
├── 14:00: Reabre ticket A (nueva sesión)
├── 15:30: Termina ticket A
└── Sesión cerrada: 1h 30m registrados ✅

TICKET A: 45m + 1h 30m = 2h 15m total ✅
TICKET B: 45m total ✅
```

El sistema **no cuenta tiempo inactivo**, solo sesiones activas.

## Datos Registrados

### Tabla: `ticket_work_sessions`

Cada sesión de trabajo registra:

| Campo | Descripción | Ejemplo |
|-------|-------------|---------|
| `ticket_id` | ID del ticket | 1 |
| `user_id` | ID del técnico | 5 |
| `started_at` | Hora de inicio | 2025-10-30 10:00:00 |
| `ended_at` | Hora de fin | 2025-10-30 10:45:00 |
| `duration_seconds` | Duración en segundos | 2700 (45 minutos) |
| `session_type` | Tipo de sesión | view, work, comment |
| `notes` | Notas opcionales | "Investigación de logs" |

## Funcionalidades Técnicas

### Heartbeat (Latido de Vida)

Para garantizar que la sesión se mantiene activa mientras el usuario trabaja:

```javascript
// Cada 30 segundos
sendHeartbeat() {
  POST /tickets/{id}/work-session/heartbeat
  → Responde con tiempo transcurrido
  → Actualiza timestamp de la sesión
}
```

Esto permite detectar si el usuario cerró el navegador inesperadamente.

### Cierre Confiable

Cuando el usuario sale del ticket:

```javascript
window.addEventListener('beforeunload', function() {
  // Usar sendBeacon para envío confiable
  navigator.sendBeacon('/tickets/{id}/work-session/end');
});
```

El navegador **garantiza** que el request se envía incluso si la pestaña se cierra inmediatamente.

## Reportes y Análisis

### Información Disponible

**Por Ticket:**
- Tiempo total invertido por todos los técnicos
- Número de sesiones de trabajo
- Lista de todos los técnicos que trabajaron
- Historial completo de sesiones con fechas

**Por Técnico:**
- Tiempo total trabajado en el día/semana/mes
- Tickets en los que trabajó
- Promedio de tiempo por ticket
- Distribución de tiempo entre tickets

**Por Proyecto:**
- Tiempo total invertido en el proyecto
- Tickets que consumieron más tiempo
- Técnicos más involucrados
- Ratio tiempo/ticket resuelto

## Casos de Uso para Administración

### 1. Facturación por Horas

```
Proyecto: Sistema de Inventario (Octubre 2025)

Tickets completados: 15
Tiempo total: 47h 30m
Tarifa: $50/hora
───────────────────────
TOTAL A FACTURAR: $2,375
```

### 2. Análisis de Eficiencia

```
Técnico: Juan Pérez (Octubre 2025)

Tickets resueltos: 23
Tiempo promedio: 2h 15m por ticket
Tiempo total: 51h 45m
───────────────────────
EFICIENCIA: 2.3 tickets/día
```

### 3. Identificación de Problemas

```
Ticket #TK202510015: "Error en pagos"
Prioridad: CRÍTICA
Tiempo invertido: 12h 30m ⚠️
Técnicos involucrados: 3
───────────────────────
ALERTA: Tiempo excesivo, requiere revisión
```

## Ventajas Competitivas

### Vs. Seguimiento Manual

❌ **Manual**: "¿Cuánto tiempo trabajaste en este ticket?"  
✅ **Automático**: El sistema sabe exactamente: 2h 37m

❌ **Manual**: Técnicos olvidan reportar tiempo  
✅ **Automático**: Cada sesión se registra automáticamente

❌ **Manual**: Datos estimados e inexactos  
✅ **Automático**: Precisión al segundo

### Vs. Otros Sistemas

✅ **No intrusivo**: No requiere "start timer" / "stop timer" manual  
✅ **Automático**: Funciona en segundo plano sin intervención  
✅ **Múltiples sesiones**: Suma automáticamente trabajo interrumpido  
✅ **Prueba auditada**: Registros con timestamps precisos  

## Próximas Mejoras

🔮 **Reportes Avanzados**
- Dashboard de tiempo por técnico/proyecto
- Gráficos de distribución de tiempo
- Exportar reportes a Excel/PDF

🔮 **Estimación Inteligente**
- Predecir tiempo de resolución basado en histórico
- "Tickets similares tomaron 2-3 horas"

🔮 **Alertas de Tiempo**
- Notificar si un ticket excede tiempo esperado
- "Este ticket lleva 5 horas, SLA es 4 horas"

🔮 **Integración con Facturación**
- Generar facturas automáticamente
- Exportar timesheet para clientes

## Configuración y Privacidad

### ¿Quién puede ver el tiempo de trabajo?

- **Técnicos**: Ven su propio tiempo y tiempo total del ticket
- **Supervisores**: Ven tiempo de todos los técnicos en sus proyectos
- **Administradores**: Ven todo el tiempo de todos
- **Clientes**: **NO** ven tiempo de trabajo (solo ven estados)

### Datos GDPR

El sistema registra:
- ✅ Quién trabajó (necesario para operación)
- ✅ Cuándo trabajó (necesario para operación)
- ✅ Cuánto tiempo (necesario para facturación)
- ❌ NO registra contenido de trabajo ni capturas de pantalla

## Conclusión

El **Sistema de Seguimiento Automático de Tiempo** transforma la gestión de tickets de un proceso basado en estimaciones a uno basado en **datos reales y verificables**.

**Resultado**: Mejor control de costos, facturación precisa, y métricas objetivas de desempeño.

---

**Implementado**: 30 de octubre de 2025  
**Versión**: 1.0  
**Estado**: ✅ Activo en producción  
**Tipo**: Seguimiento automático no intrusivo