Browse Source

feat(hadis): add manageable BookContributorRole & BookEditionContributor models and relax edition source_url validation

master
Mohsen Taba 3 weeks ago
parent
commit
5705bfbb08
  1. 219
      apps/hadis/migrations/0074_bookcontributorrole_bookeditioncontributor_and_seed.py
  2. 79
      apps/hadis/models/reference.py
  3. 21
      apps/hadis/serializers/hadis.py
  4. 37
      apps/hadis/serializers/reference_v2.py
  5. 236
      apps/hadis/serializers/serializers_admin.py
  6. 7
      apps/hadis/urls.py
  7. 46
      apps/hadis/views_admin.py
  8. 197
      docs/PODCAST_RSS_DISTRIBUTION_GUIDE.md

219
apps/hadis/migrations/0074_bookcontributorrole_bookeditioncontributor_and_seed.py

@ -0,0 +1,219 @@
from django.db import migrations, models
import django.db.models.deletion
from django.utils.text import slugify
import utils.mixins
CONTRIBUTOR_ROLES_SEED = [
{
"id": 1,
"slug": "tahqiq-textual-criticism",
"title": [
{"language_code": "ar", "text": "تحقيق", "title": "تحقيق"},
{"language_code": "ru", "text": "Тахкик (Текстология)", "title": "Тахкик (Текстология)"},
{"language_code": "en", "text": "Tahqiq (Textual Criticism)", "title": "Tahqiq (Textual Criticism)"},
],
},
{
"id": 2,
"slug": "scholarly-study-foreword",
"title": [
{"language_code": "ar", "text": "دراسة", "title": "دراسة"},
{"language_code": "ru", "text": "Исследование / Предисловие", "title": "Исследование / Предисловие"},
{"language_code": "en", "text": "Scholarly Study / Foreword", "title": "Scholarly Study / Foreword"},
],
},
{
"id": 3,
"slug": "commentator",
"title": [
{"language_code": "ar", "text": "تعليق", "title": "تعليق"},
{"language_code": "ru", "text": "Комментатор", "title": "Комментатор"},
{"language_code": "en", "text": "Commentator", "title": "Commentator"},
],
},
{
"id": 4,
"slug": "takhrij-hadith-sources-verification",
"title": [
{"language_code": "ar", "text": "تخريج", "title": "تخريج"},
{"language_code": "ru", "text": "Тахридж (Валидация хадисов/источников)", "title": "Тахридж (Валидация хадисов/источников)"},
{"language_code": "en", "text": "Takhrij (Hadith/Sources Verification)", "title": "Takhrij (Hadith/Sources Verification)"},
],
},
{
"id": 5,
"slug": "reviewer-supervisor",
"title": [
{"language_code": "ar", "text": "مراجعة", "title": "مراجعة"},
{"language_code": "ru", "text": "Редактор / Куратор", "title": "Редактор / Куратор"},
{"language_code": "en", "text": "Reviewer / Supervisor", "title": "Reviewer / Supervisor"},
],
},
{
"id": 6,
"slug": "compiler",
"title": [
{"language_code": "ar", "text": "إعداد", "title": "إعداد"},
{"language_code": "ru", "text": "Составитель", "title": "Составитель"},
{"language_code": "en", "text": "Compiler", "title": "Compiler"},
],
},
{
"id": 7,
"slug": "translator",
"title": [
{"language_code": "ar", "text": "ترجمة", "title": "ترجمة"},
{"language_code": "ru", "text": "Переводчик", "title": "Переводчик"},
{"language_code": "en", "text": "Translator", "title": "Translator"},
],
},
{
"id": 8,
"slug": "production-issuance",
"title": [
{"language_code": "ar", "text": "نشر", "title": "نشر"},
{"language_code": "ru", "text": "Подготовка к печати", "title": "Подготовка к печати"},
{"language_code": "en", "text": "Production / Issuance", "title": "Production / Issuance"},
],
},
{
"id": 9,
"slug": "sponsor-patron",
"title": [
{"language_code": "ar", "text": "تمويل", "title": "تمويل"},
{"language_code": "ru", "text": "Меценат / Спонсор издания", "title": "Меценат / Спонсор издания"},
{"language_code": "en", "text": "Sponsor / Patron", "title": "Sponsor / Patron"},
],
},
]
def seed_contributor_roles_and_migrate_contributors(apps, schema_editor):
BookContributorRole = apps.get_model("hadis", "BookContributorRole")
BookEditionContributor = apps.get_model("hadis", "BookEditionContributor")
BookResearcher = apps.get_model("hadis", "BookResearcher")
BookEditor = apps.get_model("hadis", "BookEditor")
for role_data in CONTRIBUTOR_ROLES_SEED:
BookContributorRole.objects.update_or_create(
id=role_data["id"],
defaults={
"title": role_data["title"],
"slug": role_data["slug"],
},
)
# Reset sequence on PostgreSQL so new roles get id >= 10
if schema_editor.connection.vendor == "postgresql":
with schema_editor.connection.cursor() as cursor:
cursor.execute(
"SELECT setval(pg_get_serial_sequence('hadis_bookcontributorrole', 'id'), "
"COALESCE((SELECT MAX(id) FROM hadis_bookcontributorrole), 1), true);"
)
tahqiq_role = BookContributorRole.objects.filter(id=1).first()
editor_role = BookContributorRole.objects.filter(id=5).first()
for res in BookResearcher.objects.select_related("author").all():
if not BookEditionContributor.objects.filter(
book_edition_id=res.book_edition_id,
author_id=res.author_id,
role_id=tahqiq_role.id if tahqiq_role else None,
).exists():
BookEditionContributor.objects.create(
book_edition_id=res.book_edition_id,
role=tahqiq_role,
author_id=res.author_id,
name=res.author.name if res.author_id and res.author else (res.name or []),
slug=res.author.slug if res.author_id and res.author else res.slug,
)
for ed in BookEditor.objects.select_related("author").all():
if not BookEditionContributor.objects.filter(
book_edition_id=ed.book_edition_id,
author_id=ed.author_id,
role_id=editor_role.id if editor_role else None,
).exists():
BookEditionContributor.objects.create(
book_edition_id=ed.book_edition_id,
role=editor_role,
author_id=ed.author_id,
name=ed.author.name if ed.author_id and ed.author else (ed.name or []),
slug=ed.author.slug if ed.author_id and ed.author else ed.slug,
)
class Migration(migrations.Migration):
dependencies = [
("hadis", "0073_transmitterlocation_transmitterorigin_and_more"),
]
operations = [
migrations.CreateModel(
name="BookContributorRole",
fields=[
("id", models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name="ID")),
("title", models.JSONField(default=list, verbose_name="Title")),
("slug", models.SlugField(allow_unicode=True, blank=True, max_length=255, null=True, verbose_name="slug")),
("created_at", models.DateTimeField(auto_now_add=True, verbose_name="created at")),
("updated_at", models.DateTimeField(auto_now=True, verbose_name="updated at")),
],
options={
"verbose_name": "Book Contributor Role",
"verbose_name_plural": "Book Contributor Roles",
"ordering": ("id",),
},
bases=(utils.mixins.LowercaseSlugMixin, models.Model),
),
migrations.CreateModel(
name="BookEditionContributor",
fields=[
("id", models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name="ID")),
("name", models.JSONField(blank=True, default=list, verbose_name="Name")),
("slug", models.SlugField(allow_unicode=True, blank=True, max_length=255, null=True, verbose_name="slug")),
(
"author",
models.ForeignKey(
blank=True,
null=True,
on_delete=django.db.models.deletion.SET_NULL,
related_name="edition_contributor_profiles",
to="hadis.bookauthor",
verbose_name="Author",
),
),
(
"book_edition",
models.ForeignKey(
on_delete=django.db.models.deletion.CASCADE,
related_name="contributors",
to="hadis.bookedition",
verbose_name="Book Edition",
),
),
(
"role",
models.ForeignKey(
blank=True,
null=True,
on_delete=django.db.models.deletion.SET_NULL,
related_name="edition_contributors",
to="hadis.bookcontributorrole",
verbose_name="Role",
),
),
],
options={
"verbose_name": "Book Edition Contributor",
"verbose_name_plural": "Book Edition Contributors",
"ordering": ("id",),
},
bases=(utils.mixins.LowercaseSlugMixin, models.Model),
),
migrations.RunPython(
seed_contributor_roles_and_migrate_contributors,
migrations.RunPython.noop,
),
]

79
apps/hadis/models/reference.py

@ -692,6 +692,8 @@ class BookAuthor(LowercaseSlugMixin, models.Model):
super().save(*args, **kwargs)
self.researcher_profiles.all().update(name=self.name, slug=self.slug)
self.editor_profiles.all().update(name=self.name, slug=self.slug)
self.edition_contributor_profiles.all().update(name=self.name, slug=self.slug)
try:
self.sync_author_dates()
except Exception:
@ -957,3 +959,80 @@ class BookEditor(LowercaseSlugMixin, models.Model):
return self.name[0]['text']
except:
return self.slug or f"Editor {self.id}"
class BookContributorRole(LowercaseSlugMixin, models.Model):
slug_source_field = 'title'
title = models.JSONField(default=list, verbose_name=_('Title'))
slug = models.SlugField(max_length=255, verbose_name=_('slug'), blank=True, null=True, allow_unicode=True)
created_at = models.DateTimeField(auto_now_add=True, verbose_name=_('created at'))
updated_at = models.DateTimeField(auto_now=True, verbose_name=_('updated at'))
class Meta:
ordering = ('id',)
verbose_name = _('Book Contributor Role')
verbose_name_plural = _('Book Contributor Roles')
def __str__(self):
if self.title and isinstance(self.title, list) and len(self.title) > 0 and isinstance(self.title[0], dict):
return self.title[0].get('text') or self.title[0].get('title') or self.title[0].get('name') or f"Role {self.id}"
return f"Role {self.id}"
def get_title(self, lang):
if not self.title or not isinstance(self.title, list):
return None
for tr in self.title:
if isinstance(tr, dict) and tr.get('language_code') == lang:
return tr.get('text', '') or tr.get('title', '') or tr.get('name', '')
for tr in self.title:
if isinstance(tr, dict) and tr.get('language_code') == 'en':
return tr.get('text', '') or tr.get('title', '') or tr.get('name', '')
return None
class BookEditionContributor(LowercaseSlugMixin, models.Model):
slug_source_field = 'name'
book_edition = models.ForeignKey(
'BookEdition',
on_delete=models.CASCADE,
related_name='contributors',
verbose_name=_('Book Edition')
)
role = models.ForeignKey(
'BookContributorRole',
on_delete=models.SET_NULL,
null=True,
blank=True,
related_name='edition_contributors',
verbose_name=_('Role')
)
author = models.ForeignKey(
'BookAuthor',
on_delete=models.SET_NULL,
null=True,
blank=True,
related_name='edition_contributor_profiles',
verbose_name=_('Author')
)
name = models.JSONField(default=list, blank=True, verbose_name=_('Name'))
slug = models.SlugField(max_length=255, verbose_name=_('slug'), null=True, blank=True, allow_unicode=True)
class Meta:
ordering = ('id',)
verbose_name = _('Book Edition Contributor')
verbose_name_plural = _('Book Edition Contributors')
def save(self, *args, **kwargs):
if self.author:
self.name = self.author.name
self.slug = self.author.slug
super().save(*args, **kwargs)
def __str__(self):
try:
return self.name[0]['text']
except Exception:
return self.slug or f"Contributor {self.id}"

21
apps/hadis/serializers/hadis.py

@ -2021,7 +2021,7 @@ def get_cached_edition_metadata():
return _EDITION_METADATA_MEM
from django.db.models import Count, Prefetch
from ..models import BookEdition, BookVolume, BookResearcher, BookEditor
from ..models import BookEdition, BookVolume, BookResearcher, BookEditor, BookEditionContributor
editions = list(
BookEdition.objects.select_related(
@ -2033,6 +2033,7 @@ def get_cached_edition_metadata():
).prefetch_related(
Prefetch('researchers', queryset=BookResearcher.objects.select_related('author')),
Prefetch('editors', queryset=BookEditor.objects.select_related('author')),
Prefetch('contributors', queryset=BookEditionContributor.objects.select_related('author', 'role')),
)
)
by_id = {}
@ -2040,6 +2041,7 @@ def get_cached_edition_metadata():
for ed in editions:
ed._cached_researchers = list(ed.researchers.all())
ed._cached_editors = list(ed.editors.all())
ed._cached_contributors = list(ed.contributors.all())
by_id[ed.id] = ed
if ed.book_reference_id and ed.book_reference_id not in first_by_book_id:
first_by_book_id[ed.book_reference_id] = ed
@ -2134,18 +2136,32 @@ def _build_edition_info_dict(obj, edition, request):
"slug": author_obj.slug,
"name": get_localized_text(author_obj.name, request) if isinstance(author_obj.name, list) else (author_obj.name or ""),
}
return {
role_obj = getattr(c, "role", None)
role_data = None
if role_obj:
role_data = {
"id": role_obj.id,
"slug": role_obj.slug,
"title": get_localized_text(role_obj.title, request) if isinstance(role_obj.title, list) else (role_obj.title or ""),
}
ret = {
"id": c.id,
"name": name,
"slug": author_obj.slug if (author_obj and author_obj.slug) else getattr(c, "slug", None),
"author_id": getattr(c, "author_id", None),
"author": author_data,
}
if role_data is not None:
ret["role_id"] = role_obj.id
ret["role"] = role_data
return ret
raw_researchers = edition._cached_researchers if hasattr(edition, '_cached_researchers') else (edition.researchers.all() if hasattr(edition, "researchers") else [])
raw_editors = edition._cached_editors if hasattr(edition, '_cached_editors') else (edition.editors.all() if hasattr(edition, "editors") else [])
raw_contributors = edition._cached_contributors if hasattr(edition, '_cached_contributors') else (edition.contributors.all() if hasattr(edition, "contributors") else [])
researchers = [_serialize_contributor(r) for r in raw_researchers]
editors = [_serialize_contributor(e) for e in raw_editors]
contributors = [_serialize_contributor(c) for c in raw_contributors]
result = {
"id": edition.id,
@ -2158,6 +2174,7 @@ def _build_edition_info_dict(obj, edition, request):
"source_url": getattr(edition, "source_url", None) or "",
"researchers": researchers,
"editors": editors,
"contributors": contributors,
}
obj._edition_info_cache = result
return result

37
apps/hadis/serializers/reference_v2.py

@ -1,6 +1,6 @@
from rest_framework import serializers
from rest_framework.pagination import PageNumberPagination
from ..models import BookReference, BookAuthor, BookEdition, BookVolume, BookTag, BookResearcher, BookEditor
from ..models import BookReference, BookAuthor, BookEdition, BookVolume, BookTag, BookResearcher, BookEditor, BookContributorRole, BookEditionContributor
from .category import get_localized_text
from apps.hadis.serializers import HadisListSerializer, HadisShortSerializer
from ..serializers.category import LocalizedField
@ -19,6 +19,38 @@ class BookAuthorV2Serializer(serializers.ModelSerializer):
model = BookAuthor
fields = ['id', 'name', 'slug', 'image']
class BookContributorRoleV2Serializer(serializers.ModelSerializer):
title = LocalizedField()
class Meta:
model = BookContributorRole
fields = ['id', 'title', 'slug']
class BookEditionContributorV2Serializer(serializers.ModelSerializer):
name = LocalizedField()
role = BookContributorRoleV2Serializer(read_only=True)
role_id = serializers.SerializerMethodField()
author = BookAuthorV2Serializer(read_only=True)
author_id = serializers.SerializerMethodField()
slug = serializers.SerializerMethodField()
class Meta:
model = BookEditionContributor
fields = ['id', 'name', 'slug', 'role', 'role_id', 'author', 'author_id']
def get_role_id(self, obj):
return obj.role_id
def get_author_id(self, obj):
return obj.author_id
def get_slug(self, obj):
if obj.author and obj.author.slug:
return obj.author.slug
return obj.slug
class BookResearcherV2Serializer(serializers.ModelSerializer):
name = LocalizedField()
author = BookAuthorV2Serializer(read_only=True)
@ -117,6 +149,7 @@ class BookEditionV2Serializer(serializers.ModelSerializer):
publication_place = serializers.SerializerMethodField()
researchers = BookResearcherV2Serializer(many=True, read_only=True)
editors = BookEditorV2Serializer(many=True, read_only=True)
contributors = BookEditionContributorV2Serializer(many=True, read_only=True)
number_of_volumes = serializers.SerializerMethodField()
class Meta:
@ -124,7 +157,7 @@ class BookEditionV2Serializer(serializers.ModelSerializer):
fields = [
'id', 'title', 'publisher', 'publication_place', 'edition_number',
'year_of_publication', 'number_of_volumes', 'notes', 'source_url', 'tag',
'researchers', 'editors'
'researchers', 'editors', 'contributors'
]
def get_publisher(self, obj):

236
apps/hadis/serializers/serializers_admin.py

@ -18,7 +18,7 @@ from ..models import (
Hadis, HadisCategory, HadisStatus, HadisTag, HadisCorrection, HadisInterpretation, HadisCollection, HadisSect, HadisInCollection, HadisTransmitter, HadisReference, ReferenceImage,
BookReference, BookReferenceImage, BookReferenceDocument, BookAuthor, BookPublisher, BookAuthorRutba, BookAttribute, BookSubjectArea, BookType, BookTag, BookEdition, BookVolume, BookResearcher, BookEditor,
BookReference, BookReferenceImage, BookReferenceDocument, BookAuthor, BookPublisher, BookAuthorRutba, BookAttribute, BookSubjectArea, BookType, BookTag, BookEdition, BookVolume, BookResearcher, BookEditor, BookContributorRole, BookEditionContributor,
Transmitters, TransmitterReliability, TransmitterRelative, NarratorLayer, OpinionStatus, ScholarlyOpinion, TransmitterOpinion, TransmitterOriginalText,
@ -8265,6 +8265,35 @@ class AdminBookVolumeSerializer(serializers.ModelSerializer):
class AdminBookContributorRoleSerializer(serializers.ModelSerializer):
title = serializers.JSONField(default=list)
slug = serializers.SlugField(max_length=255, required=False, allow_null=True, allow_blank=True, allow_unicode=True)
class Meta:
model = BookContributorRole
fields = ["id", "title", "slug", "created_at", "updated_at"]
class AdminBookEditionContributorSerializer(serializers.ModelSerializer):
id = serializers.IntegerField(required=False)
name = serializers.JSONField(required=False, default=list)
role_detail = AdminBookContributorRoleSerializer(source="role", read_only=True)
author_detail = serializers.SerializerMethodField()
class Meta:
model = BookEditionContributor
fields = ["id", "role", "role_detail", "author", "author_detail", "name", "slug"]
def get_author_detail(self, obj):
if obj.author_id and obj.author:
return {
"id": obj.author.id,
"name": obj.author.name,
"slug": obj.author.slug,
}
return None
class AdminBookResearcherSerializer(serializers.ModelSerializer):
id = serializers.IntegerField(required=False)
@ -8359,6 +8388,8 @@ class AdminBookEditionSerializer(serializers.ModelSerializer):
notes = serializers.JSONField(required=False, default=list)
source_url = serializers.CharField(max_length=1000, required=False, allow_null=True, allow_blank=True)
tag = serializers.PrimaryKeyRelatedField(
queryset=BookTag.objects.all(),
@ -8381,6 +8412,8 @@ class AdminBookEditionSerializer(serializers.ModelSerializer):
editors = AdminBookEditorSerializer(many=True, required=False)
contributors = AdminBookEditionContributorSerializer(many=True, required=False)
researcher_author_id = serializers.IntegerField(write_only=True, required=False, allow_null=True)
editor_author_id = serializers.IntegerField(write_only=True, required=False, allow_null=True)
@ -8443,6 +8476,8 @@ class AdminBookEditionSerializer(serializers.ModelSerializer):
"editors",
"contributors",
"researcher_author_id",
"editor_author_id",
@ -8558,10 +8593,80 @@ class AdminBookEditionSerializer(serializers.ModelSerializer):
def _sync_contributors_list(self, edition, contributors_data):
if contributors_data is None:
return
edition.contributors.all().delete()
researcher_authors = []
editor_authors = []
for c_item in contributors_data:
if not isinstance(c_item, dict):
continue
role_val = c_item.get("role") if "role" in c_item else c_item.get("role_id")
author_val = c_item.get("author") if "author" in c_item else c_item.get("author_id")
role_obj = role_val if isinstance(role_val, BookContributorRole) else None
if not role_obj and role_val not in (None, "", "none", "null"):
try:
role_obj = BookContributorRole.objects.filter(id=int(role_val)).first()
except (ValueError, TypeError):
role_obj = None
author_obj = author_val if isinstance(author_val, BookAuthor) else None
if not author_obj and author_val not in (None, "", "none", "null"):
try:
author_obj = BookAuthor.objects.filter(id=int(author_val)).first()
except (ValueError, TypeError):
author_obj = None
raw_name = c_item.get("name") or (author_obj.name if author_obj else [])
raw_slug = c_item.get("slug") or (author_obj.slug if author_obj else None)
if not author_obj and not raw_name:
continue
BookEditionContributor.objects.create(
book_edition=edition,
role=role_obj,
author=author_obj,
name=raw_name,
slug=raw_slug,
)
if role_obj and role_obj.id == 1 and author_obj:
researcher_authors.append(author_obj)
elif role_obj and role_obj.id == 5 and author_obj:
editor_authors.append(author_obj)
# Keep legacy researchers/editors tables in sync when contributors are saved
edition.researchers.all().delete()
for a_obj in researcher_authors:
BookResearcher.objects.create(
book_edition=edition,
author=a_obj,
name=a_obj.name,
slug=a_obj.slug,
)
edition.editors.all().delete()
for a_obj in editor_authors:
BookEditor.objects.create(
book_edition=edition,
author=a_obj,
name=a_obj.name,
slug=a_obj.slug,
)
def _invalidate_edition_cache(self):
try:
from . import hadis as hadis_serializers
hadis_serializers._EDITION_METADATA_MEM = None
except Exception:
pass
def create(self, validated_data):
books_data = validated_data.pop("books", None)
contributors_data = validated_data.pop("contributors", None)
researchers_data = validated_data.pop("researchers", [])
editors_data = validated_data.pop("editors", [])
@ -8576,25 +8681,19 @@ class AdminBookEditionSerializer(serializers.ModelSerializer):
edition = super().create(validated_data)
for res_data in researchers_data:
BookResearcher.objects.create(book_edition=edition, **res_data)
for ed_data in editors_data:
BookEditor.objects.create(book_edition=edition, **ed_data)
author_links_dict = {}
if has_res_id:
author_links_dict["researcher_author_id"] = res_author_id
if has_ed_id:
author_links_dict["editor_author_id"] = ed_author_id
self._handle_author_links(edition, author_links_dict)
if contributors_data is not None:
self._sync_contributors_list(edition, contributors_data)
else:
for res_data in researchers_data:
BookResearcher.objects.create(book_edition=edition, **res_data)
for ed_data in editors_data:
BookEditor.objects.create(book_edition=edition, **ed_data)
author_links_dict = {}
if has_res_id:
author_links_dict["researcher_author_id"] = res_author_id
if has_ed_id:
author_links_dict["editor_author_id"] = ed_author_id
self._handle_author_links(edition, author_links_dict)
if books_data is not None:
@ -8604,6 +8703,8 @@ class AdminBookEditionSerializer(serializers.ModelSerializer):
edition.books.add(edition.book_reference)
self._invalidate_edition_cache()
return edition
@ -8612,6 +8713,8 @@ class AdminBookEditionSerializer(serializers.ModelSerializer):
books_data = validated_data.pop("books", None)
contributors_data = validated_data.pop("contributors", None)
researchers_data = validated_data.pop("researchers", None)
editors_data = validated_data.pop("editors", None)
@ -8626,71 +8729,86 @@ class AdminBookEditionSerializer(serializers.ModelSerializer):
edition = super().update(instance, validated_data)
if researchers_data is not None:
if contributors_data is not None:
self._sync_contributors_list(instance, contributors_data)
else:
if researchers_data is not None:
# Delete researchers no longer in the request payload
# Delete researchers no longer in the request payload
keep_ids = [r.get("id") for r in researchers_data if r.get("id")]
keep_ids = [r.get("id") for r in researchers_data if r.get("id")]
instance.researchers.exclude(id__in=keep_ids).delete()
instance.researchers.exclude(id__in=keep_ids).delete()
for res_data in researchers_data:
for res_data in researchers_data:
res_id = res_data.get("id")
res_id = res_data.get("id")
if res_id:
if res_id:
# Update existing researcher
# Update existing researcher
res_data_clean = {k: v for k, v in res_data.items() if k != "id"}
res_data_clean = {k: v for k, v in res_data.items() if k != "id"}
BookResearcher.objects.filter(id=res_id, book_edition=instance).update(**res_data_clean)
BookResearcher.objects.filter(id=res_id, book_edition=instance).update(**res_data_clean)
res_obj = BookResearcher.objects.filter(id=res_id, book_edition=instance).first()
res_obj = BookResearcher.objects.filter(id=res_id, book_edition=instance).first()
if res_obj:
if res_obj:
res_obj.save()
res_obj.save()
else:
else:
# Create new researcher
# Create new researcher
BookResearcher.objects.create(book_edition=instance, **res_data)
BookResearcher.objects.create(book_edition=instance, **res_data)
if editors_data is not None:
if editors_data is not None:
# Delete editors no longer in the request payload
# Delete editors no longer in the request payload
keep_ids = [e.get("id") for e in editors_data if e.get("id")]
keep_ids = [e.get("id") for e in editors_data if e.get("id")]
instance.editors.exclude(id__in=keep_ids).delete()
instance.editors.exclude(id__in=keep_ids).delete()
for ed_data in editors_data:
for ed_data in editors_data:
ed_id = ed_data.get("id")
ed_id = ed_data.get("id")
if ed_id:
if ed_id:
# Update existing editor
# Update existing editor
ed_data_clean = {k: v for k, v in ed_data.items() if k != "id"}
ed_data_clean = {k: v for k, v in ed_data.items() if k != "id"}
BookEditor.objects.filter(id=ed_id, book_edition=instance).update(**ed_data_clean)
BookEditor.objects.filter(id=ed_id, book_edition=instance).update(**ed_data_clean)
ed_obj = BookEditor.objects.filter(id=ed_id, book_edition=instance).first()
ed_obj = BookEditor.objects.filter(id=ed_id, book_edition=instance).first()
if ed_obj:
if ed_obj:
ed_obj.save()
ed_obj.save()
else:
else:
# Create new editor
BookEditor.objects.create(book_edition=instance, **ed_data)
author_links_dict = {}
if has_res_id:
# Create new editor
author_links_dict["researcher_author_id"] = res_author_id
BookEditor.objects.create(book_edition=instance, **ed_data)
if has_ed_id:
author_links_dict["editor_author_id"] = ed_author_id
self._handle_author_links(edition, author_links_dict)
@ -8712,19 +8830,7 @@ class AdminBookEditionSerializer(serializers.ModelSerializer):
edition.save(update_fields=['book_reference'])
author_links_dict = {}
if has_res_id:
author_links_dict["researcher_author_id"] = res_author_id
if has_ed_id:
author_links_dict["editor_author_id"] = ed_author_id
self._handle_author_links(edition, author_links_dict)
self._invalidate_edition_cache()
return edition

7
apps/hadis/urls.py

@ -69,8 +69,8 @@ from .views_admin import (
DovodiTransmitterProfessionViewSet,
DovodiSahabiStatusViewSet,
DovodiMadhhabViewSet,
DovodiRelationTypeViewSet
DovodiRelationTypeViewSet,
DovodiBookContributorRoleViewSet
)
from .views.reference_v2 import BookAuthorListView, BookAuthorDetailView, AuthorReferencesListView, BookAuthorSyncView
@ -175,6 +175,9 @@ admin_router.register(r'dovodi-countries', DovodiCountryViewSet, basename='dovod
admin_router.register(r'countries', DovodiCountryViewSet, basename='admin-countries')
admin_router.register(r'dovodi-publishers', DovodiBookPublisherViewSet, basename='dovodi-publishers')
admin_router.register(r'publishers', DovodiBookPublisherViewSet, basename='admin-publishers')
admin_router.register(r'dovodi-contributor-roles', DovodiBookContributorRoleViewSet, basename='dovodi-contributor-roles')
admin_router.register(r'contributor-roles', DovodiBookContributorRoleViewSet, basename='admin-contributor-roles')
admin_router.register(r'book-contributor-roles', DovodiBookContributorRoleViewSet, basename='admin-book-contributor-roles')
admin_router.register(r'dovodi-kunyas', DovodiKunyaViewSet, basename='dovodi-kunyas')
admin_router.register(r'dovodi-mawla-statuses', DovodiMawlaStatusViewSet, basename='dovodi-mawla-statuses')
admin_router.register(r'mawla-statuses', DovodiMawlaStatusViewSet, basename='admin-mawla-statuses')

46
apps/hadis/views_admin.py

@ -24,7 +24,7 @@ from .models import (
Hadis, HadisCategory, HadisCollection, HadisInCollection, HadisCorrection, HadisInterpretation, HadisStatus, HadisTag, HadisSect, HadisTransmitter, HadisReference, ReferenceImage,
BookReference, BookReferenceImage, BookReferenceDocument, BookAuthor, BookAuthorRutba, BookAttribute, BookSubjectArea, BookType, BookTag, BookEdition, BookVolume,
BookReference, BookReferenceImage, BookReferenceDocument, BookAuthor, BookAuthorRutba, BookAttribute, BookSubjectArea, BookType, BookTag, BookEdition, BookVolume, BookContributorRole, BookEditionContributor,
Transmitters, TransmitterReliability, NarratorLayer, OpinionStatus, ScholarlyOpinion, TransmitterOpinion, TransmitterOriginalText,
@ -129,6 +129,7 @@ from .serializers.serializers_admin import (
AdminTransmitterOriginalTextSerializer,
AdminBookEditionSerializer,
AdminBookContributorRoleSerializer,
AdminBookVolumeSerializer,
@ -2842,7 +2843,7 @@ class AdminBookEditionViewSet(ModelViewSet):
"publisher_item__country",
"city_of_publication_city__country",
"country_of_publication_country",
).prefetch_related("books", "volumes", "researchers", "editors")
).prefetch_related("books", "volumes", "researchers", "editors", "contributors__role", "contributors__author")
book_reference_id = self.request.query_params.get("book_reference_id")
@ -2895,6 +2896,47 @@ class AdminBookTagViewSet(ModelViewSet):
return queryset.order_by("-id")
class DovodiBookContributorRoleViewSet(ModelViewSet):
permission_classes = [IsAuthenticated, IsSuperAdmin]
authentication_classes = [TokenAuthentication]
serializer_class = AdminBookContributorRoleSerializer
pagination_class = OptionalPagination
parser_classes = (JSONParser, MultiPartParser, FormParser)
def get_queryset(self):
queryset = BookContributorRole.objects.all()
search_query = self.request.query_params.get("search")
if search_query:
queryset = queryset.filter(
Q(title__icontains=search_query) | Q(slug__icontains=search_query)
)
return queryset.order_by("id")
def perform_create(self, serializer):
super().perform_create(serializer)
try:
from .serializers import hadis as hadis_serializers
hadis_serializers._EDITION_METADATA_MEM = None
except Exception:
pass
def perform_update(self, serializer):
super().perform_update(serializer)
try:
from .serializers import hadis as hadis_serializers
hadis_serializers._EDITION_METADATA_MEM = None
except Exception:
pass
def perform_destroy(self, instance):
super().perform_destroy(instance)
try:
from .serializers import hadis as hadis_serializers
hadis_serializers._EDITION_METADATA_MEM = None
except Exception:
pass

197
docs/PODCAST_RSS_DISTRIBUTION_GUIDE.md

@ -0,0 +1,197 @@
# راهنمای جامع پیاده‌سازی و تست سیستم انتشار خودکار پادکست (RSS Distribution & Import)
این مستند یک نقشه راه عملیاتی از صفر تا صد است تا بدون وابستگی به اکانت‌های کارفرما، بتوانیم کل چرخه **تولید فید RSS در بک‌اند**، **ایمپورت از RSS خارجی** و **انتشار خودکار روی پلتفرم‌های پادکست (Castbox، Spotify، Apple Podcasts و Mave)** را با اکانت‌های تستی خودمان پیاده‌سازی و آزمایش کنیم.
---
## ۱. معماری کلی سیستم چگونه کار می‌کند؟
در اکوسیستم جهانی پادکست، پلتفرم‌های شنیدن پادکست فایل صوتی را از شما دریافت (Push) نمی‌کنند، بلکه از طریق یک لینک استاندارد **XML (RSS 2.0 + iTunes Tags)** که سرور شما تولید می‌کند، اپیزودها را می‌خوانند (Pull).
```mermaid
sequenceDiagram
autonumber
participant Admin as "پنل ری‌اکت (ادمین)"
participant Backend as "بک‌اند جنگو (Dovoodi)"
participant RSS as "اندپوینت RSS (/api/podcast/rss.xml)"
participant Platforms as "پلتفرم‌ها (Castbox / Apple / Spotify)"
Admin->>Backend: آپلود اپیزود جدید (MP3 + کاور + عنوان + توضیحات)
Backend->>Backend: ذخیره در جدول Podcast و محاسبه زمان (audio_time)
Platforms->>RSS: درخواست دوره‌ای (Polling) برای بررسی اپیزودهای جدید
RSS->>Backend: خواندن لیست اپیزودهای فعال از دیتابیس
RSS-->>Platforms: برگرداندن XML استاندارد با تگ‌های <item> و <enclosure>
Platforms->>Platforms: انتشار خودکار اپیزود جدید در اپلیکیشن‌ها
```
---
## ۲. پیش‌نیازهای فنی برای اینکه پلتفرم‌ها فید ما را قبول کنند
پلتفرم‌های پادکست (مخصوصاً Apple Podcasts و Castbox) قبل از تایید لینک RSS شما، چند قانون فنی را اعتبارسنجی (Validate) می‌کنند:
> [!IMPORTANT]
> **الزامات اجباری فید RSS استاندارد پادکست:**
> 1. **پشتیبانی از HTTPS و Byte-Range:** لینک فید RSS، لینک عکس کاور و لینک فایل‌های صوتی `.mp3` حتماً باید روی `https://` باشند و سرور وب (Nginx) باید هدر `Accept-Ranges: bytes` را روی فایل‌های صوتی برگرداند (که Nginx به‌صورت پیش‌فرض روی فایل‌های استاتیک/مدیا پشتیبانی می‌کند).
> 2. **ابعاد تصویر کاور کانال (`<itunes:image>`):** تصویر کاور اصلی پادکست باید مربع (`1:1`) و حداقل **`1400x1400` پیکسل** و حداکثر **`3000x3000` پیکسل** (فرمت JPG یا PNG با رنگ RGB) باشد.
> 3. **وجود حداقل ۱ اپیزود منتشرشده:** فید RSS بدون تگ `<item>` (اپیزود) توسط پلتفرم‌ها تایید نمی‌شود؛ پس قبل از ثبت لینک در پلتفرم‌ها باید حداقل ۱ اپیزود تستی در پنل ساخته باشیم.
> 4. **تگ `<itunes:owner>` معتبر:** داخل فید باید یک تگ `<itunes:email>` وجود داشته باشد که به آن ایمیل دسترسی داشته باشید، چون پلتفرم‌هایی مثل Castbox و Spotify کد تایید مالکیت (OTP) را به همان ایمیل داخل فید می‌فرستند!
---
## ۳. پیاده‌سازی در کد پروژه (بک‌اند و پنل ری‌اکت)
### بخش الف: تغییرات بک‌اند جنگو (`dovoodi/backend`)
#### ۱. مدل تنظیمات کانال پادکست (`PodcastChannelSettings` یا فیلدهای تکمیلی در `PodcastPlaylist`)
در فایل `apps/podcast/models.py` یک مدل Singleton (یا سطح پلی‌لیست) برای نگهداری متادیتای کلی فید RSS تعریف می‌کنیم:
- `title`: نام کانال پادکست (مثلاً `Про ислам`)
- `description`: توضیحات کانال
- `author`: نام گوینده/نویسنده (`<itunes:author>`)
- `owner_name` و `owner_email`: نام و ایمیل مالک برای تایید مالکیت در پلتفرم‌ها (`<itunes:owner>`)
- `language`: کد زبان (مثلاً `ru` یا `en`)
- `category` و `subcategory`: دسته‌بندی استاندارد اپل (مثلاً `Religion & Spirituality` -> `Islam`)
- `copyright`: متن کپی‌رایت
- `cover_image`: تصویر کاور اصلی کانال (۱۴۰۰×۱۴۰۰)
- `explicit`: بولین (`false`)
- `source_rss_url`: لینک RSS خارجی جهت ایمپورت/سینک (مثلاً `https://cloud.mave.digital/34205`)
همچنین در مدل `Podcast`:
- افزودن فیلد اختیاری `external_guid = models.CharField(max_length=255, null=True, blank=True, unique=True)` تا هنگام ایمپورت از RSS خارجی، از ساخت اپیزود تکراری جلوگیری شود و شناسه `<guid>` هر اپیزود ثابت بماند.
- افزودن فیلدهای اختیاری `episode_number` و `season_number`.
#### ۲. ساخت اندپوینت خروجی RSS XML در `apps/podcast/views.py` و `apps/podcast/urls.py`
ایجاد یک View عمومی (بدون نیاز به توکن لاگین، چون سرورهای Apple و Castbox باید بتوانند آن را بخوانند) در مسیر:
- `/api/podcast/rss.xml` (فید سراسری پادکست‌ها)
- `/api/podcast/playlists/<slug>/rss.xml` (فید اختصاصی هر پلی‌لیست)
این View هدر `Content-Type: application/rss+xml; charset=utf-8` برمی‌گرداند و ساختار زیر را تولید می‌کند:
```xml
<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0"
xmlns:dc="http://purl.org/dc/elements/1.1/"
xmlns:content="http://purl.org/rss/1.0/modules/content/"
xmlns:atom="http://www.w3.org/2005/Atom"
xmlns:itunes="http://www.itunes.com/dtds/podcast-1.0.dtd">
<channel>
<title><![CDATA[عنوان کانال]]></title>
<description><![CDATA[توضیحات کانال]]></description>
<link>https://yourdomain.com</link>
<language>ru</language>
<itunes:type>episodic</itunes:type>
<itunes:explicit>false</itunes:explicit>
<itunes:author>نام نویسنده</itunes:author>
<itunes:owner>
<itunes:name>نام مالک</itunes:name>
<itunes:email>your-test-email@gmail.com</itunes:email>
</itunes:owner>
<itunes:image href="https://api.yourdomain.com/media/podcast/channel_cover.jpg"/>
<itunes:category text="Religion &amp; Spirituality">
<itunes:category text="Islam"/>
</itunes:category>
<!-- تکرار برای هر اپیزود فعال در جدول Podcast -->
<item>
<title><![CDATA[عنوان اپیزود]]></title>
<description><![CDATA[توضیحات اپیزود]]></description>
<guid isPermaLink="false">podcast-uuid-or-id</guid>
<pubDate>Thu, 23 Apr 2026 03:00:00 GMT</pubDate>
<enclosure url="https://api.yourdomain.com/media/podcast/audio/episode1.mp3"
length="48752533"
type="audio/mpeg"/>
<itunes:duration>3037</itunes:duration>
<itunes:image href="https://api.yourdomain.com/media/podcast_thumbnails/ep1.png"/>
<itunes:explicit>false</itunes:explicit>
<itunes:episodeType>full</itunes:episodeType>
</item>
</channel>
</rss>
```
#### ۳. ساخت سرویس و اندپوینت Import از RSS خارجی (`/api/podcast/admin/import-rss/`)
- دریافت آدرس فید (مثلاً `https://cloud.mave.digital/34205`) یا فایل XML.
- پارس کردن تگ `<channel>` و تمام تگ‌های `<item>` با `xml.etree.ElementTree`.
- بررسی `guid` هر آیتم؛ اگر قبلاً در جدول `Podcast` وجود نداشت:
- دانلود تصویر `<itunes:image>` و فایل صوتی `<enclosure url="...">`
- تبدیل `<itunes:duration>` (ثانیه) به `datetime.time` برای فیلد `audio_time`
- ذخیره اپیزود در دیتابیس.
---
### بخش ب: تغییرات پنل ری‌اکت (`dovodi-panel/dashboard`)
در بخش پادکست‌های پنل (`src/pages/Podcasts.tsx` / `src/components/archive/ArchiveSectionPage.tsx`):
1. **کارت / مودال «RSS & Distribution Settings»:**
- نمایش لینک RSS سایت ما همراه با دکمه **Copy RSS URL** و دکمه **Preview XML**.
- فرم ویرایش مشخصات فید کانال (`Channel Title`، `Author`، `Owner Email` برای دریافت کد تایید پلتفرم‌ها، `Cover 1400x1400`، `Language`، `Category`).
2. **مودال «Import from RSS Feed»:**
- ورودی لینک RSS (یا آپلود فایل XML فید) + انتخاب پلی‌لیست مقصد.
- نمایش پیش‌نمایش تعداد اپیزودهای پیداشده در فید و شروع ایمپورت در پس‌زمینه.
---
## ۴. مراحل تست عملی توسط خودمان (با اکانت‌های تستی رایگان)
برای اینکه بدون نیاز به کارفرما، کل فرآیند را خودمان تست کنیم، مراحل زیر را به ترتیب انجام می‌دهیم:
```mermaid
flowchart LR
A["۱. آماده‌سازی لینک عمومی\n(سرور تست یا Cloudflare Tunnel)"] --> B["۲. ساخت ۱ اپیزود تستی در پنل\nو تنظیم ایمیل خودمان در Owner Email"]
B --> C["۳. تست اعتبارسنجی فید در\nCastFeedValidator / Podba.se"]
C --> D["۴. ثبت فید در Castbox و Spotify\nو دریافت کد تایید روی ایمیل"]
D --> E["۵. آپلود اپیزود دوم در پنل\nو مشاهده انتشار خودکار"]
```
### گام ۱: قابل دسترس کردن بک‌اند روی اینترنت (اگر روی لوکال تست می‌کنید)
چون سرورهای Castbox و Spotify باید بتوانند لینک RSS و فایل MP3 شما را دانلود کنند، نمی‌توانید آدرس `http://127.0.0.1:8000` را به آن‌ها بدهید.
- **اگر روی سرور استیجینگ/پروداکشن هستید:** از همان دامنه `https://...` سرور استفاده کنید.
- **اگر روی سیستم لوکال خودتان تست می‌کنید:** با یک دستور رایگان Cloudflare Tunnel یا ngrok یک لینک HTTPS عمومی بگیرید:
```powershell
npx cloudflared tunnel --url http://127.0.0.1:8000
```
این دستور یک آدرس مثل `https://random-name.trycloudflare.com` به شما می‌دهد که لینک فید شما می‌شود:
`https://random-name.trycloudflare.com/api/podcast/rss.xml`
### گام ۲: تنظیم ایمیل خودتان در فید و ساخت اپیزود تستی اول
1. در تنظیمات RSS پنل، فیلد **Owner Email** را روی **ایمیل شخصی خودتان** (مثلاً جیمیل خودتان) بگذارید.
2. یک تصویر مربع حداقل `1400x1400` پیکسل برای کاور کانال انتخاب کنید.
3. در پنل ری‌اکت یک پادکست تستی با یک فایل `.mp3` کوتاه آپلود و ذخیره کنید.
### گام ۳: تست سلامت فید در ابزارهای Validator رایگان (قبل از ثبت در پلتفرم‌ها)
قبل از اینکه سراغ ساخت اکانت در پلتفرم‌ها بروید، لینک `rss.xml` خودتان را در یکی از این دو سایت رایگان تست کنید تا مطمئن شوید ۱۰۰٪ استاندارد است:
1. **Cast Feed Validator:** https://www.castfeedvalidator.com
2. **Podbase Validator:** https://podba.se/validate
> [!TIP]
> اگر هر دو سایت تیک سبز دادند (کاور ۱۴۰۰×۱۴۰۰، تگ‌های iTunes و پشتیبانی از Byte-Range روی فایل MP3)، فید شما آماده اتصال به تمام پلتفرم‌های دنیاست.
### گام ۴: ثبت رایگان در پلتفرم‌ها با اکانت تستی خودتان
#### ۱. تست در **Castbox** (کاملاً رایگان و سریع‌ترین برای تست - حدود ۵ دقیقه)
1. وارد سایت **Castbox Creator Studio** شوید: https://castbox.fm/creator (با جیمیل خودتان ثبت‌نام کنید).
2. از منوی بالا یا داشبورد روی **Claim Ownership / Submit Podcast** کلیک کنید.
3. لینک RSS سایت خودمان (`https://.../api/podcast/rss.xml`) را وارد کنید.
4. کست‌باکس ایمیل داخل تگ `<itunes:email>` فید را می‌خواند و یک کد تایید به جیمیل شما می‌فرستد.
5. کد را وارد کنید؛ پادکست بلافاصله در Castbox ساخته می‌شود!
#### ۲. تست در **Spotify for Creators (Podcasters)** (کاملاً رایگان - حدود ۵ تا ۱۰ دقیقه)
1. وارد https://creators.spotify.com شوید و با یک اکانت رایگان Spotify لاگین کنید.
2. گزینه **I already have a podcast** را بزنید و لینک RSS سایت خودمان را وارد کنید.
3. اسپاتیفای یک کد ۸ رقمی به ایمیل داخل `<itunes:email>` فید می‌فرستد.
4. کد را وارد کنید و Submit را بزنید؛ پادکست شما روی Spotify قرار می‌گیرد.
#### ۳. تست در **Mave (`mave.digital`)** (برای تست ایمپورت و فید Mave)
1. وارد https://app.mave.digital شوید و با ایمیل خودتان یک اکانت رایگان بسازید.
2. گزینه **Создать подкаст (Create Podcast)** -> **Импортировать (Import via RSS)** را بزنید.
3. لینک RSS سرور خودمان را بدهید تا ببینید چطور Mave اپیزودهای پنل ما را می‌خواند، یا برعکس لینک RSS تستی Mave را در پنل خودمان ایمپورت کنید.
#### ۴. تست در **Apple Podcasts Connect**
> [!NOTE]
> برخلاف Castbox و Spotify که کاملاً رایگان هستند، ثبت پادکست جدید در https://podcastsconnect.apple.com نیازمند داشتن یک Apple Account با روش پرداخت معتبر (یا اکانت توسعه‌دهنده اپل) است و بررسی اولیه آن توسط تیم اپل ۲۴ تا ۷۲ ساعت طول می‌کشد. بنابراین برای تست فنی خودمان، **Castbox** و **Spotify** بهترین و سریع‌ترین گزینه‌ها هستند و از دقیقاً همان استاندارد XML اپل استفاده می‌کنند.
### گام ۵: تست انتشار خودکار اپیزود دوم
1. حالا که فید را در Castbox یا Spotify ثبت کردید، دیگر وارد سایت آن‌ها نشوید.
2. فقط وارد **پنل ری‌اکت خودمان** شوید و **اپیزود تستی شماره ۲** را آپلود کنید.
3. لینک `/api/podcast/rss.xml` را رفرش کنید تا ببینید اپیزود ۲ به بالای XML اضافه شده است.
4. پس از سینک دوره‌ای پلتفرم، اپیزود ۲ به‌صورت خودکار در Castbox و Spotify ظاهر می‌شود!
Loading…
Cancel
Save