Задокументирован модуль News и добавлены тесты

Author: Toksi86

docs/modules/news.md

@@ -1,3 +1,182 @@
 # News
 
-TODO
+## Назначение
+
+News отвечает за публикации и новости в разных частях продукта.
+
+Модуль хранит новости в единой модели `News` и связывает их с объектами через
+generic relation:
+
+- проектами;
+- пользователями;
+- партнерскими программами;
+- объектами ленты, например вакансиями.
+
+Одна и та же модель используется для двух близких, но разных сценариев:
+
+- обычная новость с текстом и файлами;
+- служебная запись ленты для существующего объекта, где `text = ""`.
+
+## Статус модуля
+
+Модуль рабочий, но связан с несколькими доменными областями и требует
+аккуратного рефакторинга. Сейчас он обслуживает проектные новости, новости
+пользователей, новости программ и часть общей ленты.
+
+Первый слой regression-тестов добавлен для живых сценариев API и feed.
+
+## Основные возможности
+
+- создание новости в контексте проекта;
+- создание новости в профиле пользователя;
+- создание новости в партнерской программе;
+- просмотр списка новостей в конкретном контексте;
+- просмотр, редактирование и удаление отдельной новости;
+- отметка просмотра новости;
+- лайк и снятие лайка с новости;
+- участие новостей в общей ленте `/feed/`;
+- закрепление новости программы через `pin`.
+
+## Архитектура
+
+- `news/models.py` - модель `News` с `content_type/object_id`, файлами, лайками,
+  просмотрами и флагом `pin`.
+- `news/managers.py` - `get_news(obj)` и `add_news(obj, **kwargs)` для работы с
+  generic relation.
+- `news/mixins.py` - выбор queryset по контексту URL: project, user или partner
+  program.
+- `news/views.py` - общий API для list/create/detail/update/delete, set_viewed и
+  set_liked.
+- `news/serializers.py` - request/response serializers для списка, detail и feed
+  представления.
+- `news/permissions.py` - права на создание и изменение новости в зависимости от
+  связанного объекта.
+- `news/admin.py` - админка `News`.
+- `news/tests/` - regression-тесты живых сценариев модуля.
+
+## Основные сущности
+
+- `News` - публикация или запись ленты.
+- `content_object` - объект, к которому относится новость.
+- `files` - вложения новости.
+- `likes` - generic likes через `core.Like`.
+- `views` - generic views через `core.View`.
+- `pin` - закрепление новости, сейчас используется для новостей программ.
+
+## API
+
+Контекстные endpoints:
+
+- `GET /projects/<project_id>/news/` - список новостей проекта.
+- `POST /projects/<project_id>/news/` - создание новости проекта.
+- `GET /projects/<project_id>/news/<news_id>/` - детальная новость проекта.
+- `PATCH /projects/<project_id>/news/<news_id>/` - редактирование новости
+  проекта.
+- `DELETE /projects/<project_id>/news/<news_id>/` - удаление новости проекта.
+- `POST /projects/<project_id>/news/<news_id>/set_viewed/` - просмотр новости
+  проекта.
+- `POST /projects/<project_id>/news/<news_id>/set_liked/` - лайк новости
+  проекта.
+
+- `GET /auth/users/<user_id>/news/` - список новостей пользователя.
+- `POST /auth/users/<user_id>/news/` - создание новости пользователя.
+- `GET /auth/users/<user_id>/news/<news_id>/` - детальная новость пользователя.
+- `PATCH /auth/users/<user_id>/news/<news_id>/` - редактирование новости
+  пользователя.
+- `DELETE /auth/users/<user_id>/news/<news_id>/` - удаление новости
+  пользователя.
+- `POST /auth/users/<user_id>/news/<news_id>/set_viewed/` - просмотр новости
+  пользователя.
+- `POST /auth/users/<user_id>/news/<news_id>/set_liked/` - лайк новости
+  пользователя.
+
+- `GET /programs/<program_id>/news/` - список новостей программы.
+- `POST /programs/<program_id>/news/` - создание новости программы.
+- `GET /programs/<program_id>/news/<news_id>/` - детальная новость программы.
+- `PATCH /programs/<program_id>/news/<news_id>/` - редактирование новости
+  программы.
+- `DELETE /programs/<program_id>/news/<news_id>/` - удаление новости программы.
+- `POST /programs/<program_id>/news/<news_id>/set_viewed/` - просмотр новости
+  программы.
+- `POST /programs/<program_id>/news/<news_id>/set_liked/` - лайк новости
+  программы.
+
+Общие endpoints:
+
+- `GET /news/` - подключен напрямую, но без контекста возвращает пустой список.
+- `GET /news/<news_id>/` - подключен напрямую, но без контекста не является
+  основным пользовательским сценарием.
+- `GET /feed/?type=...` - общая лента, которая читает данные из `News`.
+
+## Основные сценарии
+
+### 1. Новость проекта
+
+Лидер проекта создает новость через `/projects/<id>/news/`.
+
+Новость сохраняется в `news.News`, а связь с проектом задается через
+`content_type = Project` и `object_id = project.id`.
+
+Новости проекта с непустым `text` отображаются как новости внутри проекта.
+Служебные feed-записи проекта с `text = ""` из списка проектных новостей
+исключаются.
+
+### 2. Новость пользователя
+
+Пользователь создает новость в своем профиле через `/auth/users/<id>/news/`.
+Создавать новость за другого пользователя нельзя.
+
+### 3. Новость программы
+
+Менеджер партнерской программы создает новость через `/programs/<id>/news/`.
+Пользователь без роли менеджера программы не может создавать и изменять такие
+новости.
+
+Новости программ сортируются с учетом `pin`: закрепленные новости идут выше
+обычных.
+
+### 4. Просмотры и лайки
+
+Просмотры и лайки работают через generic-модели `core.View` и `core.Like`.
+Они привязаны к самой новости, а не к объекту, которому эта новость посвящена.
+
+### 5. Лента
+
+`/feed/` читает `News` и возвращает элементы в формате, зависящем от типа
+связанного объекта.
+
+Для проектных записей важно различать:
+
+- `text = ""` - служебная запись ленты о проекте;
+- `text != ""` - полноценная новость проекта, которая в ленте возвращается как
+  `type_model = "news"`.
+
+Лента исключает новости, связанные с непубличными или черновыми проектами.
+
+## Ограничения и правила
+
+- Новость проекта может создавать и изменять только лидер проекта.
+- Новость пользователя может создавать и изменять только сам пользователь.
+- Новость программы может создавать и изменять только менеджер программы.
+- Прямой `/news/` без project/user/program context не является основным
+  пользовательским API.
+- Старые `ProjectNews*` в `projects` не являются текущей реализацией проектных
+  новостей; живые routes используют `news.News`.
+
+## Тесты
+
+Текущие regression-тесты проверяют:
+
+- `NewsManager.add_news()` привязывает новость к content object и файлам;
+- `NewsManager.get_news()` возвращает новости нужного объекта;
+- лидер проекта может создавать, редактировать и удалять новости проекта;
+- пользователь без роли лидера не может создавать новость проекта;
+- список новостей проекта исключает служебные feed-записи с `text = ""`;
+- новости проекта можно отметить просмотренными и лайкнуть;
+- пользователь может создавать новости только в своем профиле;
+- менеджер программы может создавать новости программы;
+- пользователь без роли менеджера не может создавать новости программы;
+- закрепленные новости программы идут выше обычных;
+- `/feed/?type=news` возвращает новости пользователя;
+- `/feed/?type=project` возвращает проектные новости как `type_model = "news"`;
+- feed исключает новости непубличных проектов.

news/tests.py

@@ -0,0 +1,95 @@
+from datetime import timedelta
+from uuid import uuid4
+
+from django.utils import timezone
+
+from files.models import UserFile
+from industries.models import Industry
+from news.models import News
+from partner_programs.models import PartnerProgram
+from projects.models import Project
+from users.models import CustomUser
+
+
+def unique_suffix() -> str:
+    return uuid4().hex[:8]
+
+
+def create_user(*, prefix: str = "news-test") -> CustomUser:
+    suffix = unique_suffix()
+    return CustomUser.objects.create_user(
+        email=f"{prefix}-{suffix}@example.com",
+        password="testpass123",
+        first_name="Test",
+        last_name="User",
+        birthday="2000-01-01",
+        is_active=True,
+    )
+
+
+def create_industry(*, name: str = "Industry") -> Industry:
+    return Industry.objects.create(name=f"{name} {unique_suffix()}")
+
+
+def create_project(
+    *,
+    leader: CustomUser | None = None,
+    name: str = "Project",
+    draft: bool = False,
+    is_public: bool = True,
+) -> Project:
+    return Project.objects.create(
+        leader=leader or create_user(prefix="news-project-leader"),
+        name=f"{name} {unique_suffix()}",
+        description="Project description",
+        draft=draft,
+        is_public=is_public,
+        industry=create_industry(),
+    )
+
+
+def create_partner_program(
+    *,
+    manager: CustomUser | None = None,
+    name: str = "Program",
+) -> PartnerProgram:
+    suffix = unique_suffix()
+    now = timezone.now()
+    program = PartnerProgram.objects.create(
+        name=f"{name} {suffix}",
+        tag=f"program-{suffix}",
+        city="Moscow",
+        datetime_registration_ends=now + timedelta(days=10),
+        datetime_started=now - timedelta(days=1),
+        datetime_finished=now + timedelta(days=30),
+        draft=False,
+    )
+    if manager is not None:
+        program.managers.add(manager)
+    return program
+
+
+def create_user_file(
+    user: CustomUser,
+    *,
+    name: str = "attachment",
+    extension: str = "pdf",
+    mime_type: str = "application/pdf",
+) -> UserFile:
+    suffix = unique_suffix()
+    return UserFile.objects.create(
+        link=f"https://cdn.example.com/news/{suffix}/{name}.{extension}",
+        user=user,
+        name=name,
+        extension=extension,
+        mime_type=mime_type,
+        size=1024,
+    )
+
+
+def create_news_for(obj, *, text: str = "News text", files=None, pin: bool = False) -> News:
+    news = News.objects.add_news(obj, text=text, files=files or [])
+    if pin:
+        news.pin = True
+        news.save(update_fields=["pin"])
+    return news

news/tests/__init__.py

@@ -0,0 +1,43 @@
+from django.test import TestCase
+from rest_framework.test import APIClient
+
+from .helpers import create_news_for, create_project, create_user
+
+
+class NewsFeedTests(TestCase):
+    def setUp(self):
+        self.client = APIClient()
+        self.user = create_user(prefix="news-feed-user")
+        self.client.force_authenticate(self.user)
+
+    def test_feed_returns_user_news_when_news_filter_requested(self):
+        news = create_news_for(self.user, text="User feed news")
+
+        response = self.client.get("/feed/?type=news")
+
+        self.assertEqual(response.status_code, 200)
+        item = response.data["results"][0]
+        self.assertEqual(item["type_model"], "news")
+        self.assertEqual(item["content"]["id"], news.id)
+        self.assertEqual(item["content"]["text"], "User feed news")
+
+    def test_feed_returns_project_news_as_news_content(self):
+        project = create_project(name="Feed project")
+        news = create_news_for(project, text="Project feed news")
+
+        response = self.client.get("/feed/?type=project")
+
+        self.assertEqual(response.status_code, 200)
+        item = response.data["results"][0]
+        self.assertEqual(item["type_model"], "news")
+        self.assertEqual(item["content"]["id"], news.id)
+        self.assertEqual(item["content"]["text"], "Project feed news")
+
+    def test_feed_excludes_news_for_private_project(self):
+        private_project = create_project(name="Private project", is_public=False)
+        create_news_for(private_project, text="Private project news")
+
+        response = self.client.get("/feed/?type=project")
+
+        self.assertEqual(response.status_code, 200)
+        self.assertEqual(response.data["results"], [])

news/tests/helpers.py

@@ -0,0 +1,31 @@
+from django.test import TestCase
+
+from news.models import News
+
+from .helpers import create_news_for, create_project, create_user_file
+
+
+class NewsManagerTests(TestCase):
+    def test_add_news_binds_news_to_content_object_and_files(self):
+        project = create_project()
+        file = create_user_file(project.leader)
+
+        news = News.objects.add_news(
+            project,
+            text="Project update",
+            files=[file],
+        )
+
+        self.assertEqual(news.content_object, project)
+        self.assertEqual(news.text, "Project update")
+        self.assertEqual(list(news.files.all()), [file])
+
+    def test_get_news_returns_only_news_for_requested_object(self):
+        project = create_project(name="Target project")
+        other_project = create_project(name="Other project")
+        target_news = create_news_for(project, text="Target news")
+        create_news_for(other_project, text="Other news")
+
+        queryset = News.objects.get_news(project).filter(text="Target news")
+
+        self.assertEqual(list(queryset), [target_news])