test(bff): relay a refused diploma as 422 with its reason, a down scanner as 503 (refs #192)

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

services/bff/Bff.Api/DownstreamClients.cs

@@ -36,9 +36,9 @@ public interface IDomainClient
     Task<bool> WithdrawRegistrationAsync(string registrationId, string bsn, CancellationToken ct = default);
 
     /// <summary>Provide (upload) the diploma the caller's own registration is waiting for ("documenten
-    /// aanleveren"). The file is carried base64-encoded. Owner-scoped by <paramref name="bsn"/>. Returns
-    /// <c>false</c> when the domain reports the registration is unknown or not the caller's (404).</summary>
-    Task<bool> ProvideDocumentsAsync(
+    /// aanleveren"). The file is carried base64-encoded. Owner-scoped by <paramref name="bsn"/>. The domain
+    /// refuses a non-PDF or infected file, and an upload it could not scan (S-29, ADR-0036).</summary>
+    Task<ProvideDocumentsResult> ProvideDocumentsAsync(
         string registrationId, string bsn, string contentBase64, string? fileName, string? contentType, CancellationToken ct = default);
 
     /// <summary>The behandelaar's werkbak — registrations awaiting beoordeling.</summary>
@@ -48,6 +48,9 @@ public interface IDomainClient
     Task DecideAsync(string registrationId, string besluit, CancellationToken ct = default);
 }
 
+/// <summary>How the domain answered a provide-documents request (S-29).</summary>
+public enum ProvideDocumentsResult { Provided, NotFound, NotAPdf, Infected, ScannerUnavailable }
+
 /// <summary>Port to the read projection.</summary>
 public interface IProjectionClient
 {
@@ -116,7 +119,7 @@ public sealed class DomainClient(HttpClient http) : IDomainClient
         return true;
     }
 
-    public async Task<bool> ProvideDocumentsAsync(
+    public async Task<ProvideDocumentsResult> ProvideDocumentsAsync(
         string registrationId, string bsn, string contentBase64, string? fileName, string? contentType, CancellationToken ct = default)
     {
         using var response = await http.PostAsJsonAsync(
@@ -124,9 +127,9 @@ public sealed class DomainClient(HttpClient http) : IDomainClient
             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 false;
+            return ProvideDocumentsResult.NotFound;
         response.EnsureSuccessStatusCode();
-        return true;
+        return ProvideDocumentsResult.Provided;
     }
 
     public async Task<IReadOnlyList<WerkbakItem>> GetWerkbakAsync(CancellationToken ct = default)

services/bff/Bff.Api/Program.cs

@@ -177,7 +177,7 @@ app.MapPost("/self-service/registrations/{id}/documents", async (string id, Prov
         return Results.BadRequest("A document is required.");
 
     var provided = await domain.ProvideDocumentsAsync(id, bsn, body.ContentBase64, body.FileName, body.ContentType, ct);
-    return provided ? Results.NoContent() : Results.NotFound();
+    return provided == ProvideDocumentsResult.Provided ? Results.NoContent() : Results.NotFound();
 })
     .RequireAuthorization()
     .Produces(StatusCodes.Status204NoContent)