Prepojenia s ďalšími balíkmi

Prepojenie je kód pre iný balík Roundly, aktívny len vtedy, keď je ten balík nainštalovaný. Žiadne nie je závislosťou za behu: každé je uvedené v suggest. Prepojený typ kroku, ktorého balík chýba, ostáva v katalógu s available: false a názvom balíka a publikovanie hlási adapter_missing. Celý balík sa nainštaluje, spustí a vykoná každý vstavaný postup aj bez akéhokoľvek prepojenia.

Dve prepojenia vyžadujú minimálnu verziu, ktorú vynúti Composer (conflict): approvals-for-laravel ≥ 2.1 (odovzdanie fázy na mieste) a opening-hours-for-laravel ≥ 2.1 (addOpenDays() / addOpenTime()). Staršia nainštalovaná verzia zablokuje composer require / update namiesto zlyhania za behu.

approvals — krok approval

// flat
{ "approvers": [ { "kind": "field", "field": "subject.approver" } ], "rule": "any", "expires_in": { "amount": 2, "unit": "business_days" } }
// staged
{ "stages": [ { "name": "Legal", "approvers": [ { "kind": "role", "role": "legal" } ], "rule": "unanimous" },
              { "name": "CFO",   "approvers": [ { "kind": "role", "role": "cfo" } ],   "rule": "any" } ],
  "expires_in": "P5D", "continue_on_rejection": false }
// an approvals preset (config approvals.workflows), approvers per stage
{ "preset": "payout", "approvers": [ [ { "kind": "field", "field": "subject.approver" } ] ] }

• Pravidlá: unanimous, quorum (quorum, required), any, weighted — pravidlá balíka approvals. Výsledky: approved, rejected, expired (povinné), cancelled (voliteľný).
• handle() vyhodnotí strany pre každú fázu (nikto → zlyhá s no_approvers; nikdy „rozhodnúť môže ktokoľvek“), vypočíta vypršanie v pracovnom čase a kolo otvorí raz (opakovanie nikdy neotvorí druhé). Výstup: {request_id, rounds, expires_at}. Čaká na rozhodnutie kola plus poistný časovač vo vypršaní + approval.expiry_grace a raz spustí probe hneď po commite.
• Na jednom subjekte môže byť otvorených viac kôl, preto rozhodujte v rámci kola — output.request_id kroku, ktorý sprístupňuje StepRunResource.
• Listener rozhodnutia beží po commite transakcie rozhodujúceho a len signalizuje: rozhodnutie, ktoré sa vráti späť, nič neobnoví.
• Kolo zrušené mimo workflowu pokračuje hranou cancelled, inak zlyhá s approval_cancelled. Zrušenie inštancie zatvorí jej otvorené kolo — či krok čaká, je vo fronte na opakovanie, alebo ešte bežal. Zatvorí sa len čakajúce kolo; rozhodnuté ostane bez zmeny.
• Preradenie (eskalácia), raz na úroveň eskalácie: kolo s fázami, ktorého otvorená fáza má názov, sa odovzdá na mieste — schvaľovatelia, ktorí už rozhodli, ostanú uvedení a ich rozhodnutia platia, nerozhodnutí sa nahradia, kolo si ponechá absolútny čas vypršania a output.request_id sa nezmení. Kolo bez fáz alebo nepomenovaná fáza sa nahradí novým kolom pre nové strany s pôvodným vypršaním; rozhodnutia v starom kole sa neprenášajú. Ak chcete odovzdanie na mieste, fázy pomenujte.
• Ručné opakovanie zlyhaného kroku approval si ponechá rovnaký idempotentný kľúč, takže znova načíta kolo, ktoré už otvoril. Chyby schvaľovania zlyhajú natrvalo (invalid_approval_request, unknown_approval_preset).

// Decide within the round the step opened — its output.request_id (exposed by StepRunResource)
Approvals::as($user)->for($subject)->within($round)->approve();

lifecycle — krok transition a udalosti prechodov

• Lifecycles::for($subject, $lifecycle)->by($user)|asSystem()->because($reason)->idempotencyKey($key)->attempt($transition). Vykonaný → transitioned. Zamietnutý → hrana denied, inak zlyhá s transition_denied:<code>.
• IdempotencyConflictException → idempotency_conflict; prehratý súbeh → opakuje sa; nesprávne použitie (neznámy lifecycle, zmazaný alebo neuložený subjekt) → transition_unusable.
• Publikovanie overí, že prechod existuje (unknown_transition), a odmietne set_field na stavovom stĺpci lifecycle (field_not_writable). Dôvodom v histórii lifecycle je workflow {key} v{n} #{instance ulid} (alebo reason uzla).
• Voliteľne: so zapnutým workflows.bridges.lifecycle.emit_transitions vyšle každá zmena stavu lifecycle po commite svojej transakcie lifecycle.<lifecycle>.<transition> pre subjekt — workflow tak môže začať (alebo wait pokračovať), keď záznam dosiahne stav, bez ohľadu na to, kto ho posunul. Vypršanie alebo prevzatie použije svoj druh (lifecycle.purchase.expired). Payload je {lifecycle, transition, kind, from, to, history_id}, aktérom je používateľ, ktorý prechod spustil, a idempotentným kľúčom je id záznamu v histórii lifecycle.

# every lifecycle state change emits lifecycle.<lifecycle>.<transition>
WORKFLOWS_LIFECYCLE_EMIT_TRANSITIONS=on

notifications — krok notify a eskalačná akcia

{ "notification": "purchase.approved", "recipients": [ { "kind": "field", "field": "subject.requester" } ],
  "data": { "amount": { "ref": "subject.amount" } }, "actor": "triggered_by" }

Notifications::send($type, $subject, $recipients, $data, $actor, null, $idempotencyKey). Výstup {recipients: n}; bez príjemcov sa krok dokončí s 0. Publikovanie overí typ (unknown_notification_type) a príjemcov. Odmietnutie zo strany notifications zlyhá natrvalo ako notification_refused:<kód z notifications> — nikdy sa neopakuje.

opening-hours — kalendáre

opening_hours:<name> číta rozvrh otváracích hodín <name> vlastníka (otvorené intervaly, sviatky, výnimky) a pracovný čas počíta priamo opening-hours: „2 pracovné dni“ a „4 pracovné hodiny“ sa počítajú presne tak ako v opening-hours, s obmedzením opening-hours.search_days. Model vlastníka musí implementovať OpeningHoursOwner (use HasOpeningHours) — workflows:doctor zlyhá pri aktívnej definícii, ktorej model vlastníka ho nemá. Pri teams je vlastníkom tím, preto model tímu nahraďte takým, ktorý ho pridá:

// config/teams.php: 'models' => ['team' => App\Models\Team::class]
namespace App\Models;

use RoundlyConsulting\OpeningHours\Concerns\HasOpeningHours;
use RoundlyConsulting\OpeningHours\Contracts\OpeningHoursOwner;
use RoundlyConsulting\Teams\Models\Team as BaseTeam;

class Team extends BaseTeam implements OpeningHoursOwner
{
    use HasOpeningHours;
}

forms, teams a sentinel

• forms — {"trigger": "manual", "form": "purchase-form"} overí vstup cez forms-for-laravel; ->withForm($request, submit: true) uloží odoslanie a jeho uuid vloží do payloadu spúšťača. Neznámy formulár → unknown_form; spúšťač s formulárom bez nainštalovaného forms → adapter_missing.
• teams — kroky inštancie, ktorú vlastní tím, bežia v Teams::runAs($team) bez ohľadu na kontext, z ktorého boli odoslané; rovnako kontroly podmienok, eskalácie aj prehľadávanie subjektov plánu for_each a jeho where. {"kind": "role", "role": "legal"} sa vyhodnotí na aktívnych členov tímu s touto rolou; strany user, field a triggered_by musia byť aktívni členovia; subjekty BelongsToTeam / ScopedToTeam vlastní ich tím.
• sentinel — bez kódu: nastavte workflows.webhooks.verify_middleware = ['sentinel.signed:<profile>'] a prichádzajúca webhook route bude overovať podpisy RFC 9421.

Odchádzajúce webhooky

Ako krok workflowu môžete zapojiť vlastnú doručovaciu službu: implementujte Contracts\DeliversWebhooks (deliver(?Model $owner, string $endpoint, string $event, array $payload, string $idempotencyKey): int|string) a uveďte ju vo workflows.adapters.webhooks. Potom sa zaregistruje krok webhook ({endpoint, event, payload?}, výsledok queued); doručenie prebehne raz za návštevu cez once().