[AZ-488] UAV tile batch upload + 5-rule quality gate

Replaces the 501 stub at POST /api/satellite/upload with a multipart batch endpoint that ingests UAV-captured tiles, runs each item through a 5-rule quality gate, and persists accepted tiles via the AZ-484 multi-source storage path with source='uav'. Quality gate (in fixed order, first failure wins): JPEG format (content-type + magic), size band 5 KiB-5 MiB, exact 256x256 dimensions, captured-at age (no future >30 s skew, no older than 7 days), luminance variance on 32x32 downsample. Closed reject-reason enumeration in v1.0.0 contract. Authorization: custom PermissionsRequirement / PermissionsAuthorization Handler that reads the JWT `permissions` claim (tolerates both repeated-string and JSON-array shapes). Endpoint protected by RequiresGpsPermission policy; 401 without token, 403 without GPS perm. Persistence: file-first to ./tiles/uav/{z}/{x}/{y}.jpg, then ITileRepository.InsertAsync UPSERT (per-source UPSERT contract from AZ-484). Per-item failures reported in response without aborting the batch. Kestrel MaxRequestBodySize and FormOptions limits set to MaxBatchSize x MaxBytes (default 100 x 5 MiB = 500 MiB). New frozen contract: _docs/02_document/contracts/api/uav-tile-upload.md v1.0.0. PT-08 NFR added to performance-tests.md as Deferred (harness work tracked in PT-07 leftover, per AZ-488 § Risk 4). Tests: 11 quality-gate unit tests, 5 handler unit tests, 3 file-path unit tests, 12 permission-handler unit tests, 7 integration tests (AC-1..AC-6, AC-8). All 253 unit tests + smoke integration suite green. Co-authored-by: Cursor <cursoragent@cursor.com>
2026-06-22 18:21:17 +00:00 · 2026-05-11 23:50:49 +03:00
parent 11b7074485
commit 1802d32107
35 changed files with 2280 additions and 107 deletions
@@ -0,0 +1,194 @@
+using System.Text.Json;
+using Microsoft.Extensions.Logging;
+using Microsoft.Extensions.Options;
+using SatelliteProvider.Common.Configs;
+using SatelliteProvider.Common.DTO;
+using SatelliteProvider.Common.Enums;
+using SatelliteProvider.Common.Utils;
+using SatelliteProvider.DataAccess.Models;
+using SatelliteProvider.DataAccess.Repositories;
+
+namespace SatelliteProvider.Services.TileDownloader;
+
+public interface IUavTileUploadHandler
+{
+    Task<UavTileUploadHandlerResult> HandleAsync(string metadataJson, IReadOnlyList<UavUploadFile> files, CancellationToken cancellationToken = default);
+}
+
+public sealed record UavUploadFile(string FileName, string? ContentType, ReadOnlyMemory<byte> Content);
+
+public sealed record UavTileUploadHandlerResult(bool EnvelopeRejected, string? EnvelopeError, UavTileBatchUploadResponse? Response);
+
+public sealed class UavTileUploadHandler : IUavTileUploadHandler
+{
+    private const string UavTileFileExtension = ".jpg";
+    private const string UavTileSubdirectory = "uav";
+
+    private readonly IUavTileQualityGate _qualityGate;
+    private readonly ITileRepository _tileRepository;
+    private readonly StorageConfig _storageConfig;
+    private readonly MapConfig _mapConfig;
+    private readonly UavQualityConfig _qualityConfig;
+    private readonly TimeProvider _timeProvider;
+    private readonly ILogger<UavTileUploadHandler> _logger;
+
+    public UavTileUploadHandler(
+        IUavTileQualityGate qualityGate,
+        ITileRepository tileRepository,
+        IOptions<StorageConfig> storageConfig,
+        IOptions<MapConfig> mapConfig,
+        IOptions<UavQualityConfig> qualityConfig,
+        ILogger<UavTileUploadHandler> logger,
+        TimeProvider? timeProvider = null)
+    {
+        _qualityGate = qualityGate ?? throw new ArgumentNullException(nameof(qualityGate));
+        _tileRepository = tileRepository ?? throw new ArgumentNullException(nameof(tileRepository));
+        _storageConfig = storageConfig?.Value ?? throw new ArgumentNullException(nameof(storageConfig));
+        _mapConfig = mapConfig?.Value ?? throw new ArgumentNullException(nameof(mapConfig));
+        _qualityConfig = qualityConfig?.Value ?? throw new ArgumentNullException(nameof(qualityConfig));
+        _logger = logger ?? throw new ArgumentNullException(nameof(logger));
+        _timeProvider = timeProvider ?? TimeProvider.System;
+    }
+
+    private static readonly JsonSerializerOptions MetadataJsonOptions = new()
+    {
+        PropertyNameCaseInsensitive = true,
+    };
+
+    public async Task<UavTileUploadHandlerResult> HandleAsync(string metadataJson, IReadOnlyList<UavUploadFile> files, CancellationToken cancellationToken = default)
+    {
+        ArgumentNullException.ThrowIfNull(files);
+
+        if (string.IsNullOrWhiteSpace(metadataJson))
+        {
+            return EnvelopeError("Request `metadata` field is required.");
+        }
+
+        UavTileBatchMetadataPayload? payload;
+        try
+        {
+            payload = JsonSerializer.Deserialize<UavTileBatchMetadataPayload>(metadataJson, MetadataJsonOptions);
+        }
+        catch (JsonException ex)
+        {
+            return EnvelopeError($"Invalid `metadata` JSON: {ex.Message}");
+        }
+
+        if (payload is null || payload.Items.Count == 0)
+        {
+            return EnvelopeError("Request `metadata.items` is required and must contain at least one entry.");
+        }
+
+        if (payload.Items.Count != files.Count)
+        {
+            return EnvelopeError($"Mismatched batch: metadata has {payload.Items.Count} entries but {files.Count} file(s) were uploaded.");
+        }
+
+        if (payload.Items.Count > _qualityConfig.MaxBatchSize)
+        {
+            return EnvelopeError($"Batch size {payload.Items.Count} exceeds the configured maximum of {_qualityConfig.MaxBatchSize}.");
+        }
+
+        var response = new UavTileBatchUploadResponse();
+        for (var index = 0; index < payload.Items.Count; index++)
+        {
+            cancellationToken.ThrowIfCancellationRequested();
+
+            var metadata = payload.Items[index];
+            var file = files[index];
+
+            var gateResult = _qualityGate.Validate(file.Content, file.ContentType, metadata);
+            if (!gateResult.Accepted)
+            {
+                response.Items.Add(new UavTileUploadResultItem
+                {
+                    Index = index,
+                    Status = UavTileUploadStatus.Rejected,
+                    RejectReason = gateResult.Reason,
+                    RejectDetails = gateResult.Details,
+                });
+                continue;
+            }
+
+            try
+            {
+                var persistedId = await PersistAsync(metadata, file.Content, cancellationToken);
+                response.Items.Add(new UavTileUploadResultItem
+                {
+                    Index = index,
+                    Status = UavTileUploadStatus.Accepted,
+                    TileId = persistedId,
+                });
+            }
+            catch (Exception ex) when (ex is IOException or UnauthorizedAccessException)
+            {
+                _logger.LogError(ex, "UAV tile persistence failed at index {Index}", index);
+                response.Items.Add(new UavTileUploadResultItem
+                {
+                    Index = index,
+                    Status = UavTileUploadStatus.Rejected,
+                    RejectReason = UavTileRejectReasons.StorageFailure,
+                });
+            }
+        }
+
+        return new UavTileUploadHandlerResult(EnvelopeRejected: false, EnvelopeError: null, Response: response);
+    }
+
+    private async Task<Guid> PersistAsync(UavTileMetadata metadata, ReadOnlyMemory<byte> imageBytes, CancellationToken cancellationToken)
+    {
+        var (tileX, tileY) = GeoUtils.WorldToTilePos(new GeoPoint(metadata.Latitude, metadata.Longitude), metadata.TileZoom);
+        var filePath = BuildUavTileFilePath(_storageConfig, metadata.TileZoom, tileX, tileY);
+
+        var directory = Path.GetDirectoryName(filePath);
+        if (!string.IsNullOrEmpty(directory))
+        {
+            Directory.CreateDirectory(directory);
+        }
+
+        // File-first, row-second so a crash leaves an orphan file rather than a row
+        // pointing at nothing (Risk 2 in the AZ-488 task spec).
+        await File.WriteAllBytesAsync(filePath, imageBytes.ToArray(), cancellationToken);
+
+        var capturedAtUtc = metadata.CapturedAt.Kind == DateTimeKind.Utc
+            ? metadata.CapturedAt
+            : metadata.CapturedAt.ToUniversalTime();
+        var now = _timeProvider.GetUtcNow().UtcDateTime;
+
+        var entity = new TileEntity
+        {
+            Id = Guid.NewGuid(),
+            TileZoom = metadata.TileZoom,
+            TileX = tileX,
+            TileY = tileY,
+            Latitude = metadata.Latitude,
+            Longitude = metadata.Longitude,
+            TileSizeMeters = metadata.TileSizeMeters,
+            TileSizePixels = _mapConfig.TileSizePixels,
+            ImageType = "jpg",
+            MapsVersion = null,
+            Version = null,
+            FilePath = filePath,
+            Source = TileSourceConverter.ToWireValue(TileSource.Uav),
+            CapturedAt = capturedAtUtc,
+            CreatedAt = now,
+            UpdatedAt = now,
+        };
+
+        return await _tileRepository.InsertAsync(entity);
+    }
+
+    public static string BuildUavTileFilePath(StorageConfig storageConfig, int tileZoom, int tileX, int tileY)
+    {
+        ArgumentNullException.ThrowIfNull(storageConfig);
+        return Path.Combine(
+            storageConfig.TilesDirectory,
+            UavTileSubdirectory,
+            tileZoom.ToString(System.Globalization.CultureInfo.InvariantCulture),
+            tileX.ToString(System.Globalization.CultureInfo.InvariantCulture),
+            tileY.ToString(System.Globalization.CultureInfo.InvariantCulture) + UavTileFileExtension);
+    }
+
+    private static UavTileUploadHandlerResult EnvelopeError(string detail) =>
+        new(EnvelopeRejected: true, EnvelopeError: detail, Response: null);
+}