# Johdanto

Queuety on WordPress-lisäosa, joka tarjoaa nopean työjonon, pysyvän työnkulkujärjestelmän ja pysyvän tilakoneympäristön. Työntekijät varaavat työt suoraan kohteesta MySQL ja käsittelevät ne pitkäkestoisessa WP-CLI-prosessissa. PHP-ympäristö, joka lataa WordPress ja WP-CLI, tarvitsee joko `mysqli` tai `pdo_mysql`.

## Miksi Queuety?

WordPress-järjestelmässä ei ole varsinaista taustatyöjärjestelmää. `wp_cron` käynnistyy vain sivukäyntien yhteydessä. Action Schedulerin oletusajuri toimii WP-Cron- ja loopback-HTTP-pyyntöjen varassa, ja käsittelee erissä enintään 30 sekuntia kerrallaan. 60 sekuntia kestävä LLM-API-kutsu päättyy PHP:n 30 sekunnin aikakatkaisuun. Monivaiheisia prosesseja ei voi suorittaa niin, että ne selviäisivät kaatumisista ja jatkaisivat siitä, mihin jäivät.

Queuety ratkaisee tämän kolmella perusrakenteella:

1. **Työt** taustatyöhön, joka suoritetaan ilman odotusta
2. **Työnkulut** pysyviin, monivaiheisiin prosesseihin
3. **Tilakoneet** pitkäkestoisten, tapahtumaohjattujen elinkaaritilojen mallintamiseen

## Pikaesimerkki

Lähetä työ suoritettavaksi nykyaikaisella API-tavalla:

```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!' );
```

Tai käytä perinteistä käsittelijänimen määrittelyä:

```php
use Queuety\Queuety;

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

Suorita pysyvä työnkulku:

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

Mallinna pitkäkestoinen istunto tilakoneella:

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

Käynnistä työntekijä:

```bash
wp queuety work
```

Jos rakennat agenttityyppistä järjestelmää, aloita [Agenttien orkestroinnista](https://queuety.inline0.dev/fi/docs/workflows/agent-orchestration). Siinä näytetään, miten suunnittelija- ja suorittajavirrat, ihmisen tekemän tarkistuksen vaiheet ja työnkulkujen väliset odotukset toimivat yhdessä.

Jos järjestelmä on tapahtumaohjattu ja pitkäikäinen, tutustu ensin [Tilakoneisiin](https://queuety.inline0.dev/fi/docs/state-machines) työnkulkujen rinnalla.

Jos haluat esimerkkejä päästä päähän -integraatioista, katso [Esimerkit](https://queuety.inline0.dev/fi/docs/examples). Niihin sisältyy nyt Neuron-pohjaisia malleja palveluntarjoajan vaihtamiseen, suoratoistoon, muistia hyödyntäviin tarkistusten uusintoihin ja riippuvaisiin työnkulkuihin.

Jos haluat käynnistää työnkulkuja WordPress-toimialuetapahtumista, kuten `save_post`, katso [Toimintojen käynnistimet](https://queuety.inline0.dev/fi/docs/features/action-triggers).

Jos haluat käyttää tietokantapohjaista suoritusympäristöä WordPressn ulkopuolella, katso [Itsenäinen käyttö](https://queuety.inline0.dev/fi/docs/features/standalone-use).

## Keskeiset erot

- **Nopea suoritus.** Työntekijät käyttävät jonoa suoraan kohteesta MySQL ja välttävät pyyntökohtaisen cron-mallin, joka hidastaa taustatyötä kohteessa WordPress.
- **Pysyvät työnkulut.** Monivaiheiset prosessit, joiden pysyvä tila säilyy PHP-aikakatkaisujen, kaatumisten ja uudelleenyritysten yli. Jokainen vaiheraja on atominen MySQL-tapahtuma.
- **Eksplisiittiset tilakoneet.** Mallinna keskusteluistuntoja, hyväksyntöjä ja muita pitkäkestoisia elinkaaria nimetyillä tiloilla, vartioiduilla siirtymillä, jonotetuilla tilaan siirtymisen toiminnoilla ja pysyvillä tapahtuma-aikajanoilla.
- **Nykyaikainen työn lähetys API.** Itsenäiset työluokat, joissa on `Dispatchable`-ominaisuus, tyypitetyt konstruktoriominaisuudet hyötykuormana sekä luokassa määritellyt `$tries`/`$timeout`/`$backoff`. `readonly`-luokka ei voi antaa näille ominaisuuksille oletusarvoja, joten määritä ne tavallisessa luokassa readonly-merkityillä ylennetyillä konstruktoriominaisuuksilla.
- **Väliohjelmistoputki.** Kerrosmallinen väliohjelmisto nopeusrajoitukseen, poikkeusten rajoittamiseen, yksilöllisiin töihin ja mukautettuun logiikkaan. Määritetään työkohtaisesti `middleware()`-metodilla.
- **Suoratoistovaiheet.** `StreamingStep`-rajapinta tuottaa osia, jotka tallennetaan heti tietokantaan. Uudelleenyrityksen yhteydessä aiemmin tallennetut osat annetaan, jotta suoratoistoa voidaan jatkaa keskeytyskohdasta. Ihanteellinen LLM-vastauksille ja suurille latauksille.
- **Liitettävä välimuistikerros.** `CacheFactory` tunnistaa automaattisesti APCu:n tai käyttää muistissa olevaa välimuistia. Mukautetut taustajärjestelmät toteuttavat `Contracts\Cache`-rajapinnan. Tätä käytetään sisäisesti nopeusrajoittimen hakuihin ja jonotilaan.
- **Eräkäsittely ja ketjutus.** Lähetä työryhmiä `then`/`catch`/`finally`-takaisinkutsuilla ja edistymisen seurannalla tai ketjuta työt niin, että kukin riippuu edellisen valmistumisesta.
- **Pysyvät viiveet ja odotukset.** `delay()` lisää prosessin uudelleenkäynnistyksistä selviävät viiveet. `wait_for_signal()`, `wait_for_signals()`, `wait_for_approval()`, `wait_for_input()` ja `wait_for_workflow()` antavat työnkulkujen odottaa ulkoisia tapahtumia tai muita työnkulkuja pitämättä PHP-prosessia käynnissä.
- **Dynaaminen for-each.** `for_each()` laajentaa ajon aikana työnkulun tilasta löytyvät haaratöiksi ja tukee kaikkien onnistumista, ensimmäistä onnistumista ja kiintiön täyttymistä odottavia suoritustiloja.
- **Asynkroniset työnkulun siirrot.** `start_workflows()` muuntaa ajon aikana löytyvät kohteet itsenäisiksi ylimmän tason työnkuluiksi, joita voi odottaa myöhemmin.
- **WordPress-toimintojen käynnistimet.** `on_action()` yhdistää ytimen tai lisäosan toimintokoukut pysyvien työnkulkujen lähetyksiin ja sisältää portitusehdot sekä idempotenssin.
- **Pysyvät artefaktit.** Tallenna nimetyt työnkulun tulosteet päätilasäiliön ulkopuolelle ja sisällytä ne tila-, CLI-tarkastelu-, vienti- ja toistotoimintoihin.
- **Työnkulkujen suojamekanismit.** `version()`, deterministinen määritelmän tiiviste, idempotentit lähetysavaimet ja työnkulkujen budjetit tekevät agenttityyppisten suoritusten tarkastelusta helpompaa ja vähentävät niiden toistumisen tai huomaamattoman hallitsemattoman jatkumisen riskiä.
- **Resurssienhallinta.** Samanaikaisuusryhmät, kustannusyksiköt, työnkulkubudjetit ja työntekijöiden hyväksyntä auttavat pitämään kalliit agenttityyppiset työt määritellyissä rajoissa.
- **Vaiheiden kompensointi.** `compensate_with()` ja `compensate_on_failure()` tarjoavat valmistuneiden vaiheiden palautuskoukut työnkulkujen peruuntuessa tai epäonnistuessa.
- **Sykesignaalit.** Pitkäkestoiset vaiheet lähettävät sykesignaaleja, jotta vanhentuneiden töiden palautusjärjestelmä ei varaa aktiivisia töitä uudelleen.
- **Työnkulkujen jäljitys.** Jokainen vaihesiirtymä tallennetaan syötteineen, tuloksineen, edeltävine ja seuraavine tiloineen, asiayhteyksineen, artefakteineen, osineen ja virheineen. Aikamatkavirheenkorjaus käyttää toimintoa `workflow_state_at()`.
- **Rinnakkaiset vaiheet.** Suorita vaiheet samanaikaisesti ja odota kaikkien valmistumista ennen etenemistä.
- **Ehdollinen haarautuminen.** Siirry nimettyihin vaiheisiin aiemman tilan perusteella käyttämällä toimintoa `_next_step`.
- **Työnkulkujen suorittaminen.** Käynnistä alityönkulkuja, jotka palauttavat tulokset päätyönkululle.
- **Prioriteettijonot.** Neljä tasoa (Low, Normal, High, Urgent) tyypiturvallisten PHP-enumeraatioiden avulla.
- **Monijonotyöntekijät.** Käsittele useita jonoja yhdessä työntekijässä tiukassa prioriteettijärjestyksessä.
- **Nopeusrajoitus.** Käsittelijäkohtaiset suorituksen rajat liukuvalla ikkunalla.
- **Toistuvat työt.** Väliin ja cron-pohjaiseen aikataulutukseen mukautettavilla päällekkäisyyskäytännöillä (Allow, Skip, Buffer).
- **Työnkulkujen peruutus.** Peru käynnissä olevia työnkulkuja ja käynnistä rekisteröidyt siivouskäsittelijät.
- **Tilan karsinta.** Poista vanhoja vaihetuloksia automaattisesti, jotta suurten työnkulkujen tilat pysyvät hallittavina.
- **Työntekijöiden rinnakkaisuus.** `--workers=N` käynnistää useita prosesseja ja käynnistää kaatuneen prosessin automaattisesti uudelleen.
- **Kattava havainnointi.** Tietokantalokit, käsittelijäkohtaiset mittarit ja tapahtumien webhookit.
- **Testausapuohjelmat.** `QueueFake` tallentaa lähetetyt työt ja erät yksikkötestien väittämiä varten.
- **PHP-attribuutit.** `#[QueuetyHandler('name')]` käsittelijöiden rekisteröintiin ilman määrityksiä.

## Näin se toimii

Työntekijät toimivat pitkäkestoisessa WP-CLI-prosessissa ja varaavat työt suoraan kohteesta MySQL. Jonorivit, työnkulkujen tila, lokit, erät, signaalit ja suoratoiston osat sijaitsevat kaikki kohteessa MySQL, joten työntekijöiden uudelleenkäynnistykset eivät kadota orkestroinnin tilaa.

Työnkulut jakavat pitkäkestoisen työn vaiheisiin. Kunkin vaiheen tulos tallennetaan tietokannan yhteiseen tilasäiliöön. Jos PHP pysähtyy kesken vaiheen, työntekijä yrittää samaa vaihetta uudelleen aiemman tilan säilyessä. Vaiheraja on yksi MySQL-tapahtuma: tilan päivitys, työn valmistuminen ja seuraavan vaiheen jonotus tapahtuvat atomisesti.

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

## Vaatimukset

- PHP 8.2 tai uudempi
- WordPress 6.4 tai uudempi
- MySQL 8.0+ tai MariaDB 10.6+, koska työntekijät varaavat töitä käyttämällä toimintoa `SELECT ... FOR UPDATE SKIP LOCKED`
- `mysqli` tai `pdo_mysql` suoritusaikaansa, joka lataa WordPress ja WP-CLI, varten: PHP
- WP-CLI erillisten työntekijöiden suorittamiseen käyttäen toimintoa `wp queuety work`
- Työntekijäpooleja varten `pcntl`- ja `posix`-laajennukset PHP (`--workers`, `--min-workers`, `--max-workers`)

Katso asennusohjeet osiosta [Aloittaminen](https://queuety.inline0.dev/fi/docs/getting-started).