Skip to content

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.php
new file mode 100644
index 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();
+ }
+}