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

---

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

- [x] **فاز ۰: سیستم شهرها و مکان‌ها (`City`)** *(انجام شده)*
- [x] **فاز ۱: کنیه‌ها (`Kunya` / `kunyas`)** — رابطه چندبه‌چند (M2M) *(تکمیل شده)*
- [x] **فاز ۲: ویژگی‌ها (`TransmitterFeature` / `features`)** — رابطه چندبه‌چند (M2M) *(تکمیل شده)*
- [x] **فاز ۳: وضعیت صحابی بودن (`SahabiStatus` / `sahabi_status`)** — رابطه تک‌به‌چند (ForeignKey / M2O) *(تکمیل شده)*
- [—] **فاز ۴: تفکیک و اتصال رتبه‌بندی و وثاقت راوی و مؤلف (`NarratorRating` و `reliability_levels`)** — *(صرف‌نظر شد / اسکیپ طبق تصمیم: سیستم فعلی نظرات رجالی پاسخگو است)*
- [x] **فاز ۵: مذاهب راویان (`Madhhab` / `madhabs`)** — رابطه چندبه‌چند (M2M) *(تکمیل شده)*
- [x] **فاز ۶: داینامیک‌سازی انواع نسبت‌های خویشاوندی (`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`) ⏭️
* **وضعیت:** `صرف‌نظر شد (Skipped)`
* **علت و تصمیم اتخاذشده:**
  - مفهوم ارزیابی‌های تفصیلی رجالی (`narrator_ratings`) در حال حاضر به‌صورت کامل، غنی و پیشرفته در سیستم نظرات رجالی (`TransmitterOpinion` و `ScholarlyOpinion`) پیاده‌سازی شده و نیازی به تغییر یا مدل تکراری ندارد.
  - برای فیلدهای وثاقت و رتبه راوی و مؤلف (`TransmitterReliability` و `BookAuthorRutba`) دست ادمین باز گذاشته شده تا بر اساس نیاز خود رتبه‌ها را مدیریت و انتخاب کنند و نیازی به ادغام جبری آنها نیست.
  - بنابراین این فاز طبق تصمیم اسکیپ شده و منطق فعلی بدون تغییر حفظ گردید.

---

### فاز ۵: مذاهب راویان (`Madhhab` / `madhabs`) ✅
* **وضعیت:** `تکمیل شده`
* **نوع رابطه طبق داکیومنت کارفرما:** **Many-to-Many (M2M)**
  > کارفرما مذهب را به عنوان یک کالکشن چندزبانه با رابطه M2M در نظر گرفته است (تا بتوان مذاهب گوناگون، انشعابات، یا نظرات متعدد درباره مذهب راوی را ثبت کرد).
* **کارهای انجام‌شده:**
  1. **مدل `Madhhab`:** ایجاد در `transmitter.py` با فیلدهای `title` (چندزبانه به ۴ زبان: fa, ar, en, ru)، `slug` (یکتا و خودکار)، متد هلپر `get_title()` و تایم‌استمپ‌ها.
  2. **اتصال رابطه چندبه‌چند به `Transmitters`:** افزودن فیلد `madhhabs = models.ManyToManyField('hadis.Madhhab', blank=True, related_name='transmitters')` به همراه حفظ کامل فیلد متنی قدیمی `madhhab` جهت سازگاری به عقب (backward compatibility).
  3. **مایگریشن و Seeding دیتابیس (۰۶۲):**
     - ساخت جدول و Seed کردن ۵ مذهب استاندارد داکیومنت کارفرما (شیعه، اهل سنت، زیدی، واقفی، فتحی).
     - انتقال خودکار دیتای تمام ۷۹ راوی موجود در دیتابیس به رکوردهای متناظر M2M (۳۴ راوی شیعه و ۴۵ راوی سنی).
  4. **سریالایزرها و APIها:**
     - ساخت `AdminMadhhabSerializer` و `DovodiMadhhabViewSet`.
     - ثبت روت‌های `/api/hadis/admin/dovodi-madhhabs/` و `/api/hadis/admin/madhhabs/`.
     - پشتیبانی کامل در `AdminTransmitterListSerializer` و `AdminTransmitterDetailSerializer` با ارسال فیلدهای `madhhabs` (لیست شناسه‌ها) و `madhhabs_detail` و همگام‌سازی دوطرفه خودکار با فیلد استرینگ قدیمی `madhhab` در توابع `create` و `update`.
  5. **داشبورد (فرانت‌اند):**
     - ساخت کامپوننت ماژولار چندانتخابی `MadhhabSelect.tsx` (با کش ماژولار در سطح حافظه، قابلیت افزودن سریع و ریموو بج‌های مذهب، سرچ و فیلتر Popover و مودال ایجاد مذهب جدید با هدر چندزبانه، نمایش کامل توضیحات بدون برش و فوتر چسبان).
     - جایگزینی سلکتور استاتیک قبلی با `MadhhabSelect` در سایدبار فرم راوی (`TransmitterSidebar.tsx` و `TransmitterFormPage.tsx`) با همگام‌سازی داینامیک.
     - افزودن تب مدیریت «مذاهب»، ستون‌های جدول و دیالوگ مدیریت کامل (`MadhhabDialog`) در صفحه آرشیو راویان (`TransmittersArchivePage.tsx`).
     - بیلد نهایی پروژه فرانت‌اند با موفقیت انجام شد (بدون هیچ خطای TypeScript یا کامپایل).

---

### فاز ۶: داینامیک‌سازی انواع نسبت‌های خویشاوندی (`RelationType` / `relatives`) ✅
* **وضعیت:** `تکمیل شده`
* **نوع رابطه طبق داکیومنت کارفرما:** **ForeignKey در جدول خویشاوندان راوی**
  > انواع نسبت‌های خویشاوندی به عنوان یک کالکشن مستقل چندزبانه با کلید شناسایی انگلیسی (`code`) و عناوین به ۴ زبان (`fa`, `ar`, `en`, `ru`) پیاده‌سازی شدند.
* **کارهای انجام‌شده:**
  1. **مدل `RelationType`:** ایجاد در `transmitter.py` با فیلدهای `code` (یکتا و کلید تطبیق انگلیسی)، `title` (چندزبانه به ۴ زبان: fa, ar, en, ru)، `slug` (یکتا و خودکار)، متد هلپر `get_title()` و تایم‌استمپ‌ها.
  2. **اتصال رابطه رابطه‌ای به `TransmitterRelative`:** افزودن کلید خارجی `relation_type_ref = models.ForeignKey('hadis.RelationType', on_delete=models.SET_NULL, null=True, blank=True, related_name='relative_links')` با حفظ سازگاری کامل به عقب با فیلد متنی قدیمی `relation_type` و همگام‌سازی خودکار در متد `save()`.
  3. **مایگریشن و Seeding دیتابیس (۰۶۳):**
     - ایجاد جدول `RelationType` و Seed کردن تمام ۲۹ نسبت خویشاوندی موجود در پروژه به همراه عناوین کامل عربی، فارسی، انگلیسی و روسی.
     - مهاجرت و اتصال خودکار هر ۹۱۱ رکورد موجود در جدول `TransmitterRelative` به رکوردهای متناظر در جدول جدید بر اساس کد نسبت.
  4. **سریالایزرها و APIها:**
     - ساخت `AdminRelationTypeSerializer` و `DovodiRelationTypeViewSet`.
     - ثبت روت‌های `/api/hadis/admin/dovodi-relation-types/` و `/api/hadis/admin/relation-types/`.
     - پشتیبانی از جستجو بر اساس `title`, `slug`, `code`.
  5. **داشبورد (فرانت‌اند):**
     - افزودن اینترفیس `RelationTypeItem` و متدهای کامل API (`getRelationTypesArchive`, `createRelationTypeArchive`, `updateRelationTypeArchive`, `deleteRelationTypeArchive`) در `transmitters.ts`.
     - طراحی و ساخت مودال کامل `RelationTypeDialog` با هدر استاندارد چندزبانه، فیلد عنوان چندزبانه، فیلد شناسه انگلیسی (`code`)، اسلاگ و فوتر چسبان با تأیید حذف.
     - افزودن تب «انواع نسبت‌ها»، ستون‌های شناسه، عنوان، کد انگلیسی و اسلاگ به همراه فیلتر سرچ و حذف تکی و دسته‌جمعی در صفحه آرشیو راویان (`TransmittersArchivePage.tsx`).
     - بیلد نهایی پروژه فرانت‌اند با موفقیت و بدون هیچ خطایی انجام گرفت.

---

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