# Durum Makineleri

Durum makineleri ve iş akışları farklı sorunları çözer.

İş akışı, "Sırada hangi işler çalışacak?" sorusunu yanıtlar. Durum makinesi ise "Bu şey hangi durumda ve buradan hangi olaylar geçerli?" sorusunu yanıtlar. Oluşturduğunuz şey yalnızca bir adım dizisi değil de zaman içinde dış girdilere tepki veren uzun ömürlü bir varlıksa (ör. bir aracı oturumu, sohbet dizisi, inceleme yaşam döngüsü, destek kaydı veya onay akışı), bu fark önem kazanır.

## Hızlı örnek

```php
use Queuety\Enums\StateMachineStatus;
use Queuety\Queuety;

$machine_id = Queuety::machine( 'agent_session' )
    ->version( 'agent-session.v1' )
    ->state( 'awaiting_user' )
    ->on( 'user_message', 'planning' )
    ->state( 'planning' )
    ->action( PlanSessionAction::class )
    ->on( 'planned', 'awaiting_review' )
    ->state( 'awaiting_review' )
    ->on( 'approve', 'completed', ReviewApprovedGuard::class )
    ->on( 'reject', 'awaiting_user' )
    ->state( 'completed', StateMachineStatus::Completed )
    ->dispatch( [ 'thread_id' => 42 ] );

Queuety::machine_event(
    $machine_id,
    'user_message',
    [ 'message' => 'Find competitors for this product' ]
);

Queuety::machine_event(
    $machine_id,
    'approve',
    [ 'approved' => true, 'reviewer' => 'editor@example.com' ]
);
```

Bu makine `awaiting_user` durumunda başlar, kullanıcı mesajı geldiğinde `planning` durumuna geçer, sıraya alınan eylemin `planned` üretmesine izin verir ve harici bir onay oturumu tamamlayana kadar `awaiting_review` durumunda bekler. Önemli olan yalnızca kod söz dizimi değildir. Yaşam döngüsünün açık, incelenebilir ve olay odaklı olmasıdır.

## Makine nasıl çalışır

Bir makine örneği gönderildiğinde Queuety; geçerli durum adını, genel durum yükünü, tanım sürümünü ve karmasını, geçerli duruma ait geçerli gelen olayları ve kalıcı bir olay zaman çizelgesini kaydeder.

Girilen durumda bir `action()` varsa Queuety, durum giriş işini kuyruğa ekler. Bu eylem yalnızca genel durumu güncelleyip makinenin sonraki olayı beklemesini sağlayabilir veya `_event` üretebilir ve sonraki geçişi hemen başlatmak için isteğe bağlı olarak `_event_payload` gönderebilir. Durumda bir eylem yoksa ve sonlandırıcı bir durum da değilse makine, `Queuety::machine_event()` ile gönderilen harici olayları bekler.

## İş akışları ile durum makineleri arasında seçim

Çalıştırma temelde adım odaklıysa iş akışı kullanın. Verileri alın, her iş için bekleyin, sentezleyin ve tamamlayın. Başlangıcı ve bitişi net olan, temel sorusu sırada hangi işin yürütülmesi gerektiği olan durumlarda bu model uygundur.

Geçerli davranış mevcut yaşam döngüsü aşamasına bağlıysa durum makinesi kullanın. Olaylar farklı sıralarda gelebiliyorsa, varlık uzun süre yaşayabiliyorsa veya `awaiting_user`, `planning`, `running_agents`, `awaiting_review` ve `completed` gibi durumlarla yaşam döngüsünü açıkça incelemeniz gerekiyorsa bu yaklaşım daha uygundur.

## İkisi birlikte nasıl çalışır

Bu iki temel yapı birbiriyle rekabet etmek yerine birlikte en iyi sonucu verir. Bir geçiş daha ağır bir yürütme gerektirdiğinde durum eylemi bir iş akışı gönderebilir; iş tamamlandığında iş akışı makineye bir olay iletebilir. Böylece uygulamada durum makinesi yaşam döngüsünü yönetirken iş akışları maliyetli veya yüksek düzeyde yapılandırılmış yürütmeyi gerçekleştirir.

## Oluşturucu yapısı

`StateMachineBuilder` bilerek küçük tutulmuştur. `initial()` ve `state()` yaşam döngüsü grafiğini tanımlar. `action()`, sıraya alınmış işi tek bir duruma bağlar. `on()`, makineyi sonraki duruma taşıyabilecek olayları bildirir. `on_queue()`, `with_priority()` ve `max_attempts()` durum eylemlerinin nasıl yürütüleceğini denetler; `version()` ve `idempotency_key()` kalıcı gönderim meta verilerini ekler. `dispatch()` makine örneğini oluşturur.

Durum eylemleri, iş akışı adımları ve işleyicilerin kullandığı aynı kaynak politikası anahtarlarını kullanan isteğe bağlı bir `config()` yöntemi de sunabilir. Böylece maliyetli bir durum geçişini paylaşılan bir eşzamanlılık grubunda tutabilir veya eylem normal bir adımdan daha fazla bütçe tükettiğinde daha yüksek bir maliyet ağırlığı atayabilirsiniz.

Daha kapsamlı kaynak modeli [Kaynak Yönetimi](https://queuety.inline0.dev/tr/docs/features/resource-management) bölümünde açıklanmıştır.

## Sözleşmeler

Durum giriş eylemleri `Queuety\Contracts\StateAction` arayüzünü uygular:

```php
namespace Queuety\Contracts;

interface StateAction {
    public function handle( array $state, ?string $event = null, array $event_payload = [], array $payload = [] ): array|string;
}
```

`$payload`, eylem tanımındaki yapılandırılmış yüktür; eylem düz sınıf adı olarak verilmişse boştur. Queuety, eylemleri `new $class()` ile oluşturur; bu nedenle eylem sınıfının zorunlu bağımsız değişkeni olmayan bir kurucusu olmalıdır.

Kuyruğa alınan giriş eyleminin çalışan kabulüne, ağırlıklı kuyruk veya sağlayıcı bütçelerine ve diğer kaynak politikalarına katılması gerektiğinde durum eylemleri; `concurrency_group`, `concurrency_limit` ve `cost_units` ile birlikte isteğe bağlı bir `config()` yöntemi de tanımlayabilir.

Geçiş korumaları `Queuety\Contracts\StateGuard` arayüzünü uygular:

```php
namespace Queuety\Contracts;

interface StateGuard {
    public function allows( array $state, array $event_payload, string $event, array $payload = [] ): bool;
}
```

## İnceleme API'leri

Çalışan makineleri incelemek için facade'i kullanın:

```php
$status   = Queuety::machine_status( $machine_id );
$machines = Queuety::list_machines();
$events   = Queuety::machine_timeline( $machine_id );
$trace    = Queuety::machine_trace( $machine_id );
$state    = Queuety::machine_state_at( $machine_id, $event_id );
```

Durum makinelerinin WP-CLI komutları yoktur: `wp queuety workflow ...` yalnızca iş akışlarını kapsar. Komut satırından makineleri incelemek için örneğin `wp eval` aracılığıyla bu PHP API'lerini kullanın.

Bu API'ler geçerli durum adını, yaşam döngüsü durumunu, genel durumu, kullanılabilir olayları, tanım meta verilerini, tüm geçiş zaman çizelgesini ve hata ayıklayıcı arayüzleri için normalleştirilmiş bir iz paketini sunar. Makine listesi satırlarında tanım sürümü, tanım karması ve idempotency anahtarı bulunur; böylece liste ekranları her makineyi ayrı ayrı yüklemeden kaynak/çalışma zamanı sürümünü gösterebilir. İz paketi; gruplandırılmış durumları, ham olayları, ilişkili eylem işlerini, günlükleri, yapıt başvurularını, parça başvurularını, işleyici girdisini/çıktısını, önceki/sonraki durumu, bağlamı, zamanlamaları ve yapılandırılmış hataları içerir.

## Aracı oturumları

Durum makineleri, işlem hatlarından çok oturumlar gibi davranan aracı sistemleri için özellikle yararlıdır. `awaiting_user`, `planning`, `running_agents`, `awaiting_review` ve `completed` durumları arasında ilerleyen bir oturumu, çok sayıda bekleme ve geri dönüş içeren tek ve çok uzun bir iş akışı tanımı olarak değil, açık bir yaşam döngüsü olarak ele almak genellikle daha kolaydır.

## Ayrıca bkz.

- [Neuron Oturum Durum Makinesi](https://queuety.inline0.dev/tr/docs/examples/neuron-session-state-machine)
- [Neuron Bellek + İnceleme Durum Makinesi](https://queuety.inline0.dev/tr/docs/examples/neuron-memory-review)
- [Aracı Düzenleme](https://queuety.inline0.dev/tr/docs/workflows/agent-orchestration)
- [İş Akışı Sinyalleri](https://queuety.inline0.dev/tr/docs/workflows/signals)
- [İş Akışı Bağımlılıkları](https://queuety.inline0.dev/tr/docs/workflows/dependencies)
- [Tekrarlar](https://queuety.inline0.dev/tr/docs/workflows/repeats)
- [Yapıtlar](https://queuety.inline0.dev/tr/docs/features/artifacts)
- [PHP API](https://queuety.inline0.dev/tr/docs/api)