# Wprowadzenie

Queuety to wtyczka WordPress zapewniająca szybką kolejkę zadań, trwały silnik przepływów pracy i środowisko uruchomieniowe trwałych maszyn stanów. Procesy robocze pobierają zadania bezpośrednio z MySQL i przetwarzają je w długotrwałym procesie WP-CLI. Środowisko uruchomieniowe PHP, które ładuje WordPress i WP-CLI, wymaga `mysqli` lub `pdo_mysql`.

## Dlaczego Queuety?

WordPress nie ma prawdziwego systemu zadań działających w tle. `wp_cron` uruchamia się tylko podczas odwiedzin strony. Domyślny mechanizm Action Scheduler działa przez WP-Cron i żądania HTTP do tej samej witryny, przetwarzając każdorazowo partie przez maksymalnie 30 sekund. Wywołanie API LLM trwające 60 sekund zostaje przerwane przez limit czasu 30 sekund w PHP. Nie ma sposobu na uruchamianie procesów wieloetapowych, które przetrwają awarie i wznowią pracę od miejsca przerwania.

Queuety rozwiązuje ten problem za pomocą trzech podstawowych elementów:

1. **Zadania** do wykonywanej w tle pracy, której wyniku nie trzeba odbierać
2. **Przepływy pracy** do trwałych, wieloetapowych procesów ze stanem zachowywanym między uruchomieniami
3. **Maszyny stanów** do długotrwałych cykli życia sterowanych zdarzeniami

## Szybki przykład

Zleć zadanie przy użyciu nowoczesnego 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!' );
```

Możesz też użyć klasycznego podejścia z nazwą procedury obsługi:

```php
use Queuety\Queuety;

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

Uruchom trwały przepływ pracy:

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

Zamodeluj długotrwałą sesję za pomocą maszyny stanów:

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

Uruchom proces roboczy:

```bash
wp queuety work
```

Jeśli tworzysz system oparty na agentach, zacznij od [Orkiestracja agentów](https://queuety.inline0.dev/pl/docs/workflows/agent-orchestration). Pokazano tam, jak współdziałają przepływy planowania i wykonywania, punkty weryfikacji przez człowieka oraz oczekiwanie na inne przepływy pracy.

Jeśli system jest sterowany zdarzeniami i długotrwały, obok przepływów pracy zacznij od [Maszyn stanów](https://queuety.inline0.dev/pl/docs/state-machines).

Jeśli szukasz przykładów integracji od początku do końca, zobacz [Przykłady](https://queuety.inline0.dev/pl/docs/examples), które obejmują teraz wzorce oparte na Neuron do przełączania dostawców, przesyłania strumieniowego, ponawiania weryfikacji z wykorzystaniem pamięci oraz zależnych przepływów pracy.

Jeśli chcesz uruchamiać przepływy pracy na podstawie zdarzeń domenowych WordPress, takich jak `save_post`, zobacz [Wyzwalacze akcji](https://queuety.inline0.dev/pl/docs/features/action-triggers).

Jeśli chcesz używać środowiska uruchomieniowego opartego na bazie danych poza WordPress, zobacz [Użycie samodzielne](https://queuety.inline0.dev/pl/docs/features/standalone-use).

## Najważniejsze wyróżniki

- **Szybkie wykonywanie.** Procesy robocze uzyskują bezpośredni dostęp do kolejki MySQL i unikają wzorca cron dla każdego żądania, który spowalnia pracę w tle w WordPress.
- **Trwałe przepływy pracy.** Procesy wieloetapowe ze stanem zachowywanym między uruchomieniami, odporne na przekroczenia limitu czasu PHP, awarie i ponowienia. Granica każdego kroku jest atomową transakcją MySQL.
- **Jawne maszyny stanów.** Modeluj sesje czatu, zatwierdzenia i inne długotrwałe cykle życia za pomocą nazwanych stanów, kontrolowanych przejść, kolejkowanych działań przy wejściu w stan oraz trwałych osi czasu zdarzeń.
- **Nowoczesne zlecanie API.** Samodzielne klasy zadań z cechą `Dispatchable`, typowanymi właściwościami konstruktora jako danymi oraz deklarowanymi w klasie elementami `$tries`/`$timeout`/`$backoff`. Klasa `readonly` nie może ustawiać wartości domyślnych tych właściwości, dlatego zadeklaruj je w zwykłej klasie za pomocą promowanych właściwości konstruktora tylko do odczytu.
- **Potok oprogramowania pośredniczącego.** Oprogramowanie pośredniczące o strukturze cebuli do ograniczania liczby żądań, łagodzenia skutków wyjątków, unikalnych zadań i własnej logiki. Deklarowane dla każdego zadania za pomocą metody `middleware()`.
- **Kroki strumieniowe.** Interfejs `StreamingStep` zwraca fragmenty, które są natychmiast zapisywane w bazie danych. Przy ponowieniu udostępniane są wcześniej zapisane fragmenty, aby strumień mógł wznowić pracę od miejsca przerwania. Idealne rozwiązanie dla odpowiedzi LLM i dużych pobrań.
- **Rozszerzalna warstwa pamięci podręcznej.** `CacheFactory` automatycznie wykrywa APCu albo przechodzi na pamięć podręczną w pamięci operacyjnej. Własne mechanizmy przechowywania danych implementują `Contracts\Cache`. Warstwa służy wewnętrznie do sprawdzania limitów żądań i stanu kolejki.
- **Przetwarzanie partiami i łączenie zadań.** Zlecaj grupy zadań z funkcjami zwrotnymi `then`/`catch`/`finally` i śledzeniem postępu albo łącz zadania sekwencyjnie, tak aby każde zależało od ukończenia poprzedniego.
- **Trwałe opóźnienia i oczekiwanie.** `delay()` dodaje opóźnienia bezpieczne przy ponownym uruchomieniu procesu. `wait_for_signal()`, `wait_for_signals()`, `wait_for_approval()`, `wait_for_input()` i `wait_for_workflow()` pozwalają przepływom pracy czekać na zdarzenia zewnętrzne lub inne przepływy bez utrzymywania aktywnego procesu PHP.
- **Dynamiczna pętla for-each.** `for_each()` rozwija gałęzie pracy wykryte podczas wykonywania na podstawie stanu przepływu pracy i obsługuje tryby ukończenia po sukcesie wszystkich, pierwszym sukcesie lub osiągnięciu kworum.
- **Asynchroniczne przekazywanie przepływów pracy.** `start_workflows()` zamienia elementy wykryte podczas wykonywania w niezależne przepływy pracy najwyższego poziomu, na które można później czekać.
- **Wyzwalacze akcji WordPress.** `on_action()` mapuje główne lub wtyczkowe haki akcji na trwałe zlecenia przepływów pracy z kontrolą warunków i idempotencją.
- **Trwałe artefakty.** Przechowuj nazwane wyniki przepływu pracy poza głównym obiektem stanu i uwzględniaj je przy sprawdzaniu stanu, inspekcji CLI, eksporcie i odtwarzaniu.
- **Zabezpieczenia przepływów pracy.** `version()`, deterministyczny skrót definicji, klucze idempotencji zleceń i budżety przepływów pracy ułatwiają analizę przebiegów agentów oraz utrudniają ich powielanie i niekontrolowane działanie.
- **Zarządzanie zasobami.** Grupy współbieżności, jednostki kosztu, budżety przepływów pracy i przyjmowanie zadań przez procesy robocze pomagają utrzymać kosztowne operacje agentów w określonych granicach.
- **Kompensacja kroków.** `compensate_with()` i `compensate_on_failure()` udostępniają mechanizmy wycofywania ukończonych kroków, gdy przepływy pracy zostaną anulowane lub zakończą się niepowodzeniem.
- **Sygnały aktywności.** Długotrwałe kroki wysyłają sygnały aktywności, aby system odzyskiwania nieaktualnych zadań nie przejął aktywnej pracy.
- **Śledzenie przepływu pracy.** Każde przejście kroku jest zapisywane wraz z danymi wejściowymi i wyjściowymi, stanem przed i po zmianie, kontekstem, artefaktami, fragmentami, błędami oraz debugowaniem w czasie przez `workflow_state_at()`.
- **Kroki równoległe.** Uruchamiaj kroki jednocześnie i czekaj na ukończenie wszystkich przed przejściem dalej.
- **Rozgałęzianie warunkowe.** Pomijaj kroki i przechodź do nazwanych na podstawie wcześniejszego stanu za pomocą `_next_step`.
- **Uruchamianie przepływów pracy.** Uruchamiaj podrzędne przepływy pracy, które przekazują wyniki z powrotem do nadrzędnego.
- **Kolejki priorytetowe.** Cztery poziomy (Low, Normal, High, Urgent) za pomocą typowanych wyliczeń PHP.
- **Procesy robocze dla wielu kolejek.** Przetwarzaj wiele kolejek z zachowaniem ścisłej kolejności priorytetów w jednym procesie roboczym.
- **Ograniczanie liczby żądań.** Limity wykonywania dla każdej procedury obsługi w ruchomym oknie.
- **Zadania cykliczne.** Planowanie według interwałów i cron z konfigurowalnymi zasadami nakładania się (Allow, Skip, Buffer).
- **Anulowanie przepływu pracy.** Anuluj uruchomione przepływy pracy i wywołuj zarejestrowane procedury czyszczenia.
- **Przycinanie stanu.** Automatycznie usuwaj stare wyniki kroków, aby ułatwić zarządzanie dużym stanem przepływu pracy.
- **Współbieżność procesów roboczych.** `--workers=N` uruchamia wiele procesów z automatycznym ponownym uruchomieniem po awarii.
- **Pełna obserwowalność.** Rejestrowanie w bazie danych, metryki dla poszczególnych procedur obsługi i webhooki zdarzeń.
- **Narzędzia do testowania.** `QueueFake` rejestruje zlecone zadania i partie, aby umożliwić asercje w testach jednostkowych.
- **Atrybuty PHP.** `#[QueuetyHandler('name')]` umożliwia rejestrowanie procedur obsługi bez konfiguracji.

## Jak to działa

Procesy robocze działają w długotrwałym procesie WP-CLI i pobierają zadania bezpośrednio z MySQL. Wiersze kolejek, stan przepływów pracy, dzienniki, partie, sygnały i fragmenty strumieni znajdują się w MySQL, więc ponowne uruchomienie procesu roboczego nie powoduje utraty stanu orkiestracji.

Przepływy pracy dzielą długotrwałe zadania na kroki. Wynik każdego kroku jest zapisywany we wspólnym obiekcie stanu w bazie danych. Jeśli PHP zakończy działanie w trakcie kroku, proces roboczy ponowi ten krok z zachowaniem całego wcześniejszego stanu. Granica kroku jest pojedynczą transakcją MySQL: aktualizacja stanu, zakończenie zadania i dodanie następnego kroku do kolejki odbywają się atomowo.

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

## Wymagania

- PHP 8.2 lub nowszy
- WordPress 6.4 lub nowszy
- MySQL 8.0+ lub MariaDB 10.6+, ponieważ procesy robocze pobierają zadania za pomocą `SELECT ... FOR UPDATE SKIP LOCKED`
- `mysqli` lub `pdo_mysql` w środowisku uruchomieniowym PHP, które ładuje WordPress i WP-CLI
- WP-CLI do uruchamiania dedykowanych procesów roboczych za pomocą `wp queuety work`
- Rozszerzenia `pcntl` i `posix` PHP do pul procesów roboczych (`--workers`, `--min-workers`, `--max-workers`)

Instrukcję instalacji znajdziesz w sekcji [Pierwsze kroki](https://queuety.inline0.dev/pl/docs/getting-started).