# Introducere

Queuety este un plugin WordPress care oferă o coadă rapidă de sarcini, un motor durabil pentru fluxuri de lucru și un runtime durabil pentru mașini de stări. Lucrătorii preiau sarcini direct din MySQL și le procesează într-un proces WP-CLI de lungă durată. Runtime-ul PHP care încarcă WordPress și WP-CLI are nevoie de `mysqli` sau de `pdo_mysql`.

## De ce Queuety?

WordPress nu are un sistem real de procesare a sarcinilor în fundal. `wp_cron` se declanșează doar la vizitarea paginilor. Executorul implicit al Action Scheduler rulează prin WP-Cron și solicitări HTTP de tip loopback, fiecare procesând loturi timp de cel mult 30 de secunde. Un apel API către un model LLM care durează 60 de secunde este oprit de limita de timp de 30 de secunde a PHP. Nu există nicio modalitate de a rula procese în mai mulți pași care să supraviețuiască blocărilor și să reia execuția de unde s-au oprit.

Queuety rezolvă această problemă cu trei primitive:

1. **Sarcini** pentru lucrări în fundal de tipul „lansează și uită”
2. **Fluxuri de lucru** pentru procese durabile cu mai mulți pași și stare persistentă
3. **Mașini de stări** pentru stări de ciclu de viață persistente, bazate pe evenimente

## Exemplu rapid

Lansați o sarcină folosind clasa modernă 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!' );
```

Sau folosiți metoda clasică cu numele gestionarului:

```php
use Queuety\Queuety;

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

Rulați un flux de lucru durabil:

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

Modelați o sesiune de lungă durată cu o mașină de stări:

```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 ] );
```

Porniți un lucrător:

```bash
wp queuety work
```

Dacă dezvoltați un sistem de tip agent, începeți cu [Orchestrarea agenților](https://queuety.inline0.dev/ro/docs/workflows/agent-orchestration). Acesta arată cum se îmbină fluxurile planificator/executor, punctele de verificare umană și așteptările dintre fluxurile de lucru.

Dacă sistemul este bazat pe evenimente și de lungă durată, începeți cu [Mașini de stări](https://queuety.inline0.dev/ro/docs/state-machines), alături de fluxurile de lucru.

Dacă doriți exemple de integrare cap-coadă, consultați [Exemple](https://queuety.inline0.dev/ro/docs/examples), care include acum modele bazate pe Neuron pentru comutarea furnizorilor, transmitere în flux, repetarea verificărilor cu memorie și fluxuri de lucru dependente.

Dacă doriți ca fluxurile de lucru să pornească de la evenimente de domeniu WordPress, precum `save_post`, consultați [Declanșatoare de acțiuni](https://queuety.inline0.dev/ro/docs/features/action-triggers).

Dacă doriți să folosiți runtime-ul susținut de baza de date în afara WordPress, consultați [Utilizare independentă](https://queuety.inline0.dev/ro/docs/features/standalone-use).

## Diferențiatori principali

- **Execuție rapidă.** Lucrătorii folosesc acces direct la coada MySQL și evită modelul cron per cerere, care încetinește lucrările în fundal în WordPress.
- **Fluxuri de lucru durabile.** Procese cu mai mulți pași și stare persistentă, care supraviețuiesc limitelor de timp PHP, avariilor și reîncercărilor. Fiecare limită dintre pași este o tranzacție MySQL atomică.
- **Mașini de stări explicite.** Modelați sesiunile de chat, aprobările și alte cicluri de viață de lungă durată cu stări denumite, tranziții protejate, acțiuni de intrare în stare puse în coadă și cronologii durabile ale evenimentelor.
- **Clasa modernă de lansare a sarcinilor API.** Clase de sarcini autonome, cu trăsătura `Dispatchable`, proprietăți tipizate în constructor folosite drept date utile și `$tries`/`$timeout`/`$backoff` declarate în clasă. O clasă `readonly` nu poate atribui valori implicite acestor proprietăți, așadar declarați-le într-o clasă obișnuită cu proprietăți promovate readonly în constructor.
- **Pipeline middleware.** Middleware în stil onion pentru limitarea ratei, reducerea frecvenței excepțiilor, sarcini unice și logică personalizată. Declarat per sarcină printr-o metodă `middleware()`.
- **Pași cu transmitere în flux.** Interfața `StreamingStep` generează segmente care sunt salvate imediat în baza de date. La reîncercare, sunt furnizate segmentele salvate anterior, astfel încât fluxul să poată continua de unde s-a oprit. Ideal pentru răspunsuri LLM și descărcări mari.
- **Strat de cache modular.** `CacheFactory` detectează automat APCu sau folosește un cache în memorie ca soluție de rezervă. Backend-urile personalizate implementează `Contracts\Cache`. Folosit intern pentru căutările limitatorului de rată și starea cozii.
- **Procesare în loturi și înlănțuire.** Lansați grupuri de sarcini cu funcții callback `then`/`catch`/`finally` și urmărirea progresului sau înlănțuiți sarcini secvențial, fiecare depinzând de finalizarea celei precedente.
- **Întârzieri și așteptări durabile.** `delay()` adaugă întârzieri sigure la repornirea procesului. `wait_for_signal()`, `wait_for_signals()`, `wait_for_approval()`, `wait_for_input()` și `wait_for_workflow()` permit fluxurilor de lucru să se oprească în așteptarea unor evenimente externe sau a altor fluxuri de lucru fără a menține activ PHP.
- **Iterare dinamică.** `for_each()` extinde lucrările pe ramuri descoperite în timpul execuției, pornind de la starea fluxului de lucru, și acceptă moduri de finalizare la succesul tuturor, la primul succes sau la atingerea cvorumului.
- **Transferuri asincrone între fluxuri de lucru.** `start_workflows()` transformă elementele descoperite în timpul execuției în fluxuri de lucru independente, de nivel superior, care pot fi așteptate ulterior.
- **Declanșatoare de acțiuni WordPress.** `on_action()` mapează hook-urile de acțiune din nucleu sau pluginuri la lansări durabile de fluxuri de lucru, cu condiții de activare și idempotență.
- **Artefacte durabile.** Stocați rezultate denumite ale fluxului de lucru în afara setului principal de stări și păstrați-le în operațiunile de stare, inspecție CLI, export și reluare.
- **Mecanisme de protecție pentru fluxurile de lucru.** `version()`, o sumă hash deterministă a definiției, chei de lansare idempotente și bugete pentru fluxuri de lucru fac rulările de tip agent mai ușor de inspectat și mai greu de duplicat sau de lăsat să continue necontrolat, fără să se observe.
- **Gestionarea resurselor.** Grupurile de concurență, unitățile de cost, bugetele fluxurilor de lucru și admiterea lucrătorilor ajută la menținerea lucrărilor costisitoare de tip agent în limite definite.
- **Compensarea pașilor.** `compensate_with()` și `compensate_on_failure()` oferă hook-uri de anulare pentru pașii finalizați, atunci când fluxurile de lucru sunt anulate sau eșuează.
- **Semnale de puls.** Pașii de lungă durată trimit semnale de puls pentru a împiedica sistemul de recuperare a sarcinilor blocate să preia lucrările active.
- **Urmărirea fluxurilor de lucru.** Fiecare tranziție de pas este înregistrată împreună cu intrarea, ieșirea, starea înainte/după, contextul, artefactele, segmentele, erorile și depanarea prin călătorie în timp folosind `workflow_state_at()`.
- **Pași paraleli.** Rulați pașii simultan și așteptați finalizarea tuturor înainte de a continua.
- **Ramificare condiționată.** Săriți la pași denumiți în funcție de starea anterioară, folosind `_next_step`.
- **Rularea fluxurilor de lucru.** Porniți fluxuri de lucru copil ale căror rezultate sunt transmise înapoi fluxului părinte.
- **Cozi prioritare.** Patru niveluri (Low, Normal, High, Urgent) prin enum-uri PHP sigure din punct de vedere al tipurilor.
- **Lucrători cu mai multe cozi.** Procesați mai multe cozi cu o ordine strictă a priorităților într-un singur lucrător.
- **Limitarea ratei.** Limite de execuție per gestionar, cu fereastră glisantă.
- **Sarcini recurente.** Programare pe intervale și bazată pe cron, cu politici configurabile pentru suprapunere (Allow, Skip, Buffer).
- **Anularea fluxurilor de lucru.** Anulați fluxurile de lucru în execuție și declanșați gestionarele de curățare înregistrate.
- **Reducerea stării.** Eliminați automat ieșirile vechi ale pașilor pentru a menține gestionabilă starea voluminoasă a fluxului de lucru.
- **Concurența lucrătorilor.** `--workers=N` bifurcă mai multe procese și le repornește automat după o avarie.
- **Observabilitate completă.** Înregistrare în baza de date, metrici per gestionar și webhook-uri pentru evenimente.
- **Utilitare de testare.** `QueueFake` înregistrează sarcinile și loturile lansate pentru aserțiuni în testele unitare.
- **Atribute PHP.** `#[QueuetyHandler('name')]` pentru înregistrarea gestionarilor fără configurare.

## Cum funcționează

Lucrătorii rulează într-un proces WP-CLI de lungă durată și preiau sarcini direct din MySQL. Rândurile cozilor, starea fluxurilor de lucru, jurnalele, loturile, semnalele și segmentele transmise în flux se află toate în MySQL, astfel încât repornirea lucrătorilor nu pierde starea de orchestrare.

Fluxurile de lucru împart lucrările de lungă durată în pași. Ieșirea fiecărui pas este salvată într-un set comun de stări din baza de date. Dacă PHP se oprește în mijlocul unui pas, lucrătorul reîncearcă pasul cu toată starea anterioară intactă. Limita dintre pași este o singură tranzacție MySQL: actualizarea stării, finalizarea sarcinii și adăugarea la coadă a pasului următor au loc atomic.

```
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
```

## Cerințe

- PHP 8.2 sau o versiune ulterioară
- WordPress 6.4 sau o versiune ulterioară
- MySQL 8.0+ sau MariaDB 10.6+, deoarece lucrătorii preiau sarcini cu `SELECT ... FOR UPDATE SKIP LOCKED`
- `mysqli` sau `pdo_mysql` în runtime-ul PHP care încarcă WordPress și WP-CLI
- WP-CLI pentru a rula lucrători dedicați cu `wp queuety work`
- Extensiile `pcntl` și `posix` PHP pentru pool-uri de lucrători (`--workers`, `--min-workers`, `--max-workers`)

Consultați [Noțiuni introductive](https://queuety.inline0.dev/ro/docs/getting-started) pentru instalare.