Dovodi_Backend/RELATIONAL_MIGRATION_ROADMAP.md

نقشه راه مهاجرت فیلدهای راویان و مؤلفان به مدل‌های رابطه‌ای

این سند بر اساس مستند نیازمندی‌های کارفرما در فایل کالکشن‌های_راویان.md تهیه شده است و مراحل تبدیل فیلدهای متنی (JSONField / CharField) به مدل‌های رابطه‌ای مستقل به همراه جزئیات پیاده‌سازی بک‌اند، فرانت‌اند و وضعیت پیشرفت را مشخص می‌کند.

---

وضعیت کلی مراحل (Overview & Checklist)

• فاز ۰: سیستم شهرها و مکان‌ها (City) (انجام شده)
• فاز ۱: کنیه‌ها (Kunya / kunyas) — رابطه چندبه‌چند (M2M) (تکمیل شده)
• فاز ۲: ویژگی‌ها (TransmitterFeature / features) — رابطه چندبه‌چند (M2M) (تکمیل شده)
• فاز ۳: وضعیت صحابی بودن (SahabiStatus / sahabi_status) — رابطه تک‌به‌چند (ForeignKey / M2O)
• فاز ۴: تفکیک و اتصال رتبه‌بندی و وثاقت راوی و مؤلف (NarratorRating و reliability_levels) — رابطه ForeignKey / M2O
• فاز ۵: مذاهب راویان (Madhhab / madhabs) — رابطه چندبه‌چند (M2M)
• فاز ۶: داینامیک‌سازی انواع نسبت‌های خویشاوندی (RelationType / relatives) — رابطه ForeignKey در TransmitterRelative
• فاز ۷: مکان‌های چندگانه راوی (narrators_locations) — اتصال چندبه‌چند با ترتیب (sort_order) و نوع (residence / death)

---

جزئیات کامل هر فاز

---

فاز ۰: سیستم شهرها و مکان‌ها (City) ✅

• وضعیت: تکمیل شده
• کارهای انجام‌شده:
  1. ایجاد مدل City در transmitter.py با فیلد چندزبانه title و slug.
  2. اتصال origin_city، lived_in_city و died_in_city در Transmitters و BookAuthor.
  3. اتصال city_of_publication_city در BookEdition.
  4. اعمال مایگریشن و استخراج ۲۲ شهر از رکوردهای قبلی.
  5. ساخت سریالایزر و ویوست AdminCitySerializer و DovodiCityViewSet.
  6. ساخت کامپوننت اختصاصی CitySelect با کش ماژولار و جلوگیری از درخواست تکراری در داشبورد.

---

فاز ۱: کنیه‌ها (Kunya / kunyas) ✅

• وضعیت: تکمیل شده
• نوع رابطه طبق داکیومنت کارفرما: Many-to-Many (M2M)

  یک راوی ممکن است چند کنیه داشته باشد (مثلاً «أبو سعید»، «أبو خالد») و همچنین یک کنیه می‌تواند متعلق به چندین راوی باشد.

• مراحل پیاده‌سازی بک‌اند:
  1. مدل Kunya:
     • فیلد title: عنوان چندزبانه (JSONField شامل زبان‌های fa, ar, ru, en)
     • فیلد slug: اسلاگ خودکار با قابلیت حروف عربی/فارسی
     • زمان‌های created_at و updated_at
  2. اتصال به Transmitters:
     • افزودن رابطه kunyas = models.ManyToManyField('Kunya', blank=True, related_name='transmitters')
     • حفظ فیلد متنی قدیمی kunya جهت پشتیبانی از کدهای گذشته (Backward Compatibility)
     • همگام‌سازی خودکار در متد save() مدل: پر شدن خودکار متن kunya از روی کنیه‌های متصل شده.
  3. دیتامایگریشن (Data Migration):
     • اسکریپت استخراج مقادیر یکتای موجود از فیلدهای Transmitters.kunya.
     • ایجاد رکوردهای Kunya و اتصال M2M آنها به راویان مربوطه بدون از دست رفتن هیچ داده‌ای.
  4. سریالایزرها و APIها:
     • ساخت AdminKunyaSerializer و DovodiKunyaViewSet (با اکشن‌های استاندارد list, create, update, delete و سرچ متنی).
     • ثبت در روت‌های API ادمین (/api/hadis/admin/kunyas/).
     • بروزرسانی AdminTransmitterDetailSerializer و AdminTransmitterListSerializer جهت ارسال و دریافت لیست شناسه‌ها و آبجکت‌های کنیه.
• مراحل پیاده‌سازی داشبورد (فرانت‌اند):
  1. ساخت کامپوننت KunyaSelect (چندانتخابی با تگ / Dropdown Multi-Select + مودال ساخت کنیه جدید با هدر چندزبانه مشابه شهر).
  2. جایگزینی فیلد متنی کنیه در فرم ویرایش/ایجاد راوی با کامپوننت جدید.

---

فاز ۲: ویژگی‌ها (TransmitterFeature / features) ✅

• وضعیت: تکمیل شده
• نوع رابطه طبق داکیومنت کارفرما: Many-to-Many (M2M)

  ویژگی‌های جسمی یا توصیفی راویان و مؤلفان (مانند «أعرج»، «أعمى فی عین واحدة»، «صاحب سر النبی» و...).

• کارهای انجام‌شده:
  1. مدل TransmitterFeature: با فیلدهای title (چندزبانه)، slug (یکتا و خودکار)، متدهای کمکی و تایم‌استمپ‌ها در transmitter.py.
  2. روابط M2M: اتصال features_list در مدل Transmitters و مدل BookAuthor با حفظ فیلد قدیمی features جهت backward compatibility.
  3. دیتامایگریشن (۰۶۰): مهاجرت و اتصال خودکار تمام ویژگی‌های راویان و مؤلفان موجود در دیتابیس به رکوردهای TransmitterFeature.
  4. سریالایزرها و APIها:
     • تعریف AdminTransmitterFeatureSerializer و ویوست DovodiTransmitterFeatureViewSet.
     • ثبت مسیرهای /api/hadis/admin/dovodi-transmitter-features/ و /api/hadis/admin/transmitter-features/.
     • پشتیبانی از features_list و features_detail به همراه سینک خودکار دوطرفه در AdminTransmitterListSerializer, AdminTransmitterDetailSerializer و AdminBookAuthorSerializer.
  5. داشبورد (فرانت‌اند):
     • ساخت کامپوننت ماژولار و کش‌شده FeatureSelect.tsx با قابلیت چندانتخابی نشان‌ها (badges) و مودال ایجاد سریع ویژگی با هدر استاندارد (آیکون کره چندزبانه) و فوتر چسبان.
     • ادغام در صفحه ویرایش/ساخت راوی (TransmitterFormPage.tsx).
     • ادغام در صفحه ویرایش/ساخت مؤلف کتاب (ReferenceAuthorFormPage.tsx).
     • افزودن تب، ستون‌ها و دیالوگ مدیریت کامل ویژگی‌ها به صفحه آرشیو راویان (TransmittersArchivePage.tsx).

---

فاز ۳: وضعیت صحابی بودن (SahabiStatus / companion_type) 🔲

• وضعیت: در انتظار اجرا
• نوع رابطه طبق داکیومنت کارفرما: Many-to-One / ForeignKey

  راوی دارای یک وضعیت مشخص صحابی بودن است.

• مراحل پیاده‌سازی بک‌اند:
  1. مدل SahabiStatus:
     • فیلد code یا slug: کد شناسه (مانند sahabi, saw_prophet, contemporary, minor_sahabi, mukhadram, unproven, disputed)
     • فیلد title: چندزبانه (JSONField) به ۴ زبان بر اساس ۷ رکورد استاندارد داکیومنت کارفرما:
       1. صحابی (сподвижник)
       2. رؤیت پیامبر (видел)
       3. درک زمان پیامبر (застал)
       4. صحابی صغیر (малый)
       5. مخضرم (мухадрам)
       6. اثبات‌نشده (недоказано)
       7. اختلافی / محل بحث (спорный)
  2. اتصال به Transmitters:
     • فیلد sahabi_status = models.ForeignKey(SahabiStatus, null=True, blank=True, on_delete=models.SET_NULL, related_name='transmitters')
     • سینک خودکار با فیلد متنی قدیمی companion_type.
  3. مایگریشن و Seeding:
     • اعمال مایگریشن و ایجاد خودکار ۷ رکورد پیش‌فرض فوق به همراه ترجمه عربی، فارسی، انگلیسی و روسی.
  4. API و سریالایزر:
     • اندپوینت /api/hadis/admin/sahabi-statuses/ و پوشش در جزئیات راوی.
• مراحل پیاده‌سازی داشبورد:
  1. افزودن دراپ‌داون تک‌انتخابی وضعیت صحابی به فرم راوی با امکان پاک کردن یا تغییر وضعیت.

---

فاز ۴: تفکیک و اتصال رتبه‌بندی و وثاقت راوی و مؤلف (NarratorRating و reliability_levels) 🔲

• وضعیت: در انتظار اجرا
• نوع رابطه طبق داکیومنت کارفرما: ForeignKey (M2O) برای هر دو فیلد

  در معماری کارفرما دو مفهوم متمایز وجود دارد: ۱. reliability_levels (۱۱ سطح کلی اعتبار: ثقه، صدوق، ضعیف، کذاب و...) ۲. narrator_ratings (عبارت دقیق ارزیابی رجالی: ثقة ثبت، صدوق له أوهام و...)

• مراحل پیاده‌سازی بک‌اند:
  1. بررسی و یکپارچه‌سازی مدل TransmitterReliability فعلی با ۱۱ سطح استاندارد کارفرما.
  2. استفاده از مدل BookAuthorRutba یا ایجاد مدل عمومی NarratorRating (با ترجمه چندزبانه) و اتصال آن به عنوان rating هم به راوی (Transmitters.narrator_rating) و هم به مؤلف (BookAuthor.rutba_status).
  3. تبدیل فیلد BookAuthor.scholarity به کلید خارجی به TransmitterReliability.
  4. سریالایزرها و مایگریشن داده‌ها.
• مراحل پیاده‌سازی داشبورد:
  1. نمایش هر دو دراپ‌داون «سطح وثاقت کلی» و «عبارت ارزیابی نهایی» در فرم راوی و مؤلف.

---

فاز ۵: مذاهب راویان (Madhhab / madhabs) 🔲

• وضعیت: در انتظار اجرا
• نوع رابطه طبق داکیومنت کارفرما: Many-to-Many (M2M)

  کارفرما مذهب را به عنوان یک کالکشن چندزبانه با رابطه M2M در نظر گرفته است (تا بتوان مذاهب گوناگون، انشعابات، یا نظرات متعدد درباره مذهب راوی را ثبت کرد).

• مراحل پیاده‌سازی بک‌اند:
  1. ساخت مدل Madhhab با فیلد چندزبانه name/title و slug.
  2. ایجاد رابطه M2M روی Transmitters.madhhabs = models.ManyToManyField('Madhhab', blank=True, related_name='transmitters').
  3. حفظ فیلد madhhab قبلی (shia/sunni) و سینک مقدار پیش‌فرض با آن.
  4. ساخت Seed داده‌های مذاهب و ثبت API ادمین.
• مراحل پیاده‌سازی داشبورد:
  1. تبدیل سلکتور دو گزینه‌ای به دراپ‌داون داینامیک چندزبانه.

---

فاز ۶: داینامیک‌سازی انواع نسبت‌های خویشاوندی (RelationType / relatives) 🔲

• وضعیت: در انتظار اجرا
• نوع رابطه طبق داکیومنت کارفرما: ForeignKey در جدول خویشاوندان راوی
• مراحل پیاده‌سازی بک‌اند:
  1. ساخت مدل RelationType شامل فیلد کلیدی و title چندزبانه (برای جایگزینی دیکشنری هاردکد شده RELATION_TYPE_MAP).
  2. متصل کردن TransmitterRelative.relation_type_ref = models.ForeignKey(RelationType, ...) به مدل جدید.
  3. دیتامایگریشن برای انتقال ۲۹ نسبت خویشاوندی موجود به رکوردهای جدول جدید.
  4. اندپوینت‌های مدیریت نسبت‌ها در پنل ادمین.
• مراحل پیاده‌سازی داشبورد:
  1. دریافت داینامیک لیست نسبت‌های خویشاوندی از API به جای گزینه‌های استاتیک در فرم خویشاوندان راوی.

---

فاز ۷: مکان‌های چندگانه راوی (narrators_locations) 🔲

• وضعیت: در انتظار اجرا
• نوع رابطه طبق داکیومنت کارفرما: رابطه چندبه‌چند با متادیتا (sort_order, type)

  برای مواردی که راوی در طول حیات خود در چند شهر مختلف سکونت داشته است.

• مراحل پیاده‌سازی بک‌اند:
  1. ایجاد مدل واسط TransmitterLocationRecord با فیلدهای transmitter, city, type (residence / death), sort_order.
  2. سینک دوطرفه با فیلدهای origin_city, lived_in_city, died_in_city فعلی.
  3. سریالایزرها و پشتیبانی در داشبورد.

---

راهنمای بروزرسانی این سند

پس از انجام هر مرحله توسط هوش مصنوعی، تیک چک‌باکس مربوطه در بخش بالا از [ ] به [x] تبدیل شده و وضعیت آن فاز از در انتظار اجرا به تکمیل شده تغییر داده خواهد شد.