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

Author: Toksi86

docs/modules/mailing.md

@@ -1,3 +1,139 @@
 # Mailing
 
-TODO
+## Назначение
+
+Модуль `mailing` отвечает за email-рассылки и шаблоны писем: хранение схем
+старой админской формы рассылки, подготовку данных письма, отправку сообщений
+через email backend и автоматические сценарии рассылок по партнерским
+программам.
+
+## Статус модуля
+
+Модуль используется в рабочих сценариях, но не подключен как публичный API.
+Основные активные точки использования:
+
+- celery-задача `run_program_mailings`;
+- старая форма рассылки из админки партнерских программ;
+- общие helper-функции отправки писем, которые используют другие модули.
+
+## Основные возможности
+
+- хранение схемы письма в `MailingSchema`;
+- рендеринг старой админской формы рассылки;
+- подготовка данных письма из формы или typed dataclass;
+- массовая отправка писем по строковому шаблону;
+- массовая отправка писем по Django template;
+- группировка писем батчами;
+- сценарные рассылки участникам партнерских программ;
+- логирование результата сценарных рассылок в `MailingScenarioLog`.
+
+## Архитектура
+
+- `mailing/models.py` - модели схем писем и логов сценарных рассылок.
+- `mailing/utils.py` - подготовка данных письма и низкоуровневые функции
+  отправки.
+- `mailing/scenarios.py` - декларативное описание сценариев рассылки по
+  программам.
+- `mailing/tasks.py` - celery-задача запуска сценариев.
+- `mailing/rendering.py` - подстановка базовых placeholders в темы и тексты.
+- `mailing/views.py` - старые views для формы рассылки; сейчас не подключены в
+  публичный URLConf.
+- `mailing/urls.py` - старые routes формы рассылки, не подключенные в
+  `procollab/urls.py`.
+- `mailing/tests/` - regression-тесты моделей, rendering/helpers и сценариев.
+
+## Ключевые сущности
+
+- `MailingSchema` - схема шаблона письма и HTML-шаблон для старой формы
+  рассылки.
+- `MailingScenarioLog` - лог отправки сценарного письма конкретному участнику
+  программы за конкретную дату.
+- `Scenario` - dataclass с кодом сценария, триггером, правилом выбора
+  получателей, шаблоном и builder-контекстом.
+- `EmailDataToPrepare` - typed input для подготовки данных письма из кода.
+
+## API и внешние точки входа
+
+Публичных endpoints модуля `mailing` сейчас нет: `mailing.urls` не подключен в
+корневой `procollab/urls.py`.
+
+Связанные внешние точки:
+
+- `/anymail/` - webhook routes библиотеки Anymail;
+- админка партнерской программы вызывает `MailingTemplateRender` напрямую через
+  custom admin view;
+- celery beat запускает `mailing.tasks.run_program_mailings` каждый день в
+  10:00.
+
+## Основные сценарии
+
+### 1. Сценарная рассылка по партнерским программам
+
+`run_program_mailings()` проходит по сценариям из `SCENARIOS`.
+
+Для каждого сценария:
+
+- вычисляется целевая дата;
+- выбираются программы по дате регистрации, окончанию регистрации или дедлайну
+  подачи проекта;
+- выбираются получатели по правилу сценария;
+- создаются `MailingScenarioLog` в статусе `pending`;
+- письмо отправляется через `send_mass_mail_from_template`;
+- статус лога меняется на `sent` или `failed` по `anymail_status`.
+
+Повторная отправка за ту же дату не дублирует письма со статусом `pending` или
+`sent`.
+
+### 2. Старая админская рассылка
+
+`MailingTemplateRender` строит контекст формы:
+
+- доступные `MailingSchema`;
+- выбранные и невыбранные пользователи;
+- поля шаблона из JSON-схемы.
+
+Сейчас этот renderer используется из админки партнерских программ.
+
+### 3. Отправка письма из других модулей
+
+Другие модули могут подготовить `EmailDataToPrepare`, получить данные через
+`prepare_mail_data()` и отправить письмо через `send_mass_mail()`.
+
+Такой flow сейчас использует `vacancy.tasks.send_email`, который также
+переиспользуется партнерскими программами и оценками проектов.
+
+## Связи с другими модулями
+
+- `partner_programs` - сценарные рассылки выбирают программы и участников через
+  selectors; админка программ использует старый renderer формы рассылки.
+- `vacancy` - задачи вакансий используют mailing helpers для email-уведомлений.
+- `project_rates` - переиспользует общий notification flow через
+  `vacancy.tasks.send_email`.
+- `users` - получатели писем.
+- `anymail` / Unisender Go - фактическая отправка писем в production.
+
+## Ограничения и риски
+
+- `mailing/urls.py` содержит старые routes, но они не подключены наружу.
+- Если старые routes будут снова подключены, для них нужно отдельно проверить
+  permissions и безопасность массовой отправки.
+- В `mailing/urls.py` есть историческая опечатка `template_fileds`; менять ее
+  без проверки старого UI не стоит.
+- `vacancy.tasks.send_email` фактически является общим helper для уведомлений,
+  но находится в модуле вакансий.
+- `MailingScenarioLog` пока не зарегистрирован в Django admin.
+
+## Тесты
+
+Текущие regression-тесты проверяют:
+
+- строковое представление `MailingSchema` и `MailingScenarioLog`;
+- подстановку placeholders в subject и template values;
+- контекст старого renderer формы рассылки;
+- подготовку данных письма из `EmailDataToPrepare`;
+- группировку писем батчами;
+- рендеринг и отправку писем по строковому шаблону;
+- отправку писем по Django template с `status_callback`;
+- выбор участников с неактивными аккаунтами для сценариев программ;
+- успешную сценарную рассылку без повторной отправки;
+- перевод сценарного лога в `failed` при ошибочном `anymail_status`.

mailing/tests/__init__.py

@@ -0,0 +1,72 @@
+from datetime import datetime, time, timedelta
+
+from django.utils import timezone
+
+from mailing.models import MailingSchema
+from partner_programs.models import PartnerProgram, PartnerProgramUserProfile
+from users.models import CustomUser
+
+
+def aware_datetime(dt_date, hour: int = 12):
+    return timezone.make_aware(
+        datetime.combine(dt_date, time(hour=hour)),
+        timezone.get_current_timezone(),
+    )
+
+
+def create_user(email: str = "mailing-user@example.com", **overrides) -> CustomUser:
+    defaults = {
+        "email": email,
+        "password": "test-password-12345",
+        "first_name": "Test",
+        "last_name": "User",
+        "birthday": "2000-01-01",
+        "is_active": True,
+    }
+    defaults.update(overrides)
+    return CustomUser.objects.create_user(**defaults)
+
+
+def create_program(**overrides) -> PartnerProgram:
+    today = timezone.localdate()
+    defaults = {
+        "name": "Mailing Program",
+        "tag": "mailing-program",
+        "city": "Moscow",
+        "datetime_registration_ends": aware_datetime(today + timedelta(days=10)),
+        "datetime_started": aware_datetime(today - timedelta(days=10)),
+        "datetime_finished": aware_datetime(today + timedelta(days=40)),
+    }
+    defaults.update(overrides)
+    return PartnerProgram.objects.create(**defaults)
+
+
+def register_program_user(
+    user: CustomUser,
+    program: PartnerProgram,
+    registered_on,
+) -> PartnerProgramUserProfile:
+    profile = PartnerProgramUserProfile.objects.create(
+        user=user,
+        partner_program=program,
+        partner_program_data={},
+    )
+    PartnerProgramUserProfile.objects.filter(id=profile.id).update(
+        datetime_created=aware_datetime(registered_on)
+    )
+    profile.refresh_from_db()
+    return profile
+
+
+def create_mailing_schema(**overrides) -> MailingSchema:
+    defaults = {
+        "name": "Default mailing schema",
+        "schema": {
+            "title": {"title": "Title", "default": "Default title"},
+            "text": {"title": "Text"},
+            "button_text": {"title": "Button text", "default": "Open"},
+        },
+        "template": "<h1>{{ title }}</h1><p>{{ text }}</p>{{ user.email }}",
+    }
+    defaults.update(overrides)
+    return MailingSchema.objects.create(**defaults)

mailing/tests/helpers.py

@@ -0,0 +1,84 @@
+from django.test import TestCase
+from django.utils import timezone
+
+from mailing.models import MailingScenarioLog
+from mailing.rendering import render_subject, render_template_value
+from mailing.views import MailingTemplateRender
+
+from .helpers import create_mailing_schema, create_program, create_user
+
+
+class MailingModelsTests(TestCase):
+    def test_mailing_schema_string_representation(self):
+        schema = create_mailing_schema(name="Program reminder")
+
+        self.assertEqual(str(schema), "MailingSchema<Program reminder>")
+
+    def test_mailing_scenario_log_string_representation(self):
+        program = create_program()
+        user = create_user()
+        log = MailingScenarioLog.objects.create(
+            scenario_code="program_registration_plus_3_inactive_account",
+            program=program,
+            user=user,
+            scheduled_for=timezone.localdate(),
+            status=MailingScenarioLog.Status.PENDING,
+        )
+
+        self.assertIn("program_registration_plus_3_inactive_account", str(log))
+        self.assertIn(f"program={program.id}", str(log))
+        self.assertIn(f"user={user.id}", str(log))
+        self.assertIn("status=pending", str(log))
+
+
+class MailingRenderingTests(TestCase):
+    def test_render_subject_replaces_program_name(self):
+        program = create_program(name="Case Cup")
+
+        subject = render_subject("{program_name}: reminder", program)
+
+        self.assertEqual(subject, "Case Cup: reminder")
+
+    def test_render_template_value_replaces_known_placeholders(self):
+        program = create_program(name="Case Cup")
+        user = create_user()
+
+        value = render_template_value(
+            "/program/{program_id}/users/{user_id}/{program_name}",
+            program,
+            user,
+        )
+
+        self.assertEqual(value, f"/program/{program.id}/users/{user.id}/Case Cup")
+
+    def test_template_render_context_contains_schema_users_and_fields(self):
+        schema = create_mailing_schema(
+            name="Participant email",
+            schema={
+                "title": {"title": "Title", "default": "Default title"},
+                "text": {"title": "Text"},
+            },
+        )
+        picked_user = create_user(email="picked@example.com")
+        unpicked_user = create_user(email="unpicked@example.com")
+
+        context = MailingTemplateRender._get_context(
+            schema.id,
+            picked_users=[picked_user],
+            unpicked_users=[unpicked_user],
+        )
+
+        selected_schema = context["schemas"][0]
+        self.assertEqual(selected_schema["id"], schema.id)
+        self.assertTrue(selected_schema["selected"])
+        self.assertEqual(context["picked_users"][0]["id"], picked_user.id)
+        self.assertTrue(context["picked_users"][0]["picked"])
+        self.assertEqual(context["unpicked_users"][0]["id"], unpicked_user.id)
+        self.assertFalse(context["unpicked_users"][0]["picked"])
+        self.assertEqual(
+            context["template_fields"],
+            [
+                {"key": "title", "title": "Title", "default": "Default title"},
+                {"key": "text", "title": "Text", "default": ""},
+            ],
+        )