feature: Approval and Promotion to VigilCareClinical

VigilCareRecordsAPI/Services/Interfaces/IIdempotencyService.cs

@@ -0,0 +1,14 @@
+public interface IIdempotencyService
+{
+    /// <summary>
+    /// Returns the cached response if the key was already used, or null if this is a new key.
+    /// </summary>
+    Task<IdempotencyRecord?> GetExistingAsync(string idempotencyKey, string operationName);
+
+    /// <summary>
+    /// Stores the result of an operation for future deduplication.
+    /// Must be called within the same transaction as the operation.
+    /// </summary>
+    Task SaveAsync(string idempotencyKey, string operationName, Guid resourceId,
+        int httpStatusCode, object responseBody, TimeSpan? ttl = null);
+}

VigilCareRecordsAPI/Services/Interfaces/IMrnGenerator.cs

@@ -0,0 +1,8 @@
+public interface IMrnGenerator
+{
+    /// <summary>
+    /// Generates the next unique MRN in the format "VCR-{6-digit padded number}".
+    /// Uses a PostgreSQL sequence for atomic increment under concurrent access.
+    /// </summary>
+    Task<string> GenerateNextMrnAsync();
+}

VigilCareRecordsAPI/Services/Interfaces/IPromotionService.cs

@@ -0,0 +1,23 @@
+public interface IPromotionService
+{
+    /// <summary>
+    /// Approves a verified or awaiting-clinical-approval batch and promotes its draft data
+    /// into live VigilCareClinical tables within a single atomic transaction.
+    /// </summary>
+    /// <param name="batchId">The batch to promote.</param>
+    /// <param name="approverUserId">The user performing the approval (separation-of-duties enforced).</param>
+    /// <param name="enableRetroactiveAlerts">
+    /// If true, outbox events are written for backfill observations so the alert engine processes them.
+    /// If false (default), backfill observations are silently inserted with no alert path.
+    /// Live-capture track always writes outbox events regardless of this flag.
+    /// </param>
+    /// <param name="idempotencyKey">Optional key for idempotent promotion. If provided and already used, returns cached result.</param>
+    /// <returns>The promotion result with all created live IDs.</returns>
+    Task<PromotionResultResponse> ApproveAndPromoteAsync(
+        Guid batchId, Guid approverUserId, bool enableRetroactiveAlerts, string? idempotencyKey);
+
+    /// <summary>
+    /// Returns the promotion result for an already-promoted batch.
+    /// </summary>
+    Task<PromotionResultResponse> GetPromotionResultAsync(Guid batchId);
+}