django-simple-comment-module 1.0.0
Простая система комментариев с рейтингом для Django
License: MIT
Requires Python: >=3.7

# Django Simple Ratings ⭐

![Django Version](https://img.shields.io/badge/django-3.2%2B-blue)
![Python Version](https://img.shields.io/badge/python-3.7%2B-blue)
![License](https://img.shields.io/badge/license-MIT-green)
![PyPI Version](https://img.shields.io/pypi/v/django-simple-ratings)

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

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

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

## 📦 Установка

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

```bash
pip install django-simple-comment-module
```

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

```bash
# Клонируйте репозиторий
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

```python
# 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-адреса

```python
# urls.py проекта

from django.urls import include, path

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

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

```bash
python manage.py makemigrations django_simple_comment_module
python manage.py migrate django_simple_comment_module
```

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

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

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

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

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

```python
# 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. Кастомизация виджета

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

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

```html
{% 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. Кастомизация шаблонов

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

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

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

```css
/* 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. Кастомизация поведения

```python
# Создание собственной формы
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. Сигналы

```python
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:

```javascript
// Получение комментариев
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

```python
# 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
```

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

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

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

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

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

### Из django-comments-xtd

```python
# 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

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

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

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

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

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

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

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

### Мониторинг

```python
# Добавьте в ваши 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

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

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

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

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

Дополнительная документация доступна:
- [📚 Полное руководство](docs/guide.md)
- [🎛️ API Reference](docs/api.md)
- [🎨 Кастомизация](docs/customization.md)
- [🚀 Развертывание](docs/deployment.md)
- [🔧 Миграция](docs/migration.md)

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

### Q: Как добавить дополнительные поля в комментарий?
**A:** Наследуйтесь от модели `Comment`:

```python
from django_simple_comment_module.models import Comment

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

### Q: Можно ли отключить капчу?
**A:** Да, в настройках:

```python
SIMPLE_RATINGS_CONFIG = {
    'CAPTCHA_ENABLED': False,
}
```

### Q: Как изменить количество звезд?
**A:** Создайте свой виджет или измените шаблон:

```html
<!-- В вашем 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](https://github.com/yourusername/django-simple-ratings/issues)
- **Discussions**: [GitHub Discussions](https://github.com/yourusername/django-simple-ratings/discussions)
- **Email**: your.email@example.com
- **Twitter**: [@yourhandle](https://twitter.com/yourhandle)

## 📜 Лицензия

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

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

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

---

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

[⭐ Поставьте звезду на GitHub](https://github.com/yourusername/django-simple-ratings)