---
title: "Jednorazové potvrdenia — Approvals for Laravel | Roundly"
description: "Jedna menovaná osoba potvrdí jednu presnú akciu viazanú na hash payloadu, raz a pred vypršaním — typované odmietnutia, zoznamy a upratovanie."
url: https://roundly-consulting.com/sk/open-source/navody/approvals-for-laravel/potvrdenia
language: sk
---

[Všetky balíky](https://roundly-consulting.com/sk/open-source.md)

[Approvals for Laravel](https://roundly-consulting.com/sk/open-source/navody/approvals-for-laravel.md)

# Jednorazové potvrdenia

Od verzie 2.3.0. Potvrdenie je najmenšie schválenie, aké existuje: jedna menovaná osoba potvrdí jednu presnú akciu, raz a pred jej vypršaním. Akciu určuje hash payloadu, ktorý vypočíta vaša aplikácia — pri volaní nástroja AI agentom hash názvu nástroja a jeho argumentov —, takže osoba potvrdzuje práve toto volanie, nie neskoršie s inými argumentmi.

Funkcia je voliteľná a má vlastnú tabuľku (approval\_confirmations, migrácia 0009). Na kolách schvaľovania — status(), progress(), approvals:expire či udalostiach kôl — sa jej použitím nič nemení:

| Záruka | Ako |
| --- | --- |
| Len menovaná osoba | confirm() aj decline() porovnajú morph typ a kľúč odpovedajúceho modelu s uloženou osobou. Zástupca, schvaľovateľ subjektu či model iného typu s rovnakým id sa odmietne (not\_the\_person). |
| Len presná akcia | Hash odovzdaný do confirm() sa musí zhodovať s uloženým, porovnáva sa v konštantnom čase (hash\_equals). Čokoľvek iné sa odmietne (mismatch) a potvrdenie ďalej čaká. |
| Raz | Prvé potvrdenie či odmietnutie presunie riadok zo stavu pending jedným podmieneným UPDATE … WHERE status = 'pending' AND (expires\_at IS NULL OR expires\_at > now). Z dvoch súbežných odpovedí sa zhodne práve jedna; druhá sa odmietne (used / declined). |
| Pred vypršaním | Zmeškané potvrdenie sa hneď javí ako vypršané (isExpired(), effectiveStatus(), scopes pre čakajúce), odmietne sa (expired) a dokončí ho upratovanie alebo odmietnutá odpoveď. |

## Vyžiadanie potvrdenia

```php
use Carbon\CarbonInterval;
use RoundlyConsulting\Approvals\Facades\Approvals;

$hash = hash('sha256', json_encode([$toolName, $arguments], JSON_THROW_ON_ERROR));

$confirmation = Approvals::confirmation($toolCall)   // the subject: any saved model
    ->payload($hash)                                 // required
    ->by($user)                                      // required: the one person who may answer
    ->singleUse()                                    // optional marker, see below
    ->expiresIn(CarbonInterval::minutes(5))          // or ->expiresIn(300) / ->expiringAt($moment)
    ->request();                                     // ApprovalConfirmation, status pending
```

| Metóda | Vracia | Účel |
| --- | --- | --- |
| `payload(string $hash)` | self | Hash presnej akcie, ktorú treba potvrdiť. Povinné. |
| `by(Model $person)` | self | Jediná osoba, ktorá môže potvrdiť alebo odmietnuť. Povinné. |
| `singleUse()` | self | Len označenie: každé potvrdenie je jednorazové, takže nič nemení. |
| `expiresIn(DateInterval\|int $interval)` | self | Vyprší o toľko od teraz (CarbonInterval alebo sekundy). |
| `expiringAt(CarbonInterface $at)` | self | Vyprší v tomto okamihu. |
| `request()` | ApprovalConfirmation | Uloží ho ako čakajúce a spustí ApprovalConfirmationRequested. Bez expirácie platí confirmations.expiry. Vyhodí InvalidConfirmationException. |

request() uloží riadok a spustí ApprovalConfirmationRequested. Ak chýba by() alebo payload(), subjekt či osoba nie sú uložené, hash je prázdny alebo dlhší ako 255 znakov alebo expirácia nie je v budúcnosti, vyhodí InvalidConfirmationException a nič neuloží. Bez expiresIn() / expiringAt() potvrdenie vyprší o approvals.confirmations.expiry sekúnd (predvolene 900, teda 15 minút; env APPROVALS\_CONFIRMATION\_EXPIRY); s hodnotou null takéto potvrdenia nevypršia.

singleUse() je len označenie, nie prepínač. Každé potvrdenie je jednorazové; režim na viacnásobné použitie neexistuje. Potvrdenie použiteľné opakovane by bolo trvalým povolením („nech agent hodinu spúšťa tento nástroj“) — to je iná vec s inými rizikami a väzba na payload by pri opakovanom volaní stratila zmysel. singleUse() existuje preto, aby miesto volania jasne povedalo, na čo sa spolieha.

Hash sa uloží tak, ako je zadaný (payload\_hash, najviac 255 znakov), a je v $hidden modelu, takže ho toArray() ani JSON nikdy nevypíšu. Na oboch stranách ho počítajte rovnako — argumenty pred hashovaním kanonizujte (poradie kľúčov, medzery).

## Potvrdenie

```php
use RoundlyConsulting\Approvals\Exceptions\ConfirmationRefusedException;

try {
    Approvals::confirm($confirmation, $request->user(), $hashOfTheCallAboutToRun);
    // run the tool
} catch (ConfirmationRefusedException $refused) {
    return response()->json([
        'code' => $refused->errorCode(),       // mismatch | used | expired | not_the_person | declined
        'message' => $refused->getMessage(),   // translated (en, sk)
    ], 409);
}
```

confirm(ApprovalConfirmation $confirmation, Model $person, string $hash) najprv načíta riadok — odovzdaná inštancia sa obnoví, takže zastaraná kópia nevadí — a potom kontroluje v tomto poradí:

- $person je menovaná osoba — inak not\_the\_person. Kontroluje sa ako prvé, takže cudzí človek sa o potvrdení nič ďalšie nedozvie.
- Potvrdenie je stále otvorené — inak used (už potvrdené), declined alebo expired (po vypršaní; neupratané potvrdenie vyprší teraz a spustí sa ApprovalConfirmationExpired).
- Hash sa zhoduje — inak mismatch; potvrdenie ďalej čaká, takže správne volanie sa ešte dá potvrdiť.
- Atomické prevzatie. Ak ho predbehne súbežná odpoveď alebo upratovanie, odmietne sa s tým, čo riadok zmenilo: used, declined alebo expired.

Pri úspechu je riadok confirmed, nastaví sa resolved\_at a spustí sa ApprovalConfirmationConfirmed. Prevzatie beží vo vlastnej transakcii, ktorá sa pri chybe serializácie zopakuje, takže pri repeatable read či serializable sa prehrávajúca relácia odmietne s used, nie databázovou chybou. Vo vašej vlastnej transakcii ide o savepoint bez opakovania — chyba serializácie sa tam dostane do vašej transakcie ako pri akomkoľvek inom zápise.

## Odmietnutie

```php
Approvals::decline($confirmation, $user, 'Not on the production repository');
```

decline(ApprovalConfirmation $confirmation, Model $person, ?string $reason = null) hash neberie. Odmietnuť môže len menovaná osoba a len kým potvrdenie čaká a nevypršalo (inak not\_the\_person, used, declined alebo expired). Odmietnutie spotrebuje potvrdenie rovnako atomicky, takže súbežné potvrdenie a odmietnutie nemôžu uspieť obe. Dôvod sa uloží do reason, nastaví sa resolved\_at a spustí sa ApprovalConfirmationDeclined.

## Dôvody odmietnutia

ConfirmationRefusedException (rozširuje ApprovalsException) nesie $refusal (ConfirmationRefusal), errorCode() (jeho hodnotu), $confirmation a preloženú getMessage() z approvals::confirmations.refused.<code>, v angličtine aj slovenčine:

| Kód | ConfirmationRefusal | Anglická správa | Vyvolá |
| --- | --- | --- | --- |
| `mismatch` | Mismatch | This confirmation was given for a different action. | confirm() |
| `used` | Used | This confirmation has already been used. | confirm(), decline() |
| `expired` | Expired | This confirmation has expired. | confirm(), decline() |
| `not_the_person` | NotThePerson | Only the person this confirmation was requested from can answer it. | confirm(), decline() |
| `declined` | Declined | This confirmation has already been declined. | confirm(), decline() |

ConfirmationRefusal::message() vráti rovnaký text v aktuálnom jazyku. Ak chcete správy preformulovať, publikujte preklady cez --tag=approvals-translations.

## Zoznamy

```php
Approvals::pendingConfirmationsFor($user)->latest()->get();   // waiting on this person
Approvals::confirmationsFor($toolCall)->get();                 // every one about the subject
Approvals::confirmationsFor($toolCall)->pending()->exists();   // any still open?
```

Obe metódy vrátia Eloquent Builder nakonfigurovaného modelu. Čakajúce znamená stav pending a nevypršané, takže zmeškané potvrdenie zo zoznamu vypadne ešte pred upratovaním. Rovnaké scopes má aj model: pendingFor($person), forSubject($subject), pending(?$moment) a overdue(?$moment).

## Upratovanie vypršaných

```php
Approvals::expireConfirmations();                              // now, every subject type
Approvals::expireConfirmations(now(), ToolCall::class);        // one subject type (class or morph alias)
```

```bash
php artisan approvals:expire-confirmations
# Expired 3 confirmation(s).
```

Príkaz naplánujte rovnako ako approvals:expire:

```php
use Illuminate\Support\Facades\Schedule;

Schedule::command('approvals:expire-confirmations')->everyFiveMinutes();
```

Každé zmeškané čakajúce potvrdenie prejde podmieneným zápisom do expired a ApprovalConfirmationExpired sa spustí raz pre každé potvrdenie; potvrdenie zodpovedané počas upratovania si odpoveď ponechá. approvals:expire sa potvrdení nedotýka, takže aplikácia, ktorá migráciu 0009 nepublikovala, ho môže spúšťať ďalej. Upratovanie slúži udalosti a poriadku v tabuľke — správnosť na ňom nezávisí, lebo zmeškané potvrdenie sa už odmieta a v zoznamoch čakajúcich už nie je.

## Čo sa neuplatňuje

- Autorizačná Gate a vylúčenia — approvals.authorization a approvals.exclusions strážia rozhodnutia o schválení. Potvrdenie svoju osobu výslovne menuje a tá je spravidla autorom toho, čo sa potvrdzuje, preto sa neuplatňuje ani jedno.
- Delegovanie — nikto nemôže potvrdiť v mene danej osoby.
- Odtlačky subjektu — väzbu zabezpečuje hash payloadu.

## Fasáda, DI a akcie

```php
// Facade
Approvals::confirm($confirmation, $user, $hash);

// Injected manager — the same API
public function __construct(private ApprovalsManager $approvals) {}
$this->approvals->confirm($confirmation, $user, $hash);

// Raw actions
app(RequestConfirmationAction::class)->execute($subject, $person, $hash, $expiresAt);
app(ConfirmAction::class)->execute($confirmation, $person, $hash);
app(DeclineAction::class)->execute($confirmation, $person, $reason);
app(ExpireConfirmationsAction::class)->execute($now, $subjectType);
```

## Model a tabuľka

ApprovalConfirmation (konfigurácia approvals.confirmation\_model, vymeniteľný; musí rozširovať model balíka) je v tabuľke approval\_confirmations — pozri Modely a schéma. Relácie subject() a person() (morph-to); pomocníci isPending(?$moment), isOverdue(?$moment), isExpired(?$moment), effectiveStatus(?$moment), isAddressedTo($person), isFor($subject) a matchesPayload($hash). Tabuľka nemá soft deletes — jej históriou je stĺpec status —, staré riadky preto v prípade potreby odstraňujte sami (Prunable); potvrdenie zmazané počas odpovede vyhodí ModelNotFoundException.

## Testovanie

Approvals::fake() zaznamenáva operácie RequestConfirmation, Confirm, Decline a ExpireConfirmations — odmietnuté potvrdenie sa nezaznamená:

```php
$fake = Approvals::fake();

// … exercise the code under test …

$fake->assertConfirmationRequested($toolCall, $user);
$fake->assertConfirmed($toolCall, $user);
$fake->assertNothingDeclined();
$fake->assertConfirmationsExpired(1);
```

ApprovalConfirmation::factory() vytvorí nakonfigurovaný model so stavmi about($subject), askedOf($person) a overdue().

## Prejavte lásku k open source

Tento balík je zadarmo pod licenciou MIT. Ak vám šetrí čas, jednorazový príspevok alebo členstvo na Patreone nám pomôže ho ďalej udržiavať, testovať a dokumentovať.

[Ďalšie spôsoby podpory vrátane kryptomien](https://roundly-consulting.com/sk/podporte-nas.md)

Odoslaním daru súhlasíte s našimi [podmienkami prijímania darov](https://roundly-consulting.com/sk/podmienky-darov.md).

[Podporte našu open-source prácu (otvorí sa v novej karte)](https://donate.stripe.com/dRmeVe8FX5PF1Qd9pXcEw00) [Pridajte sa k nám na Patreone (otvorí sa v novej karte)](https://www.patreon.com/cw/roundly)

## Chcete to zabudovať do svojho produktu?

Naše balíky integrujeme do zákazkových Laravel a AI riešení. Napíšte nám, na čom pracujete, a ozveme sa do 48 hodín.

[Ponuka do 48 hodín](https://roundly-consulting.com/sk/kontakt.md) [Prezrieť všetky balíky](https://roundly-consulting.com/sk/open-source/navody/approvals-for-laravel.md)
