Рефакторинг модуля News и удаление legacy ProjectNews

Author: Toksi86

docs/modules/feed.md

@@ -1,3 +1,90 @@
 # Feed
 
-TODO
+## Назначение
+
+Feed отвечает за общую ленту `/feed/`.
+
+Модуль не хранит отдельную доменную модель ленты. Он читает записи из
+`news.News` и возвращает их во frontend-формате, зависящем от связанного
+объекта.
+
+## Статус модуля
+
+Модуль рабочий, но небольшой и связан с `news`, `projects` и `vacancy`.
+Основная логика сосредоточена во view, serializer и service helpers.
+
+## Основные возможности
+
+- сбор общей ленты по query-параметру `type`;
+- отображение пользовательских новостей;
+- отображение проектных новостей;
+- отображение служебных записей для проектов и вакансий;
+- исключение записей непубличных или черновых проектов;
+- передача признака лайка текущим пользователем.
+
+## Архитектура
+
+- `feed/views.py` - endpoint `/feed/`, фильтрация по типам и финальная сборка
+  response payload.
+- `feed/serializers.py` - `FeedNewsResponseSerializer`, который превращает
+  `news.News` в элемент ленты.
+- `feed/services.py` - helpers для лайков и служебных feed-записей.
+- `feed/mapping.py` - соответствие content object типам и serializers.
+- `feed/constants.py` - типы моделей, для которых signals создают feed-записи.
+- `feed/signals.py` - подключение signal handlers.
+- `feed/tests/` - regression-тесты API и service helpers.
+
+## Основные сценарии
+
+### 1. Пользователь открывает ленту
+
+Frontend вызывает `/feed/?type=...`.
+View выбирает подходящие `news.News`, сериализует их и возвращает элементы
+ленты с полями `type_model` и `content`.
+
+### 2. В ленту попадает обычная новость
+
+Если `news.News` содержит текст и относится к пользователю или проекту, лента
+возвращает ее как новость.
+
+Проектная новость с текстом возвращается как `type_model = "news"`, даже если
+ее `content_object` - проект.
+
+### 3. В ленту попадает служебная запись
+
+Служебные feed-записи создаются через `feed.services.create_news_for_model()`.
+Они используют `news.News` с пустым `text` и связью на объект, например проект
+или вакансию.
+
+### 4. Проект становится недоступным для публичной ленты
+
+Если проект черновой или непубличный, связанные с ним записи не возвращаются в
+`/feed/`.
+
+## API
+
+- `GET /feed/?type=news` - новости пользователей.
+- `GET /feed/?type=project` - проектные новости и проектные feed-записи.
+- `GET /feed/?type=project|news` - комбинированная выдача по нескольким типам.
+
+## Ограничения и правила
+
+- Feed читает данные из `news.News`, но не отвечает за создание обычных
+  project/user/program news.
+- Служебная feed-запись определяется через пустой `text`.
+- Signals проектов могут создавать или удалять feed-записи, но тесты этих
+  side effects остаются в модуле `projects`.
+- `DevScript` в `feed/views.py` остается служебным legacy-инструментом и не
+  является основным пользовательским API.
+
+## Тесты
+
+Текущие regression-тесты проверяют:
+
+- `/feed/?type=news` возвращает пользовательские новости;
+- `/feed/?type=project` возвращает проектные новости в frontend-формате;
+- новости непубличных проектов не попадают в feed;
+- `get_liked_news()` возвращает лайкнутые текущим пользователем записи;
+- `create_news_for_model()` создает одну служебную feed-запись без дублей;
+- `delete_news_for_model()` удаляет только служебную feed-запись и не трогает
+  обычную новость с текстом.

docs/modules/news.md

@@ -12,7 +12,7 @@ generic relation:
 - партнерскими программами;
 - объектами ленты, например вакансиями.
 
-Одна и та же модель используется для двух близких, но разных сценариев:
+Одна и та же модель используется для двух сценариев:
 
 - обычная новость с текстом и файлами;
 - служебная запись ленты для существующего объекта, где `text = ""`.
@@ -23,7 +23,7 @@ generic relation:
 аккуратного рефакторинга. Сейчас он обслуживает проектные новости, новости
 пользователей, новости программ и часть общей ленты.
 
-Первый слой regression-тестов добавлен для живых сценариев API и feed.
+Первый слой regression-тестов добавлен для живых сценариев API.
 
 ## Основные возможности
 
@@ -41,14 +41,16 @@ generic relation:
 
 - `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/managers.py` - низкоуровневые `get_news(obj)` и `add_news(obj,
+  **kwargs)` для работы с generic relation.
+- `news/services.py` - явное создание project/user/program news и helpers для
+  различения обычной новости и feed-записи.
+- `news/querysets.py` - явные queryset helpers по контексту 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/serializers.py` - request/response serializers для создания, списка и
+  detail.
 - `news/permissions.py` - права на создание и изменение новости в зависимости от
   связанного объекта.
 - `news/admin.py` - админка `News`.
@@ -63,45 +65,29 @@ generic relation:
 - `views` - generic views через `core.View`.
 - `pin` - закрепление новости, сейчас используется для новостей программ.
 
+Feed-запись определяется через helper `is_feed_record(news)`, а обычная новость
+через `is_content_news(news)`. Сейчас оба helper'а используют текущий признак
+`text`, но вызывающий код не должен напрямую проверять `text == ""`.
+
 ## 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:
+Контекстные endpoints работают для трех базовых URL:
+
+- `/projects/<project_id>/news/` - новости проекта;
+- `/auth/users/<user_id>/news/` - новости пользователя;
+- `/programs/<program_id>/news/` - новости партнерской программы.
+
+Для каждого контекста доступны:
+
+- `GET <base>` - список новостей;
+- `POST <base>` - создание новости;
+- `GET <base><news_id>/` - детальная новость;
+- `PATCH <base><news_id>/` - редактирование новости;
+- `DELETE <base><news_id>/` - удаление новости;
+- `POST <base><news_id>/set_viewed/` - просмотр новости;
+- `POST <base><news_id>/set_liked/` - лайк новости.
+
+Связанные endpoints:
 
 - `GET /news/` - подключен напрямую, но без контекста возвращает пустой список.
 - `GET /news/<news_id>/` - подключен напрямую, но без контекста не является
@@ -117,9 +103,8 @@ generic relation:
 Новость сохраняется в `news.News`, а связь с проектом задается через
 `content_type = Project` и `object_id = project.id`.
 
-Новости проекта с непустым `text` отображаются как новости внутри проекта.
-Служебные feed-записи проекта с `text = ""` из списка проектных новостей
-исключаются.
+Новости проекта с текстом отображаются внутри проекта. Служебные feed-записи
+из списка проектных новостей исключаются.
 
 ### 2. Новость пользователя
 
@@ -148,8 +133,8 @@ generic relation:
 Для проектных записей важно различать:
 
 - `text = ""` - служебная запись ленты о проекте;
-- `text != ""` - полноценная новость проекта, которая в ленте возвращается как
-  `type_model = "news"`.
+- новость с текстом - полноценная новость проекта, которая в ленте возвращается
+  как `type_model = "news"`.
 
 Лента исключает новости, связанные с непубличными или черновыми проектами.
 
@@ -160,23 +145,16 @@ generic relation:
 - Новость программы может создавать и изменять только менеджер программы.
 - Прямой `/news/` без project/user/program context не является основным
   пользовательским API.
-- Старые `ProjectNews*` в `projects` не являются текущей реализацией проектных
-  новостей; живые routes используют `news.News`.
+- Несуществующий project/user/program context возвращает `404`.
+- Проектные новости реализованы через `news.News`.
 
 ## Тесты
 
 Текущие regression-тесты проверяют:
 
-- `NewsManager.add_news()` привязывает новость к content object и файлам;
-- `NewsManager.get_news()` возвращает новости нужного объекта;
-- лидер проекта может создавать, редактировать и удалять новости проекта;
-- пользователь без роли лидера не может создавать новость проекта;
-- список новостей проекта исключает служебные feed-записи с `text = ""`;
-- новости проекта можно отметить просмотренными и лайкнуть;
-- пользователь может создавать новости только в своем профиле;
-- менеджер программы может создавать новости программы;
-- пользователь без роли менеджера не может создавать новости программы;
-- закрепленные новости программы идут выше обычных;
-- `/feed/?type=news` возвращает новости пользователя;
-- `/feed/?type=project` возвращает проектные новости как `type_model = "news"`;
-- feed исключает новости непубличных проектов.
+- manager, service и query helpers;
+- project/user/program API;
+- права на создание и изменение новостей;
+- лайки и просмотры;
+- исключение служебных feed-записей из списка новостей проекта;
+- сортировку закрепленных новостей программы.

docs/modules/projects.md

@@ -42,7 +42,7 @@ Projects отвечают за проектную часть Procollab: созд
 ## Архитектура
 
 - `projects/models.py` - модели проекта, участников, целей, компаний,
-  ресурсов, ссылок, достижений и остаточной старой модели `ProjectNews`.
+  ресурсов, ссылок и достижений.
 - `projects/views.py` - HTTP endpoints и значительная часть orchestration
   logic.
 - `projects/serializers.py` - request/response contracts, часть validation и
@@ -69,8 +69,6 @@ Projects отвечают за проектную часть Procollab: созд
 - `Resource` - ресурс проекта.
 - проектные новости - новости внутри проекта; актуальный API реализован через
   `news.News` с привязкой к `Project` через `content_type/object_id`.
-- `ProjectNews` - старая модель проектных новостей, оставшаяся после переноса
-  данных в `news.News`.
 - `DefaultProjectCover` - дефолтная обложка проекта.
 - `DefaultProjectAvatar` - дефолтный аватар проекта.
 
@@ -208,9 +206,6 @@ Projects отвечают за проектную часть Procollab: созд
 `news`: запись хранится в `news.News`, а связь с проектом задается через
 `content_type = Project` и `object_id = project.id`.
 
-Старые `ProjectNews`, `ProjectNews*Serializer` и `ProjectNews*View` остаются в
-коде, но текущие routes проекта подключены к `news.views`.
-
 ## Ограничения и правила
 
 - Публичный каталог показывает только `draft = False` и `is_public = True`.
@@ -222,7 +217,7 @@ Projects отвечают за проектную часть Procollab: созд
 - Компания может быть связана с проектом только один раз.
 - Ресурс может ссылаться только на компанию, уже привязанную к проекту.
 - Проектные новости являются живым frontend-сценарием, но текущие routes
-  используют общий модуль `news`, а не старую модель `ProjectNews`.
+  используют общий модуль `news`.
 
 ## Тесты
 

feed/serializers.py

@@ -5,11 +5,12 @@
 from files.serializers import UserFileSerializer
 from news.mapping import NewsMapping
 from news.models import News
+from news.services import is_content_news
 from projects.models import Project
 from users.models import CustomUser
 
 
-class NewsFeedListSerializer(serializers.ModelSerializer):
+class FeedNewsResponseSerializer(serializers.ModelSerializer):
     name = serializers.SerializerMethodField()
     image_address = serializers.SerializerMethodField()
     is_user_liked = serializers.SerializerMethodField()
@@ -21,13 +22,13 @@ class NewsFeedListSerializer(serializers.ModelSerializer):
 
     def get_type_model(self, obj) -> str:
         model_type = CONTENT_OBJECT_MAPPING[obj.content_type.model]
-        if obj.text != "" and model_type == "project":
+        if is_content_news(obj) and model_type == "project":
             return "news"
         return model_type
 
     def get_content_object(self, obj) -> dict:
         type_model = obj.content_type.model
-        if obj.text != "" and self.get_type_model(obj) == "project":
+        if is_content_news(obj) and self.get_type_model(obj) == "project":
             type_model = "news"
         serializer = CONTENT_OBJECT_SERIALIZER_MAPPING[type_model](obj.content_object)
         return serializer.data
@@ -41,7 +42,7 @@ def get_likes_count(self, obj):
     def get_name(self, obj):
         if obj.content_type.model == CustomUser.__name__.lower():
             return f"{obj.content_object.first_name} {obj.content_object.last_name}"
-        elif obj.text != "" and obj.content_type.model == Project.__name__.lower():
+        elif is_content_news(obj) and obj.content_type.model == Project.__name__.lower():
             return f"{obj.content_object.name}"
 
     def get_image_address(self, obj):