Add a task to process returned letter lists

Adds an API endpoint `/letters/returned` that accepts a list of
notification references and creates a task to update their status.

Adds a new task that uses the list of references to update the status
of notifications to 'returned-letter'.

The update is currently done using a single query and logs the
number of changed records (including notification history records).
This could potentially be done within the `/letters/returned` endpoint,
but creating a job right away allows us to extend this more easily
in the future (e.g. logging missing notifications or adding callbacks).

The job is using the database tasks queue.

tests/app/celery/test_tasks.py

@@ -27,6 +27,7 @@ from app.celery.tasks import (
     get_template_class,
     s3,
     send_inbound_sms_to_service,
+    process_returned_letters_list,
 )
 from app.config import QueueNames
 from app.dao import jobs_dao, services_dao
@@ -1551,3 +1552,14 @@ def test_process_incomplete_jobs_sets_status_to_in_progress_and_resets_processin
     assert job2.processing_started == datetime.utcnow()
 
     assert mock_process_incomplete_job.mock_calls == [call(str(job1.id)), call(str(job2.id))]
+
+
+def test_process_returned_letters_list(mocker, sample_letter_template):
+    create_notification(sample_letter_template, reference='ref1')
+    create_notification(sample_letter_template, reference='ref2')
+
+    process_returned_letters_list(['ref1', 'ref2', 'unknown-ref'])
+
+    assert [
+        n.status for n in Notification.query.all()
+    ] == ['returned-letter', 'returned-letter']

tests/app/letters/test_returned_letters.py

@@ -0,0 +1,23 @@
+import pytest
+
+
+@pytest.mark.parametrize('status, references', [
+    (200, ["1234567890ABCDEF", "1234567890ABCDEG"]),
+    (400, ["1234567890ABCDEFG", "1234567890ABCDEG"]),
+    (400, ["1234567890ABCDE", "1234567890ABCDEG"]),
+    (400, ["1234567890ABCDE\u26d4", "1234567890ABCDEG"]),
+    (400, ["NOTIFY0001234567890ABCDEF", "1234567890ABCDEG"]),
+])
+def test_process_returned_letters(status, references, admin_request, mocker):
+    mock_celery = mocker.patch("app.letters.rest.process_returned_letters_list.apply_async")
+
+    response = admin_request.post(
+        'letter-job.create_process_returned_letters_job',
+        _data={"references": references},
+        _expected_status=status
+    )
+
+    if status != 200:
+        assert '{} does not match'.format(references[0]) in response['errors'][0]['message']
+    else:
+        mock_celery.assert_called_once_with([references], queue='database-tasks')