Merge pull request #2737 from alphagov/returned-letter-statistics

Add an endpoint to return returned letter stats

app/dao/returned_letters_dao.py

@@ -13,6 +13,7 @@ from app.models import (
     Template,
     User,
 )
+from app.utils import midnight_n_days_ago
 
 
 def _get_notification_ids_for_references(references):
@@ -50,6 +51,25 @@ def insert_or_update_returned_letters(references):
         db.session.connection().execute(stmt)
 
 
+def fetch_recent_returned_letter_count(service_id):
+    return db.session.query(
+        func.count(ReturnedLetter.notification_id).label('returned_letter_count'),
+    ).filter(
+        ReturnedLetter.service_id == service_id,
+        ReturnedLetter.reported_at > midnight_n_days_ago(7),
+    ).one()
+
+
+def fetch_most_recent_returned_letter(service_id):
+    return db.session.query(
+        ReturnedLetter.reported_at,
+    ).filter(
+        ReturnedLetter.service_id == service_id,
+    ).order_by(
+        desc(ReturnedLetter.reported_at)
+    ).first()
+
+
 def fetch_returned_letter_summary(service_id):
     return db.session.query(
         func.count(ReturnedLetter.notification_id).label('returned_letter_count'),

app/service/rest.py

@@ -31,8 +31,10 @@ from app.dao.fact_notification_status_dao import (
 from app.dao.inbound_numbers_dao import dao_allocate_number_for_service
 from app.dao.organisation_dao import dao_get_organisation_by_service_id
 from app.dao.returned_letters_dao import (
+    fetch_most_recent_returned_letter,
+    fetch_recent_returned_letter_count,
     fetch_returned_letter_summary,
-    fetch_returned_letters
+    fetch_returned_letters,
 )
 from app.dao.service_data_retention_dao import (
     fetch_service_data_retention,
@@ -120,7 +122,7 @@ from app.schemas import (
     email_data_request_schema
 )
 from app.user.users_schema import post_set_permissions_schema
-from app.utils import pagination_links
+from app.utils import midnight_n_days_ago, pagination_links
 
 service_blueprint = Blueprint('service', __name__)
 
@@ -946,6 +948,35 @@ def check_if_reply_to_address_already_in_use(service_id, email_address):
         )
 
 
+@service_blueprint.route('/<uuid:service_id>/returned-letter-statistics', methods=['GET'])
+def returned_letter_statistics(service_id):
+
+    most_recent = fetch_most_recent_returned_letter(service_id)
+
+    if not most_recent:
+        return jsonify({
+            'returned_letter_count': 0,
+            'most_recent_report': None,
+        })
+
+    most_recent_reported_at = datetime.combine(
+        most_recent.reported_at, datetime.min.time()
+    )
+
+    if most_recent_reported_at < midnight_n_days_ago(7):
+        return jsonify({
+            'returned_letter_count': 0,
+            'most_recent_report': most_recent.reported_at.strftime(DATETIME_FORMAT_NO_TIMEZONE),
+        })
+
+    count = fetch_recent_returned_letter_count(service_id)
+
+    return jsonify({
+        'returned_letter_count': count.returned_letter_count,
+        'most_recent_report': most_recent.reported_at.strftime(DATETIME_FORMAT_NO_TIMEZONE),
+    })
+
+
 @service_blueprint.route('/<uuid:service_id>/returned-letter-summary', methods=['GET'])
 def returned_letter_summary(service_id):
     results = fetch_returned_letter_summary(service_id)

tests/app/dao/test_returned_letters_dao.py

@@ -1,14 +1,22 @@
+import uuid
 from datetime import datetime, timedelta, date
 
 from freezegun import freeze_time
 
 from app.dao.returned_letters_dao import (
     insert_or_update_returned_letters,
+    fetch_most_recent_returned_letter,
+    fetch_recent_returned_letter_count,
     fetch_returned_letter_summary,
     fetch_returned_letters
 )
 from app.models import ReturnedLetter, NOTIFICATION_RETURNED_LETTER
-from tests.app.db import create_notification, create_notification_history, create_returned_letter
+from tests.app.db import (
+    create_notification,
+    create_notification_history,
+    create_returned_letter,
+    create_service,
+)
 
 
 def test_insert_or_update_returned_letters_inserts(sample_letter_template):
@@ -90,6 +98,62 @@ def test_insert_or_update_returned_letters_with_duplicates_in_reference_list(sam
         assert x.notification_id in [notification_1.id, notification_2.id]
 
 
+def test_get_returned_letter_count(sample_service):
+    # Before 7 days – don’t count
+    create_returned_letter(
+        sample_service,
+        reported_at=datetime(2001, 1, 1)
+    )
+    create_returned_letter(
+        sample_service,
+        reported_at=datetime(2010, 11, 1, 23, 59, 59),
+    )
+    # In the last 7 days – count
+    create_returned_letter(
+        sample_service,
+        reported_at=datetime(2010, 11, 2, 0, 0, 0),
+    )
+    create_returned_letter(
+        sample_service,
+        reported_at=datetime(2010, 11, 8, 10, 0),
+    )
+    create_returned_letter(
+        sample_service,
+        reported_at=datetime(2010, 11, 8, 10, 0),
+    )
+    # Different service – don’t count
+    create_returned_letter(
+        create_service(service_id=uuid.uuid4(), service_name='Other service'),
+        reported_at=datetime(2010, 11, 8, 10, 0),
+    )
+
+    with freeze_time('2010-11-08 10:10'):
+        result = fetch_recent_returned_letter_count(sample_service.id)
+
+    assert result.returned_letter_count == 3
+
+
+def test_fetch_most_recent_returned_letter_for_service(sample_service):
+    # Older
+    create_returned_letter(
+        sample_service,
+        reported_at=datetime(2009, 9, 9, 9, 9),
+    )
+    # Newer
+    create_returned_letter(
+        sample_service,
+        reported_at=datetime(2010, 10, 10, 10, 10),
+    )
+    # Newest, but different service
+    create_returned_letter(
+        create_service(service_id=uuid.uuid4(), service_name='Other service'),
+        reported_at=datetime(2011, 11, 11, 11, 11),
+    )
+    result = fetch_most_recent_returned_letter(sample_service.id)
+
+    assert str(result.reported_at) == '2010-10-10'
+
+
 def test_get_returned_letter_summary(sample_service):
     now = datetime.utcnow()
     create_returned_letter(sample_service, reported_at=now)

tests/app/service/test_rest.py

@@ -3382,6 +3382,64 @@ def test_get_monthly_notification_data_by_service(mocker, admin_request):
     assert response == []
 
 
+@freeze_time('2019-12-11 13:30')
+def test_get_returned_letter_statistics(admin_request, sample_service):
+    create_returned_letter(sample_service, reported_at=datetime.utcnow() - timedelta(days=3))
+    create_returned_letter(sample_service, reported_at=datetime.utcnow() - timedelta(days=2))
+    create_returned_letter(sample_service, reported_at=datetime.utcnow() - timedelta(days=1))
+
+    response = admin_request.get('service.returned_letter_statistics', service_id=sample_service.id)
+
+    assert response == {
+        'returned_letter_count': 3,
+        'most_recent_report': '2019-12-10 00:00:00.000000'
+    }
+
+
+@freeze_time('2019-12-11 13:30')
+def test_get_returned_letter_statistics_with_old_returned_letters(
+    mocker,
+    admin_request,
+    sample_service,
+):
+    create_returned_letter(sample_service, reported_at=datetime.utcnow() - timedelta(days=8))
+    create_returned_letter(sample_service, reported_at=datetime.utcnow() - timedelta(days=800))
+
+    count_mock = mocker.patch(
+        'app.service.rest.fetch_recent_returned_letter_count',
+    )
+
+    assert admin_request.get(
+        'service.returned_letter_statistics',
+        service_id=sample_service.id,
+    ) == {
+        'returned_letter_count': 0,
+        'most_recent_report': '2019-12-03 00:00:00.000000',
+    }
+
+    assert count_mock.called is False
+
+
+def test_get_returned_letter_statistics_with_no_returned_letters(
+    mocker,
+    admin_request,
+    sample_service,
+):
+    count_mock = mocker.patch(
+        'app.service.rest.fetch_recent_returned_letter_count',
+    )
+
+    assert admin_request.get(
+        'service.returned_letter_statistics',
+        service_id=sample_service.id,
+    ) == {
+        'returned_letter_count': 0,
+        'most_recent_report': None,
+    }
+
+    assert count_mock.called is False
+
+
 @freeze_time('2019-12-11 13:30')
 def test_get_returned_letter_summary(admin_request, sample_service):
     create_returned_letter(sample_service, reported_at=datetime.utcnow() - timedelta(days=3))