Merge branch 'develop' into 5599-email-template-updates

Author: elipe17

Taskfile.yml

@@ -231,18 +231,22 @@ tasks:
       - npm install
 
   frontend-test:
-    desc: Run frontend unit tests in docker (watch-less)
+    desc: 'Run frontend unit tests in docker (watch-less). E.g: task frontend-test JEST_ARGS="--testPathPattern=FeedbackReports"'
     dir: tdrs-frontend
+    vars:
+      JEST_ARGS: '{{.JEST_ARGS | default ""}}'
     cmds:
       - docker compose -f docker-compose.local.yml up -d --build tdp-frontend-test
-      - docker compose -f docker-compose.local.yml exec tdp-frontend-test sh -c "npm run test"
+      - docker compose -f docker-compose.local.yml exec tdp-frontend-test sh -c "npm run test -- {{.JEST_ARGS}}"
 
   frontend-test-cov:
-    desc: Run frontend unit tests with coverage in docker
+    desc: 'Run frontend unit tests with coverage in docker. E.g: task frontend-test-cov JEST_ARGS="--testPathPattern=FeedbackReports"'
     dir: tdrs-frontend
+    vars:
+      JEST_ARGS: '{{.JEST_ARGS | default ""}}'
     cmds:
       - docker compose -f docker-compose.local.yml up -d --build tdp-frontend-test
-      - docker compose -f docker-compose.local.yml exec tdp-frontend-test sh -c "npm run test:cov"
+      - docker compose -f docker-compose.local.yml exec tdp-frontend-test sh -c "npm run test:cov -- {{.JEST_ARGS}}"
 
   frontend-lint:
     desc: Run eslint in the frontend test container

tdrs-backend/tdpservice/email/email_enums.py

@@ -25,6 +25,12 @@ class DataFileEmail(Enum):
     UPCOMING_SUBMISSION_DEADLINE = "upcoming-submission-deadline.html"
 
 
+class FeedbackReportEmail(Enum):
+    """Email templates related to feedback report reminders."""
+
+    REPORT_AVAILABLE = "feedback/report-available.html"
+
+
 class TanfDataFileEmail(Enum):
     """Email templates related to TANF data file submissions."""
 

tdrs-backend/tdpservice/email/helpers/feedback_report.py

@@ -0,0 +1,67 @@
+"""Helper functions for sending feedback report notification emails."""
+
+from django.conf import settings
+
+from tdpservice.email.email import automated_email, log
+from tdpservice.email.email_enums import FeedbackReportEmail
+from tdpservice.reports.models import ReportFile
+
+
+def send_feedback_report_available_email(report_file: ReportFile, recipients):
+    """
+    Send an email to Data Analysts when a feedback report is available.
+
+    Parameters
+    ----------
+        report_file: The ReportFile that was created
+        recipients: List of email addresses (usernames) to send to
+    """
+    if not recipients:
+        return
+
+    # Format date_extracted_on as MM/DD/YYYY
+    date_extracted_str = (
+        report_file.date_extracted_on.strftime("%m/%d/%Y")
+        if report_file.date_extracted_on
+        else "N/A"
+    )
+
+    # Only create logger_context if we have a valid user (LogEntry requires user_id)
+    logger_context = None
+    if report_file.user:
+        logger_context = {
+            "user_id": report_file.user.id,
+            "object_id": report_file.id,
+            "object_repr": f"ReportFile for {report_file.stt.name} FY {report_file.year} ({date_extracted_str})",
+            "content_type": ReportFile,
+        }
+
+    template_path = FeedbackReportEmail.REPORT_AVAILABLE.value
+    subject = f"Feedback Report Available: {report_file.stt.name} - FY {report_file.year}"
+    text_message = (
+        f"A new feedback report is available for {report_file.stt.name} "
+        f"for Fiscal Year {report_file.year} (reflects data submitted through {date_extracted_str})."
+    )
+
+    context = {
+        "stt_name": report_file.stt.name,
+        "fiscal_year": report_file.year,
+        "date_extracted_on": date_extracted_str,
+        "report_date": report_file.created_at.strftime("%m/%d/%Y"),
+        "url": settings.FRONTEND_BASE_URL,
+        "subject": subject,
+    }
+
+    log(
+        f"Feedback report available; emailing Data Analysts {list(recipients)}",
+        logger_context=logger_context,
+    )
+
+    automated_email(
+        email_path=template_path,
+        recipient_email=recipients,
+        subject=subject,
+        email_context=context,
+        text_message=text_message,
+        logger_context=logger_context,
+    )

tdrs-backend/tdpservice/email/helpers/test/test_feedback_report.py

@@ -0,0 +1,126 @@
+"""Test cases for feedback report email helper."""
+
+from datetime import date
+
+import pytest
+from unittest.mock import patch, MagicMock
+from django.core import mail
+from django.utils import timezone
+
+from tdpservice.email.helpers.feedback_report import send_feedback_report_available_email
+
+
+@pytest.fixture
+def mock_report_file(stt, user):
+    """Create a mock ReportFile for testing."""
+    report_file = MagicMock()
+    report_file.id = 1
+    report_file.stt = stt
+    report_file.year = 2025
+    report_file.date_extracted_on = date(2025, 1, 31)
+    report_file.created_at = timezone.now()
+    report_file.user = user
+    return report_file
+
+
+@pytest.mark.django_db
+class TestSendFeedbackReportAvailableEmail:
+    """Tests for send_feedback_report_available_email function."""
+
+    def test_sends_email_to_recipients(self, mock_report_file):
+        """Test that email is sent to provided recipients."""
+        recipients = ["user1@example.com", "user2@example.com"]
+
+        send_feedback_report_available_email(mock_report_file, recipients)
+
+        assert len(mail.outbox) == 1
+        assert mock_report_file.stt.name in mail.outbox[0].subject
+        assert "2025" in mail.outbox[0].subject
+
+    def test_does_not_send_email_when_no_recipients(self, mock_report_file):
+        """Test that no email is sent when recipients list is empty."""
+        send_feedback_report_available_email(mock_report_file, [])
+
+        assert len(mail.outbox) == 0
+
+    def test_does_not_send_email_when_recipients_is_none(self, mock_report_file):
+        """Test that no email is sent when recipients is None."""
+        send_feedback_report_available_email(mock_report_file, None)
+
+        assert len(mail.outbox) == 0
+
+    def test_email_contains_expected_text_message(self, mock_report_file):
+        """Test that email body contains expected text."""
+        recipients = ["user@example.com"]
+
+        send_feedback_report_available_email(mock_report_file, recipients)
+
+        assert len(mail.outbox) == 1
+        assert mock_report_file.stt.name in mail.outbox[0].body
+        assert "2025" in mail.outbox[0].body
+        assert "01/31/2025" in mail.outbox[0].body
+
+    def test_uses_correct_email_template(self, mock_report_file):
+        """Test that the correct email template is referenced."""
+        recipients = ["user@example.com"]
+
+        with patch("tdpservice.email.helpers.feedback_report.automated_email") as mock_email:
+            send_feedback_report_available_email(mock_report_file, recipients)
+
+            mock_email.assert_called_once()
+            call_kwargs = mock_email.call_args[1]
+            assert call_kwargs["email_path"] == "feedback/report-available.html"
+
+    def test_email_context_contains_required_fields(self, mock_report_file):
+        """Test that email context contains all required template variables."""
+        recipients = ["user@example.com"]
+
+        with patch("tdpservice.email.helpers.feedback_report.automated_email") as mock_email:
+            send_feedback_report_available_email(mock_report_file, recipients)
+
+            call_kwargs = mock_email.call_args[1]
+            context = call_kwargs["email_context"]
+
+            assert "stt_name" in context
+            assert "fiscal_year" in context
+            assert "date_extracted_on" in context
+            assert "report_date" in context
+            assert "url" in context
+            assert "subject" in context
+
+            assert context["stt_name"] == mock_report_file.stt.name
+            assert context["fiscal_year"] == 2025
+            assert context["date_extracted_on"] == "01/31/2025"
+
+    def test_handles_report_file_without_user(self, stt):
+        """Test that email is sent even if report_file.user is None."""
+        report_file = MagicMock()
+        report_file.id = 1
+        report_file.stt = stt
+        report_file.year = 2025
+        report_file.date_extracted_on = date(2025, 1, 31)
+        report_file.created_at = timezone.now()
+        report_file.user = None
+
+        recipients = ["user@example.com"]
+
+        send_feedback_report_available_email(report_file, recipients)
+
+        assert len(mail.outbox) == 1
+
+    def test_handles_report_file_without_date_extracted_on(self, stt, user):
+        """Test that email is sent even if date_extracted_on is None."""
+        report_file = MagicMock()
+        report_file.id = 1
+        report_file.stt = stt
+        report_file.year = 2025
+        report_file.date_extracted_on = None
+        report_file.created_at = timezone.now()
+        report_file.user = user
+
+        recipients = ["user@example.com"]
+
+        send_feedback_report_available_email(report_file, recipients)
+
+        assert len(mail.outbox) == 1
+        assert "N/A" in mail.outbox[0].body

tdrs-backend/tdpservice/email/templates/feedback/report-available.html

@@ -0,0 +1,32 @@
+{% extends 'base.html' %}
+
+{% block content %}
+<div style="color: #000000;">
+    <p>Hello,</p>
+
+    <p>
+        A new Feedback Report is available for <b>{{ stt_name }}</b> for Fiscal Year <b>{{ fiscal_year }}</b> (reflects data submitted through <b>{{ date_extracted_on }}</b>).
+    </p>
+
+    <p>
+        The report was uploaded on <b>{{ report_date }}</b>. Please review the feedback and, if needed, resubmit complete and accurate data.
+    </p>
+
+    <p>
+        <a
+            class="button"
+            href="{{ url }}/feedback-reports?year={{ fiscal_year }}"
+            style="background-color:#336a90;border-radius:4px;color:#ffffff;display:inline-block;font-family:sans-serif;font-size:18px;font-weight:bold;line-height:60px;text-align:center;text-decoration:none;width: auto; padding-left: 24px; padding-right: 24px;-webkit-text-size-adjust:none;"
+        >
+            View Feedback Reports
+        </a>
+    </p>
+
+    <p>
+        Please contact TDP Admin team at <a href="mailto:TANFData@acf.hhs.gov" target="_blank">TANFData@acf.hhs.gov</a> if you need further assistance.
+    </p>
+
+    <p>Thank you,</p>
+    TDP Team
+</div>
+{% endblock %}

tdrs-backend/tdpservice/reports/admin.py

@@ -23,7 +23,7 @@ def queryset(self, request, queryset):
             versions = queryset.filter(
                 stt__stt_code=OuterRef("stt__stt_code"),
                 year=OuterRef("year"),
-                quarter=OuterRef("quarter"),
+                date_extracted_on=OuterRef("date_extracted_on"),
             ).order_by("-version")
 
             # Filter to only records with the latest version
@@ -39,15 +39,15 @@ class ReportFileAdmin(ReadOnlyAdminMixin, admin.ModelAdmin):
     list_display = [
         "id",
         "year",
-        "quarter",
+        "date_extracted_on",
         "stt",
         "version",
         "user",
     ]
     list_filter = [
         "stt",
         "year",
-        "quarter",
+        "date_extracted_on",
         "user",
         VersionFilter
     ]

tdrs-backend/tdpservice/reports/migrations/0003_auto_20260130_1950.py

@@ -0,0 +1,39 @@
+# Generated by Django 3.2.15 on 2026-01-30 19:50
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('reports', '0002_initial'),
+    ]
+
+    operations = [
+        migrations.RemoveConstraint(
+            model_name='reportfile',
+            name='unique_reports_reportfile_fields',
+        ),
+        migrations.RemoveField(
+            model_name='reportfile',
+            name='quarter',
+        ),
+        migrations.RemoveField(
+            model_name='reportsource',
+            name='quarter',
+        ),
+        migrations.AddField(
+            model_name='reportfile',
+            name='date_extracted_on',
+            field=models.DateField(blank=True, null=True),
+        ),
+        migrations.AddField(
+            model_name='reportsource',
+            name='date_extracted_on',
+            field=models.DateField(blank=True, null=True),
+        ),
+        migrations.AddConstraint(
+            model_name='reportfile',
+            constraint=models.UniqueConstraint(fields=('version', 'date_extracted_on', 'year', 'stt'), name='unique_reports_reportfile_fields'),
+        ),
+    ]