Rozhodnutia a stavy

Každé rozhodnutie je riadok Approval medzi aktérom a schvaľovaným modelom. Nesie explicitný stav — pending, approved, rejected, cancelled alebo expired — plus voliteľný dôvod, voliteľnú expiráciu, váhu a čas rozhodnutia.

Životný cyklus rozhodnutia

use RoundlyConsulting\Approvals\Facades\Approvals;

// 1. Ask for a decision — records a pending row.
Approvals::for($contract)->as($legal)->ask();
Approvals::for($contract)->hasPending();              // true

// 2. The same actor decides — the pending row becomes approved.
Approvals::for($contract)->as($legal)->because('Clauses reviewed')->approve();
Approvals::for($contract)->as($legal)->isApproved();  // true

// 3. Changed their mind — the approval is withdrawn (cancelled), only the rejection counts.
Approvals::for($contract)->as($legal)->because('New revision uploaded')->reject();

// 4. Or withdraw the live decision without replacing it.
Approvals::for($contract)->as($legal)->cancel();      // status: cancelled

Jedno živé rozhodnutie na slot

Každý aktér má na jeden slot jedno živé rozhodnutie — samostatné rozhodnutie o schvaľovanom modeli alebo rozhodnutie v jednej žiadosti (či v jednom stupni viacstupňovej žiadosti). Nové rozhodnutie to pôvodné zmení, nepridá druhé: dvojité schválenie nič nezmení a zamietnutie po schválení schválenie stiahne (jeho stav bude cancelled), takže sa počíta len zamietnutie — a naopak.

Slot stráži unikátny index v databáze, takže dve súbežné schválenia toho istého aktéra sa započítajú raz. Nová žiadosť alebo ďalší stupeň je nový slot: schválenie staršej žiadosti vám nikdy nezabráni schváliť ďalšiu.

Povolené prechody

Stavy sa menia cez strážený stavový automat. Rozhodnuté schválenie či zamietnutie sa dá ešte zrušiť — stiahnuť alebo nahradiť, keď aktér zmení názor — a schválenie vyprší, keď mu uplynie platnosť. Zrušené a expirované sú koncové stavy:

use RoundlyConsulting\Approvals\Enums\ApprovalStatus;

ApprovalStatus::Pending->canTransitionTo(ApprovalStatus::Approved);    // true
ApprovalStatus::Approved->canTransitionTo(ApprovalStatus::Cancelled);  // true — withdrawn or superseded
ApprovalStatus::Approved->canTransitionTo(ApprovalStatus::Expired);    // true — lapses once its expiry passes
ApprovalStatus::Rejected->canTransitionTo(ApprovalStatus::Cancelled);  // true — withdrawn or superseded
ApprovalStatus::Approved->canTransitionTo(ApprovalStatus::Rejected);   // false — a change of mind writes a new decision
ApprovalStatus::Cancelled->canTransitionTo(ApprovalStatus::Approved);  // false — terminal

Prechodové metódy na modeli Approval — approve(), reject(), cancel() a markExpired() — overia každý krok a pri nepovolenom vyhodia InvalidStatusTransitionException.

Čo robí ktoré volanie

• approve() — zapíše schválenie do slotu aktéra. Čakajúce vyžiadanie sa rozhodne priamo, držané zamietnutie sa nahradí a zapíše sa nové schválenie. Opätovné schválenie vráti to isté schválenie a nespustí žiadne udalosti.
• reject() — zrkadlovo: čakajúce vyžiadanie sa rozhodne priamo a držané schválenie sa stiahne, takže sa počíta len zamietnutie.
• ask() — zapíše čakajúce rozhodnutie pre aktéra, adresované práve tomuto modelu, nikdy tomu, koho zastupuje. Ak už aktér v slote živé rozhodnutie má, vráti ho nezmenené.
• cancel() / cancelApproval() — stiahne živé rozhodnutie aktéra (čakajúce, schválené alebo zamietnuté), prípadne to, ktoré urobil ako zástupca, v tom istom kole, kam by smerovalo rozhodnutie. Vráti ho, alebo null, ak nie je čo stiahnuť.
• toggle() / toggleApproval() — jednoduchý palec hore, nižšie.

Pri uzavretej žiadosti vyhodia ClosedApprovalRequestException — bez účinku zostane len zopakovanie schválenia či zamietnutia, ktoré tam aktér už má (pozri Žiadosti pre viacerých schvaľovateľov). Metódy traitu GivesApprovals — approve(), reject(), cancelApproval() a toggleApproval() — sú skratkou pre tie isté volania fasády.

Čítanie rozhodnutia

$approval = Approvals::for($deployment)->as($user)->because('LGTM')->approve();

$approval->status;           // ApprovalStatus::Approved
$approval->reason;           // 'LGTM'
$approval->decided_at;       // CarbonImmutable
$approval->expires_at;       // ?CarbonImmutable
$approval->weight;           // int — 1 unless weighted
$approval->actor;            // the model whose decision this is
$approval->approvable;       // the model decided on
$approval->approvalRequest;  // ?ApprovalRequest it counts toward
$approval->stage;            // ?ApprovalRequestStage, for staged requests
$approval->wasDelegated();   // bool — decided by a delegate

Jednoduchý prepínač

Zapnutie a vypnutie jedným klikom pre lajky, odporúčania či schvaľovanie jedným recenzentom:

Approvals::for($deployment)->as($user)->toggle(); // true  — approved (status: approved)
Approvals::for($deployment)->as($user)->toggle(); // false — withdrawn (status: cancelled, soft-deleted)

$user->toggleApproval($deployment);                // the same through the GivesApprovals trait

Zapnutie je approve() — platí autorizačná kontrola, menovaní schvaľovatelia žiadosti, delegovanie aj otvorená žiadosť a zamietnutie, ktoré držíte, sa nahradí. Vypnutie stiahne vaše živé schválenie a mäkko ho zmaže. Obe spustia ApprovalToggled aj ApprovalStatusChanged.