feat: 알림 전송 실패 시 실패 사유를 기록하여 API에서 볼 수 있게 함 + 각 send_to에 대한 렌더링 결과를 얻을 수 있도록 API 추가

Co-authored-by: Copilot <copilot@github.com>

Author: MU-Software

app/admin_api/serializers/notification.py

@@ -22,8 +22,8 @@
 
 class _NotiHistorySentToAdminSerializerBase(BaseAbstractSerializer, JsonSchemaSerializer, serializers.ModelSerializer):
     class Meta:
-        fields = COMMON_ADMIN_FIELDS + ("recipient", "context", "status")
-        read_only_fields = (*COMMON_ADMIN_FIELDS, "status")
+        fields = COMMON_ADMIN_FIELDS + ("recipient", "context", "status", "failure_reason")
+        read_only_fields = (*COMMON_ADMIN_FIELDS, "status", "failure_reason")
 
 
 class EmailNotificationHistorySentToAdminSerializer(_NotiHistorySentToAdminSerializerBase):

app/admin_api/test/notification_test.py

@@ -265,6 +265,7 @@ def test_create_history_marks_sent_to_failed_when_send_raises(api_client, sms_te
     body = response.json()
     assert body["sent_to_status_summary"]["failed"] == 1
     assert body["sent_to_list"][0]["status"] == NotificationStatus.FAILED
+    assert "external api down" in body["sent_to_list"][0]["failure_reason"]
 
 
 @pytest.mark.django_db(transaction=True)
@@ -426,6 +427,66 @@ def test_retry_noop_when_no_failed_sent_to(api_client, email_history):
     mock_client.send_message.assert_not_called()
 
 
+# ---- History Render SentTo As HTML -----------------------------------------
+
+
+@pytest.mark.django_db
+def test_render_sent_to_as_html_returns_html_with_rendered_context(api_client, email_history):
+    sent_to = email_history.sent_to_list.get()
+    response = api_client.get(
+        reverse(
+            "v1:admin-notification-email-history-render-sent-to-as-html",
+            kwargs={"pk": email_history.id, "sent_to_id": sent_to.id},
+        )
+    )
+    assert response.status_code == http.HTTPStatus.OK
+    assert response["Content-Type"].startswith("text/html")
+    body = response.content.decode()
+    assert body.lstrip().startswith("<html")
+    # email_history fixture의 context (name="길동")가 template_data를 거쳐 HTML에 반영되어야 함.
+    assert "Hi 길동" in body
+    assert "Hello 길동" in body
+
+
+@pytest.mark.django_db
+def test_render_sent_to_as_html_uses_history_template_data_snapshot(api_client, email_history, email_template):
+    # History.template_data는 발송 시점의 snapshot이므로, 이후 Template.data를 바꿔도
+    # 기존 sent_to의 렌더 결과는 영향을 받지 않아야 한다.
+    sent_to = email_history.sent_to_list.get()
+    url = reverse(
+        "v1:admin-notification-email-history-render-sent-to-as-html",
+        kwargs={"pk": email_history.id, "sent_to_id": sent_to.id},
+    )
+
+    before = api_client.get(url).content.decode()
+
+    email_template.data = '{"title":"DIFFERENT {{ name }}","from_":"X","send_to":"Y","body":"CHANGED {{ name }}"}'
+    email_template.save()
+
+    after = api_client.get(url).content.decode()
+    assert before == after
+    assert "Hi 길동" in after
+    assert "Hello 길동" in after
+    assert "DIFFERENT" not in after
+    assert "CHANGED" not in after
+
+
+@pytest.mark.django_db
+def test_render_sent_to_as_html_404_when_sent_to_belongs_to_other_history(api_client, email_history, email_template):
+    other = EmailNotificationHistory.objects.create_for_recipients(
+        template=email_template,
+        recipients=[{"recipient": "other@example.com", "context": {"name": "다른", "recipient": "y"}}],
+    )
+    other_sent_to = other.sent_to_list.get()
+    response = api_client.get(
+        reverse(
+            "v1:admin-notification-email-history-render-sent-to-as-html",
+            kwargs={"pk": email_history.id, "sent_to_id": other_sent_to.id},
+        )
+    )
+    assert response.status_code == http.HTTPStatus.NOT_FOUND
+
+
 # ---- 채널 간 격리 -----------------------------------------------------------
 
 

app/admin_api/views/notification.py

@@ -24,6 +24,7 @@
     NHNCloudSMSNotificationTemplate,
 )
 from rest_framework.decorators import action
+from rest_framework.generics import get_object_or_404
 from rest_framework.mixins import CreateModelMixin, ListModelMixin, RetrieveModelMixin
 from rest_framework.renderers import StaticHTMLRenderer
 from rest_framework.request import Request
@@ -32,7 +33,7 @@
 
 TEMPLATE_READ_METHODS = ["list", "retrieve", "render_preview"]
 TEMPLATE_CRUD_METHODS = TEMPLATE_READ_METHODS + ["create", "update", "partial_update", "destroy"]
-HISTORY_METHODS = ["list", "retrieve", "create", "retry"]
+HISTORY_METHODS = ["list", "retrieve", "create", "retry", "render_sent_to_as_html"]
 
 
 # ---- Template -----------------------------------------------------------
@@ -95,6 +96,16 @@ def retry(self, *args: tuple, **kwargs: dict) -> Response:
         serializer.retry()
         return Response(data=serializer.data)
 
+    @extend_schema(responses=build_html_responses(names=["Notification History SentTo Render As HTML"]))
+    @action(
+        detail=True,
+        methods=["get"],
+        url_path=r"sent-to/(?P<sent_to_id>[^/.]+)/render",
+        renderer_classes=[StaticHTMLRenderer],
+    )
+    def render_sent_to_as_html(self, request: Request, sent_to_id: str, *args: tuple, **kwargs: dict) -> Response:
+        return Response(data=get_object_or_404(self.get_object().sent_to_list.all(), pk=sent_to_id).render_as_html())
+
 
 @extend_schema_view(**{m: extend_schema(tags=[OpenAPITag.ADMIN_NOTI_EMAIL]) for m in HISTORY_METHODS})
 class EmailNotificationHistoryAdminViewSet(_NotiHistoryAdminViewSetBase):

app/notification/migrations/0002_emailnotificationhistorysentto_failure_reason_and_more.py

@@ -0,0 +1,22 @@
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+    dependencies = [("notification", "0001_initial")]
+    operations = [
+        migrations.AddField(
+            model_name="emailnotificationhistorysentto",
+            name="failure_reason",
+            field=models.TextField(blank=True, null=True),
+        ),
+        migrations.AddField(
+            model_name="nhncloudkakaoalimtalknotificationhistorysentto",
+            name="failure_reason",
+            field=models.TextField(blank=True, null=True),
+        ),
+        migrations.AddField(
+            model_name="nhncloudsmsnotificationhistorysentto",
+            name="failure_reason",
+            field=models.TextField(blank=True, null=True),
+        ),
+    ]

app/notification/models/base.py

@@ -1,6 +1,7 @@
 from enum import StrEnum, auto
 from json import loads as json_loads
 from logging import getLogger
+from traceback import format_exc
 from typing import TYPE_CHECKING, Any, ClassVar, Generic, NotRequired, TypedDict, TypeVar
 from uuid import uuid4
 
@@ -196,6 +197,7 @@ class NotificationHistorySentToBase(BaseAbstractModel):
         default=NotificationStatus.CREATED,
         db_index=True,
     )
+    failure_reason = models.TextField(null=True, blank=True)
 
     class Meta:
         abstract = True
@@ -276,13 +278,15 @@ def build_send_parameters(self) -> SendParameters:
 
     def send(self) -> None:
         self.status = NotificationStatus.SENDING
-        self.save(update_fields=["status"])
+        self.failure_reason = None
+        self.save(update_fields=["status", "failure_reason"])
 
         try:
             self.history.client.send_message(data=self.build_send_parameters())
         except Exception:
             self.status = NotificationStatus.FAILED
-            self.save(update_fields=["status"])
+            self.failure_reason = format_exc()
+            self.save(update_fields=["status", "failure_reason"])
             slack_logger.exception(
                 "Notification send failed: history_id=%s template_code=%s recipient=%s",
                 self.history.id,

app/notification/tasks.py

@@ -1,3 +1,5 @@
+from traceback import format_exc
+
 from celery import shared_task
 from django.apps import apps
 from notification.models.base import NotificationStatus, slack_logger
@@ -15,6 +17,10 @@ def send_notification_to_recipient(model_label: str, sent_to_id: str) -> None:
     except Exception:
         sent_to.refresh_from_db(fields=["status"])
         if sent_to.status != NotificationStatus.FAILED:
+            sent_to_class.objects.filter(pk=sent_to_id).update(
+                status=NotificationStatus.FAILED,
+                failure_reason=format_exc(),
+            )
             slack_logger.exception(
                 "Batch send unexpected error: history_id=%s recipient=%s",
                 sent_to.history_id,

app/notification/test/history_send_test.py

@@ -61,6 +61,36 @@ def test_sent_to_failure_transitions_to_failed_and_propagates(email_template):
     assert sent_to.status == NotificationStatus.FAILED
 
 
+@pytest.mark.django_db
+def test_sent_to_failure_records_traceback_in_failure_reason(email_template):
+    history = _create_history(email_template)
+    sent_to = history.sent_to_list.get()
+    with patch.object(EmailNotificationHistory, "client") as mock_client:
+        mock_client.send_message.side_effect = RuntimeError("kaboom-xyz")
+        with pytest.raises(RuntimeError):
+            sent_to.send()
+    sent_to.refresh_from_db()
+    assert sent_to.failure_reason is not None
+    assert "RuntimeError" in sent_to.failure_reason
+    assert "kaboom-xyz" in sent_to.failure_reason
+    assert "Traceback" in sent_to.failure_reason
+
+
+@pytest.mark.django_db
+def test_sent_to_retry_clears_previous_failure_reason(email_template):
+    history = _create_history(email_template)
+    sent_to = history.sent_to_list.get()
+    sent_to.status = NotificationStatus.FAILED
+    sent_to.failure_reason = "previous failure"
+    sent_to.save(update_fields=["status", "failure_reason"])
+
+    with patch.object(EmailNotificationHistory, "client"):
+        sent_to.send()
+    sent_to.refresh_from_db()
+    assert sent_to.status == NotificationStatus.SENT
+    assert sent_to.failure_reason is None
+
+
 @pytest.mark.django_db
 def test_sent_to_failure_logs_to_slack_logger(email_template, caplog):
     history = _create_history(email_template, recipient="bad@example.com")

app/notification/test/tasks_test.py

@@ -96,3 +96,28 @@ def test_task_logs_unexpected_error_when_inner_save_fails(sent_to, caplog):
     records = [r for r in caplog.records if "Batch send unexpected" in r.getMessage()]
     assert len(records) == 1
     assert records[0].exc_info is not None
+
+
+@pytest.mark.django_db
+def test_task_records_failure_reason_on_external_failure(sent_to):
+    with patch.object(EmailNotificationHistory, "client") as mock_client:
+        mock_client.send_message.side_effect = RuntimeError("boom-task")
+        with pytest.raises(RuntimeError):
+            send_notification_to_recipient(LABEL, sent_to.id)
+    sent_to.refresh_from_db()
+    assert sent_to.status == NotificationStatus.FAILED
+    assert sent_to.failure_reason is not None
+    assert "boom-task" in sent_to.failure_reason
+
+
+@pytest.mark.django_db
+def test_task_records_failure_reason_when_inner_save_fails(sent_to):
+    # send() 내부 save() 자체가 망가졌을 때, task의 outer fallback이 queryset.update()로
+    # status=FAILED와 failure_reason을 기록해야 한다.
+    with patch.object(EmailNotificationHistorySentTo, "save", side_effect=RuntimeError("db down")):
+        with pytest.raises(RuntimeError, match="db down"):
+            send_notification_to_recipient(LABEL, sent_to.id)
+    sent_to.refresh_from_db()
+    assert sent_to.status == NotificationStatus.FAILED
+    assert sent_to.failure_reason is not None
+    assert "db down" in sent_to.failure_reason