# Въведение

Queuety е плъгин WordPress, който осигурява бърза опашка за задачи, устойчив механизъм за работни процеси и среда за изпълнение на устойчиви автомати на състоянията. Работниците заемат задачи директно от MySQL и ги обработват в дълго работещ процес WP-CLI. Средата за изпълнение PHP, която зарежда WordPress и WP-CLI, изисква или `mysqli`, или `pdo_mysql`.

## Защо Queuety?

WordPress няма истинска система за фонови задачи. `wp_cron` се задейства само при посещения на страници. Стандартният изпълнител на Action Scheduler разчита на WP-Cron и циклични заявки HTTP, като всяка обработва пакети за не повече от 30 секунди. Обаждане към LLM чрез API, което отнема 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/bg/docs/workflows/agent-orchestration). Там е показано как работят заедно потоците с планиране и изпълнение, етапите за човешки преглед и изчакването между работни потоци.

Ако системата се управлява от събития и работи продължително, започнете с [Машини на състоянията](https://queuety.inline0.dev/bg/docs/state-machines) заедно с работните потоци.

За примери за интеграция от начало до край вижте [Примери](https://queuety.inline0.dev/bg/docs/examples), където вече са включени модели, базирани на Neuron, за смяна на доставчик, поточно предаване, повторни прегледи с памет и зависими работни потоци.

За да стартирате работни потоци от събития в домейна на WordPress, като `save_post`, вижте [Тригери за действия](https://queuety.inline0.dev/bg/docs/features/action-triggers).

За да използвате средата за изпълнение, базирана на DB, извън WordPress, вижте [Самостоятелна употреба](https://queuety.inline0.dev/bg/docs/features/standalone-use).

## Основни отличителни характеристики

- **Бързо изпълнение.** Работниците осъществяват директен достъп до опашката MySQL и избягват модела cron за всяка заявка, който забавя фоновата работа в WordPress.
- **Устойчиви работни потоци.** Многоетапни процеси със запазено състояние, които преживяват времевите ограничения PHP, сривовете и повторните опити. Границата на всяка стъпка е атомарна транзакция MySQL.
- **Явно дефинирани машини на състоянията.** Моделирайте чат сесии, одобрения и други дълготрайни жизнени цикли с именувани състояния, защитени преходи, поставяни в опашка действия при влизане в състояние и устойчиви времеви линии на събитията.
- **Модерно разпределяне на задачи API.** Самостоятелни класове за задачи с трейта `Dispatchable`, типизирани свойства на конструктора като полезен товар и `$tries`/`$timeout`/`$backoff`, декларирани в класа. Класът `readonly` не може да задава стойности по подразбиране за тези свойства, затова ги декларирайте в обикновен клас със свойства readonly, промотирани от конструктора.
- **Конвейер от междинен софтуер.** Междинен софтуер с onion архитектура за ограничаване на честотата, ограничаване на изключенията, уникални задачи и персонализирана логика. Декларира се за всяка задача чрез метод `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`
- Разширенията `pcntl` и `posix` PHP за пулове от работници (`--workers`, `--min-workers`, `--max-workers`)

За инсталиране вижте [Първи стъпки](https://queuety.inline0.dev/bg/docs/getting-started).