TenantAtlas/app/Support/Tenants/TenantOperabilityReasonCode.php

<?php

declare(strict_types=1);

namespace App\Support\Tenants;

use App\Support\ReasonTranslation\NextStepOption;
use App\Support\ReasonTranslation\ReasonResolutionEnvelope;

enum TenantOperabilityReasonCode: string
{
    case WorkspaceMismatch = 'workspace_mismatch';
    case TenantNotEntitled = 'tenant_not_entitled';
    case MissingCapability = 'missing_capability';
    case WrongLane = 'wrong_lane';
    case SelectorIneligibleLifecycle = 'selector_ineligible_lifecycle';
    case TenantNotArchived = 'tenant_not_archived';
    case TenantAlreadyArchived = 'tenant_already_archived';
    case OnboardingNotResumable = 'onboarding_not_resumable';
    case CanonicalViewFollowupOnly = 'canonical_view_followup_only';
    case RememberedContextStale = 'remembered_context_stale';

    public function operatorLabel(): string
    {
        return match ($this) {
            self::WorkspaceMismatch => 'Workspace context changed',
            self::TenantNotEntitled => 'Tenant access removed',
            self::MissingCapability => 'Permission required',
            self::WrongLane => 'Available from a different surface',
            self::SelectorIneligibleLifecycle => 'Tenant unavailable in the current lifecycle',
            self::TenantNotArchived => 'Tenant is not archived',
            self::TenantAlreadyArchived => 'Tenant already archived',
            self::OnboardingNotResumable => 'Onboarding cannot be resumed',
            self::CanonicalViewFollowupOnly => 'Follow-up requires tenant context',
            self::RememberedContextStale => 'Saved tenant context is stale',
        };
    }

    public function shortExplanation(): string
    {
        return match ($this) {
            self::WorkspaceMismatch => 'The current workspace scope no longer matches this tenant interaction.',
            self::TenantNotEntitled => 'The current actor is no longer entitled to this tenant.',
            self::MissingCapability => 'The current actor is missing the capability required for this tenant action.',
            self::WrongLane => 'This question can only be completed from a different tenant interaction lane.',
            self::SelectorIneligibleLifecycle => 'This tenant lifecycle is not selectable from the current surface.',
            self::TenantNotArchived => 'This action requires an archived tenant, but the tenant is still active or onboarding.',
            self::TenantAlreadyArchived => 'The tenant is already archived, so there is nothing else to do for this action.',
            self::OnboardingNotResumable => 'This onboarding session can no longer be resumed from the current lifecycle state.',
            self::CanonicalViewFollowupOnly => 'This canonical workspace view is informational only and cannot complete tenant follow-up directly.',
            self::RememberedContextStale => 'The remembered tenant context is no longer valid for the current tenant selector state.',
        };
    }

    public function actionability(): string
    {
        return match ($this) {
            self::TenantAlreadyArchived => 'non_actionable',
            self::SelectorIneligibleLifecycle, self::TenantNotArchived, self::OnboardingNotResumable, self::CanonicalViewFollowupOnly, self::RememberedContextStale => 'prerequisite_missing',
            default => 'permanent_configuration',
        };
    }

    /**
     * @return array<int, NextStepOption>
     */
    public function nextSteps(): array
    {
        return match ($this) {
            self::TenantAlreadyArchived => [],
            self::MissingCapability => [
                NextStepOption::instruction('Ask a tenant Owner to grant the required capability.', scope: 'tenant'),
            ],
            self::TenantNotEntitled, self::WorkspaceMismatch => [
                NextStepOption::instruction('Return to an entitled tenant context before retrying.', scope: 'workspace'),
            ],
            self::WrongLane, self::CanonicalViewFollowupOnly => [
                NextStepOption::instruction('Open the tenant-specific management surface for follow-up.', scope: 'tenant'),
            ],
            self::SelectorIneligibleLifecycle, self::RememberedContextStale => [
                NextStepOption::instruction('Refresh the tenant selector and choose an eligible tenant context.', scope: 'tenant'),
            ],
            self::TenantNotArchived => [
                NextStepOption::instruction('Archive the tenant before retrying this action.', scope: 'tenant'),
            ],
            self::OnboardingNotResumable => [
                NextStepOption::instruction('Review the onboarding record and start a new onboarding flow if needed.', scope: 'tenant'),
            ],
        };
    }

    /**
     * @param  array<string, mixed>  $context
     */
    public function toReasonResolutionEnvelope(string $surface = 'detail', array $context = []): ReasonResolutionEnvelope
    {
        return new ReasonResolutionEnvelope(
            internalCode: $this->value,
            operatorLabel: $this->operatorLabel(),
            shortExplanation: $this->shortExplanation(),
            actionability: $this->actionability(),
            nextSteps: $this->nextSteps(),
            showNoActionNeeded: $this->actionability() === 'non_actionable',
            diagnosticCodeLabel: $this->value,
        );
    }
}