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

---

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

- [x] **فاز ۰: سیستم شهرها و مکان‌ها (`City`)** *(انجام شده)*
- [x] **فاز ۱: کنیه‌ها (`Kunya` / `kunyas`)** — رابطه چندبه‌چند (M2M) *(تکمیل شده)*
- [x] **فاز ۲: ویژگی‌ها (`TransmitterFeature` / `features`)** — رابطه چندبه‌چند (M2M) *(تکمیل شده)*
- [x] **فاز ۳: وضعیت صحابی بودن (`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`:** با فیلدهای `title` (چندزبانه به ۴ زبان: fa, ar, en, ru)، `slug` (یکتا و خودکار)، متدهای هلپر `get_title()` و تایم‌استمپ‌ها.
  2. **اتصال به `Transmitters`:** افزودن کلید خارجی `sahabi_status = models.ForeignKey('hadis.SahabiStatus', on_delete=models.SET_NULL, null=True, blank=True, related_name='transmitters')` با حفظ و همگام‌سازی خودکار فیلد قدیمی `companion_type`.
  3. **مایگریشن و Seeding (۰۶۱):** ساخت جدول و ایجاد خودکار ۷ رکورد استاندارد داکیومنت کارفرما به زبان‌های عربی، فارسی، انگلیسی و روسی:
     1. صحابی (`companion` / `сподвижник`)
     2. رؤیت پیامبر (`saw-the-prophet` / `видел`)
     3. درک زمان پیامبر (`contemporary` / `застал`)
     4. صحابی صغیر (`minor-companion` / `малый`)
     5. مخضرم (`mukhadram` / `мухадрам`)
     6. اثبات‌نشده (`unproven` / `недоказано`)
     7. اختلافی / محل بحث (`disputed` / `спорный`)
  4. **سریالایزرها و APIها:**
     - ساخت `AdminSahabiStatusSerializer` و `DovodiSahabiStatusViewSet`.
     - ثبت در روت‌های `/api/hadis/admin/dovodi-sahabi-statuses/` و `/api/hadis/admin/sahabi-statuses/`.
     - پشتیبانی در `AdminTransmitterListSerializer` و `AdminTransmitterDetailSerializer` همراه با همگام‌سازی دوطرفه.
  5. **داشبورد (فرانت‌اند):**
     - ساخت کامپوننت ماژولار تک‌انتخابی `SahabiStatusSelect.tsx` (با کش مشترک در سطح حافظه، قابلیت جستجو و پاک کردن انتخاب، همراه با مودال ساخت سریع با هدر چندزبانه استاندارد و فوتر چسبان).
     - قرارگیری فیلد وضعیت صحابی در فرم راوی (`TransmitterFormPage.tsx`).
     - افزودن تب، ستون‌ها و دیالوگ مدیریت کامل «وضعیت صحابی» به صفحه آرشیو راویان (`TransmittersArchivePage.tsx`).

---

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