feat(bff): relay refused diplomas as 422 with reason, scanner down as 503 (refs #192)

openapi.json and the generated portal client regenerated from the served spec.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

services/bff/Bff.Api/DownstreamClients.cs

@@ -51,6 +51,9 @@ public interface IDomainClient
 /// <summary>How the domain answered a provide-documents request (S-29).</summary>
 public enum ProvideDocumentsResult { Provided, NotFound, NotAPdf, Infected, ScannerUnavailable }
 
+/// <summary>The body of a 422 provide-documents answer: why the file was refused.</summary>
+public sealed record Refusal(string Reason);
+
 /// <summary>Port to the read projection.</summary>
 public interface IProjectionClient
 {
@@ -125,9 +128,18 @@ public sealed class DomainClient(HttpClient http) : IDomainClient
         using var response = await http.PostAsJsonAsync(
             $"registrations/{registrationId}/documents",
             new { bsn, contentBase64, fileName, contentType }, ct);
-        // The domain 404s an unknown or not-owned registration; relay that rather than fail hard.
-        if (response.StatusCode == System.Net.HttpStatusCode.NotFound)
-            return ProvideDocumentsResult.NotFound;
+        // The domain 404s an unknown or not-owned registration, 422s a refused file with its reason and
+        // 503s when its scanner is down (S-29); relay those rather than fail hard.
+        switch (response.StatusCode)
+        {
+            case System.Net.HttpStatusCode.NotFound:
+                return ProvideDocumentsResult.NotFound;
+            case System.Net.HttpStatusCode.ServiceUnavailable:
+                return ProvideDocumentsResult.ScannerUnavailable;
+            case System.Net.HttpStatusCode.UnprocessableEntity:
+                var refusal = await response.Content.ReadFromJsonAsync<Refusal>(ct);
+                return refusal?.Reason == "infected" ? ProvideDocumentsResult.Infected : ProvideDocumentsResult.NotAPdf;
+        }
         response.EnsureSuccessStatusCode();
         return ProvideDocumentsResult.Provided;
     }