<?php
/**
 * Per-subject automation run (docs/20 §2).
 *
 * @package Bookline
 */

declare( strict_types=1 );

namespace Bookline\Domain\Automation;

use Bookline\Domain\Shared\DomainException;
use DateTimeImmutable;

/**
 * Audit trail for one trigger delivery against one subject.
 *
 * @since 0.1.0
 */
final class AutomationRun {

	/**
	 * Constructor.
	 *
	 * @param int|null                   $id                   Database id.
	 * @param int                        $automation_id        Automation id.
	 * @param string                     $trigger_event_id     Event delivery id.
	 * @param SubjectType                $subject_type         Subject type.
	 * @param int                        $subject_id           Subject id.
	 * @param int|null                   $customer_id          Customer id.
	 * @param AutomationRunStatus        $status               Status.
	 * @param SkipReason|null            $skip_reason          Skip reason.
	 * @param int                        $current_step         Current step index.
	 * @param DateTimeImmutable|null     $scheduled_for       Next step due UTC.
	 * @param DateTimeImmutable|null     $started_at          Started UTC.
	 * @param DateTimeImmutable|null     $completed_at        Completed UTC.
	 * @param AutomationContext          $context              Snapshot.
	 * @param string|null                $error                Error.
	 * @param int|null                   $action_scheduler_id  Job id.
	 * @param list<array<string, mixed>> $steps           Per-step results.
	 * @param DateTimeImmutable          $created_at           Created UTC.
	 * @param DateTimeImmutable          $updated_at           Updated UTC.
	 */
	public function __construct(
		private ?int $id,
		private readonly int $automation_id,
		private readonly string $trigger_event_id,
		private readonly SubjectType $subject_type,
		private readonly int $subject_id,
		private readonly ?int $customer_id,
		private AutomationRunStatus $status,
		private ?SkipReason $skip_reason,
		private int $current_step,
		private ?DateTimeImmutable $scheduled_for,
		private ?DateTimeImmutable $started_at,
		private ?DateTimeImmutable $completed_at,
		private AutomationContext $context,
		private ?string $error,
		private ?int $action_scheduler_id,
		private array $steps,
		private readonly DateTimeImmutable $created_at,
		private DateTimeImmutable $updated_at,
	) {}

	/**
	 * Id.
	 *
	 * @since 0.1.0
	 */
	public function id(): ?int {
		return $this->id;
	}

	/**
	 * Automation id.
	 *
	 * @since 0.1.0
	 */
	public function automation_id(): int {
		return $this->automation_id;
	}

	/**
	 * Trigger event id.
	 *
	 * @since 0.1.0
	 */
	public function trigger_event_id(): string {
		return $this->trigger_event_id;
	}

	/**
	 * Subject type.
	 *
	 * @since 0.1.0
	 */
	public function subject_type(): SubjectType {
		return $this->subject_type;
	}

	/**
	 * Subject id.
	 *
	 * @since 0.1.0
	 */
	public function subject_id(): int {
		return $this->subject_id;
	}

	/**
	 * Customer id.
	 *
	 * @since 0.1.0
	 */
	public function customer_id(): ?int {
		return $this->customer_id;
	}

	/**
	 * Status.
	 *
	 * @since 0.1.0
	 */
	public function status(): AutomationRunStatus {
		return $this->status;
	}

	/**
	 * Skip reason.
	 *
	 * @since 0.1.0
	 */
	public function skip_reason(): ?SkipReason {
		return $this->skip_reason;
	}

	/**
	 * Current step.
	 *
	 * @since 0.1.0
	 */
	public function current_step(): int {
		return $this->current_step;
	}

	/**
	 * Scheduled for.
	 *
	 * @since 0.1.0
	 */
	public function scheduled_for(): ?DateTimeImmutable {
		return $this->scheduled_for;
	}

	/**
	 * Started at.
	 *
	 * @since 0.1.0
	 */
	public function started_at(): ?DateTimeImmutable {
		return $this->started_at;
	}

	/**
	 * Completed at.
	 *
	 * @since 0.1.0
	 */
	public function completed_at(): ?DateTimeImmutable {
		return $this->completed_at;
	}

	/**
	 * Context.
	 *
	 * @since 0.1.0
	 */
	public function context(): AutomationContext {
		return $this->context;
	}

	/**
	 * Error.
	 *
	 * @since 0.1.0
	 */
	public function error(): ?string {
		return $this->error;
	}

	/**
	 * Action scheduler id.
	 *
	 * @since 0.1.0
	 */
	public function action_scheduler_id(): ?int {
		return $this->action_scheduler_id;
	}

	/**
	 * Steps.
	 *
	 * @return list<array<string, mixed>>
	 *
	 * @since 0.1.0
	 */
	public function steps(): array {
		return $this->steps;
	}

	/**
	 * Created.
	 *
	 * @since 0.1.0
	 */
	public function created_at(): DateTimeImmutable {
		return $this->created_at;
	}

	/**
	 * Updated.
	 *
	 * @since 0.1.0
	 */
	public function updated_at(): DateTimeImmutable {
		return $this->updated_at;
	}

	/**
	 * Assign id.
	 *
	 * @param int $id Id.
	 *
	 * @throws DomainException When the id is already assigned.
	 *
	 * @since 0.1.0
	 */
	public function assign_id( int $id ): void {
		if ( null !== $this->id ) {
			throw new DomainException( 'automation_run.id_assigned', 'Run id is already assigned.' );
		}
		$this->id = $id;
	}

	/**
	 * Bind scheduler id.
	 *
	 * @param int $scheduler_id Scheduler id.
	 *
	 * @since 0.1.0
	 */
	public function bind_scheduler( int $scheduler_id ): void {
		$this->action_scheduler_id = $scheduler_id;
	}

	/**
	 * Mark running.
	 *
	 * @param DateTimeImmutable $when When.
	 *
	 * @since 0.1.0
	 */
	public function mark_running( DateTimeImmutable $when ): void {
		$this->status     = AutomationRunStatus::Running;
		$this->started_at = $this->started_at ?? $when;
		$this->updated_at = $when;
	}

	/**
	 * Record a step result and advance.
	 *
	 * @param ActionResult      $result Result.
	 * @param DateTimeImmutable $when   When.
	 * @param array<string, mixed> $meta Optional display metadata.
	 *
	 * @since 0.1.0
	 */
	public function record_step( ActionResult $result, DateTimeImmutable $when, array $meta = [] ): void {
		$this->steps[]        = array_merge( $result->to_step_array(), $meta );
		$this->current_step += $result->advance();
		$this->updated_at = $when;
	}

	/**
	 * Skip a layout-only step without writing a history row.
	 *
	 * @param DateTimeImmutable $when When.
	 *
	 * @since 0.1.0
	 */
	public function skip_layout_step( DateTimeImmutable $when ): void {
		++$this->current_step;
		$this->updated_at = $when;
	}

	/**
	 * Complete.
	 *
	 * @param DateTimeImmutable $when When.
	 *
	 * @since 0.1.0
	 */
	public function mark_completed( DateTimeImmutable $when ): void {
		$this->status       = AutomationRunStatus::Completed;
		$this->completed_at = $when;
		$this->scheduled_for = null;
		$this->updated_at   = $when;
	}

	/**
	 * Skip the whole run.
	 *
	 * @param SkipReason        $reason Reason.
	 * @param DateTimeImmutable $when   When.
	 *
	 * @since 0.1.0
	 */
	public function mark_skipped( SkipReason $reason, DateTimeImmutable $when ): void {
		$this->status       = AutomationRunStatus::Skipped;
		$this->skip_reason  = $reason;
		$this->completed_at = $when;
		$this->scheduled_for = null;
		$this->updated_at   = $when;
	}

	/**
	 * Fail.
	 *
	 * @param string            $error Error.
	 * @param DateTimeImmutable $when  When.
	 *
	 * @since 0.1.0
	 */
	public function mark_failed( string $error, DateTimeImmutable $when ): void {
		$this->status       = AutomationRunStatus::Failed;
		$this->error        = $error;
		$this->completed_at = $when;
		$this->scheduled_for = null;
		$this->updated_at   = $when;
	}

	/**
	 * Cancel.
	 *
	 * @param SkipReason|null   $reason Reason.
	 * @param DateTimeImmutable $when   When.
	 *
	 * @since 0.1.0
	 */
	public function mark_cancelled( ?SkipReason $reason, DateTimeImmutable $when ): void {
		$this->status       = AutomationRunStatus::Cancelled;
		$this->skip_reason  = $reason;
		$this->completed_at = $when;
		$this->scheduled_for = null;
		$this->updated_at   = $when;
	}

	/**
	 * Schedule next step.
	 *
	 * @param DateTimeImmutable $when When.
	 *
	 * @since 0.1.0
	 */
	public function schedule_next( DateTimeImmutable $when ): void {
		$this->status        = AutomationRunStatus::Pending;
		$this->scheduled_for = $when;
		$this->updated_at    = $when;
	}

	/**
	 * Clear a queued step without changing status.
	 *
	 * @param DateTimeImmutable $when When.
	 *
	 * @since 0.1.0
	 */
	public function clear_schedule( DateTimeImmutable $when ): void {
		$this->scheduled_for = null;
		$this->updated_at    = $when;
	}

	/**
	 * Whether the run is still open.
	 *
	 * @since 0.1.0
	 */
	public function is_open(): bool {
		return in_array(
			$this->status,
			[ AutomationRunStatus::Pending, AutomationRunStatus::Running ],
			true
		);
	}
}