A free open source IT asset/license management system
Added fulfillment action
snipe8bc39efaecbe
diff --git a/app/Actions/CheckoutRequests/FulfillCheckoutRequestAction.php b/app/Actions/CheckoutRequests/FulfillCheckoutRequestAction.phpnew file mode 100644index 0000000000..b1138ed4f2--- /dev/null+++ b/app/Actions/CheckoutRequests/FulfillCheckoutRequestAction.php@@ -0,0 +1,133 @@+<?php++namespace App\Actions\CheckoutRequests;++use App\Enums\CheckoutRequestState;+use App\Exceptions\InvalidCheckoutRequestTransition;+use App\Models\Actionlog;+use App\Models\CheckoutRequest;+use Illuminate\Support\Carbon;++/**+ * Close (or partially close) the fulfillment between a+ * checkout event and the CheckoutRequest it satisfied. Called from+ * the fulfillment hook inside every checkout controller (asset /+ * accessory / consumable / component / license, web + API) after+ * the checkout write commits and the checkout Actionlog row is+ * written.+ *+ * Partial fulfillment: a request for 5 pens that admin only has 3+ * of currently fulfills 3, stays pending, and lets the admin come+ * back for the remaining 2 later. Original `quantity` is+ * immutable so the audit trail preserves what the requester asked+ * for; `fulfilled_quantity` is the running counter of what's+ * actually been delivered. State only flips to `fulfilled` when+ * fulfilled_quantity catches up to quantity.+ *+ * This deliberately silent on the notification side. The requester+ * already gets the standard checkout notification via+ * CheckoutableListener when the checkout event fires. A second+ * "your request was fulfilled" mail would double-notify for one+ * action.+ *+ * This also deliberately does not write its own Actionlog either. Same+ * rationale as the notification skip. The checkout event's+ * actionlog IS the audit trail. The CheckoutRequest row's own new+ * columns (state=fulfilled, fulfilled_at, fulfilled_by,+ * checkout_actionlog_id pointing back at that same actionlog)+ * close the loop without doubling the item's history tab.+ *+ * Idempotent: no-op when the request is already fulfilled or the+ * incoming qty is 0. Safe to fire twice (retry, request-cycle+ * re-entry).+ */+class FulfillCheckoutRequestAction+{+ /**+ * @param CheckoutRequest $request The request to fulfill (or partially fulfill)+ * @param Actionlog|null $checkoutActionlog Actionlog row for the checkout that triggered this fulfillment+ * @param int|null $qty How many units this fulfillment delivered. null = "assume the full remainder"+ * (matches how the single-target checkout flow works — one checkout event+ * handles the whole request). Overfulfill (qty > remaining) is capped at+ * remaining so an accidental large qty upstream can't push fulfilled_quantity+ * past quantity.+ * @param int|null $fulfilledByUserId Admin who did the checkout. Falls back to auth()->id().+ *+ * @throws InvalidCheckoutRequestTransition when the request is+ * canceled or in some other non-pending terminal state.+ */+ public static function run(+ CheckoutRequest $request,+ ?Actionlog $checkoutActionlog = null,+ ?int $qty = null,+ ?int $fulfilledByUserId = null,+ ): void {+ // Idempotency: an already-fulfilled row silently no-ops so+ // callers don't have to gate the hook on "did we already+ // fulfill this in this same POST cycle?".+ if ($request->state === CheckoutRequestState::Fulfilled) {+ return;+ }++ // Only pending rows are eligible. Canceled rows throw so+ // the caller can decide (usually log + skip).+ if ($request->state !== CheckoutRequestState::Pending) {+ throw new InvalidCheckoutRequestTransition(+ $request,+ $request->state,+ CheckoutRequestState::Fulfilled,+ );+ }++ $remaining = $request->remainingQuantity();+ if ($remaining <= 0) {+ // Row is pending but already fully counted. Flip to+ // fulfilled to reconcile the state with the counter.+ self::markFullyFulfilled($request, $checkoutActionlog, $fulfilledByUserId);++ return;+ }++ // Default: this fulfillment covers the whole remaining+ // amount (single-target checkout flow, or an admin who+ // opted in without editing qty). Overfulfill caps at+ // remaining so accidental large qtys upstream don't push+ // fulfilled_quantity past quantity.+ $delta = $qty === null ? $remaining : max(0, min($qty, $remaining));+ if ($delta === 0) {+ return;+ }++ $request->fulfilled_quantity = (int) $request->fulfilled_quantity + $delta;++ if ($request->fulfilled_quantity >= $request->quantity) {+ self::markFullyFulfilled($request, $checkoutActionlog, $fulfilledByUserId);++ return;+ }++ // Partial: counter advanced, state stays pending. Row+ // stays on the admin queue for the remainder.+ $request->save();+ }++ private static function markFullyFulfilled(+ CheckoutRequest $request,+ ?Actionlog $checkoutActionlog,+ ?int $fulfilledByUserId,+ ): void {+ $request->state = CheckoutRequestState::Fulfilled;+ $request->fulfilled_at = Carbon::now();+ $request->fulfilled_by = $fulfilledByUserId ?? auth()->id();+ $request->checkout_actionlog_id = $checkoutActionlog?->id;+ if ($request->fulfilled_quantity < $request->quantity) {+ // Belt: the caller reached here without incrementing+ // fulfilled_quantity past quantity (e.g. remainingQuantity+ // returned 0 branch). Set it to the requested amount so+ // downstream reads never see fulfilled with a lower+ // counter.+ $request->fulfilled_quantity = $request->quantity;+ }+ $request->save();+ }+}