50 lines
2.0 KiB
PHP
50 lines
2.0 KiB
PHP
<?php
|
|
|
|
declare(strict_types=1);
|
|
|
|
namespace MeshVault\Indexer\Contracts;
|
|
|
|
use MeshVault\Indexer\ScannedFile;
|
|
|
|
/**
|
|
* Explicit, user-confirmed import grouping with decision persistence for replay/idempotency.
|
|
* Contrasts with LegacyGuessedImportGroupingAdapter which performs fresh stateless lookups.
|
|
*/
|
|
interface ExplicitImportGroupingAdapterInterface
|
|
{
|
|
/**
|
|
* Resolve or create a model for the given file under explicit user confirmation.
|
|
*
|
|
* @param string $sourcePath Absolute source root
|
|
* @param ScannedFile $file File with relativePath, size, hash
|
|
* @param array<string, mixed> $context Optional confirmation context:
|
|
* - 'model_id' => int: user-selected existing model (must match folder/title)
|
|
* - 'model_name' => string: user-provided model title
|
|
* - 'folder_path' => string: user-provided folder path (must exist or be creatable)
|
|
* - 'create_new' => bool: force new model even if match exists
|
|
* @return int Model ID (existing or newly created)
|
|
* @throws \DomainException If context conflicts with existing catalog state
|
|
* @throws \InvalidArgumentException If context is malformed
|
|
*/
|
|
public function modelFor(string $sourcePath, ScannedFile $file, array $context = []): int;
|
|
|
|
/**
|
|
* Persist the user's grouping decision for replay/idempotency.
|
|
* Called after successful import job creation with confirmed context.
|
|
*
|
|
* @param int $jobId Import job ID
|
|
* @param list<array{source_path: string, model_id: int, context: array}> $decisions
|
|
* @return void
|
|
*/
|
|
public function persistDecisions(int $jobId, array $decisions): void;
|
|
|
|
/**
|
|
* Recover grouping decisions for a resumed/interrupted job.
|
|
* Returns model_id per source_path, or empty array if no decision was recorded.
|
|
*
|
|
* @param int $jobId Import job ID
|
|
* @return array<string, int> Map of source_path => model_id
|
|
*/
|
|
public function recoverDecisions(int $jobId): array;
|
|
}
|