# AllTasks Widget Plugin

Plugin para Leantime que agrega un widget administrativo de "Todas las Tareas" al dashboard, permitiendo supervisar todas las tareas de todos los usuarios con filtros avanzados.

## 📋 Descripción

Este plugin extiende el dashboard de Leantime con un widget especializado para administradores que muestra todas las tareas del sistema. A diferencia del widget "Mis Tareas" que solo muestra las tareas asignadas al usuario actual, este widget permite:

- **Supervisión global**: Ver todas las tareas de todos los usuarios en los proyectos del administrador
- **Filtrado multi-dimensional**: Por proyecto, usuario asignado y estado de tarea
- **Agrupación flexible**: Organizar tareas por usuario o por proyecto según necesidad
- **Actualización dinámica**: Filtros y agrupación interactivos sin recargar la página completa

### 🎯 Casos de Uso

- **Project Managers**: Supervisar el progreso de todos los miembros del equipo
- **Administradores**: Vista general de todas las tareas activas en el sistema
- **Scrum Masters**: Monitorear sprints y distribución de trabajo
- **Directores**: Seguimiento de múltiples proyectos simultáneamente

## ✨ Características

### Funcionalidades Principales
- ✅ **Acceso restringido**: Visible únicamente para usuarios con rol de administrador
- ✅ **Agrupación dual**: Por usuario (predeterminado) o por proyecto
- ✅ **Filtros dinámicos**: Actualización en tiempo real con HTMX
- ✅ **Cambio de estado**: Dropdown interactivo para actualizar el estado de tareas sin salir del widget
- ✅ **Información completa**: Usuario asignado, fecha de vencimiento, estado y prioridad
- ✅ **Multiidioma**: Soporte para Inglés y Español
- ✅ **Indicadores visuales**: Resaltado de tareas vencidas y estados por color
- ✅ **Límite distribuido**: Paginación inteligente entre múltiples proyectos
- ✅ **Persistencia**: Los filtros y agrupación se mantienen en la sesión
- ✅ **Recarga automática**: El widget se actualiza automáticamente al cambiar estados

### Opciones de Agrupación

#### 👥 Agrupación por Usuario (Predeterminado)
- Tareas organizadas por usuario asignado
- Muestra el nombre del proyecto en cada tarea
- Ideal para ver la carga de trabajo de cada miembro del equipo
- Usuarios sin tareas asignadas aparecen como "Unassigned"

#### 📁 Agrupación por Proyecto
- Tareas organizadas por proyecto
- Muestra el avatar del usuario asignado en cada tarea
- Ideal para seguimiento de progreso por proyecto
- Solo muestra proyectos abiertos del administrador

### Filtros Disponibles

#### 1. Filtro por Proyecto
- **Todos los Proyectos** (predeterminado): Muestra tareas de todos los proyectos asignados al administrador
- **Proyecto específico**: Filtra tareas de un solo proyecto
- Solo se muestran proyectos "abiertos" en los que el administrador participa

#### 2. Filtro por Usuario
- **Todos los Usuarios** (predeterminado): Muestra tareas de cualquier usuario
- **Usuario específico**: Filtra tareas asignadas a un usuario particular
- Incluye usuarios activos e inactivos del sistema

#### 3. Filtro por Estado
- **Tareas no Completadas** (predeterminado): Filtra tareas con estado diferente a "DONE"
- **Todos los Estados**: Muestra tareas en cualquier estado
- **Completadas**: Solo tareas marcadas como "DONE"
- Los estados se obtienen dinámicamente de cada proyecto

## 🚀 Instalación

### Prerequisitos
- Leantime v3.x o superior
- PHP 8.1 o superior
- Rol de administrador para usar el widget

### Instalación mediante CLI

```bash
php bin/leantime plugin:install leantime/alltasks
php bin/leantime plugin:enable leantime/alltasks
php bin/leantime plugin:list
```
### ⚠️ Importante: Case-Sensitivity en Linux

El plugin usa mayúsculas en su nombre (`AllTasks`) lo cual es importante en servidores Linux:

- ✅ **URL correcta**: `https://tu-servidor.com/hx/AllTasks/AllTasks/get`
- ❌ **URL incorrecta**: `https://tu-servidor.com/hx/alltasks/alltasks/get` (404 en Linux)

**Windows vs Linux:**
- En **Windows** (desarrollo local): Ambas URLs funcionan porque Windows ignora mayúsculas/minúsculas
- En **Linux** (producción): Solo la URL con mayúsculas correctas funcionará

Si obtienes error 404 en producción pero funciona en local, verifica que:
1. La carpeta del plugin se llame exactamente `AllTasks` (con A y T mayúsculas)
2. El archivo `register.php` tenga la URL correcta con mayúsculas
3. Los permisos permitan lectura: `chmod -R 755 app/Plugins/AllTasks`
### Verificación

1. Inicia sesión como administrador
2. Ve al dashboard (`/dashboard/home`)
3. Busca el widget "Todas las Tareas" / "All Tasks"
4. Agrégalo al dashboard desde el selector de widgets

## 📂 Estructura del Plugin

```
app/Plugins/AllTasks/
├── bootstrap.php                 # Bootstrap del plugin (requerido por Leantime)
├── composer.json                 # Metadatos y configuración del plugin
├── register.php                  # Registro del widget en el sistema de eventos
├── README.md                     # Esta documentación
├── Hxcontrollers/
│   └── AllTasks.php             # Controlador HTMX principal
├── Services/
│   └── AllTasks.php             # Servicio del plugin (install/uninstall)
├── Templates/
│   └── get.blade.php            # Vista Blade del widget
└── Language/
    ├── en-US.ini                # Traducciones en inglés
    └── es-ES.ini                # Traducciones en español
```

## 🔧 Arquitectura Técnica

### Flujo de Datos

```
1. Usuario aplica filtros o cambia agrupación en UI
        ↓
2. HTMX envía petición GET → /hx/AllTasks/AllTasks/get
        ↓
3. AllTasks Controller recibe parámetros:
   - projectFilter (ID o vacío)
   - userFilter (ID o vacío)  
   - statusFilter ('not_done', 'done', '')
   - groupBy ('user' o 'project')
        ↓
4. Controlador ejecuta flujo:
   a) Obtener proyectos del admin (ProjectService)
   b) Determinar proyectos efectivos (filtro aplicado)
   c) Por cada proyecto:
      - Obtener información del proyecto
      - Obtener status labels del proyecto
      - Consultar tareas (TicketService)
   d) Agrupar tareas según groupBy:
      - Por usuario: Agrupa por editorId
      - Por proyecto: Agrupa por projectId
   e) Contar total de tareas
        ↓
5. Renderizar vista Blade con datos
        ↓
6. HTMX reemplaza contenido en DOM
```

### Componentes Principales

#### 1. Controlador (Hxcontrollers/AllTasks.php)

**Responsabilidades:**
- Autenticación de administrador
- Gestión de parámetros de filtros
- Persistencia de filtros en sesión
- Obtención de datos desde servicios
- Distribución de límite de paginación entre proyectos
- Preparación de datos para la vista

**Servicios utilizados:**
- `AuthService`: Verificación de permisos
- `ProjectService`: Proyectos del administrador
- `TicketService`: Obtención de tareas y estados
- `UserService`: Lista de usuarios para filtros

**Optimización implementada (distribución de límite):**
```php
$perProjectLimit = !empty($projectFilter) 
    ? $params['limit'] 
    : (int)ceil($params['limit'] / count($effectiveProjectIds));
```

#### 2. Vista (Templates/get.blade.php)

**Componentes UI:**
- **Selector de agrupación**: Dropdown con opciones "Por Usuario" y "Por Proyecto"
- **Header con filtros**: Dropdown con 3 selectores (proyecto, usuario, estado)
- **Badge de filtros activos**: Contador visual de filtros aplicados
- **Lista agrupada**: Accordion por grupo (usuario o proyecto) con contador de tareas
- **Tarjetas de tareas**: Información completa de cada tarea
- **Dropdown de estado**: Selector interactivo para cambiar el estado de cualquier tarea
- **Estado vacío**: Mensaje cuando no hay tareas

**Renderizado Dinámico:**
- **Por Usuario**: Ícono `fa-user`, muestra nombre de proyecto en cada tarea
- **Por Proyecto**: Ícono `fa-folder`, muestra avatar de usuario en cada tarea

**Interactividad:**
- **Cambio de estado**: Dropdown con todos los estados disponibles del proyecto
- **Actualización automática**: Widget se recarga 500ms después de cambiar un estado
- **JavaScript nativo**: Integrado con `leantime.ticketsController.initStatusDropdown()`
- **Event delegation**: Listeners optimizados para evitar múltiples bindings

**Tecnologías:**
- **Blade**: Motor de plantillas de Laravel
- **HTMX**: Actualizaciones dinámicas sin JavaScript
- **Tailwind CSS**: Estilos modernos y responsivos
- **Font Awesome**: Iconografía

#### 3. Registro (register.php)

**Funciones:**
- Registra el namespace de vistas `alltasks`
- Registra archivos de idioma
- Hook en el evento `availableWidgets`
- Validación de rol de administrador
- Configuración de dimensiones del widget

**Evento utilizado:**
```php
EventDispatcher::add_filter_listener(
    'leantime.domain.widgets.services.widgets.__construct.availableWidgets',
    function ($widgets) { ... }
);
```

### Flujo de Filtros

#### Filtro por Proyecto

Sin filtro: se usan todos los proyectos del admin.  
Con filtro: se valida el acceso y se usa solo ese proyecto.

```php
$effectiveProjectIds = $userProjectIds;

if (!empty($projectFilter)) {
    if (in_array($projectFilter, $userProjectIds)) {
        $effectiveProjectIds = [$projectFilter];
    }
}
```

#### Filtro por Usuario

El filtro de usuario se pasa al searchCriteria:
- String vacío ('') → muestra todos los usuarios
- ID numérico → filtra por editorId o colaborador

```php
'users' => $userFilter,
```

#### Filtro por Estado

Opciones de filtro:
- `'not_done'` → tareas NO completadas (statusType !== 'DONE')
- `'done'` → tareas completadas (statusType === 'DONE')  
- `''` → todas las tareas sin filtro

**Importante**: Cada proyecto tiene sus propios status labels que se obtienen dinámicamente.

```php
$statusLabels[$projectId] = $ticketsService->getStatusLabels($projectId);
```

## 🛠️ Personalización

### Cambiar el Límite de Tareas

Edita `Hxcontrollers/AllTasks.php`, línea 24:
```php
private int $limit = 50;
```

### Agregar Más Idiomas

1. Crea un nuevo archivo en `Language/` (ejemplo: `fr-FR.ini` para francés):
```bash
Language/fr-FR.ini
```

2. Copia el contenido de `en-US.ini` y traduce

3. Registra en `register.php`:
```php
$registration->registerLanguageFiles(['en-US', 'es-ES', 'fr-FR']);
```

### Cambiar Permisos de Acceso

Edita `register.php`, línea 18. Por defecto solo los admins pueden ver el widget:
```php
if ($auth->userIsAtLeast('admin')) { ... }
```

Para permitir también a managers:
```php
if ($auth->userIsAtLeast('manager')) { ... }
```

Opciones disponibles: `'admin'`, `'manager'`, `'editor'`, `'member'`

### Modificar Posición del Widget

Edita `register.php`, líneas 24-27:
```php
'gridX' => 0,
'gridY' => 37,
'gridHeight' => 30,
'gridWidth' => 8,
```

Rangos: gridX y gridWidth (0-12), gridHeight ajusta altura, gridY ajusta posición vertical.

### Personalizar la Vista

Edita `Templates/get.blade.php`:

**Cambiar colores:**

Las clases de estado (`label-success`, `label-warning`, etc.) provienen de Leantime:

```blade
<span class="label {{ $statusLabels[$projectId][$ticket['status']]['class'] }}">
</span>
```

**Agregar campos adicionales:**
```blade
@if(!empty($ticket['storypoints']))
    <div class="story-points">
        <i class="fa fa-chart-bar"></i> {{ $ticket['storypoints'] }} pts
    </div>
@endif
```

## 🧪 Desarrollo

### Debugging

Habilita debug en `Hxcontrollers/AllTasks.php` agregando logs:
```php
public function get()
{
    error_log('Filters: ' . json_encode([
        'project' => $projectFilter,
        'user' => $userFilter,
        'status' => $statusFilter
    ]));
}
```

Logs en: `storage/logs/leantime.log`

### Testing

Casos de prueba sugeridos:

1. **Sin filtros** → debe mostrar todas las tareas de proyectos del admin
2. **Filtro proyecto** → solo tareas de ese proyecto
3. **Filtro usuario** → solo tareas del usuario
4. **Filtro 'not_done'** → sin tareas completadas
5. **Combinación de filtros** → respeta todos los filtros
6. **Usuario sin proyectos** → mensaje de "no tareas"
7. **Usuario no-admin** → mensaje de error de permisos

### Extensiones Sugeridas

1. **Export a CSV**: Agregar botón para exportar tareas filtradas
2. **Búsqueda por texto**: Filtro adicional por título/descripción
3. **Filtro por milestone**: Agrupar por hitos
4. **Gráficos**: Agregar estadísticas visuales
5. **Notificaciones**: Alertas de tareas vencidas

## 🐛 Troubleshooting

### El widget no aparece

**Causa**: Plugin no registrado correctamente

**Solución**:
```bash
php bin/leantime plugin:list
php bin/leantime plugin:enable leantime/alltasks
```

### "No tienes autorización para ver todas las tareas"

**Causa**: Usuario no tiene rol de administrador

**Solución**: Verificar rol en base de datos. Los roles deben ser >= 40 para admin:
```sql
SELECT username, role FROM zp_user WHERE id = [USER_ID];
```

### Filtros no funcionan

**Causa**: Sesión no persiste o HTMX no se ejecuta

**Solución**:
1. Revisar consola del navegador (F12) para errores JavaScript
2. Verificar que HTMX esté cargado: `typeof htmx !== 'undefined'`
3. Limpiar caché del navegador

### Tareas no se filtran correctamente

**Causa**: Status labels no coinciden entre proyectos

**Solución**: El plugin obtiene status labels por proyecto. Verificar que cada proyecto tenga configurados sus estados en Configuración → Estados del proyecto.

## 📊 Rendimiento

### Optimizaciones Implementadas

1. **Límite distribuido**: Evita que proyectos grandes acaparen todas las consultas
2. **Consultas por proyecto**: Cada proyecto se consulta individualmente con su propio contexto
3. **Status labels cacheados**: Se obtienen una vez por proyecto
4. **Lazy loading**: Solo se cargan proyectos visibles para el admin

### Métricas Aproximadas

- **Tiempo de carga**: ~200-500ms (dependiendo de cantidad de proyectos)
- **Consultas a BD**: N+1 (N = proyectos filtrados)
- **Memoria**: ~5-10MB (50 tareas típico)

### Escalabilidad

Para instalaciones con **100+ proyectos activos**, considera:
1. Aumentar el límite de tiempo de PHP: `max_execution_time = 60`
2. Implementar caché de proyectos del usuario
3. Agregar índices a las tablas: `zp_tickets(projectId, status)`, `zp_relationuserproject(userId, projectId)`

## 🔒 Seguridad

- ✅ Validación de rol de administrador en cada petición
- ✅ Filtrado de proyectos basado en asignación real del usuario
- ✅ Sin exposición de datos de proyectos no asignados
- ✅ Parámetros sanitizados por Leantime framework
- ✅ Sin inyección SQL (uso de ORM/Query Builder)

## 📄 Licencia

MIT License - Libre para uso y modificación

## 👨‍💻 Autor

Desarrollado como extensión personalizada para Leantime

## 🔗 Referencias

- [Documentación de Leantime](https://docs.leantime.io/)
- [Sistema de Plugins de Leantime](https://docs.leantime.io/plugins/)
- [HTMX Documentation](https://htmx.org/docs/)
- [Blade Templates](https://laravel.com/docs/blade)

---

**Nota**: Este plugin no modifica el código base de Leantime ni la base de datos, por lo que es seguro para actualizaciones futuras del sistema.
