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

---

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

- [x] **فاز ۰: سیستم شهرها و مکان‌ها (`City`)** *(انجام شده)*
- [x] **فاز ۱: کنیه‌ها (`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`: چندزبانه (`JSONField`)
     - فیلد `slug`: اسلاگ یکتا
     - متدهای کمکی جهت دریافت عنوان به زبان‌های مختلف
  2. **اتصال به راویان و مؤلفان:**
     - رابطه M2M در `Transmitters.features_list = models.ManyToManyField('TransmitterFeature', blank=True, related_name='transmitters')`
     - رابطه M2M در `BookAuthor.features_list = models.ManyToManyField('TransmitterFeature', blank=True, related_name='authors')`
     - همگام‌سازی در متد `save()` با فیلدهای متنی قدیمی `features`.
  3. **دیتامایگریشن:**
     - انتقال ویژگی‌های متنی موجود در دیتابیس به رکوردهای یکتای `TransmitterFeature` و اتصال به راویان و مؤلفان.
  4. **سریالایزر و API:**
     - ویوست و سریالایزر `AdminTransmitterFeatureViewSet` در اندپوینت `/api/hadis/admin/transmitter-features/`.
     - پشتیبانی در سریالایزرهای راوی و مؤلف.
* **مراحل پیاده‌سازی داشبورد:**
  1. کامپوننت `FeatureSelect` چندانتخابی همراه با مودال ساخت سریع ویژگی.
  2. قرارگیری در تب ویژگی‌های راوی و صفحه مؤلف کتاب.

---

### فاز ۳: وضعیت صحابی بودن (`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]` تبدیل شده و وضعیت آن فاز از `در انتظار اجرا` به `تکمیل شده` تغییر داده خواهد شد.