From 28725792d7ea59934cca25b630a844c85cd1d398 Mon Sep 17 00:00:00 2001
From: hamed <15238-genius.ha@users.noreply.drupalcode.org>
Date: Mon, 20 Jul 2026 11:17:39 +0330
Subject: [PATCH] feat: update purge commands documentation for clarity on
 production usage

---
 docs/api/doctor-import.md                  | 15 ++++++++++++++-
 src/Doctor/Command/PurgeDoctorsCommand.php |  3 ++-
 2 files changed, 16 insertions(+), 2 deletions(-)

diff --git a/docs/api/doctor-import.md b/docs/api/doctor-import.md
index 1331c68f..5bff4c04 100644
--- a/docs/api/doctor-import.md
+++ b/docs/api/doctor-import.md
@@ -285,6 +285,10 @@ php bin/console app:doctors:purge-unclaimed --all-sources   # هر منبعِ غ
 > فقط وقتی حذف می‌شود که غیرفعال (`status=0`) و با موبایلِ `imp_` باشد — تا کاربر واقعی
 > به‌اشتباه پاک نشود.
 
+> ✅ **این کامند روی پروداکشن قابل اجراست** — با `--i-know-this-is-prod`. برای همین هم
+> ساخته شده: پاک‌کردن دستهٔ اشتباهِ خزنده از روی سایت زنده، بدون دست‌زدن به پزشکان واقعی.
+> با `app:doctors:purge` اشتباه نگیر (پایین) که هرگز روی prod اجرا نمی‌شود.
+
 ### پاک‌سازی کامل برای دیتابیس تست
 
 حذف **همهٔ** پزشکان + داده‌های وابسته (FK-safe) برای شروع تمیز:
@@ -296,4 +300,13 @@ php bin/console app:doctors:purge --force    # حذف واقعی + کاربرا
 
 > ⚠️ مخرب — `appointments`/`comments`/`rates` را هم پاک می‌کند. **فقط در محیط
 > `dev`/`test` اجرا می‌شود**؛ روی هر `APP_ENV` دیگری (از جمله `prod`) بدون هیچ راه
-> فراری با خطا متوقف می‌شود.
+> فراری با خطا متوقف می‌شود. سوییچ `--i-know-this-is-prod` اینجا **وجود ندارد** —
+> تنها کامند این خانواده است که هیچ راهی برای اجرا روی prod ندارد.
+
+### خلاصهٔ تفاوت دو کامند حذف
+
+| | `purge-unclaimed` | `purge` |
+|---|---|---|
+| چه چیزی حذف می‌شود | فقط پزشکان خزنده‌ای که claim نشده‌اند | **همهٔ** پزشکان، حتی دستی و claim‌شده |
+| اجرا روی prod | ✅ با `--i-know-this-is-prod` | ❌ هرگز |
+| کاربرد | پاک‌کردن دستهٔ اشتباهِ ایمپورت از سایت زنده | ساخت دیتابیس تمیز برای تست |
diff --git a/src/Doctor/Command/PurgeDoctorsCommand.php b/src/Doctor/Command/PurgeDoctorsCommand.php
index 2c79f7b4..756960b5 100644
--- a/src/Doctor/Command/PurgeDoctorsCommand.php
+++ b/src/Doctor/Command/PurgeDoctorsCommand.php
@@ -14,7 +14,8 @@ use Symfony\Component\Console\Style\SymfonyStyle;
  * پاک‌سازی کامل همهٔ پزشکان و داده‌های وابسته — برای ساختِ یک دیتابیس تمیزِ تست.
  *
  * مخرب است: بدون --force فقط تعداد رکوردهای هر جدول را گزارش می‌دهد (dry-run).
- * روی prod نیازمند --i-know-this-is-prod است.
+ * فقط در dev/test اجرا می‌شود و برای prod هیچ راه فراری ندارد — برخلاف
+ * app:doctors:purge-unclaimed که با --i-know-this-is-prod روی prod هم اجرا می‌شود.
  *
  *   php bin/console app:doctors:purge            # فقط گزارش
  *   php bin/console app:doctors:purge --force     # پاک‌سازی