review_service¶

1. Назначение¶

review_service хранит отзывы пользователей по товарам, формирует статистику по рейтингам и ограничивает создание отзывов бизнес-условиями покупки.

2. API-каталог¶

Базовый префикс: /api/.

Метод	Путь	Auth	Назначение
GET	`/reviews/`	AllowAny	Список отзывов
POST	`/reviews/`	IsAuthenticated	Создание отзыва
GET	`/reviews/{id}/`	AllowAny	Чтение отзыва
PUT/PATCH	`/reviews/{id}/`	Owner	Обновление
DELETE	`/reviews/{id}/`	Owner или staff	Удаление
GET	`/reviews/by_model/`	AllowAny	Отзывы по товару
GET	`/reviews/statistics/`	AllowAny	Агрегированная статистика
GET	`/reviews/seller_reviews/`	IsAuthenticated	Отзывы по товарам продавца

3. Модель данных¶

`Review`¶

model_3d_id
user FK -> auth_app.User
rating (1..5)
text
created_at, updated_at
unique_together: (model_3d_id, user)

4. Бизнес-правила¶

Запрещен self-review продавца на свой товар.
Оставить отзыв может только покупатель с доставленным и оплаченным заказом.
Один пользователь может оставить только один отзыв на товар.

5. Интеграции¶

product_service: определение продавца товара и имени.
order_service: проверка факта покупки/доставки.
admin_service: best-effort создание уведомления.

6. Ошибки и edge-cases¶

400 при отсутствии обязательных query/body полей.
403 при нарушении бизнес-правил авторства/покупки.
Возможна ошибка из-за некорректного использования permissions.PermissionDenied в коде.
Для seller_reviews требуется проверить фактическое применение permission-декларации.

7. Диаграмма проверки права на отзыв¶

sequenceDiagram
  participant U as User
  participant R as review_service
  participant P as product_service_data
  participant O as order_service_data

  U->>R: POST /api/reviews
  R->>P: check seller ownership
  alt user_is_seller
    R-->>U: 403
  else user_not_seller
    R->>O: check paid+delivered order
    alt no_order
      R-->>U: 403
    else valid_order
      R-->>U: 201
    end
  end

8. Дополнительная детализация внутренних функций (append-only)¶

8.1 Функции допуска к созданию отзыва¶

`ReviewViewSet.is_user_product_seller(user, model_3d_id)`¶

Источник: review_service/review_app/views.py
Назначение: проверить, является ли пользователь продавцом указанного товара.
Вход:
user;
model_3d_id.
Выход:
bool.
Side effects:
direct import модели product-service;
при недоступности импорта используется SQL fallback-запрос к таблице продукта.
Edge-cases:
при ошибках проверки применяется fail-secure (False), чтобы не разрешить self-review.

`ReviewViewSet.has_user_purchased_product(user, model_3d_id)`¶

Назначение: подтвердить факт покупки товара пользователем.
Вход:
user, model_3d_id.
Выход:
bool.
Условия valid purchase:
заказ в статусе оплаты paid;
заказ в статусе delivered.
Side effects:
direct import order_app либо SQL fallback.

8.2 `ReviewViewSet.perform_create(self, serializer)`¶

Источник: review_service/review_app/views.py
Назначение: централизованная проверка бизнес-условий перед сохранением отзыва.
Вход:
валидированный serializer.
Выход:
созданный отзыв в стандартном DRF flow.
Side effects:
запись Review в БД;
best-effort создание уведомления в admin_app.Notification.
Ошибки:
PermissionDenied, если пользователь пытается оставить отзыв на свой товар;
PermissionDenied, если не подтверждена покупка.

8.3 Агрегирующие функции статистики¶

`ReviewViewSet.by_model(self, request)`¶

Вход:
query param model_3d_id.
Выход:
список отзывов по товару;
average_rating;
total_reviews.
Ошибки:
400 при отсутствии model_3d_id.

`ReviewViewSet.statistics(self, request)`¶

Вход:
query param model_3d_id.
Выход:
агрегаты рейтинга и распределение оценок 1..5.

`ReviewViewSet.seller_reviews(self, request)`¶

Вход:
optional filters: product_id, rating, date_from, date_to, search.
Выход:
отзывы по товарам продавца;
агрегаты by_rating и by_product.
Edge-cases:
формат дат для фильтров должен быть согласован с DRF parsing (рекомендуется фиксировать ISO-формат в интеграционном контуре).

8.4 Контракт serializer-уровня¶

`ReviewSerializer.create(self, validated_data)`¶

Источник: review_service/review_app/serializers.py
Назначение: закрепить автора отзыва за текущим пользователем запроса.
Side effects:
поле user не принимается напрямую из клиента, а задается сервером из контекста request.

9. Соответствие master-документации¶

Источник верхнего уровня: Master-документация проекта.

Контроль	Требование	Проверка	Артефакт
Ownership control	Изменение/удаление отзыва разрешено только owner/staff	проверка permission сценариев	integration tests
Data quality	Агрегаты и фильтры seller_reviews воспроизводимы	проверка дат/рейтингов и подсчетов	QA report
API consistency	Контракты review endpoint-ов стабильны для frontend	контрактные smoke тесты	release checklist
Risk capture	Ограничения формата дат и edge-cases документированы	ревью секции ограничений	docs review