django-simple-comment-module 1.0.0

Простая система комментариев с рейтингом для Django

Django Simple Ratings ⭐

Простая, но мощная система комментариев с рейтингом для Django. Поддерживает анонимных и авторизованных пользователей, ответы администратора, модерацию и многое другое.

✨ Особенности

• ⭐ 5-звездочный рейтинг - интуитивный интерфейс оценки
• 💬 Комментарии - с поддержкой ответов администратора
• 👥 Поддержка всех пользователей - анонимные и авторизованные
• 🛡️ Защита от спама - встроенная капча и ограничения
• 📊 Статистика - средний рейтинг, распределение звезд
• 🎨 Адаптивный дизайн - работает на всех устройствах
• ⚡ AJAX взаимодействие - без перезагрузки страницы
• 🔧 Легкая интеграция - всего 3 шага установки

📦 Установка

Способ 1: Установка из PyPI (рекомендуется)

pip install django-simple-comment-module

Способ 2: Установка из исходников

# Клонируйте репозиторий
git clone https://github.com/glazyrinae/django-simple-comment-module
cd django-simple-comment-module

# Установите в режиме разработки
pip install -e .

# Или соберите пакет
python setup.py sdist bdist_wheel
pip install dist/django_simple_comment_module-*.tar.gz

🚀 Быстрый старт

Шаг 1: Добавьте в настройки Django

# settings.py

INSTALLED_APPS = [
    # ...
    'django.contrib.contenttypes',  # Обязательно для GenericForeignKey
    'django_simple_comment_module',
    # ...
]

# Опциональные настройки (по умолчанию)
SIMPLE_RATINGS_CONFIG = {
    'ITEMS_PER_PAGE': 10,           # Количество комментариев на странице
    'REQUIRE_EMAIL': False,         # Обязателен ли email для анонимных
    'ALLOW_ANONYMOUS': True,        # Разрешить анонимные комментарии
    'MODERATE_ALL': False,          # Модерировать все комментарии
    'AUTO_APPROVE_AUTH': True,      # Автоодобрение для авторизованных
    'CAPTCHA_ENABLED': True,        # Включить капчу для анонимных
    'COOLDOWN_SECONDS': 30,         # Задержка между комментариями
}

Шаг 2: Добавьте URL-адреса

# urls.py проекта

from django.urls import include, path

urlpatterns = [
    # ...
    path('ratings/', include('django_simple_comment_module.urls')),
    # ...
]

Шаг 3: Выполните миграции

python manage.py makemigrations django_simple_comment_module
python manage.py migrate django_simple_comment_module

Шаг 4: Используйте в шаблонах

<!-- В шаблоне вашего объекта (товара, статьи и т.д.) -->
{% load rating_tags %}

<div class="product-detail">
    <h1>{{ product.title }}</h1>
    <p>{{ product.description }}</p>
    
    <!-- Виджет комментариев -->
    {% comments_widget product %}
</div>

📖 Подробное руководство

1. Базовая интеграция

# views.py
from django.shortcuts import render
from django_simple_comment_module.models import Comment

def product_detail(request, product_id):
    product = get_object_or_404(Product, id=product_id)
    
    # Получение статистики
    stats = Comment.get_statistics(product)
    
    # Получение комментариев
    comments = Comment.get_for_object(product)
    
    context = {
        'product': product,
        'rating_stats': stats,
        'comments': comments,
    }
    return render(request, 'product_detail.html', context)

2. Кастомизация виджета

{% comments_widget object 
    show_form=True      # Показывать форму добавления
    show_stats=True     # Показывать статистику
    items_per_page=10   # Комментариев на странице
    sort_by='newest'    # Сортировка: newest, oldest, highest, lowest
 %}

3. Шаблонные теги

{% load rating_tags %}

<!-- Средний рейтинг -->
Средняя оценка: {% average_rating product %}

<!-- Количество комментариев -->
Отзывов: {% get_comments_count product %}

<!-- Полная статистика -->
{% get_rating_stats product as stats %}
<div class="stats">
    Среднее: {{ stats.average_rating|floatformat:1 }}
    Всего: {{ stats.total }}
    С ответами: {{ stats.with_replies }}
</div>

4. Административная панель

После установки в админке Django появятся:

• Комментарии - управление всеми комментариями
• Комментарии на модерации - только ожидающие одобрения
• Одобренные комментарии - только активные комментарии

Доступные действия:

• Одобрение/отклонение комментариев
• Ответы от имени администратора
• Верификация комментариев
• Пометить как спам

🎨 Кастомизация

1. Кастомизация шаблонов

Создайте в своем проекте:

your_project/
└── templates/
    └── django_simple_comment_module/
        ├── widget.html          # Основной виджет
        ├── comment_item.html    # Элемент комментария
        └── form.html            # Форма добавления

2. Кастомизация стилей

/* your_static/css/custom_ratings.css */

/* Переопределение цветов звезд */
.stars-display .star.filled {
    color: #ff6b35; /* Ваш цвет */
}

/* Кастомизация сообщений */
.message-success {
    background-color: #d4edda;
    border-color: #c3e6cb;
    color: #155724;
}

/* Адаптация под ваш дизайн */
.comments-widget {
    font-family: 'Your Font', sans-serif;
    max-width: 800px;
}

3. Кастомизация поведения

# Создание собственной формы
from django_simple_comment_module.forms import CommentForm

class CustomCommentForm(CommentForm):
    """Расширенная форма с дополнительными полями"""
    
    class Meta(CommentForm.Meta):
        fields = CommentForm.Meta.fields + ['custom_field']
    
    def clean_custom_field(self):
        # Ваша валидация
        pass

# Использование кастомной формы
from django_simple_comment_module.views import SubmitCommentView

class CustomSubmitView(SubmitCommentView):
    form_class = CustomCommentForm

🔧 Расширенные возможности

1. Сигналы

from django_simple_comment_module.models import Comment
from django.dispatch import receiver
from django.db.models.signals import post_save

@receiver(post_save, sender=Comment)
def handle_new_comment(sender, instance, created, **kwargs):
    """Обработка нового комментария"""
    if created:
        # Отправка уведомления
        send_notification_email(instance)
        
        # Интеграция с другими системами
        update_product_rating(instance.content_object)

def send_notification_email(comment):
    """Отправка email уведомления"""
    # Ваша логика отправки email
    pass

2. API эндпоинты

Пакет предоставляет JSON API:

// Получение комментариев
fetch('/ratings/list/{content_type_id}/{object_id}/?page=1&sort=newest')
    .then(response => response.json())
    .then(data => console.log(data));

// Отправка комментария
fetch('/ratings/submit/{content_type_id}/{object_id}/', {
    method: 'POST',
    body: new FormData(form)
});

3. Интеграция с Django REST Framework

# serializers.py
from django_simple_comment_module.models import Comment
from rest_framework import serializers

class CommentSerializer(serializers.ModelSerializer):
    class Meta:
        model = Comment
        fields = '__all__'

# views.py
from rest_framework import viewsets

class CommentViewSet(viewsets.ModelViewSet):
    queryset = Comment.objects.all()
    serializer_class = CommentSerializer

🧪 Тестирование

# Установите зависимости для тестирования
pip install -e .[test]

# Запустите тесты
pytest

# С покрытием кода
coverage run -m pytest
coverage report
coverage html  # Генерация HTML отчета

📊 Миграция с других систем

Из django-comments-xtd

# migration_script.py
from old_app.models import OldComment
from django_simple_comment_module.models import Comment
from django.contrib.contenttypes.models import ContentType

def migrate_comments():
    for old_comment in OldComment.objects.all():
        Comment.objects.create(
            content_type=ContentType.objects.get_for_model(old_comment.content_object),
            object_id=old_comment.object_id,
            name=old_comment.user_name,
            email=old_comment.user_email,
            rating=old_comment.rating or 0,
            text=old_comment.comment,
            created_at=old_comment.submit_date,
            status='approved' if old_comment.is_public else 'pending'
        )

🤝 Участие в разработке

Мы приветствуем вклад в развитие проекта!

Процесс внесения изменений

1. Форкните репозиторий
2. Создайте ветку для фичи (git checkout -b feature/amazing-feature)
3. Зафиксируйте изменения (git commit -m 'Add amazing feature')
4. Отправьте в репозиторий (git push origin feature/amazing-feature)
5. Создайте Pull Request

Требования к коду

# Проверка стиля кода
flake8 django_simple_comment_module

# Форматирование кода
black django_simple_comment_module

# Сортировка импортов
isort django_simple_comment_module

📈 Производительность

Оптимизация запросов

Пакет использует:

• Индексы для быстрого поиска
• Select related для уменьшения запросов
• Кэширование статистики
• Пагинацию для больших списков

Мониторинг

# Добавьте в ваши middleware
from django_simple_comment_module.middleware import RatingMetricsMiddleware

MIDDLEWARE = [
    # ...
    'django_simple_comment_module.middleware.RatingMetricsMiddleware',
    # ...
]

🔒 Безопасность

Встроенные механизмы защиты:

• ✅ Валидация всех входных данных
• ✅ Защита от XSS-атак
• ✅ Защита от CSRF
• ✅ Лимиты на частоту запросов
• ✅ Защита от SQL-инъекций
• ✅ Безопасное хранение паролей (для авторизованных)

Рекомендации по безопасности:

1. Всегда используйте HTTPS в продакшене
2. Регулярно обновляйте Django и зависимости
3. Настройте правильные CORS-заголовки
4. Используйте Django Security Middleware

🌐 Многоязычность

# settings.py
LANGUAGES = [
    ('en', 'English'),
    ('ru', 'Russian'),
    # Добавьте другие языки
]

# Шаблоны поддерживают i18n
{% trans "Leave a comment" %}

📄 Документация

Дополнительная документация доступна:

• 📚 Полное руководство
• 🎛️ API Reference
• 🎨 Кастомизация
• 🚀 Развертывание
• 🔧 Миграция

🤔 Часто задаваемые вопросы

Q: Как добавить дополнительные поля в комментарий?

A: Наследуйтесь от модели Comment:

from django_simple_comment_module.models import Comment

class ExtendedComment(Comment):
    additional_field = models.CharField(max_length=100)

Q: Можно ли отключить капчу?

A: Да, в настройках:

SIMPLE_RATINGS_CONFIG = {
    'CAPTCHA_ENABLED': False,
}

Q: Как изменить количество звезд?

A: Создайте свой виджет или измените шаблон:

<!-- В вашем widget.html -->
<div class="stars-selector">
    {% for i in "12345" %}
        <!-- Ваша кастомизация -->
    {% endfor %}
</div>

Q: Поддерживается ли Django 4.x?

A: Да, поддерживаются Django 3.2, 4.0, 4.1, 4.2.

📞 Поддержка

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: [e-mail]
• Twitter: @yourhandle

📜 Лицензия

Этот проект распространяется под лицензией MIT. Подробнее в файле LICENSE.

🙏 Благодарности

• Разработчикам Django за фантастический фреймворк
• Сообществу за идеи и вклад
• Всем пользователям за отзывы и поддержку

---

Сделано с ❤️ для сообщества Django

⭐ Поставьте звезду на GitHub