<?php

namespace App\Doctor\Service\Repair;

use Symfony\Component\Console\Style\SymfonyStyle;
use Symfony\Component\DependencyInjection\Attribute\AutoconfigureTag;

/**
 * یک گام ترمیمِ دادهٔ ایمپورت‌شده از خزندهٔ نظام پزشکی.
 *
 * هر گام باید idempotent باشد: اجرای دوم روی دادهٔ ترمیم‌شده باید صفر تغییر بدهد.
 * گام‌ها مستقل‌اند و ترتیبشان نباید نتیجه را عوض کند؛ اگر روزی وابستگی پیدا شد،
 * باید صریح مستند شود نه اینکه به ترتیب ثبت در کانتینر تکیه کند.
 *
 * پیاده‌سازی‌ها خودشان flush نمی‌کنند — کامند یک‌بار در پایان flush می‌کند تا کل
 * ترمیم یک تراکنش باشد و --dry-run هیچ‌وقت چیزی ننویسد.
 */
#[AutoconfigureTag('app.doctor_repair_step')]
interface DoctorRepairStep
{
    /** شناسهٔ کوتاه برای --only / --skip (kebab-case). */
    public function name(): string;

    /** یک خط فارسی: این گام چه چیزی را درست می‌کند. */
    public function description(): string;

    public function run(RepairOptions $options, SymfonyStyle $io): RepairResult;
}
