# Giriş

Queuety, hızlı bir iş kuyruğu, kalıcı iş akışı altyapısı ve kalıcı durum makinesi çalışma zamanı sağlayan bir WordPress eklentisidir. Çalışanlar işleri doğrudan MySQL üzerinden alır ve uzun süre çalışan bir WP-CLI sürecinde işler. WordPress ve WP-CLI öğelerini yükleyen PHP çalışma zamanı için `mysqli` veya `pdo_mysql` gerekir.

## Queuety neden?

WordPress gerçek bir arka plan işi sistemine sahip değildir. `wp_cron` yalnızca sayfa ziyaretlerinde tetiklenir. Action Scheduler varsayılan çalıştırıcısı WP-Cron ve döngüsel HTTP istekleri üzerinden çalışır; her biri en fazla 30 saniye boyunca toplu işleri işler. 60 saniye süren bir LLM API çağrısı, PHP için belirlenen 30 saniyelik zaman aşımında sonlandırılır. Çökmelerden etkilenmeden kalıp kaldığı yerden devam eden çok adımlı süreçleri çalıştırmanın bir yolu yoktur.

Queuety bunu üç temel yapı taşıyla çözer:

1. **İşler**: Başlatılıp arka planda unutulan işler
2. **İş akışları**: Kalıcı durumlu, dayanıklı çok adımlı süreçler
3. **Durum makineleri**: Uzun ömürlü, olay odaklı yaşam döngüsü durumu

## Hızlı örnek

Modern API kullanarak bir iş dağıtın:

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

Ya da klasik işleyici adı yöntemini kullanın:

```php
use Queuety\Queuety;

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

Kalıcı bir iş akışı çalıştırın:

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

Durum makinesiyle uzun ömürlü bir oturumu modelleyin:

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

Bir çalışan başlatın:

```bash
wp queuety work
```

Bir ajan tarzı sistem geliştiriyorsanız [Ajan Orkestrasyonu](https://queuety.inline0.dev/tr/docs/workflows/agent-orchestration) ile başlayın. Planlayıcı/yürütücü akışlarının, insan incelemesi aşamalarının ve iş akışları arası beklemelerin nasıl bir araya geldiğini gösterir.

Sistem olay odaklı ve uzun ömürlüyse iş akışlarının yanı sıra [Durum Makineleri](https://queuety.inline0.dev/tr/docs/state-machines) ile başlayın.

Uçtan uca entegrasyon örnekleri için [Örnekler](https://queuety.inline0.dev/tr/docs/examples) sayfasına bakın. Bu sayfada artık sağlayıcı değiştirme, akış, bellek destekli inceleme tekrarları ve bağımlı iş akışları için Neuron tabanlı örüntüler bulunuyor.

İş akışlarının WordPress `save_post` gibi alan olaylarıyla başlamasını istiyorsanız [Eylem Tetikleyicileri](https://queuety.inline0.dev/tr/docs/features/action-triggers) sayfasına bakın.

DB destekli çalışma zamanını WordPress dışında kullanmak istiyorsanız [Bağımsız Kullanım](https://queuety.inline0.dev/tr/docs/features/standalone-use) sayfasına bakın.

## Öne çıkan özellikler

- **Hızlı yürütme.** Çalışanlar doğrudan MySQL kuyruğuna erişir ve WordPress içinde arka plan işlerini yavaşlatan istek başına cron modelinden kaçınır.
- **Kalıcı iş akışları.** Kalıcı durum içeren çok adımlı süreçler PHP zaman aşımlarına, çökmelere ve yeniden denemelere dayanır. Her adım sınırı atomik bir MySQL işlemidir.
- **Açıkça tanımlanmış durum makineleri.** Sohbet oturumlarını, onayları ve diğer uzun ömürlü yaşam döngülerini adlandırılmış durumlar, koşullu geçişler, kuyruğa alınan durum giriş eylemleri ve kalıcı olay zaman çizelgeleriyle modelleyin.
- **Modern dağıtım API.** `Dispatchable` trait'ini, yük olarak türü belirlenmiş kurucu özelliklerini ve sınıfta tanımlanmış `$tries`/`$timeout`/`$backoff` öğelerini kullanan, kendi kendine yeterli iş sınıfları. Bir `readonly` sınıfı bu özelliklere varsayılan değer veremez; bu nedenle bunları salt okunur tanıtılmış kurucu özelliklerine sahip normal bir sınıfta tanımlayın.
- **Ara katman işlem hattı.** Hız sınırlama, istisna kısıtlama, benzersiz işler ve özel mantık için soğan tarzı ara katman yazılımı. İş başına bir `middleware()` yöntemiyle tanımlanır.
- **Akış adımları.** `StreamingStep` arayüzü, hemen veritabanına kaydedilen parçalar üretir. Yeniden denemede, akış kaldığı yerden sürdürülebilsin diye önceden kaydedilmiş parçalar sağlanır. LLM yanıtları ve büyük indirmeler için idealdir.
- **Takılabilir önbellek katmanı.** `CacheFactory` APCu'yu otomatik algılar veya bellek içi önbelleğe geri döner. Özel arka uçlar `Contracts\Cache` arayüzünü uygular. Hız sınırlayıcı aramaları ve kuyruk durumu için dahili olarak kullanılır.
- **Toplu işleme ve zincirleme.** İlerleme takibi ve `then`/`catch`/`finally` geri çağrılarıyla iş grupları dağıtın ya da her işin bir öncekinin tamamlanmasına bağlı olduğu işleri sırayla zincirleyin.
- **Kalıcı gecikmeler ve beklemeler.** `delay()`, süreç yeniden başlatmalarına dayanıklı gecikmeler ekler. `wait_for_signal()`, `wait_for_signals()`, `wait_for_approval()`, `wait_for_input()` ve `wait_for_workflow()`, PHP çalışır durumda tutulmadan iş akışlarının harici olayları veya diğer iş akışlarını beklemesini sağlar.
- **Dinamik her öğe için döngüsü.** `for_each()`, çalışma zamanında keşfedilen dallanmış işleri iş akışı durumundan genişletir ve tümü başarılı, ilk başarılı veya yeter sayı tamamlanma modlarını destekler.
- **Asenkron iş akışı devri.** `start_workflows()`, çalışma zamanında keşfedilen öğeleri daha sonra beklenebilecek bağımsız üst düzey iş akışlarına dönüştürür.
- **WordPress eylem tetikleyicileri.** `on_action()`, çekirdek veya eklenti eylem kancalarını koşullandırma ve idempotensiyle kalıcı iş akışı dağıtımlarına eşler.
- **Kalıcı yapıtlar.** Adlandırılmış iş akışı çıktılarını ana durum çantasının dışında saklayın; bunları durum, CLI incelemesi, dışa aktarma ve yeniden oynatma boyunca taşıyın.
- **İş akışı korumaları.** `version()`, belirleyici tanım karması, idempotent dağıtım anahtarları ve iş akışı bütçeleri, ajan tarzı çalıştırmaların incelenmesini kolaylaştırır ve çoğaltılmalarını veya sessizce kontrolden çıkmalarını zorlaştırır.
- **Kaynak yönetimi.** Eşzamanlılık grupları, maliyet birimleri, iş akışı bütçeleri ve çalışan kabulü, maliyetli ajan tarzı işlerin tanımlı sınırlar içinde kalmasına yardımcı olur.
- **Adım telafisi.** `compensate_with()` ve `compensate_on_failure()`, iş akışları iptal edildiğinde veya başarısız olduğunda tamamlanmış adımlar için geri alma kancaları sağlar.
- **Kalp atışları.** Uzun süre çalışan adımlar, eski iş kurtarma sisteminin etkin işleri yeniden sahiplenmesini önlemek için kalp atışları gönderir.
- **İş akışı izleme.** Her adım geçişi; girdi, çıktı, önceki/sonraki durum, bağlam, yapıtlar, parçalar, hatalar ve `workflow_state_at()` aracılığıyla zamanda geriye dönük hata ayıklama bilgileriyle kaydedilir.
- **Paralel adımlar.** Adımları eşzamanlı çalıştırın ve ilerlemeden önce hepsinin tamamlanmasını bekleyin.
- **Koşullu dallanma.** Önceki duruma göre `_next_step` kullanarak adlandırılmış adımlara atlayın.
- **İş akışlarını çalıştırma.** Sonuçları üst öğeye geri ileten alt iş akışlarını başlatın.
- **Öncelik kuyrukları.** Tür güvenli PHP enum'larıyla dört düzey (Düşük, Normal, Yüksek, Acil).
- **Çok kuyruklu çalışanlar.** Tek bir çalışanda birden fazla kuyruğu katı öncelik sırasına göre işleyin.
- **Hız sınırlama.** Kayan pencereli, işleyici başına yürütme sınırları.
- **Yinelenen işler.** Yapılandırılabilir çakışma politikalarıyla (İzin ver, Atla, Arabelleğe al) aralığa ve cron tabanlı zamanlama.
- **İş akışını iptal etme.** Çalışan iş akışlarını iptal edin ve kayıtlı temizlik işleyicilerini tetikleyin.
- **Durum budama.** Büyük iş akışı durumunu yönetilebilir tutmak için eski adım çıktılarını otomatik kaldırın.
- **Çalışan eşzamanlılığı.** `--workers=N` birden fazla süreci çökme durumunda otomatik yeniden başlatmayla çatallar.
- **Tam gözlemlenebilirlik.** Veritabanı günlükleri, işleyici başına ölçümler ve olay webhook'ları.
- **Test yardımcı programları.** `QueueFake`, birim testlerinde doğrulama için dağıtılan işleri ve toplu işleri kaydeder.
- **PHP öznitelikleri.** Sıfır yapılandırmayla işleyici kaydı için `#[QueuetyHandler('name')]`.

## Nasıl çalışır

Çalışanlar, uzun ömürlü bir WP-CLI sürecinde çalışır ve işleri doğrudan MySQL üzerinden alır. Kuyruk satırları, iş akışı durumu, günlükler, toplu işler, sinyaller ve akış parçalarının tümü MySQL içinde tutulur; bu nedenle çalışanların yeniden başlatılması orkestrasyon durumunu kaybettirmez.

İş akışları, uzun süren işleri adımlara böler. Her adım çıktısını veritabanındaki paylaşılan bir durum çantasına kaydeder. PHP bir adımın ortasında kapanırsa çalışan, önceki tüm durum korunarak o adımı yeniden dener. Adım sınırı tek bir MySQL işlemidir: durum güncellemesi, işin tamamlanması ve sonraki adımın kuyruğa alınması atomik olarak gerçekleşir.

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

## Gereksinimler

- PHP 8.2 veya üzeri
- WordPress 6.4 veya üzeri
- MySQL 8.0+ veya MariaDB 10.6+, çünkü çalışanlar işleri `SELECT ... FOR UPDATE SKIP LOCKED` ile alır
- WordPress ve WP-CLI öğelerini yükleyen PHP çalışma zamanında `mysqli` veya `pdo_mysql`
- `wp queuety work` ile özel çalışanlar çalıştırmak için WP-CLI
- Çalışan havuzları için `pcntl` ve `posix` PHP uzantıları (`--workers`, `--min-workers`, `--max-workers`)

Kurulum için [Başlarken](https://queuety.inline0.dev/tr/docs/getting-started) sayfasına bakın.