# Introducción

Queuety es un plugin de WordPress que proporciona una cola de tareas rápida, un motor de flujos de trabajo duraderos y un entorno de ejecución de máquinas de estados duraderas. Los workers reclaman tareas directamente desde MySQL y las procesan en un proceso WP-CLI de larga duración. El entorno PHP que carga WordPress y WP-CLI necesita `mysqli` o `pdo_mysql`.

## ¿Por qué Queuety?

WordPress no tiene un sistema real de tareas en segundo plano. `wp_cron` solo se activa cuando se visitan páginas. El ejecutor predeterminado de Action Scheduler se basa en WP-Cron y en solicitudes HTTP de loopback, y cada una procesa lotes durante un máximo de 30 segundos. Una llamada a un API de LLM que tarda 60 segundos termina por el tiempo límite de 30 segundos de PHP. No hay forma de ejecutar procesos de varios pasos que sobrevivan a fallos y retomen desde donde se quedaron.

Queuety resuelve esto con tres primitivas:

1. **Tareas** para trabajos en segundo plano que se ejecutan sin esperar respuesta
2. **Flujos de trabajo** para procesos duraderos de varios pasos con estado persistente
3. **Máquinas de estados** para estados de ciclo de vida duraderos y basados en eventos

## Ejemplo rápido

Envíe una tarea con la clase moderna API:

```php
use Queuety\Contracts\Job;
use Queuety\Dispatchable;

readonly class SendEmailJob implements Job {
    use Dispatchable;

    public function __construct(
        public string $to,
        public string $subject,
        public string $body,
    ) {}

    public function handle(): void {
        wp_mail( $this->to, $this->subject, $this->body );
    }
}

SendEmailJob::dispatch( 'user@example.com', 'Welcome', 'Hello from Queuety!' );
```

O use el enfoque clásico basado en el nombre del controlador:

```php
use Queuety\Queuety;

Queuety::dispatch( 'send_email', [ 'to' => 'user@example.com' ] );
```

Ejecute un flujo de trabajo duradero:

```php
Queuety::workflow( 'generate_report' )
    ->then( FetchDataHandler::class )
    ->then( CallLLMHandler::class )
    ->then( FormatOutputHandler::class )
    ->dispatch( [ 'user_id' => 42 ] );
```

Modele una sesión de larga duración con una máquina de estados:

```php
use Queuety\Enums\StateMachineStatus;

Queuety::machine( 'agent_session' )
    ->state( 'awaiting_user' )
    ->on( 'user_message', 'planning' )
    ->state( 'planning' )
    ->action( PlanSessionAction::class )
    ->on( 'planned', 'completed' )
    ->state( 'completed', StateMachineStatus::Completed )
    ->dispatch( [ 'thread_id' => 42 ] );
```

Inicie un worker:

```bash
wp queuety work
```

Si está creando un sistema con agentes, empiece por [Agent Orchestration](https://queuety.inline0.dev/es/docs/workflows/agent-orchestration). Allí se explica cómo encajan los flujos de planificación y ejecución, los puntos de revisión humana y las esperas entre flujos de trabajo.

Si el sistema se basa en eventos y tiene una larga duración, empiece por [State Machines](https://queuety.inline0.dev/es/docs/state-machines) junto con los flujos de trabajo.

Si busca ejemplos de integración de extremo a extremo, consulte [Examples](https://queuety.inline0.dev/es/docs/examples), que ahora incluye patrones basados en Neuron para cambiar de proveedor, transmitir datos, repetir revisiones con memoria y gestionar flujos de trabajo dependientes.

Si quiere iniciar flujos de trabajo a partir de eventos de dominio de WordPress, como `save_post`, consulte [Action Triggers](https://queuety.inline0.dev/es/docs/features/action-triggers).

Si quiere usar el entorno de ejecución respaldado por la base de datos fuera de WordPress, consulte [Standalone Use](https://queuety.inline0.dev/es/docs/features/standalone-use).

## Diferencias clave

- **Ejecución rápida.** Los workers acceden directamente a la cola MySQL y evitan el patrón cron por solicitud que ralentiza el trabajo en segundo plano en WordPress.
- **Flujos de trabajo duraderos.** Procesos de varios pasos con estado persistente que sobreviven a los tiempos límite de PHP, los fallos y los reintentos. El límite de cada paso es una transacción atómica de MySQL.
- **Máquinas de estados explícitas.** Modele sesiones de chat, aprobaciones y otros ciclos de vida prolongados con estados con nombre, transiciones protegidas, acciones en cola al entrar en un estado y cronologías duraderas de eventos.
- **Envío moderno con API.** Clases de tareas autónomas con el trait `Dispatchable`, propiedades tipadas del constructor como carga útil y `$tries`/`$timeout`/`$backoff` declarados en la clase. Una clase `readonly` no puede asignar valores predeterminados a estas propiedades, así que declárelas en una clase normal con propiedades promovidas de solo lectura en el constructor.
- **Canalización de middleware.** Middleware en forma de cebolla para limitar la frecuencia, regular excepciones, gestionar tareas únicas y añadir lógica personalizada. Se declara por tarea mediante un método `middleware()`.
- **Pasos de transmisión.** La interfaz `StreamingStep` produce fragmentos que se guardan inmediatamente en la base de datos. Al reintentar, se proporcionan los fragmentos guardados para que la transmisión pueda reanudarse desde donde se quedó. Ideal para respuestas de LLM y descargas grandes.
- **Capa de caché conectable.** `CacheFactory` detecta automáticamente APCu o recurre a una caché en memoria. Los backends personalizados implementan `Contracts\Cache`. Se usa internamente para las consultas del limitador de frecuencia y el estado de la cola.
- **Lotes y cadenas.** Envíe grupos de tareas con funciones de retorno `then`/`catch`/`finally` y seguimiento del progreso, o encadene tareas secuencialmente, de modo que cada una dependa de que termine la anterior.
- **Retrasos y esperas duraderos.** `delay()` añade retrasos seguros ante el reinicio del proceso. `wait_for_signal()`, `wait_for_signals()`, `wait_for_approval()`, `wait_for_input()` y `wait_for_workflow()` permiten que los flujos de trabajo esperen eventos externos u otros flujos sin mantener activo PHP.
- **Bucle dinámico para cada elemento.** `for_each()` amplía el trabajo de ramas detectado durante la ejecución a partir del estado del flujo de trabajo y admite los modos de finalización cuando todas se completan correctamente, cuando se completa la primera o al alcanzar un quórum.
- **Transferencias asíncronas entre flujos de trabajo.** `start_workflows()` convierte elementos detectados durante la ejecución en flujos de trabajo independientes de nivel superior, a los que se puede esperar más adelante.
- **Activadores de acciones de WordPress.** `on_action()` asigna hooks de acciones del núcleo o de plugins a envíos de flujos de trabajo duraderos, con controles y garantías de idempotencia.
- **Artefactos duraderos.** Guarde resultados con nombre de los flujos de trabajo fuera del contenedor de estado principal y consérvelos en el estado, la inspección de CLI, la exportación y la reproducción.
- **Controles de seguridad para flujos de trabajo.** `version()`, un hash de definición determinista, claves de envío idempotentes y presupuestos para flujos de trabajo facilitan la inspección de ejecuciones con agentes y ayudan a evitar duplicados o que se prolonguen sin control.
- **Gestión de recursos.** Los grupos de concurrencia, las unidades de coste, los presupuestos de flujos de trabajo y la admisión de workers ayudan a mantener el trabajo costoso con agentes dentro de límites definidos.
- **Compensación de pasos.** `compensate_with()` y `compensate_on_failure()` proporcionan hooks de reversión para pasos completados cuando los flujos de trabajo se cancelan o fallan.
- **Señales de actividad.** Los pasos de larga duración envían señales para evitar que el sistema de recuperación de tareas obsoletas reclame trabajo activo.
- **Trazabilidad de flujos de trabajo.** Cada transición de paso se registra con la entrada, la salida, el estado anterior y posterior, el contexto, los artefactos, los fragmentos, los errores y la depuración temporal mediante `workflow_state_at()`.
- **Pasos paralelos.** Ejecute pasos simultáneamente y espere a que todos terminen antes de continuar.
- **Ramificación condicional.** Salte a pasos con nombre según el estado anterior mediante `_next_step`.
- **Ejecución de flujos de trabajo.** Inicie flujos de trabajo secundarios que devuelvan resultados al principal.
- **Colas prioritarias.** Cuatro niveles (baja, normal, alta y urgente) mediante enumeraciones PHP seguras en cuanto a tipos.
- **Workers con varias colas.** Procese varias colas con un orden estricto de prioridad en un solo worker.
- **Limitación de frecuencia.** Límites de ejecución por controlador con ventana deslizante.
- **Tareas recurrentes.** Programación basada en intervalos y cron con políticas de solapamiento configurables (permitir, omitir, almacenar en búfer).
- **Cancelación de flujos de trabajo.** Cancele flujos en ejecución y active los controladores de limpieza registrados.
- **Poda del estado.** Elimine automáticamente las salidas antiguas de los pasos para mantener manejable el estado de los flujos de trabajo grandes.
- **Concurrencia de workers.** `--workers=N` inicia varios procesos con reinicio automático en caso de fallo.
- **Observabilidad completa.** Registro en base de datos, métricas por controlador y webhooks de eventos.
- **Utilidades de prueba.** `QueueFake` registra las tareas y los lotes enviados para realizar aserciones en pruebas unitarias.
- **Atributos PHP.** `#[QueuetyHandler('name')]` para registrar controladores sin configuración.

## Cómo funciona

Los workers se ejecutan en un proceso WP-CLI de larga duración y reclaman tareas directamente desde MySQL. Las filas de cola, el estado de los flujos de trabajo, los registros, los lotes, las señales y los fragmentos transmitidos se almacenan en MySQL, por lo que los reinicios de workers no hacen perder el estado de orquestación.

Los flujos de trabajo dividen las tareas de larga duración en pasos. Cada paso guarda su resultado en un contenedor de estado compartido en la base de datos. Si PHP falla a mitad de un paso, el worker lo reintenta con todo el estado anterior intacto. El límite del paso es una única transacción de MySQL: la actualización del estado, la finalización de la tarea y la incorporación del siguiente paso a la cola ocurren de forma atómica.

```
Workflow: generate_report (3 steps)

Step 0: fetch_data     -> state: {user_data: {...}}
Step 1: call_llm       -> PHP dies -> retry -> state: {user_data: {...}, llm_response: "..."}
Step 2: format_output  -> state: {user_data: {...}, llm_response: "...", report_url: "/reports/42.pdf"}

Workflow: completed
```

## Requisitos

- PHP 8.2 o posterior
- WordPress 6.4 o posterior
- MySQL 8.0+ o MariaDB 10.6+, porque los workers reclaman tareas con `SELECT ... FOR UPDATE SKIP LOCKED`
- `mysqli` o `pdo_mysql` en el entorno PHP que carga WordPress y WP-CLI
- WP-CLI para ejecutar workers dedicados con `wp queuety work`
- Las extensiones `pcntl` y `posix` de PHP para pools de workers (`--workers`, `--min-workers`, `--max-workers`)

Consulte [Getting Started](https://queuety.inline0.dev/es/docs/getting-started) para la instalación.