# Εισαγωγή

Το Queuety είναι ένα πρόσθετο WordPress που παρέχει γρήγορη ουρά εργασιών, μηχανή ροών εργασίας με διαρκή αποθήκευση και περιβάλλον εκτέλεσης μηχανής καταστάσεων με διαρκή αποθήκευση. Οι workers αναλαμβάνουν εργασίες απευθείας από το MySQL και τις επεξεργάζονται μέσα σε διεργασία WP-CLI μεγάλης διάρκειας. Το περιβάλλον εκτέλεσης PHP που φορτώνει τα WordPress και WP-CLI χρειάζεται είτε το `mysqli` είτε το `pdo_mysql`.

## Γιατί το Queuety;

Το WordPress δεν διαθέτει πραγματικό σύστημα εργασιών στο παρασκήνιο. Το `wp_cron` ενεργοποιείται μόνο όταν υπάρχουν επισκέψεις σε σελίδες. Ο προεπιλεγμένος εκτελεστής του Action Scheduler βασίζεται στο WP-Cron και σε αιτήματα loopback 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 ] );
```

Εκκινήστε έναν worker:

```bash
wp queuety work
```

Αν δημιουργείτε σύστημα τύπου agent, ξεκινήστε με την ενότητα [Ενορχήστρωση agent](https://queuety.inline0.dev/el/docs/workflows/agent-orchestration). Δείχνει πώς συνδυάζονται οι ροές planner/executor, τα σημεία ελέγχου από άνθρωπο και οι αναμονές μεταξύ ροών εργασίας.

Αν το σύστημα καθοδηγείται από συμβάντα και έχει μεγάλο κύκλο ζωής, ξεκινήστε με τις [Μηχανές καταστάσεων](https://queuety.inline0.dev/el/docs/state-machines) μαζί με τις ροές εργασίας.

Αν θέλετε παραδείγματα ολοκληρωμένης ενσωμάτωσης, δείτε τα [Παραδείγματα](https://queuety.inline0.dev/el/docs/examples), που περιλαμβάνουν πλέον μοτίβα βασισμένα σε Neuron για εναλλαγή παρόχων, ροή δεδομένων, επαναλήψεις ελέγχου με υποστήριξη μνήμης και εξαρτημένες ροές εργασίας.

Αν θέλετε οι ροές εργασίας να ξεκινούν από συμβάντα τομέα του WordPress, όπως το `save_post`, δείτε τους [Ενεργοποιητές ενεργειών](https://queuety.inline0.dev/el/docs/features/action-triggers).

Αν θέλετε να χρησιμοποιήσετε το περιβάλλον εκτέλεσης που βασίζεται στη βάση δεδομένων εκτός του WordPress, δείτε την ενότητα [Αυτόνομη χρήση](https://queuety.inline0.dev/el/docs/features/standalone-use).

## Βασικά χαρακτηριστικά

- **Γρήγορη εκτέλεση.** Οι workers έχουν άμεση πρόσβαση στην ουρά MySQL και αποφεύγουν το μοτίβο cron ανά αίτημα, που επιβραδύνει την εργασία στο παρασκήνιο στο WordPress.
- **Ροές εργασίας με διαρκή αποθήκευση.** Διαδικασίες πολλών βημάτων με μόνιμη κατάσταση που επιβιώνουν από χρονικά όρια PHP, διακοπές λειτουργίας και επαναλήψεις. Κάθε όριο βήματος είναι ατομική συναλλαγή MySQL.
- **Ρητές μηχανές καταστάσεων.** Μοντελοποιήστε συνεδρίες συνομιλίας, εγκρίσεις και άλλους κύκλους ζωής μεγάλης διάρκειας με ονομασμένες καταστάσεις, μεταβάσεις με φρουρούς, ενέργειες εισόδου σε κατάσταση που μπαίνουν στην ουρά και διαρκή χρονολόγια συμβάντων.
- **Σύγχρονο API αποστολής API.** Αυτοτελείς κλάσεις εργασιών με το trait `Dispatchable`, τυποποιημένες ιδιότητες κατασκευαστή ως φορτίο και `$tries`/`$timeout`/`$backoff` δηλωμένα στην κλάση. Μια κλάση `readonly` δεν μπορεί να ορίσει προεπιλεγμένες τιμές για αυτές τις ιδιότητες, γι’ αυτό δηλώστε τις σε κανονική κλάση με ιδιότητες κατασκευαστή που προωθούνται ως readonly.
- **Αγωγός ενδιάμεσου λογισμικού.** Ενδιάμεσο λογισμικό τύπου κρεμμυδιού για περιορισμό ρυθμού, περιορισμό συχνότητας εξαιρέσεων, μοναδικές εργασίες και προσαρμοσμένη λογική. Δηλώνεται ανά εργασία μέσω μιας μεθόδου `middleware()`.
- **Βήματα ροής δεδομένων.** Η διεπαφή `StreamingStep` αποδίδει τμήματα που αποθηκεύονται αμέσως στη βάση δεδομένων. Σε περίπτωση επανάληψης, παρέχονται τα ήδη αποθηκευμένα τμήματα, ώστε η ροή να συνεχιστεί από εκεί που σταμάτησε. Ιδανικό για αποκρίσεις LLM και μεγάλες λήψεις.
- **Επεκτάσιμη βαθμίδα cache.** Το `CacheFactory` εντοπίζει αυτόματα το APCu ή χρησιμοποιεί εφεδρικά cache στη μνήμη. Τα προσαρμοσμένα συστήματα αποθήκευσης υλοποιούν το `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()` αντιστοιχίζει hooks ενεργειών του πυρήνα ή πρόσθετων σε αποστολές διαρκών ροών εργασίας με ελέγχους προϋποθέσεων και ιδιοδυναμία.
- **Διαρκή τεχνουργήματα.** Αποθηκεύστε ονομασμένα αποτελέσματα ροών εργασίας έξω από την κύρια συλλογή κατάστασης και διατηρήστε τα κατά την επιθεώρηση κατάστασης, την επιθεώρηση CLI, την εξαγωγή και την επανάληψη.
- **Δικλίδες ασφαλείας ροών εργασίας.** Το `version()`, ένα ντετερμινιστικό hash ορισμού, κλειδιά αποστολής με ιδιοδυναμία και προϋπολογισμοί ροών εργασίας διευκολύνουν την επιθεώρηση εκτελέσεων τύπου agent και αποτρέπουν καλύτερα τη διπλή εκτέλεση ή την ανεξέλεγκτη συνέχισή τους.
- **Διαχείριση πόρων.** Ομάδες ταυτόχρονης εκτέλεσης, μονάδες κόστους, προϋπολογισμοί ροών εργασίας και αποδοχή εργασιών από worker βοηθούν να παραμένει η δαπανηρή εργασία τύπου agent εντός καθορισμένων ορίων.
- **Αντιστάθμιση βημάτων.** Τα `compensate_with()` και `compensate_on_failure()` παρέχουν hooks επαναφοράς για ολοκληρωμένα βήματα όταν οι ροές εργασίας ακυρώνονται ή αποτυγχάνουν.
- **Σήματα ζωής.** Τα βήματα μεγάλης διάρκειας στέλνουν σήματα ζωής, ώστε το σύστημα ανάκτησης παλιών εργασιών να μην αναλαμβάνει ενεργή εργασία.
- **Ανίχνευση ροών εργασίας.** Κάθε μετάβαση βήματος καταγράφεται μαζί με την είσοδο, την έξοδο, την κατάσταση πριν και μετά, το περιβάλλον, τα τεχνουργήματα, τα τμήματα ροής, τα σφάλματα και τον εντοπισμό σφαλμάτων με μετάβαση στον χρόνο μέσω του `workflow_state_at()`.
- **Παράλληλα βήματα.** Εκτελέστε βήματα ταυτόχρονα και περιμένετε να ολοκληρωθούν όλα πριν συνεχίσετε.
- **Διακλάδωση υπό όρους.** Μεταβείτε σε ονομασμένα βήματα βάσει προηγούμενης κατάστασης με το `_next_step`.
- **Εκτέλεση ροών εργασίας.** Ξεκινήστε θυγατρικές ροές εργασίας που επιστρέφουν αποτελέσματα στη γονική.
- **Ουρές προτεραιότητας.** Τέσσερα επίπεδα (Low, Normal, High, Urgent) μέσω τυποποιημένων enum PHP.
- **Workers πολλών ουρών.** Επεξεργαστείτε πολλές ουρές με αυστηρή σειρά προτεραιότητας σε έναν worker.
- **Περιορισμός ρυθμού.** Όρια εκτέλεσης ανά χειριστή με κυλιόμενο παράθυρο.
- **Επαναλαμβανόμενες εργασίες.** Προγραμματισμός βάσει διαστημάτων και cron με διαμορφώσιμες πολιτικές επικάλυψης (Allow, Skip, Buffer).
- **Ακύρωση ροών εργασίας.** Ακυρώστε εκτελούμενες ροές εργασίας και ενεργοποιήστε καταχωρισμένους χειριστές καθαρισμού.
- **Περιορισμός κατάστασης.** Αφαιρείτε αυτόματα παλιές εξόδους βημάτων, ώστε η κατάσταση μεγάλων ροών εργασίας να παραμένει διαχειρίσιμη.
- **Ταυτόχρονη εκτέλεση worker.** Το `--workers=N` δημιουργεί πολλαπλές διεργασίες με αυτόματη επανεκκίνηση σε περίπτωση κατάρρευσης.
- **Πλήρης παρατηρησιμότητα.** Καταγραφή στη βάση δεδομένων, μετρικές ανά χειριστή και webhook συμβάντων.
- **Βοηθητικά εργαλεία δοκιμών.** Το `QueueFake` καταγράφει τις αποσταλμένες εργασίες και δέσμες για επιβεβαιώσεις σε δοκιμές μονάδων.
- **Γνωρίσματα PHP.** Το `#[QueuetyHandler('name')]` για καταχώριση χειριστών χωρίς ρυθμίσεις.

## Πώς λειτουργεί

Οι workers εκτελούνται μέσα σε διεργασία WP-CLI μεγάλης διάρκειας και αναλαμβάνουν εργασίες απευθείας από το MySQL. Οι γραμμές ουράς, η κατάσταση ροών εργασίας, τα αρχεία καταγραφής, οι δέσμες, τα σήματα και τα τμήματα ροής δεδομένων αποθηκεύονται στο MySQL, επομένως οι επανεκκινήσεις worker δεν χάνουν την κατάσταση ενορχήστρωσης.

Οι ροές εργασίας χωρίζουν τις εργασίες μεγάλης διάρκειας σε βήματα. Κάθε βήμα αποθηκεύει την έξοδό του σε κοινή συλλογή κατάστασης στη βάση δεδομένων. Αν το PHP τερματιστεί στη μέση ενός βήματος, ο worker επαναλαμβάνει αυτό το βήμα με ανέπαφη όλη την προηγούμενη κατάσταση. Το όριο του βήματος είναι μία συναλλαγή 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+, επειδή οι workers αναλαμβάνουν εργασίες με το `SELECT ... FOR UPDATE SKIP LOCKED`
- `mysqli` ή `pdo_mysql` στο περιβάλλον εκτέλεσης PHP που φορτώνει τα WordPress και WP-CLI
- WP-CLI για εκτέλεση αποκλειστικών workers με το `wp queuety work`
- Οι επεκτάσεις PHP `pcntl` και `posix` για ομάδες διεργασιών worker (`--workers`, `--min-workers`, `--max-workers`)

Για εγκατάσταση, δείτε την ενότητα [Γρήγορη εκκίνηση](https://queuety.inline0.dev/el/docs/getting-started).