# Вступ

Queuety — це плагін WordPress зі швидкою чергою завдань, рушієм робочих процесів та середовищем виконання автоматів станів, які зберігають стан між запусками. Воркери отримують завдання безпосередньо з MySQL та обробляють їх у довготривалому процесі WP-CLI. Для середовища виконання PHP, що завантажує WordPress і WP-CLI, потрібен або `mysqli`, або `pdo_mysql`.

## Чому Queuety?

У WordPress немає повноцінної системи фонових завдань. `wp_cron` запускається лише під час відвідування сторінок. Стандартний виконавець Action Scheduler працює через WP-Cron і циклічні запити HTTP, що обробляють пакети не довше ніж 30 секунд. Виклик API для LLM, який триває 60 секунд, буде перервано через 30-секундний тайм-аут PHP. Немає способу запускати багатоетапні процеси, які переживають збої та продовжуються з місця зупинки.

Queuety вирішує цю проблему за допомогою трьох базових механізмів:

1. **Завдання** для фонової роботи без очікування відповіді
2. **Робочі процеси** для довготривалих багатоетапних процесів зі збереженням стану
3. **Автомати станів** для довготривалого стану життєвого циклу, яким керують події

## Короткий приклад

Поставте завдання в чергу за допомогою сучасного 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!' );
```

Або скористайтеся класичним підходом із назвою обробника:

```php
use Queuety\Queuety;

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

Запустіть довготривалий робочий процес:

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

Змоделюйте довготривалий сеанс за допомогою автомата станів:

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

Запустіть воркер:

```bash
wp queuety work
```

Якщо ви створюєте агентну систему, почніть із розділу [Оркестрація агентів](https://queuety.inline0.dev/uk/docs/workflows/agent-orchestration). У ньому показано, як взаємодіють потоки планування й виконання, етапи перевірки людиною та очікування між робочими процесами.

Якщо система керується подіями й працює довготривало, разом із робочими процесами ознайомтеся з розділом [Автомати станів](https://queuety.inline0.dev/uk/docs/state-machines).

Приклади інтеграції від початку до кінця див. у розділі [Приклади](https://queuety.inline0.dev/uk/docs/examples). Тепер він містить шаблони на основі Neuron для перемикання провайдерів, потокової обробки, повторних перевірок із використанням пам’яті та залежних робочих процесів.

Якщо ви хочете запускати робочі процеси на основі доменних подій WordPress, як-от `save_post`, див. розділ [Тригери дій](https://queuety.inline0.dev/uk/docs/features/action-triggers).

Якщо ви хочете використовувати середовище виконання з базою даних поза межами WordPress, див. розділ [Автономне використання](https://queuety.inline0.dev/uk/docs/features/standalone-use).

## Ключові відмінності

- **Швидке виконання.** Воркери мають прямий доступ до черги MySQL і уникають шаблону cron для кожного запиту, який уповільнює фонову роботу в WordPress.
- **Надійні робочі процеси.** Багатокрокові процеси зі збереженим станом, які витримують тайм-аути PHP, збої та повторні спроби. Межа кожного кроку — це атомарна транзакція MySQL.
- **Явні автомати станів.** Моделюйте сеанси чату, погодження та інші довготривалі життєві цикли за допомогою іменованих станів, переходів із перевірками, поставлених у чергу дій під час входу в стан і стійких часових шкал подій.
- **Сучасна диспетчеризація API.** Самодостатні класи завдань із трейтом `Dispatchable`, типізованими властивостями конструктора як даними завдання та `$tries`/`$timeout`/`$backoff`, оголошеними в класі. Клас `readonly` не може задавати значення за замовчуванням для цих властивостей, тож оголошуйте їх у звичайному класі з readonly promoted властивостями конструктора.
- **Конвеєр проміжного ПЗ.** Проміжне ПЗ у стилі цибулини для обмеження частоти запитів, гальмування винятків, унікальних завдань і власної логіки. Оголошується для кожного завдання через метод `middleware()`.
- **Потокові кроки.** Інтерфейс `StreamingStep` передає фрагменти, які одразу зберігаються в базі даних. Під час повторної спроби надаються раніше збережені фрагменти, щоб потік міг продовжитися з місця зупинки. Ідеально для відповідей LLM і великих завантажень.
- **Підключуваний рівень кешу.** `CacheFactory` автоматично виявляє APCu або використовує кеш у пам’яті як запасний варіант. Власні бекенди реалізують `Contracts\Cache`. Використовується всередині для пошуку даних обмежувача частоти запитів і стану черги.
- **Пакетна обробка та ланцюжки.** Диспетчеризуйте групи завдань із колбеками `then`/`catch`/`finally` і відстеженням прогресу або послідовно зв’язуйте завдання, щоб кожне залежало від завершення попереднього.
- **Стійкі затримки й очікування.** `delay()` додає затримки, безпечні до перезапуску процесу. `wait_for_signal()`, `wait_for_signals()`, `wait_for_approval()`, `wait_for_input()` і `wait_for_workflow()` дають змогу робочим процесам призупинятися в очікуванні зовнішніх подій або інших робочих процесів, не утримуючи PHP активним.
- **Динамічний for-each.** `for_each()` розгортає гілки роботи, виявлені під час виконання на основі стану робочого процесу, і підтримує режими завершення «усі успішно», «перший успішно» та «кворум».
- **Асинхронна передача керування робочими процесами.** `start_workflows()` перетворює виявлені під час виконання елементи на незалежні робочі процеси верхнього рівня, які можна очікувати пізніше.
- **Тригери дій WordPress.** `on_action()` перетворює хуки дій ядра або плагінів на диспетчеризацію стійких робочих процесів із перевірками умов і ідемпотентністю.
- **Стійкі артефакти.** Зберігайте іменовані результати робочих процесів поза основним сховищем стану та використовуйте їх під час перегляду статусу, CLI, експорту й відтворення.
- **Захисні механізми робочих процесів.** `version()`, детермінований хеш визначення, ключі ідемпотентної диспетчеризації та бюджети робочих процесів полегшують перегляд запусків у стилі агентів і зменшують ризик дублювання чи непомітного виходу за межі.
- **Керування ресурсами.** Групи паралельності, одиниці вартості, бюджети робочих процесів і допуск завдань воркером допомагають утримувати витратну роботу у стилі агентів у визначених межах.
- **Компенсація кроків.** `compensate_with()` і `compensate_on_failure()` надають хуки для відкату завершених кроків, коли робочі процеси скасовуються або завершуються помилкою.
- **Сигнали активності.** Довготривалі кроки надсилають сигнали активності, щоб система відновлення застарілих завдань не перехоплювала активну роботу.
- **Трасування робочих процесів.** Кожен перехід між кроками фіксується разом із вхідними та вихідними даними, станом до й після, контекстом, артефактами, фрагментами, помилками та налагодженням із переміщенням у часі через `workflow_state_at()`.
- **Паралельні кроки.** Виконуйте кроки одночасно й дочекайтеся їх усіх перед переходом далі.
- **Умовне розгалуження.** Переходьте до іменованих кроків на основі попереднього стану за допомогою `_next_step`.
- **Запуск робочих процесів.** Запускайте дочірні робочі процеси, результати яких повертаються батьківському.
- **Черги пріоритетів.** Чотири рівні (Low, Normal, High, Urgent) через типобезпечні переліки PHP.
- **Воркери з кількома чергами.** Обробляйте кілька черг із суворим порядком пріоритетів в одному воркері.
- **Обмеження частоти запитів.** Ліміти виконання для кожного обробника зі ковзним вікном.
- **Повторювані завдання.** Планування через інтервали та cron із налаштовуваними правилами перетину (Allow, Skip, Buffer).
- **Скасування робочих процесів.** Скасовуйте запущені робочі процеси та запускайте зареєстровані обробники очищення.
- **Очищення стану.** Автоматично видаляйте застарілі результати кроків, щоб спростити керування великим станом робочого процесу.
- **Паралельність воркерів.** `--workers=N` запускає кілька процесів із автоматичним перезапуском після збою.
- **Повна спостережуваність.** Журналювання в базі даних, метрики для кожного обробника та вебхуки подій.
- **Засоби тестування.** `QueueFake` записує диспетчеризовані завдання та пакети для перевірок в модульних тестах.
- **Атрибути PHP.** `#[QueuetyHandler('name')]` для реєстрації обробників без додаткового налаштування.

## Як це працює

Воркери працюють у довготривалому процесі WP-CLI і отримують завдання безпосередньо з MySQL. Рядки черги, стан робочих процесів, журнали, пакети, сигнали та потокові фрагменти зберігаються в MySQL, тому перезапуск воркерів не призводить до втрати стану оркестрації.

Робочі процеси розбивають тривалі завдання на кроки. Результат кожного кроку зберігається в спільному сховищі стану в базі даних. Якщо PHP завершується посеред кроку, воркер повторно виконує цей крок із незмінним попереднім станом. Межа кроку — це одна транзакція MySQL: оновлення стану, завершення завдання та додавання наступного кроку до черги відбуваються атомарно.

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

## Вимоги

- PHP 8.2 або новіша версія
- WordPress 6.4 або новіша версія
- MySQL 8.0+ або MariaDB 10.6+, оскільки воркери отримують завдання за допомогою `SELECT ... FOR UPDATE SKIP LOCKED`
- `mysqli` або `pdo_mysql` у середовищі виконання PHP, яке завантажує WordPress і WP-CLI
- WP-CLI для запуску виділених воркерів із `wp queuety work`
- Розширення PHP `pcntl` і `posix` для пулів воркерів (`--workers`, `--min-workers`, `--max-workers`)

Щоб установити, див. [Початок роботи](https://queuety.inline0.dev/uk/docs/getting-started).