You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
 

44 KiB

راهنمای جامع و طرح استاندارد ایمپورت دسته‌جمعی داده‌ها (فرمت JSON)

با سلام و احترام؛
این سند به عنوان راهنمای کامل و طرح استاندارد (Blueprint) برای آماده‌سازی و ایمپورت دسته‌جمعی داده‌های شما به بخش‌های مختلف سامانه (شامل آرگومنت‌ها، احادیث، آیات قرآن، تاریخ، فتاوا، نقل‌قول‌ها، راویان، علما و منابع) بر اساس آخرین تغییرات و قابلیت‌های جدید سامانه تدوین شده است.

هدف ما از طراحی این ساختار این است که شما بتوانید اطلاعات دیتابیس فعلی خود را با ساده‌ترین و منعطف‌ترین فرمت ممکن خروجی بگیرید و سامانه به صورت خودکار تمام پردازش‌های فنی و ارتباطات پیچیده را انجام دهد.


۱. قابلیت‌های هوشمند سامانه (برای کاهش کار دستی شما)

در نسخه جدید، چندین قابلیت خودکار به سامانه اضافه شده است تا در صورت خالی بودن برخی فیلدها، سیستم خودش آن‌ها را تکمیل کند:

  1. تکمیل خودکار عنوان آرگومنت/حدیث (title):
    اگر برای یک حدیث، فتوا، نقل‌قول یا مطلب تاریخی، فیلد title را خالی بگذارید، سامانه به صورت خودکار عنوان اولین کتاب منبع (Source) متصل به آن را به عنوان تیتر قرار می‌دهد.
  2. تکمیل خودکار نام راوی یا گوینده در تیتر (title_narrator):
    اگر این فیلد را خالی بگذارید:
    • در صورتی که مطلب دارای سلسله روات باشد، سامانه به صورت خودکار نام مشهور (known_as یا نام کامل) اولین راویِ زنجیره سند را در آن قرار می‌دهد.
    • در صورتی که سلسله روات نداشته باشد (مثل فتاوا، تاریخ یا نقل‌قول)، سامانه نام مشهور مولفِ کتاب منبع را در آن قرار می‌دهد.
  3. تکمیل خودکار عنوان در «تصحیحات»، «تفاسیر» و «متون رجالی راویان»:
    در هر سه بخشِ تصحیحات حدیث (corrections)، تفاسیر تاپیک‌ها (interpretations) و متون اصلی راویان (original_texts)، ارسال فیلد title اختیاری است. در صورت خالی بودن، عنوانِ کتاب مرجع متصل به آن‌ها به صورت خودکار جایگزین می‌شود.
  4. منطق هوشمند نمایش نسخه‌های چاپی کتاب‌ها (editions.language):
    در داده‌های مربوط به هر نسخه چاپی (Edition)، فیلد کد زبان چاپ (language) وجود دارد:
    • اگر کد زبان نسخه "ar" (عربی) باشد، آن نسخه به صورت عمومی (Global) در تمامی زبان‌های سایت و اپلیکیشن نمایش داده می‌شود.
    • اگر کد زبان نسخه غیر عربی (مثلاً "ru"، "fa"، "en" و...) باشد، آن نسخه فقط و فقط زمانی به کاربر نمایش داده می‌شود که کاربر دقیقاً همان زبان را برای رابط کاربری سایت/اپلیکیشن انتخاب کرده باشد.
  5. بانک مرکزی قرآن کریم (۱۱۴ سوره و ۶۲۳۶ آیه):
    بانک کامل متن عربی آیات و ترجمه‌های معتبر در سامانه مستقر شده است؛ بنابراین برای تاپیک‌های قرآنی کافی است شماره سوره (surah_number)، بازه آیات (ayah_from تا ayah_to) و کلید مترجمان منتخب (selected_translator_keys) را مشخص کنید (البته ارسال مستقیم متن و ترجمه سفارشی نیز همچنان پشتیبانی می‌شود).
  6. عدم نیاز به ارسال لینک‌های اشتراک‌گذاری (share_link) و اسلاگ (slug):
    سامانه به صورت پویا و خودکار برای تمامی بخش‌ها اسلاگ و لینک اشتراک‌گذاری تولید می‌کند.

۲. قوانین عمومی در آماده‌سازی فایل‌های JSON

الف) شناسه یکتا (id) برای اتصال بخش‌ها به یکدیگر

هر رکورد (راوی، مولف، کتاب، شهر، دسته‌بندی، حدیث و...) دارای یک فیلد "id" است که همان کد یکتای دیتابیس خودتان است (می‌تواند عدد مثل 105 یا متن مثل "nar_105" باشد).

  • با استفاده از این کد، بخش‌های مختلف به هم متصل می‌شوند.
  • اگر فایلی را مجدداً ارسال و ایمپورت کنید، رکورد تکراری ساخته نمی‌شود بلکه رکورد قبلی بر اساس همین کد به‌روزرسانی (Update) می‌گردد.

ب) فرمت فیلدهای چندزبانه (پشتیبانی از ۳ حالت به انتخاب شما)

تمامی فیلدهای متنی چندزبانه (از جمله ru, ar, en, fa, ur, tr, az, uz, tg, ky, id, bn, de, es, fr, ha, sw, zh) را می‌توانید به هر یک از ۳ روش زیر ارسال کنید:

  1. روش اول (پیشنهادی - آبجکت ساده بر اساس کد زبان):
    "title": { "ru": "Книга веры", "ar": "كتاب الإيمان", "en": "Book of Faith" }
    
  2. روش دوم (متن ساده - در صورتی که فقط یک زبان دارید):
    "title": "Книга веры"
    
  3. روش سوم (آرایه استاندارد):
    "title": [
      { "language_code": "ru", "text": "Книга веры" },
      { "language_code": "ar", "text": "كتاب الإيمان" }
    ]
    

ج) فرمت استاندارد سال تولد، وفات و سن (birth_year_hijri, death_year_hijri, age_at_death)

موتور هوشمند تاریخ در سامانه، فرمت‌های زیر را به صورت خودکار به زبان‌های مختلف ترجمه و استانداردسازی می‌کند:

  • سال دقیق هجری: "148" (برای سال‌های قبل از هجرت از علامت منفی استفاده کنید: "-15")
  • بازه زمانی (بین دو سال): "140..150"
  • تقریبی (حدودِ): "~150"
  • بعد از سال / بیش از: ">150"
  • قبل از سال / کمتر از: "<150"
  • چند احتمال (یا): "148;149" یا "140..145;148..150"
  • تگ‌های مفهومی دوره تاریخی: "#early_islam" (صدر اسلام)، "#hijra_habasha" (هجرت به حبشه)، "#umayyad_era" (دوران اموی) و یا هر تگ دلخواه جدید با علامت #.

در تمامی بخش‌هایی که فیلد links دارند (احادیث، تصحیحات و تفاسیر)، می‌توانید به هر دو شکل زیر لینک‌ها را قرار دهید:

  • حالت اول (آبجکت کلید-مقدار ساده):
    "links": {
      "Sunnah.com": "https://sunnah.com/muslim:2424",
      "Dorar": "https://dorar.net/hadith/123"
    }
    
  • حالت دوم (لیست آبجکت‌ها):
    "links": [
      { "title": "Sunnah.com", "url": "https://sunnah.com/muslim:2424" },
      { "title": "Dorar", "url": "https://dorar.net/hadith/123" }
    ]
    

۳. ترتیب و ساختار ۵ مرحله‌ای ایمپورت داده‌ها

برای اینکه ارتباط بین بخش‌ها (مثل اتصال حدیث به راوی، کتاب و دسته‌بندی) کاملاً دقیق برقرار شود، داده‌ها در ۵ فایل (یا ۵ گام) به ترتیب زیر سازماندهی می‌شوند:

گام اول: اطلاعات پایه، جغرافیا، تگ‌ها، نقش‌ها و وضعیت‌ها (01_lookups.json)

در ساختار جدید، اطلاعاتی مثل کشورها، شهرها، ناشران، کنیه‌ها، مشاغل، ویژگی‌های راویان، مذاهب، وضعیت صحابی بودن، وضعیت ولاء (mawla_statuses)، خاستگاه‌ها و نسبت‌ها (transmitter_origins)، اماکن تاریخی سکونت/وفات (transmitter_locations)، نقش‌های مشارکت‌کنندگان نسخه چاپی (contributor_roles) و انواع نسبت‌های خویشاوندی به صورت جداول مستقل درآمدند تا در فیلترها و جستجوها یکپارچه باشند.

نکته برای راحتی شما: اگر این موارد را به صورت فهرست جداگانه دارید، در این فایل قرار دهید. همچنین اگر در فایل راویان یا کتاب‌ها مستقیماً نام شهر، کنیه، شغل، ولاء یا تگ را بنویسید، سیستم ایمپورت به صورت خودکار آن را در این جداول ثبت و متصل خواهد کرد.

{
  "countries": [
    { "id": "country_iraq", "title": { "ru": "Ирак", "ar": "العراق", "en": "Iraq" } },
    { "id": "country_iran", "title": { "ru": "Иран", "ar": "إيران", "en": "Iran" } },
    { "id": "country_lebanon", "title": { "ru": "Ливан", "ar": "لبنان", "en": "Lebanon" } }
  ],
  "cities": [
    { "id": "city_kufa", "country_id": "country_iraq", "title": { "ru": "Куфа", "ar": "الكوفة", "en": "Kufa" } },
    { "id": "city_baghdad", "country_id": "country_iraq", "title": { "ru": "Багдад", "ar": "بغداد", "en": "Baghdad" } },
    { "id": "city_tehran", "country_id": "country_iran", "title": { "ru": "Тегеран", "ar": "طهران", "en": "Tehran" } },
    { "id": "city_beirut", "country_id": "country_lebanon", "title": { "ru": "Бейрут", "ar": "بيروت", "en": "Beirut" } }
  ],
  "transmitter_origins": [
    {
      "id": "orig_kufi",
      "city_id": "city_kufa",
      "title": { "ru": "Куфиец (аль-Куфи)", "ar": "الكوفي", "en": "Al-Kufi" }
    },
    {
      "id": "orig_baghdadi",
      "city_id": "city_baghdad",
      "title": { "ru": "Багдадец (аль-Багдади)", "ar": "البغدادي", "en": "Al-Baghdadi" }
    }
  ],
  "transmitter_locations": [
    {
      "id": "loc_kufa",
      "city_id": "city_kufa",
      "title": { "ru": "Куфа", "ar": "الكوفة", "en": "Kufa" }
    },
    {
      "id": "loc_baghdad",
      "city_id": "city_baghdad",
      "title": { "ru": "Багдад", "ar": "بغداد", "en": "Baghdad" }
    }
  ],
  "publishers": [
    {
      "id": "pub_dar_islamiya",
      "country_id": "country_iran",
      "city_id": "city_tehran",
      "title": { "ru": "Дар аль-Кутуб аль-Исламия", "ar": "دار الكتب الإسلامية", "en": "Dar al-Kutub al-Islamiyya" }
    }
  ],
  "contributor_roles": [
    { "id": 1, "title": { "ru": "Исследователь (Мухаккик)", "ar": "تحقيق", "en": "Researcher" }, "order": 1 },
    { "id": 2, "title": { "ru": "Переводчик", "ar": "ترجمة", "en": "Translator" }, "order": 2 },
    { "id": 3, "title": { "ru": "Комментатор (Шарих)", "ar": "شرح", "en": "Commentator" }, "order": 3 },
    { "id": 4, "title": { "ru": "Примечания и глоссы (Та'лик)", "ar": "تعليق وحواشي", "en": "Footnotes & Glosses" }, "order": 4 },
    { "id": 5, "title": { "ru": "Редактор (Мусаххих)", "ar": "تصحيح وضبط", "en": "Editor" }, "order": 5 },
    { "id": 6, "title": { "ru": "Составитель (Джами')", "ar": "جمع وترتيب", "en": "Compiler" }, "order": 6 },
    { "id": 7, "title": { "ru": "Сократитель (Мухтасир)", "ar": "اختصار وتهذيب", "en": "Abridger" }, "order": 7 },
    { "id": 8, "title": { "ru": "Составитель указателей", "ar": "فهرسة", "en": "Index Compiler" }, "order": 8 },
    { "id": 9, "title": { "ru": "Автор предисловия", "ar": "تقديم", "en": "Introducer" }, "order": 9 }
  ],
  "madhhabs": [
    {
      "id": "madhhab_imami",
      "title": { "ru": "Шииты-имамиты", "ar": "الشيعة الإمامية", "en": "Twelver Shia" },
      "description": { "ru": "Последователи двенадцати Имамов" }
    },
    {
      "id": "madhhab_shafii",
      "title": { "ru": "Шафииты", "ar": "الشافعية", "en": "Shafi'i" }
    }
  ],
  "sahabi_statuses": [
    {
      "id": "sahabi_prophet",
      "title": { "ru": "Сподвижник Пророка (с)", "ar": "صحابي", "en": "Companion of the Prophet" },
      "description": { "ru": "Встречал Пророка (с) и уверовал в него" }
    },
    {
      "id": "sahabi_sadiq",
      "title": { "ru": "Сподвижник Имама Садика (а)", "ar": "من أصحاب الإمام الصادق", "en": "Companion of Imam al-Sadiq" }
    }
  ],
  "mawla_statuses": [
    {
      "id": "mawla_banu_shayban",
      "title": { "ru": "Вольноотпущенник Бану Шайбан", "ar": "مولى بني شيبان", "en": "Mawla of Banu Shayban" },
      "description": { "ru": "Клиент или вольноотпущенник племени Бану Шайбан" }
    }
  ],
  "kunyas": [
    { "id": "kunya_abul_hasan", "title": { "ru": "Абу аль-Хасан", "ar": "أبو الحسن", "en": "Abu al-Hasan" } },
    { "id": "kunya_abu_abdillah", "title": { "ru": "Абу Абдуллах", "ar": "أبو عبد الله", "en": "Abu Abdillah" } }
  ],
  "professions": [
    { "id": "prof_faqih", "title": { "ru": "Факих (Правовед)", "ar": "فقيه", "en": "Jurist (Faqih)" } },
    { "id": "prof_muhaddith", "title": { "ru": "Мухаддис", "ar": "محدث", "en": "Hadith Scholar" } }
  ],
  "features": [
    { "id": "feat_hafiz", "title": { "ru": "Обладатель сильной памяти", "ar": "كثير الحفظ", "en": "Strong Memory" } },
    { "id": "feat_kufan_leader", "title": { "ru": "Глава куфийцев", "ar": "وجه الكوفيين", "en": "Leader in Kufa" } }
  ],
  "relation_types": [
    { "code": "parents", "title": { "ru": "Родители", "ar": "الوالدان", "en": "Parents" } },
    { "code": "children", "title": { "ru": "Дети", "ar": "الأولاد", "en": "Children" } },
    { "code": "siblings", "title": { "ru": "Братья и сестры", "ar": "الإخوة", "en": "Siblings" } },
    { "code": "students", "title": { "ru": "Ученики", "ar": "التلاميذ", "en": "Students" } }
  ],
  "hadith_statuses": [
    {
      "id": "status_sahih",
      "title": { "ru": "Достоверный (Сахих)", "ar": "صحيح", "en": "Authentic (Sahih)" },
      "description": { "ru": "Описание достоверного хадиса..." },
      "color": "green",
      "order": 1
    }
  ],
  "transmitter_reliabilities": [
    {
      "id": "rel_thiqa",
      "title": { "ru": "Надёжный (Сика)", "ar": "ثقة", "en": "Reliable (Thiqa)" },
      "description": { "ru": "Заслуживающий доверия передатчик" },
      "color": "green"
    }
  ],
  "opinion_statuses": [
    {
      "id": "op_confirmed",
      "title": { "ru": "Подтверждение (Таусик)", "ar": "توثيق", "en": "Confirmed" },
      "color": "green"
    }
  ],
  "author_rutbas": [
    {
      "id": "rutba_hafiz",
      "title": { "ru": "Хафиз", "ar": "حافظ", "en": "Hafiz" },
      "description": { "ru": "Высокий уровень в хадисоведении" },
      "color": "blue"
    }
  ],
  "hadith_tags": [
    { "id": "tag_imamat", "title": { "ru": "Имамат", "ar": "الإمامة", "en": "Imamate" } },
    { "id": "tag_fiqh", "title": { "ru": "Фикх", "ar": "الفقه", "en": "Fiqh" } }
  ],
  "book_tags": [
    { "id": "btag_primary", "title": { "ru": "Основной источник", "ar": "مصدر رئيسي" } }
  ],
  "book_subject_areas": [
    { "id": "subj_hadith", "title": { "ru": "Книги хадисов", "ar": "كتب الحديث" } }
  ],
  "book_types": [
    { "id": "type_shia_primary", "sect": "shia", "title": { "ru": "Первоисточник (Шииты)", "ar": "مصدر شيعي" } },
    { "id": "type_sunni_primary", "sect": "sunni", "title": { "ru": "Первоисточник (Сунниты)", "ar": "مصدر سني" } }
  ]
}

رنگ‌های مجاز (color): "green", "blue", "yellow", "orange", "red", "purple", "gray"


گام دوم: راویان، علما، خویشاوندان و اقوال رجالی (02_narrators_and_scholars.json)

در این فایل، فهرست مولفان/علما (scholars_and_authors) و راویان (transmitters) قرار می‌گیرد.

نکات مهم این بخش در ساختار جدید:

  1. ارتباط مولف با راوی (related_narrator_id): اگر یک مولف کتاب، خودش در لیست راویان هم حضور دارد، می‌توانید کد راوی او را در related_narrator_id قرار دهید تا پروفایل آن‌ها به هم لینک شود.
  2. پشتیبانی از چند خاستگاه و چند مکان سکونت/وفات (برای راویان و علما):
    علاوه بر فیلدهای تکیِ قبلی (origin_city_id, lived_in_city_id, died_in_city_id)، اکنون می‌توانید برای هر راوی یا عالم لیستی از چند خاستگاه (origin_ids)، چند شهر محل سکونت (lived_in_location_ids) و چند مکان وفات (died_in_location_ids) ارسال کنید.
  3. مذهب راوی (madhhab_id) و وضعیت ولاء چندگانه (mawla_status_ids):
    • برای مذهب راوی می‌توانید علاوه بر مقدار کلی "shia" / "sunni"، شناسه مذهب دقیق را در madhhab_id قرار دهید.
    • برای وضعیت ولاء («مولى / آزادشده توسط») می‌توانید یک یا چند شناسه از جدول mawla_statuses را در mawla_status_ids قرار دهید (همچنین فیلد متنی freed_slave_of نیز همچنان پشتیبانی می‌شود).
  4. خویشاوندان و ارتباطات راوی (relatives): هر راوی می‌تواند لیستی از خویشاوندان، شاگردان یا قبیله خود را با کد نسبت (relation_type)، نام (name) و کد راوی متناظر (narrator_id در صورتی که آن شخص خودش در دیتابیس پروفایل راوی دارد) داشته باشد.
    • کدهای آماده relation_type: "parents", "children", "siblings", "spouses", "stepfather", "stepmother", "stepchildren", "uncles_and_aunts", "nephews_and_nieces", "cousins", "grandparents", "grandchildren_and_great_grandchildren", "granduncles_and_grandaunts", "grandnephews_and_grandnieces", "foster_mother", "foster_children", "in_laws", "students", "owners_and_masters", "tribe", "friends_and_companions", "allies", "neighbors", "wards_and_proteges", "other_relatives", "cousins_of_parents", "cousins_of_grandparents", "cousins_children", "cousins_grandchildren_and_great_grandchildren".
  5. اقوال رجالی استاندارد (scholarly_opinions): اگر عبارات رجالی ثابتی دارید که برای چندین راوی تکرار می‌شوند (مثلاً عبارت «ثقة» یا «کان ضعیفاً»)، می‌توانید آن‌ها را در scholarly_opinions تعریف کنید و در بخش opinions راوی فقط opinion_id بدهید، و یا مستقیماً متن قول (opinion_text) را زیر همان راوی بنویسید.
{
  "scholarly_opinions": [
    {
      "id": "sop_thiqa_eye",
      "status_id": "op_confirmed",
      "opinion_text": {
        "ar": "ثقة عين",
        "ru": "Надёжный, выдающийся (Сика Айн)"
      }
    }
  ],
  "scholars_and_authors": [
    {
      "id": "author_najashi",
      "related_narrator_id": null,
      "name": { "ru": "Ан-Наджаши", "ar": "النجاشي", "en": "Al-Najashi" },
      "known_as": { "ru": "Абу аль-Аббас ан-Наджаши", "ar": "أبو العباس النجاشي" },
      "scholarity": { "ru": "Ученый в области риджал", "ar": "عالم بالرجال" },
      "tabaqa": { "ru": "5-й век хиджры", "ar": "القرن الخامس" },
      "rutba_id": "rutba_hafiz",
      "feature_ids": ["feat_hafiz"],
      "origin_ids": ["orig_baghdadi"],
      "lived_in_location_ids": ["loc_baghdad", "loc_kufa"],
      "died_in_location_ids": ["loc_baghdad"],
      "origin_city_id": "city_baghdad",
      "lived_in_city_id": "city_baghdad",
      "died_in_city_id": "city_baghdad",
      "birth_year_hijri": "372",
      "death_year_hijri": "450",
      "age_at_death": "78",
      "birth_year_miladi": 982,
      "death_year_miladi": 1058,
      "image_path": "authors/najashi.jpg"
    }
  ],
  "transmitters": [
    {
      "id": "nar_101",
      "narrator_number": 101,
      "gender": "male",
      "madhhab": "shia",
      "madhhab_id": "madhhab_imami",
      "madhhab_ids": ["madhhab_imami"],
      "reliability_id": "rel_thiqa",
      "sahabi_status_id": "sahabi_sadiq",
      "mawla_status_ids": ["mawla_banu_shayban"],
      "generation": 5,
      "full_name": { "ru": "Зурара ибн Айян", "ar": "زرارة بن أعين الشيباني", "en": "Zurara ibn A'yan" },
      "known_as": { "ru": "Зурара", "ar": "زرارة" },
      "kunya_ids": ["kunya_abul_hasan"],
      "nickname": { "ru": "Аш-Шайбани", "ar": "الشيباني" },
      "origin_ids": ["orig_kufi"],
      "lived_in_location_ids": ["loc_kufa"],
      "died_in_location_ids": ["loc_kufa"],
      "origin_city_id": "city_kufa",
      "lived_in_city_id": "city_kufa",
      "died_in_city_id": "city_kufa",
      "birth_year_hijri": "~80",
      "death_year_hijri": "150",
      "age_at_death": "~70",
      "freed_slave_of": { "ru": "Бану Шайбан", "ar": "بني شيبان" },
      "profession_ids": ["prof_faqih", "prof_muhaddith"],
      "feature_ids": ["feat_hafiz", "feat_kufan_leader"],
      "tadlis": false,
      "ikhtilat": false,
      "in_sahih_bukhari": false,
      "in_sahih_muslim": false,
      "tags": ["Куфа", "Сподвижники"],
      "description": { "ru": "Подробная биография передатчика...", "ar": "..." },
      "thumbnail_path": null,
      "relatives": [
        {
          "relation_type": "siblings",
          "name": "Хумран ибн Айян",
          "narrator_id": "nar_102"
        },
        {
          "relation_type": "parents",
          "name": "Айян ибн Сансан",
          "narrator_id": null
        }
      ],
      "opinions": [
        {
          "scholar_id": "author_najashi",
          "opinion_id": "sop_thiqa_eye",
          "status_id": "op_confirmed",
          "opinion_text": {
            "ar": "شيخ أصحابنا في زمانه ومتقدمهم، وكان قارئاً فقيهاً متكلماً",
            "ru": "Шейх наших соратников в свое время и их лидер, был чтецом, факихом, мутакаллимом"
          },
          "order": 1
        }
      ],
      "original_texts": [
        {
          "title": null,
          "text": "زرارة بن أعين بن سنسن مولى بني شيبان...",
          "translation": { "ru": "Зурара ибн Айян ибн Сансан, вольноотпущенник Бану Шайбан..." },
          "order": 1,
          "references": [
            {
              "book_id": "book_rijal_najashi",
              "edition_id": "ed_najashi_1",
              "volume_id": null,
              "volume": "1",
              "pages": "175",
              "hadith_number": "463",
              "address": "Риджал ан-Наджаши, том 1, стр. 175",
              "url": "https://example.com/book/175",
              "screenshots_folder": "screens_trx/nar_101/ex_1"
            }
          ]
        }
      ]
    }
  ]
}

گام سوم: منابع، کتاب‌ها، چاپ‌ها، عوامل چاپ و جلدها (03_sources.json)

در ساختار جدید منابع:

  1. اولویت نمایش کتاب (priority): هر کتاب (books) دارای فیلد priority است (عدد کمتر = اولویت بالاتر در لیست منابع).
  2. اتصال نسخه چاپی به کتاب‌ها (editions.connected_book_ids):
    رابطه بین نسخه چاپی (Edition) و کتاب‌ها (BookReference) صرفاً به صورت چندبه‌چند (books / connected_book_ids) است و نیازی به تفکیک «کتاب اصلی» و «کتاب فرعی» وجود ندارد. هر نسخه چاپی می‌تواند به یک یا چند اثر/کتاب مرتبط در connected_book_ids متصل شود (در صورتی که editions را در زیرمجموعه یک کتاب قرار دهید، شناسه آن کتاب نیز به صورت خودکار به لیست کتاب‌های مرتبط اضافه می‌شود).
  3. کد زبان چاپ نسخه (editions.language):
    هر نسخه چاپی (Edition) دارای فیلد "language" (کد دوحرفی زبان چاپ از بین ۱۸ زبان سامانه: "ar", "ru", "en", "fa", "ur", "tr", "az", "uz", "tg", "ky", "id", "bn", "de", "es", "fr", "ha", "sw", "zh"؛ پیش‌فرض "ar") است:
    • اگر "language": "ar" باشد: این نسخه چاپی به صورت عمومی (Global) در تمام زبان‌های سایت و اپلیکیشن نمایش داده می‌شود.
    • اگر "language" غیر عربی باشد (مثلاً "ru"): این نسخه فقط زمانی به کاربر نمایش داده می‌شود که زبان انتخاب‌شده توسط کاربر در سایت/اپلیکیشن دقیقاً "ru" باشد.
  4. عوامل و مشارکت‌کنندگان نسخه چاپی و ارتباط با جلدهای خاص (editions.contributors):
    هر نسخه چاپی می‌تواند لیستی از مشارکت‌کنندگان (contributors) داشته باشد که در آن هر فرد از لیست علما/مولفان (author_id) با یک نقش مشخص (role_id از جدول contributor_roles مثل محقق، مترجم، شارح، مصحح و...) به آن چاپ متصل می‌شود:
    • فیلد volume_ids (اختصاص مشارکت‌کننده به جلدهای مشخص): برای هر مشارکت‌کننده می‌توانید آرایه volume_ids (شامل شناسه‌های جلدهای همان نسخه از بخش volumes) را ارسال کنید:
      • اگر volume_ids خالی ([]) یا null باشد (یا ارسال نشود): به این معناست که آن شخص در کل نسخه چاپی (تمامی جلدها) مشارکت داشته است.
      • اگر در volume_ids شناسه جلدهای خاصی (مثلاً ["vol_kafi_1", "vol_kafi_2"]) درج شود: مشارکت آن شخص با آن نقش، صرفاً مربوط به همان جلدهای مشخص‌شده خواهد بود.
    • (فیلدهای قدیمی researcher_ids و editor_ids نیز همچنان برای سازگاری با داده‌های قبلی پشتیبانی می‌شوند).
{
  "books": [
    {
      "id": "book_kafi",
      "priority": 1,
      "order": 1,
      "title": { "ru": "Аль-Кафи", "ar": "الكافي", "en": "Al-Kafi" },
      "description": { "ru": "Важнейший сборник шиитских хадисов...", "ar": "..." },
      "language": { "ru": "Арабский", "ar": "العربية", "en": "Arabic" },
      "author_id": "author_kulayni",
      "type_id": "type_shia_primary",
      "tag_id": "btag_primary",
      "subject_area_ids": ["subj_hadith"],
      "number_page": 4500,
      "rate": 5.0,
      "has_editions": true,
      "attributes": [
        {
          "title": { "ru": "Век написания", "ar": "قرن التأليف" },
          "value": { "ru": "4-й век хиджры", "ar": "القرن الرابع الهجري" }
        }
      ],
      "editions": [
        {
          "id": "ed_kafi_dar_islamiya",
          "language": "ar",
          "title": { "ru": "Издание Дар аль-Кутуб (Тегеран)", "ar": "طبعة دار الكتب الإسلامية" },
          "connected_book_ids": ["book_kafi"],
          "edition_number": "4",
          "year_of_publication": "1407 هـ / 1986 م",
          "number_of_volumes": 8,
          "publisher_id": "pub_dar_islamiya",
          "country_id": "country_iran",
          "city_id": "city_tehran",
          "tag_id": "btag_primary",
          "isbn": "978-964-440-001-1",
          "source_url": "https://lib.eshia.ir/11005",
          "contributors": [
            {
              "role_id": 1,
              "author_id": "author_ghaffari",
              "volume_ids": null
            },
            {
              "role_id": 4,
              "author_id": "author_naeini",
              "volume_ids": ["vol_kafi_1", "vol_kafi_2"]
            }
          ],
          "researcher_ids": ["author_ghaffari"],
          "editor_ids": [],
          "notes": { "ru": "С исследованием Али Акбара Гаффари" },
          "volumes": [
            {
              "id": "vol_kafi_1",
              "title": "1",
              "cover_image_path": "books/book_kafi/ed_1/vol_1_cover.jpg",
              "pdf_file_path": "books/book_kafi/ed_1/01.pdf"
            },
            {
              "id": "vol_kafi_2",
              "title": "2",
              "cover_image_path": "books/book_kafi/ed_1/vol_2_cover.jpg",
              "pdf_file_path": "books/book_kafi/ed_1/02.pdf"
            }
          ]
        }
      ]
    }
  ]
}

گام چهارم: دسته‌بندی‌ها، تاپیک‌ها و آیات قرآن (04_categories_and_quran.json)

قانون ساختاری دسته‌بندی‌ها و تاپیک‌ها: در سامانه، درخت دسته‌بندی به دو سطح تقسیم می‌شود:

  1. شاخه/پوشه ساختاری ("is_topic": false): فقط نقش پوشه مادر را دارد و زیرمجموعه می‌گیرد (مستقیماً حدیثی داخل آن قرار نمی‌گیرد و "source_type": null است).
  2. تاپیک نهایی ("is_topic": true): آخرین برگ درخت است که احادیث، آرگومنت‌ها، آیات قرآن و تفاسیر به آن متصل می‌شوند. برای هر تاپیک حتماً باید "source_type" از بین یکی از ۵ مورد زیر مشخص شود:
    • "quran" (قرآن)
    • "hadith" (حدیث)
    • "history" (تاریخ)
    • "fatwa" (فتوا)
    • "quote" (نقل‌قول)

نحوه تعریف آیه در تاپیک‌های قرآنی (quran_verse): با توجه به اضافه شدن بانک مرکزی قرآن کریم (شامل ۱۱۴ سوره، ۶۲۳۶ آیه و ترجمه‌های چندزبانه)، در بخش quran_verse می‌توانید به سادگی شماره سوره (surah_number از ۱ تا ۱۱۴)، شماره آیه شروع (ayah_from)، شماره آیه پایان (ayah_to) و کلید مترجمان منتخب (selected_translator_keys) را مشخص کنید تا متن عربی و ترجمه‌ها به صورت خودکار از بانک مرکزی قرآن خوانده شوند. همچنین در صورت تمایل می‌توانید متن و ترجمه اختصاصی را نیز مستقیماً ارسال نمایید:

{
  "categories": [
    {
      "id": "cat_imamat_root",
      "parent_id": null,
      "sect": "sunni",
      "is_topic": false,
      "source_type": null,
      "order": 1,
      "title": { "ru": "Имамат и Халифат", "ar": "الإمامة والخلافة", "en": "Imamate and Caliphate" },
      "description": { "ru": "Раздел, посвященный вопросам руководства после Пророка (с)" },
      "xmind_file_path": null
    },
    {
      "id": "topic_ayah_tathir",
      "parent_id": "cat_imamat_root",
      "sect": "sunni",
      "is_topic": true,
      "source_type": "quran",
      "order": 1,
      "title": { "ru": "Аят ат-Татхир (Очищение)", "ar": "آية التطهير", "en": "Verse of Purification" },
      "description": { "ru": "Кто входит в Ахль аль-Бейт согласно суннитским источникам" },
      "xmind_file_path": "xmind/tathir.xmind",
      "quran_verse": {
        "surah_number": 33,
        "ayah_from": 33,
        "ayah_to": 33,
        "selected_translator_keys": [
          "ru.kuliev",
          "ru.krachkovsky",
          "ru.osmanov",
          "en.sahih"
        ],
        "surah_name": { "ru": "Аль-Ахзаб (Союзники)", "ar": "الأحزاب", "en": "Al-Ahzab" },
        "ayah_number": "33",
        "arabic_text": "إِنَّمَا يُرِيدُ اللَّهُ لِيُذْهِبَ عَنكُمُ الرِّجْسَ أَهْلَ الْبَيْتِ وَيُطَهِّرَكُمْ تَطْهِيرًا",
        "primary_translation": {
          "ru": "О обитатели дома! Аллах желает лишь избавить вас от скверны и очистить вас полностью.",
          "en": "Allah intends only to remove from you the impurity, O People of the [Prophet's] household..."
        },
        "primary_translator": {
          "ru": "Э. Кулиев",
          "en": "Sahih International"
        },
        "secondary_translations": [
          {
            "language_code": "ru",
            "translator": "И. Ю. Крачковский",
            "translation_text": "Аллах хочет только удалить от вас скверну, о люди дома, и очистить вас очищением."
          },
          {
            "language_code": "ru",
            "translator": "М.-Н. О. Османов",
            "translation_text": "Воистину, Аллах хочет отвратить от вас скверну, о члены дома [Пророка]..."
          }
        ]
      }
    },
    {
      "id": "topic_hadith_thaqalayn",
      "parent_id": "cat_imamat_root",
      "sect": "sunni",
      "is_topic": true,
      "source_type": "hadith",
      "order": 2,
      "title": { "ru": "Хадис ас-Сакалайн (Две драгоценности)", "ar": "حديث الثقلين" },
      "description": { "ru": "Хадисы об оставлении Корана и Ахль аль-Бейт" }
    }
  ]
}

گام پنجم: آرگومنت‌ها (احادیث، تاریخ، فتوا، نقل‌قول)، سلسله روات، تصحیحات، تفاسیر و کالکشن‌ها (05_arguments_hadiths.json)

این فایل شامل محتوای اصلی است:

  1. hadiths (تمامی آرگومنت‌ها اعم از حدیث، تاریخ، فتوا، نقل‌قول):
    • هر آیتم می‌تواند به یک تاپیک اصلی (primary_topic_id) و در صورت نیاز به چند تاپیک دیگر (additional_topic_ids) متصل شود.
    • همان‌طور که در بخش ۱ توضیح داده شد، اگر title یا title_narrator را خالی (null) بگذارید، سامانه آن‌ها را به صورت هوشمند از روی اولین منبع و اولین راوی/مولف پر می‌کند.
  2. chains (سلسله روات):
    • حالت ساده: اگر زنجیره سند بدون ابهام است، می‌توانید فقط آرایه‌ای از کد (یا شماره) راویان بفرستید: "chains": [ ["nar_101", "nar_102", "nar_105"] ]
    • حالت پیشرفته: اگر یک حدیث چند طریق/شاخه دارد یا در نقطه‌ای از سند افتادگی (is_gap: true) یا تردید بین چند راوی (is_uncertain: true به همراه uncertain_transmitter_ids) وجود دارد، مطابق نمونه زیر به صورت آبجکت ارسال کنید.
  3. corrections (تصحیحات و بررسی‌های سندی هر حدیث) و interpretations (تفاسیر و شروح هر تاپیک).
  4. collections (مجموعه‌های منتخب صفحه اصلی - در صورت نیاز).
{
  "hadiths": [
    {
      "id": "hadith_1001",
      "number": 1,
      "primary_topic_id": "topic_ayah_tathir",
      "additional_topic_ids": ["topic_hadith_thaqalayn"],
      "status_id": "status_sahih",
      "hadis_status_text": { "ru": "Достоверный по условиям Муслима", "ar": "صحيح على شرط مسلم" },
      "visibility": true,
      "title": null,
      "title_narrator": null,
      "text": "عَنْ أُمِّ سَلَمَةَ قَالَتْ: فِي بَيْتِي نَزَلَتْ: {إِنَّمَا يُرِيدُ اللَّهُ لِيُذْهِبَ عَنكُمُ الرِّجْسَ أَهْلَ الْبَيْتِ}...",
      "translation": {
        "ru": "Передается от Умм Саламы, что она сказала: «В моем доме был ниспослан аят: Поистине, Аллах желает избавить вас от скверны, о Ахль аль-Бейт...»",
        "en": "Narrated by Umm Salama: In my house the verse was revealed..."
      },
      "description": {
        "ru": "Краткое примечание к хадису"
      },
      "explanations": [
        {
          "language_code": "ru",
          "items": [
            {
              "title": "Разбор лексики (Ахль аль-Бейт)",
              "detail": "Подробное объяснение значения выражения Ахль аль-Бейт в контексте данного хадиса..."
            },
            {
              "title": "Исторический контекст",
              "detail": "Обстоятельства ниспослания (Асбаб ан-Нузуль)..."
            }
          ]
        }
      ],
      "address": {
        "ru": ["Сахих Муслим", "Книга достоинств сподвижников", "Глава о достоинствах Ахль аль-Бейт"]
      },
      "links": [
        { "title": "Sunnah.com", "url": "https://sunnah.com/muslim:2424" },
        { "title": "Dorar.net", "url": "https://dorar.net/hadith/123" }
      ],
      "tag_ids": ["tag_imamat"],
      "chains": [
        [
          {
            "transmitter_id": "nar_101",
            "order": 0,
            "layer_number": 1,
            "layer_name": { "ru": "Сподвижники (Сахаба)", "ar": "الصحابة" },
            "is_gap": false,
            "is_uncertain": false
          },
          {
            "transmitter_id": "nar_102",
            "order": 1,
            "layer_number": 2,
            "is_gap": false,
            "is_uncertain": true,
            "uncertain_transmitter_ids": ["nar_102", "nar_103"]
          }
        ]
      ],
      "references": [
        {
          "book_id": "book_kafi",
          "edition_id": "ed_kafi_dar_islamiya",
          "volume_id": "vol_kafi_1",
          "volume": "1",
          "pages": "287",
          "hadith_number": "3295",
          "address": "Сунан ат-Тирмизи, том 5, стр. 351, хадис № 3205",
          "url": "https://shamela.ws/book/123/456",
          "description": { "ru": "Издание Дар аль-Кутуб" },
          "screenshots_folder": "screens/hadith_1001/ref_1"
        }
      ],
      "corrections": [
        {
          "id": "corr_501",
          "priority": 1,
          "title": null,
          "narrator": "Мухаммад Насируддин аль-Альбани",
          "text": "قال الألباني في صحيح سنن الترمذي: صحيح",
          "translation": { "ru": "Аль-Альбани сказал в «Сахих Сунан ат-Тирмизи»: Достоверно (Сахих)." },
          "links": [
            { "title": "Источник", "url": "https://example.com/albani" }
          ],
          "references": [
            {
              "book_id": "book_sahih_tirmidhi",
              "edition_id": null,
              "volume_id": null,
              "volume": "3",
              "pages": "90",
              "hadith_number": "3205",
              "address": "Сахих Сунан ат-Тирмизи, том 3, стр. 90",
              "url": null,
              "screenshots_folder": "screens/corr_501/ref_1"
            }
          ]
        }
      ]
    }
  ],
  "interpretations": [
    {
      "id": "interp_201",
      "topic_id": "topic_ayah_tathir",
      "priority": 1,
      "narrator": "Ибн Касир",
      "title": null,
      "text": "<p dir=\"rtl\">وهذا نص في دخول أزواج النبي صلى الله عليه وسلم في أهل البيت ههنا...</p>",
      "translation": {
        "ru": "<p>Толкование Ибн Касира и приведение хадисов о плаще...</p>"
      },
      "links": [
        { "title": "Тафсир онлайн", "url": "https://example.com/tafsir" }
      ],
      "references": [
        {
          "book_id": "book_tafsir_ibn_kathir",
          "edition_id": null,
          "volume_id": null,
          "volume": "6",
          "pages": "410",
          "hadith_number": null,
          "address": "Тафсир аль-Куран аль-Азим, том 6, стр. 410",
          "url": null,
          "screenshots_folder": "screens/interp_201/ref_1"
        }
      ]
    }
  ],
  "collections": [
    {
      "id": "col_featured_imamat",
      "display_position": "pinned",
      "order": 1,
      "status": true,
      "title": { "ru": "Важнейшие хадисы об Имамате", "ar": "أهم أحاديث الإمامة" },
      "summary": { "ru": "Подборка ключевых аргументов из достоверных источников" },
      "thumbnail_path": "collections/imamat.jpg",
      "hadith_ids": ["hadith_1001"]
    }
  ]
}

۴. ساختار پوشه ارسالی (فایل‌های JSON به همراه تصاویر و مستندات)

در صورتی که همراه با داده‌ها، فایل‌های پیوست (اسکرین‌شات منابع، تصاویر جلد کتاب‌ها، فایل‌های PDF یا فایل‌های XMind) دارید، کافی است کل پکیج را در قالب یک فایل فشرده (ZIP) مطابق پوشه‌بندی زیر قرار دهید و مسیر نسبی فایل‌ها را در JSON درج نمایید:

import_package/
├── 01_lookups.json
├── 02_narrators_and_scholars.json
├── 03_sources.json
├── 04_categories_and_quran.json
├── 05_arguments_hadiths.json
└── media/
    ├── authors/              # تصاویر مولفان و علما
    ├── books/                # تصاویر جلدها و فایل‌های PDF هر کتاب/چاپ/جلد
    ├── collections/          # تصاویر کاور مجموعه‌ها (Collections)
    ├── screens/              # اسکرین‌شات‌های منابع احادیث، تصحیحات و تفاسیر
    └── screens_trx/          # اسکرین‌شات‌های منابع متون رجالی راویان (Original Texts)

جمع‌بندی و گام بعدی همکاری

ما می‌توانیم این فرآیند را مرحله‌به‌مرحله پیش ببریم؛ یعنی ابتدا از گام ۱ و ۲ (اطلاعات پایه، راویان و علما) یا هر بخشی که در دیتابیس شما آماده‌تر است یک نمونه خروجی ارسال فرمایید تا تست و بررسی کنیم و در صورت نیاز به هرگونه تطبیق با ساختار دیتابیس شما، اسکریپت ایمپورت را دقیقاً مطابق خروجی شما تنظیم نماییم.