# Gestión de tareas internas

Acceso: **Gestión de tareas** en el menú principal, independiente de Contabilidad y CRM. Ruta: `/admin/tareas-usuarios`.

Para cuentas cliente, debe estar seleccionado **Gestión de tareas** en **Módulos contratados**. Al desactivarlo se ocultan el menú y la campana, se bloquea el acceso a tareas y evidencias y se suspenden sus correos; los datos se conservan para una reactivación. Agregar el módulo al catálogo no lo contrata automáticamente para las cuentas existentes.

## Primer uso

1. Un administrador abre **Configuración por empresa** y designa supervisores adicionales, días de aviso y si las entregas requieren revisión. Los administradores ya supervisan las empresas a las que tienen acceso.
2. En **Supervisión → Ajustar capacidad**, registra las horas semanales disponibles de cada usuario. El valor inicial es 40 horas; cero representa ausencia de disponibilidad. Esta capacidad es global por usuario, entre todas sus empresas.
3. Usa **Nueva tarea** para indicar empresa, instrucciones, asignados, responsable principal, fechas y esfuerzo total estimado.
4. Cada asignado encuentra el trabajo en **Mis tareas**. Puede registrar avance, horas efectivamente trabajadas, bloqueos, comentarios y evidencias.
5. El supervisor consulta **Supervisión** y abre los indicadores para ver los pendientes concretos. **Tareas del equipo** permite buscar y filtrar por empresa, usuario, estado y vencimiento.

## Flujo de trabajo

- **Pendiente:** aún no se inicia, avance 0%.
- **En proceso:** trabajo iniciado, avance entre 0 y 99%.
- **Bloqueada:** exige explicar el impedimento y la ayuda necesaria.
- **En revisión:** ejecución terminada, avance 100%, pendiente de aceptación.
- **Completada:** registra fecha y usuario que confirma el cierre. Si la empresa exige revisión, debe hacerlo un supervisor que no forme parte de los asignados.
- **Cancelada:** solo el supervisor puede cancelar y debe registrar un motivo.

Las tareas cerradas conservan su historial y no se editan ni se eliminan. Para trabajo adicional se crea otra tarea. Los comentarios y evidencias pueden añadirse después del cierre.

Al registrar tiempo, se ingresan las horas de esa actualización, no el total acumulado. La tarea muestra el total registrado y el historial identifica quién lo registró. Si alguien actualiza una tarea mientras otro tiene abierto el formulario, se pide revisar la versión más reciente antes de guardar.

## Plantillas y repetición

Una plantilla pertenece a la cuenta y contiene hasta 50 tareas con instrucciones, horas estimadas, prioridad, repetición y pasos. No contiene fechas ni responsables concretos de los pasos. El formulario muestra dos columnas en pantallas medianas y grandes, y una en móviles. Las fechas y plazos guardados en plantillas antiguas ya no se usan al asignarlas.

El operario selecciona tareas y solicita aprobación para una empresa. Al aprobar, se crea una copia de cada tarea en **Tareas pendientes de configurar**, visible en el dashboard y en Gestión de tareas. Se conserva la definición solicitada aunque después cambie la plantilla. El responsable de configurar es el operario solicitante; los administradores de esa empresa también pueden completar la configuración.

**Asignar a empresas** permite al administrador elegir hasta 30 empresas y sus propios responsables. También genera tareas pendientes de configurar, sin una aprobación adicional. Si algún destino o asignado es inválido, no se crea ninguna copia. Reintentar la misma solicitud no duplica el grupo.

**Configurar tarea** abre el formulario completo: inicio, entrega interna, vencimiento ante el ente de control, avisos, repetición, grupo, horas, etiquetas, operarios asignados y responsables de cada paso. Se conservan nombre, instrucciones y pasos aprobados; se pueden añadir pasos y reorganizarlos. Cuando hay varias personas, cada paso debe tener un responsable de entre los asignados. El operario que configura debe permanecer entre los asignados; el administrador puede ajustar el equipo completo.

**Guardar y activar tarea** valida las fechas, el calendario laboral, las etiquetas, los responsables y el límite de 8 horas diarias antes de crear la tarea activa. La entrega interna y ambos plazos de aviso son obligatorios; las etiquetas pueden quedar vacías. Si la configuración falla o se cierra la ventana, la tarea sigue pendiente de configurar. Repetir el guardado no crea duplicados. Estas copias pendientes no consumen capacidad, no admiten cronómetros ni avances, y no generan vencimientos o correos de tareas activas. Los registros de aprobación, configuración y activación quedan en Auditoría. Las tareas que ya existían antes del cambio mantienen su programación.

Las tareas también pueden repetirse semanal o mensualmente **al completarse**. Se genera una sola sucesora desde el calendario anterior, incluso si quedó atrasado. No se saltan períodos. La repetición mensual conserva el día original; por ejemplo, 31 de enero → 28 de febrero → 31 de marzo. Antes de repetir, todos los asignados deben mantener su acceso activo a la empresa.

## Carga y vencimientos

La carga visible de los próximos siete días suma las horas pendientes de tareas abiertas cuyo inicio y vencimiento están dentro o antes de ese horizonte:

`horas estimadas × (1 − avance / 100) ÷ número de asignados`

Incluye atrasos; excluye canceladas y completadas. Las entregas en revisión se cuentan aparte, con cero horas pendientes de ejecución. Se muestra una ocupación porcentual respecto de la capacidad semanal y se señala sobrecarga cuando se excede. Si solo se supervisa parte de las empresas de una persona, se indica que puede tener otra carga no visible. No se revelan tareas de empresas fuera del alcance del supervisor.

Las fechas vencen al final del día, según la zona horaria configurada en la aplicación. El estado de plazo tiene texto además de color: en plazo, por vencer, vence hoy o vencida. La ventana de aviso se configura entre 1 y 30 días por empresa. Los indicadores de completadas y puntualidad consideran el historial disponible con los filtros elegidos; no representan un período mensual implícito.

## Permisos y evidencias

- Solo usuarios internos activos con acceso al panel y a la empresa. Los usuarios del portal de clientes están excluidos.
- El usuario asignado ve sus propias tareas; un supervisor ve todas las de las empresas que supervisa.
- Solo los administradores pueden nombrar supervisores o cambiar las reglas de empresa. Los supervisores pueden gestionar tareas, plantillas y capacidad.
- Se vuelve a comprobar el acceso al consultar, modificar, descargar evidencias y enviar un correo. Una relación de empresa incorrecta no concede acceso entre cuentas distintas.
- Archivos privados de hasta 10 MB: PDF, imágenes PNG/JPEG/WebP, TXT, CSV, XLSX y DOCX. Se descargan mediante una ruta autenticada; nunca se publican en el disco público.

## Operación técnica

La migración `2026_09_07_000001_create_internal_task_management.php` crea tablas separadas con prefijo `work_task`. No modifica datos contables ni tareas del CRM.

Los avisos se guardan en el módulo y aparecen en la campana de la barra superior, incluso mientras se trabaja en otro módulo. Al abrir un aviso se marca como leído. Los contadores se actualizan cada minuto.

Los correos se encolan en la conexión `database`, cola exclusiva `work-tasks`, después de confirmar la transacción. Se usa la configuración de correo de la empresa o la global del sistema. El envío tiene tres intentos y vuelve a comprobar destinatario, permiso y preferencia de empresa. Desactivar el correo no desactiva las notificaciones internas.

El comando `php artisan tareas:recordar-vencimientos` está registrado cada hora en Laravel. Genera como máximo un recordatorio diario por tarea y destinatario; no recuerda tareas cerradas. Laravel también programa el procesamiento de `work-tasks` cada minuto, de forma independiente a la cola de facturación.

**En el servidor:** ejecutar el programador de Laravel cada minuto (`php artisan schedule:run`, mediante cron o un servicio).

**En local (`APP_ENV=local`):** no se registran tareas automáticas en el programador de Laravel. El script de Windows también omite su ejecución automática en este entorno. Para ejecutar manualmente los recordatorios y procesar su cola cuando sea necesario: `powershell -File scripts/run-work-task-scheduler.ps1 -Manual`. También se pueden ejecutar los comandos Artisan individuales. La opción `-Manual` puede generar avisos y enviar correos pendientes.

**Alternativa para este Windows:** `scripts/install-work-task-scheduler.ps1` registra `SistemaGlobal-TareasInternas`. Ejecuta cada minuto el script `scripts/run-work-task-scheduler.ps1`, exclusivamente para recordatorios y la cola `work-tasks`. No ejecuta el resto del programador de Laravel. Funciona sin ventanas, con permisos limitados, mientras el usuario de Windows mantiene su sesión iniciada. No sirve como sustituto de un servicio de servidor que deba trabajar con la sesión cerrada. Los registros se guardan en `storage/logs/work-task-scheduler-AAAA-MM-DD.log`.

El instalador no modifica una tarea existente con otra configuración. Para validar el script sin procesar avisos: `powershell -File scripts/run-work-task-scheduler.ps1 -ValidateOnly`. Al desplegar en otro servidor hay que configurar allí una de las alternativas de ejecución, usando la ruta de PHP correspondiente.

Estado de esta instalación local al 07/09/2026: tablas instaladas y tarea de Windows registrada, **desactivada a la espera de autorización para iniciar el envío automático**. La revisión automática de acciones bloqueó la ejecución porque puede enviar información interna por correo. Las notificaciones dentro del módulo y el resto de funciones se pueden utilizar. No se enviaron correos de prueba a usuarios reales.

Comprobaciones sin enviar correos:

```text
php artisan schedule:list
php artisan migrate:status
php artisan queue:failed
php -d extension=pdo_sqlite vendor/phpunit/phpunit/phpunit tests/Feature/Work/WorkTasksTest.php
```

Las pruebas usan una base SQLite aislada y simulan correo y cola; no envían mensajes ni crean tareas en la base operativa.

## Eliminar plantillas

En **Plantillas de tareas**, los administradores pueden usar **Eliminar** y confirmar el nombre de la plantilla. El borrado solo se permite cuando no tiene empresa vinculada, tareas creadas, configuraciones, lotes de asignación ni solicitudes pendientes o aprobadas. Las solicitudes rechazadas conservan su historial. La condición se vuelve a comprobar al confirmar y la eliminación queda registrada en Auditoría.

## Vencimientos en el dashboard

El dashboard general y «Mi dashboard de trabajo» muestran «Mis vencimientos» con las fechas de los próximos 30 días y las ya vencidas. El operario ve sus tareas asignadas y los vencimientos del maestro de sus empresas; el administrador ve las tareas y empresas dentro de su alcance. Este listado reúne todas las empresas autorizadas aunque se esté trabajando en una empresa seleccionada.

- Verde: de 8 a 30 días. Amarillo: de 2 a 7 días. Rojo: mañana, hoy y vencidos.
- Se incluyen vencimiento de tarea, entrega interna, presentación cuando difiere del vencimiento y correcciones pendientes. Las tareas completadas o canceladas se excluyen.
- En el maestro se incluyen permisos activos que aplican, fechas de renta y anexo patrimonial, y campos de fecha cuya clave o nombre indica vencimiento, caducidad o expiración. Para otros permisos personalizados se utiliza el tipo «Permiso con vencimiento». No se consideran fechas históricas como constitución. Los campos vinculados a permisos no se duplican.
- Al entrar al panel aparece un modal con lo que vence hoy y lo vencido pendiente. Se muestra después de la selección obligatoria de empresa. «Entendido» lo cierra en esa sesión; vuelve al iniciar sesión, cambiar el día o cambiar la lista pendiente. Renovar la fecha, desactivar el permiso o completar/cancelar la tarea retira el vencimiento anterior. Los cambios sujetos a aprobación cuentan cuando se aprueban.
- Las fechas y colores se recalculan con días calendario de Ecuador (`America/Guayaquil`), al consultar la página y cada minuto mientras está abierta. No necesitan programador, cola ni correo y funcionan con las tareas automáticas locales desactivadas.