<?php

namespace App\Services\Import\Contracts;

use App\Models\Import;

interface EntityHandlerInterface
{
    /**
     * Process a single row for this entity.
     *
     * @param  Import  $import  The import instance
     * @param  array  $mapped  Mapped data for this entity
     * @param  array  $raw  Raw row data
     * @param  array  $context  Additional context (previous entity results, etc.)
     * @return array Result with action, entity instance, applied_fields, etc.
     */
    public function process(Import $import, array $mapped, array $raw, array $context = []): array;

    /**
     * Validate mapped data before processing.
     *
     * @param  array  $mapped  Mapped data for this entity
     * @return array Validation result ['valid' => bool, 'errors' => array]
     */
    public function validate(array $mapped): array;

    /**
     * Get the entity class name this handler manages.
     *
     * @return string
     */
    public function getEntityClass(): string;

    /**
     * Resolve existing entity by key/reference.
     *
     * @param  array  $mapped  Mapped data for this entity
     * @param  array  $context  Additional context
     * @return mixed|null Existing entity instance or null
     */
    public function resolve(array $mapped, array $context = []): mixed;
}