A free open source IT asset/license management system
WIP: First pass at command
Marcus Moore8c489ff49eea
diff --git a/app/Console/Commands/RegenerateAcceptances.php b/app/Console/Commands/RegenerateAcceptances.phpnew file mode 100644index 0000000000..a22b8a53f1--- /dev/null+++ b/app/Console/Commands/RegenerateAcceptances.php@@ -0,0 +1,517 @@+<?php++namespace App\Console\Commands;++use App\Models\Accessory;+use App\Models\AccessoryCheckout;+use App\Models\Asset;+use App\Models\Category;+use App\Models\CheckoutAcceptance;+use App\Models\Component;+use App\Models\Consumable;+use App\Models\LicenseSeat;+use App\Models\User;+use Illuminate\Console\Command;+use Illuminate\Database\Eloquent\Builder;+use Illuminate\Database\Eloquent\Collection as EloquentCollection;+use Illuminate\Database\Eloquent\Model;++/**+ * Re-requests EULA acceptance from users who currently hold items.+ *+ * @phpstan-type Checkoutable Accessory|Asset|Component|Consumable|LicenseSeat+ * @phpstan-type Candidate array{item: Checkoutable, user: User, units: int}+ * @phpstan-type ClassifiedCandidate array{item: Checkoutable, user: User, units: int, qty: int, outcome: string, declined: bool}+ */+class RegenerateAcceptances extends Command+{+ protected $signature = 'snipeit:regenerate-acceptances+ {--category=* : Limit to these category ids (default: all categories requiring acceptance)}+ {--company=* : Limit to these company ids (default: all companies)}+ {--exclude-declined : Skip users whose latest response was a decline (default: re-ask them)}';++ protected $description = 'Re-request EULA acceptance from users who currently hold items';++ /**+ * How many items to load per builder query. Each chunk of items costs one+ * acceptance-history query, however many holders those items turn out to have.+ */+ private const CHUNK_SIZE = 500;++ private const OUTCOME_SEND = 'send';++ private const OUTCOME_COVERED = 'covered';++ private const OUTCOME_DECLINED_EXCLUDED = 'declined_excluded';++ /**+ * Category ids passed via --category, empty when the operator did not filter.+ *+ * @var array<int, string>+ */+ private array $categoryIds = [];++ /**+ * Company ids passed via --company, empty when the operator did not filter.+ *+ * @var array<int, string>+ */+ private array $companyIds = [];++ private bool $excludeDeclined = false;++ /**+ * The would-be rows of the preview table, in the order the builders found them.+ *+ * @var array<int, array{0: string, 1: string, 2: string, 3: int, 4: int}>+ */+ private array $previewRows = [];++ /**+ * How many pairs each checkoutable type contributed to the preview.+ *+ * @var array<string, int>+ */+ private array $sendCountsByType = [];++ private int $candidateCount = 0;++ private int $previouslyDeclined = 0;++ private int $alreadyCovered = 0;++ private int $declinedAndExcluded = 0;++ public function handle(): int+ {+ $this->categoryIds = $this->option('category');+ $this->companyIds = $this->option('company');+ $this->excludeDeclined = (bool) $this->option('exclude-declined');++ $this->findAssetCandidates();+ $this->findLicenseSeatCandidates();+ $this->findAccessoryCandidates();+ $this->findConsumableCandidates();+ $this->findComponentCandidates();++ return $this->printPreview();+ }++ /**+ * Assets assigned directly to a user, plus assets assigned to another asset+ * that is itself assigned to a user.+ *+ * The category is reached through `model.category` rather than the tidier+ * `Asset::category()` relation because `Asset::category()` is a `hasOneThrough`,+ * so Laravel adds a `SoftDeletableHasManyThrough` global scope that excludes+ * assets whose AssetModel is soft-deleted.+ * A live checkout of such an asset asks `requireAcceptance()`+ * instead, which reads `$this->model->category` where `model()` is+ * `belongsTo(...)->withTrashed()` — so it says yes and creates an acceptance row.+ * Going through the relation would make this command regenerate a smaller set than+ * a live checkout creates, which is the divergence it exists to remove.+ */+ private function findAssetCandidates(): void+ {+ Asset::query()+ ->whereHas('model.category', fn (Builder $q) => $this->scopeToRequestedCategories($q))+ ->when($this->companyIds, fn (Builder $q) => $q->whereIn('assets.company_id', $this->companyIds))+ // ->whereNotNull('assets.assigned_to')+ ->whereIn('assets.assigned_type', [User::class, Asset::class])+ ->with('assignedTo')+ ->chunkById(self::CHUNK_SIZE, function (EloquentCollection $assets): void {+ $candidates = [];++ foreach ($assets as $asset) {+ if ($user = $this->resolveHolder($this->assignedTarget($asset))) {+ $candidates[] = ['item' => $asset, 'user' => $user, 'units' => 1];+ }+ }++ $this->classifyChunk($candidates);+ });+ }++ /**+ * License seats, keyed on the asset they are attached to where there is one.+ *+ * `license_seats.assigned_to` is denormalised and unreliable in both directions:+ * the API asset-checkout path attaches a seat without ever stamping it, and five+ * checkin paths clear it while deliberately leaving `asset_id` set. So a seat with+ * an `asset_id` takes its holder from that asset's *current* assignment, and only a+ * seat with no asset falls back to `assigned_to`. Either way a seat yields at most+ * one pair, so seats carrying both columns cannot double-count.+ */+ private function findLicenseSeatCandidates(): void+ {+ LicenseSeat::query()+ ->whereHas('license.category', fn (Builder $q) => $this->scopeToRequestedCategories($q))+ ->when($this->companyIds, fn (Builder $q) => $q->whereHas('license',+ fn (Builder $license) => $license->whereIn('licenses.company_id', $this->companyIds)+ ))+ ->byAssigned()+ ->with(['asset.assignedTo', 'user'])+ ->chunkById(self::CHUNK_SIZE, function (EloquentCollection $seats): void {+ $candidates = [];++ foreach ($seats as $seat) {+ $user = $seat->asset_id+ ? $this->resolveHolder($seat->asset)+ : $seat->user;++ if ($user instanceof User) {+ $candidates[] = ['item' => $seat, 'user' => $user, 'units' => 1];+ }+ }++ $this->classifyChunk($candidates);+ });+ }++ /**+ * Accessories, one pivot row per unit held. Rows assigned to a location are never+ * candidates; rows assigned to an asset resolve to that asset's holder.+ */+ private function findAccessoryCandidates(): void+ {+ Accessory::query()+ ->whereHas('category', fn (Builder $q) => $this->scopeToRequestedCategories($q))+ ->when($this->companyIds, fn (Builder $q) => $q->whereIn('accessories.company_id', $this->companyIds))+ ->whereHas('checkouts', fn (Builder $q) => $q->whereIn('assigned_type', [User::class, Asset::class]))+ ->with(['checkouts' => fn ($q) => $q->whereIn('assigned_type', [User::class, Asset::class])])+ ->chunkById(self::CHUNK_SIZE, function (EloquentCollection $accessories): void {+ $candidates = [];++ foreach ($accessories as $accessory) {+ $unitsPerUser = [];+ $usersById = [];++ foreach ($accessory->checkouts as $checkout) {+ if (! $user = $this->resolveHolder($this->assignedTarget($checkout))) {+ continue;+ }++ $usersById[$user->id] = $user;+ $unitsPerUser[$user->id] = ($unitsPerUser[$user->id] ?? 0) + 1;+ }++ foreach ($unitsPerUser as $userId => $units) {+ $candidates[] = ['item' => $accessory, 'user' => $usersById[$userId], 'units' => $units];+ }+ }++ $this->classifyChunk($candidates);+ });+ }++ /**+ * Consumables, one pivot row per unit held. `consumables_users` has no+ * `assigned_type` column, so consumables are user-only by schema.+ */+ private function findConsumableCandidates(): void+ {+ Consumable::query()+ ->whereHas('category', fn (Builder $q) => $this->scopeToRequestedCategories($q))+ ->when($this->companyIds, fn (Builder $q) => $q->whereIn('consumables.company_id', $this->companyIds))+ ->has('users')+ ->with('users')+ ->chunkById(self::CHUNK_SIZE, function (EloquentCollection $consumables): void {+ $candidates = [];++ foreach ($consumables as $consumable) {+ $unitsPerUser = [];+ $usersById = [];++ foreach ($consumable->users as $user) {+ $usersById[$user->id] = $user;+ $unitsPerUser[$user->id] = ($unitsPerUser[$user->id] ?? 0) + 1;+ }++ foreach ($unitsPerUser as $userId => $units) {+ $candidates[] = ['item' => $consumable, 'user' => $usersById[$userId], 'units' => $units];+ }+ }++ $this->classifyChunk($candidates);+ });+ }++ /**+ * Components, whose holders are always reached through an asset. Unlike the other+ * pivots, `components_assets` carries an `assigned_qty` column rather than writing+ * one row per unit, so units are summed from that column.+ */+ private function findComponentCandidates(): void+ {+ Component::query()+ ->whereHas('category', fn (Builder $q) => $this->scopeToRequestedCategories($q))+ ->when($this->companyIds, fn (Builder $q) => $q->whereIn('components.company_id', $this->companyIds))+ ->has('assets')+ ->with('assets.assignedTo')+ ->chunkById(self::CHUNK_SIZE, function (EloquentCollection $components): void {+ $candidates = [];++ foreach ($components as $component) {+ $unitsPerUser = [];+ $usersById = [];++ foreach ($component->assets as $asset) {+ if (! $user = $this->resolveHolder($asset)) {+ continue;+ }++ $usersById[$user->id] = $user;+ $unitsPerUser[$user->id] = ($unitsPerUser[$user->id] ?? 0) + (int) $asset->pivot->assigned_qty;+ }++ foreach ($unitsPerUser as $userId => $units) {+ $candidates[] = ['item' => $component, 'user' => $usersById[$userId], 'units' => $units];+ }+ }++ $this->classifyChunk($candidates);+ });+ }++ /**+ * Classifies one builder's chunk of candidates and folds them into the preview.+ *+ * @param array<int, Candidate> $candidates+ */+ private function classifyChunk(array $candidates): void+ {+ if ($candidates === []) {+ return;+ }++ $history = $this->acceptanceHistory($candidates);++ foreach ($candidates as $candidate) {+ $key = $this->pairKey($candidate['item']->getKey(), $candidate['user']->getKey());++ $this->recordOutcome($this->classify($candidate, $history[$key] ?? new EloquentCollection));+ }+ }++ /**+ * Decides what to do with one pair by comparing the units it holds against the+ * pending acceptance rows that already cover them.+ *+ * Accepted rows deliberately do not count as coverage — re-asking a holder who+ * accepted is the whole point of the command. Only an in-flight *pending* ask+ * counts, and it counts by quantity rather than existence: a user holding three+ * accessory units with one pending unit is still under-covered for two, so the+ * shortfall is what gets re-requested and the existing pending row is left alone.+ * Where a holder can only ever hold one of a thing (an asset, a license seat) the+ * quantity comparison collapses into "is there a pending row".+ *+ * @param Candidate $candidate+ * @param EloquentCollection<int, CheckoutAcceptance> $history+ * @return ClassifiedCandidate+ */+ private function classify(array $candidate, EloquentCollection $history): array+ {+ $pendingCoverage = $history+ ->filter(fn (CheckoutAcceptance $acceptance) => $acceptance->isPending())+ ->sum(fn (CheckoutAcceptance $acceptance) => $acceptance->qty ?? 1);++ $shortfall = $candidate['units'] - $pendingCoverage;+ $declined = $this->latestResponse($history)?->declined_at !== null;++ return [+ ...$candidate,+ 'qty' => $shortfall,+ 'declined' => $declined,+ 'outcome' => match (true) {+ $shortfall <= 0 => self::OUTCOME_COVERED,+ $declined && $this->excludeDeclined => self::OUTCOME_DECLINED_EXCLUDED,+ default => self::OUTCOME_SEND,+ },+ ];+ }++ /**+ * Tallies one classified pair, adding a preview row when it is one to re-request.+ *+ * @param ClassifiedCandidate $pair+ */+ private function recordOutcome(array $pair): void+ {+ $this->candidateCount++;++ if ($pair['outcome'] === self::OUTCOME_COVERED) {+ $this->alreadyCovered++;++ return;+ }++ if ($pair['declined']) {+ $this->previouslyDeclined++;+ }++ if ($pair['outcome'] === self::OUTCOME_DECLINED_EXCLUDED) {+ $this->declinedAndExcluded++;++ return;+ }++ $type = class_basename($pair['item']);+ $this->sendCountsByType[$type] = ($this->sendCountsByType[$type] ?? 0) + 1;++ $this->previewRows[] = [+ $pair['user']->present()->fullName,+ $pair['item']->present()->name,+ $type,+ $pair['units'],+ $pair['qty'],+ ];+ }++ /**+ * The pair's most recent answered acceptance, or null when they never answered one.+ *+ * "Most recent" is the highest id — acceptance timestamps have second granularity+ * and nothing backdates a row. Pending rows are skipped rather than treated as the+ * latest word, because a re-request's own pending row would otherwise bury the+ * decline it superseded and make a decliner look like someone who never answered.+ *+ * @param EloquentCollection<int, CheckoutAcceptance> $history+ */+ private function latestResponse(EloquentCollection $history): ?CheckoutAcceptance+ {+ return $history+ ->reject(fn (CheckoutAcceptance $acceptance) => $acceptance->isPending())+ ->sortByDesc('id')+ ->first();+ }++ /**+ * Every acceptance row belonging to a pair in this chunk, keyed by (item, user).+ *+ * A chunk always comes from one builder, so one `checkoutable_type` covers it. The+ * query over-fetches — cross pairs (item A × user 2 when only A × 1 and B × 2 are+ * wanted) and each pair's full history — which is harmless and much cheaper than a+ * query per pair. Soft-deleted rows stay invisible: a trashed accepted row making+ * its pair look never-asked is what compliance wants.+ *+ * @param array<int, Candidate> $candidates+ * @return array<string, EloquentCollection<int, CheckoutAcceptance>>+ */+ private function acceptanceHistory(array $candidates): array+ {+ $itemIds = [];+ $userIds = [];++ foreach ($candidates as $candidate) {+ $itemIds[] = $candidate['item']->getKey();+ $userIds[] = $candidate['user']->getKey();+ }++ return CheckoutAcceptance::query()+ ->where('checkoutable_type', $candidates[0]['item']->getMorphClass())+ ->whereIn('checkoutable_id', array_unique($itemIds))+ ->whereIn('assigned_to_id', array_unique($userIds))+ ->get()+ ->groupBy(fn (CheckoutAcceptance $acceptance) => $this->pairKey(+ $acceptance->checkoutable_id,+ $acceptance->assigned_to_id,+ ))+ ->all();+ }++ /**+ * The (checkoutable, user) pair as one lookup key, scoped to a single chunk.+ */+ private function pairKey(int|string $itemId, int|string $userId): string+ {+ return $itemId.'|'.$userId;+ }++ /**+ * Prints what this run would re-request, and creates nothing.+ */+ private function printPreview(): int+ {+ if ($this->candidateCount === 0) {+ $this->info('No users currently hold items requiring acceptance in that scope.');++ return 0;+ }++ if ($this->previewRows !== []) {+ $this->table(['User', 'Item', 'Type', 'Units held', 'Qty'], $this->previewRows);+ }++ $this->info('To re-request: '.count($this->previewRows).'.');++ foreach ($this->sendCountsByType as $type => $count) {+ $this->line(' '.$type.': '.$count);+ }++ $this->info('Previously declined: '.$this->previouslyDeclined.'.');+ $this->info('Already covered by a pending request: '.$this->alreadyCovered.'.');++ if ($this->excludeDeclined) {+ $this->info('Previously declined and excluded: '.$this->declinedAndExcluded.'.');+ }++ $this->info('Nothing was created.');++ return 0;+ }++ /**+ * Reads a model's assignment target, eager-loaded or not.+ *+ * `Asset::assignedTo()` and `AccessoryCheckout::assignedTo()` are declared+ * `morphTo('assigned', ...)`, so the morph name and the method name differ. Eager+ * loading stores the result under the *morph* name — `with('assignedTo')` leaves+ * `$model->assignedTo` null and puts the real model on `$model->assigned`, which is+ * why AssetsTransformer::transformAssignedTo() reads `$asset->assigned`. Reading the+ * loaded relation when it is there and falling back to the method otherwise keeps+ * this correct whether or not the caller eager-loaded it.+ */+ private function assignedTarget(Asset|AccessoryCheckout $model): ?Model+ {+ return $model->relationLoaded('assigned')+ ? $model->getRelation('assigned')+ : $model->assignedTo;+ }++ /**+ * Walks a checkout target down to the user who holds it, mirroring+ * CheckoutableListener::resolveAcceptanceTarget(). A user holds their own items;+ * an asset's items are held by whoever that asset is assigned to. Anything else+ * — a location, an unassigned asset — has no holder. Soft-deleted users are not+ * holders either: every relation this walks is declared withTrashed(), so a deleted+ * user would otherwise come back and be re-asked to accept.+ */+ private function resolveHolder(?Model $target): ?User+ {+ if ($target instanceof User) {+ return $target->trashed() ? null : $target;+ }++ if ($target instanceof Asset) {+ $holder = $this->assignedTarget($target);++ return $holder instanceof User ? $this->resolveHolder($holder) : null;+ }++ return null;+ }++ /**+ * Narrows a Category query to the categories this run cares about.+ *+ * @param Builder<Category> $query+ * @return Builder<Category>+ */+ private function scopeToRequestedCategories(Builder $query): Builder+ {+ return $query->requiresAcceptance()+ ->when($this->categoryIds, function (Builder $query) {+ return $query->whereIn('categories.id', $this->categoryIds);+ });+ }+}