feature: Observation Ingest, Synchronous Alert Detection, and Alert Lifecycle

2026-06-16 21:05:06 +08:00
parent 882d4af3e6
commit de603df151
26 changed files with 1471 additions and 5 deletions
@@ -0,0 +1,123 @@
+using System.Text.Json;
+using Microsoft.EntityFrameworkCore;
+
+public class AlertService : IAlertService
+{
+    private readonly AppDbContext _db;
+
+    public AlertService(AppDbContext db) => _db = db;
+
+    public async Task<PagedResult<ClinicalAlert>> ListByEncounterAsync(
+        Guid encounterId, AlertStatus? status, int page, int pageSize)
+    {
+        var query = _db.ClinicalAlerts
+            .AsNoTracking()
+            .Where(a => a.EncounterId == encounterId);
+
+        if (status.HasValue)
+            query = query.Where(a => a.Status == status.Value);
+
+        var total = await query.CountAsync();
+        var alerts = await query
+            .OrderByDescending(a => a.TriggeredAt)
+            .Skip((page - 1) * pageSize)
+            .Take(pageSize)
+            .ToListAsync();
+
+        return new PagedResult<ClinicalAlert>(alerts, page, pageSize, total);
+    }
+
+    public async Task<PagedResult<ClinicalAlert>> ListGlobalAsync(
+        AlertStatus? status, AlertSeverity? severity, string? department, int page, int pageSize)
+    {
+        var query = _db.ClinicalAlerts
+            .AsNoTracking()
+            .Include(a => a.Encounter)
+            .AsQueryable();
+
+        if (status.HasValue)
+            query = query.Where(a => a.Status == status.Value);
+
+        if (severity.HasValue)
+            query = query.Where(a => a.Severity == severity.Value);
+
+        if (!string.IsNullOrEmpty(department))
+            query = query.Where(a => a.Encounter.Department == department);
+
+        var total = await query.CountAsync();
+        var alerts = await query
+            .OrderByDescending(a => a.TriggeredAt)
+            .Skip((page - 1) * pageSize)
+            .Take(pageSize)
+            .ToListAsync();
+
+        return new PagedResult<ClinicalAlert>(alerts, page, pageSize, total);
+    }
+
+    public async Task<ClinicalAlert> GetByIdAsync(Guid id)
+    {
+        var alert = await _db.ClinicalAlerts
+            .AsNoTracking()
+            .Include(a => a.Encounter)
+            .FirstOrDefaultAsync(a => a.Id == id);
+
+        if (alert is null)
+            throw new NotFoundException("Alert not found.", "ALERT_NOT_FOUND");
+
+        return alert;
+    }
+
+    public async Task<ClinicalAlert> AcknowledgeAsync(Guid id, AcknowledgeAlertRequest req)
+    {
+        var alert = await _db.ClinicalAlerts.FindAsync(id);
+        if (alert is null)
+            throw new NotFoundException("Alert not found.", "ALERT_NOT_FOUND");
+
+        if (alert.Status != AlertStatus.Open && alert.Status != AlertStatus.Escalated)
+            throw new ConflictException(
+                $"Alert cannot be acknowledged from status '{alert.Status}'.",
+                "ALERT_NOT_ACKNOWLEDGEABLE");
+
+        alert.Status = AlertStatus.Acknowledged;
+        alert.AcknowledgedAt = DateTimeOffset.UtcNow;
+        alert.AcknowledgedBy = req.ClinicianId;
+
+        // Write an outbox event so the Kafka consumer (Phase 6) can cancel the
+        // pending RabbitMQ escalation timer when it sees this acknowledgment.
+        _db.OutboxEvents.Add(new OutboxEvent
+        {
+            Id = Guid.NewGuid(),
+            Topic = "alert.acknowledged",
+            Payload = JsonSerializer.Serialize(new
+            {
+                alertId = alert.Id,
+                encounterId = alert.EncounterId,
+                acknowledgedBy = req.ClinicianId,
+                acknowledgedAt = alert.AcknowledgedAt,
+                note = req.Note
+            }),
+            CreatedAt = DateTimeOffset.UtcNow
+        });
+
+        await _db.SaveChangesAsync();
+        return alert;
+    }
+
+    public async Task<ClinicalAlert> ResolveAsync(Guid id)
+    {
+        var alert = await _db.ClinicalAlerts.FindAsync(id);
+        if (alert is null)
+            throw new NotFoundException("Alert not found.", "ALERT_NOT_FOUND");
+
+        if (alert.Status != AlertStatus.Acknowledged)
+            throw new ConflictException(
+                "Alert must be acknowledged before it can be resolved.",
+                "ALERT_NOT_ACKNOWLEDGED");
+
+        alert.Status = AlertStatus.Resolved;
+        alert.ResolvedAt = DateTimeOffset.UtcNow;
+        await _db.SaveChangesAsync();
+
+        return alert;
+    }
+}
@@ -0,0 +1,14 @@
+public interface IAlertService
+{
+    Task<PagedResult<ClinicalAlert>> ListByEncounterAsync(
+        Guid encounterId, AlertStatus? status, int page, int pageSize);
+
+    Task<PagedResult<ClinicalAlert>> ListGlobalAsync(
+        AlertStatus? status, AlertSeverity? severity, string? department, int page, int pageSize);
+
+    Task<ClinicalAlert> GetByIdAsync(Guid id);
+
+    Task<ClinicalAlert> AcknowledgeAsync(Guid id, AcknowledgeAlertRequest req);
+
+    Task<ClinicalAlert> ResolveAsync(Guid id);
+}
@@ -0,0 +1,10 @@
+public interface IObservationQueryService
+{
+    Task<CursorPage<Observation>> GetHistoryAsync(
+        Guid encounterId,
+        string? code,
+        DateTimeOffset? from,
+        DateTimeOffset? to,
+        int limit,
+        string? cursorToken);
+}
@@ -0,0 +1,4 @@
+public interface IObservationService
+{
+    Task<IngestResult> IngestAsync(Guid encounterId, IngestObservationRequest req);
+}
@@ -0,0 +1,59 @@
+using Microsoft.EntityFrameworkCore;
+
+public class ObservationQueryService : IObservationQueryService
+{
+    private readonly AppDbContext _db;
+
+    public ObservationQueryService(AppDbContext db) => _db = db;
+
+    public async Task<CursorPage<Observation>> GetHistoryAsync(
+        Guid encounterId,
+        string? code,
+        DateTimeOffset? from,
+        DateTimeOffset? to,
+        int limit,
+        string? cursorToken)
+    {
+        limit = Math.Clamp(limit, 1, 100);
+        var cursor = ObservationCursor.Decode(cursorToken);
+
+        var query = _db.Observations
+            .AsNoTracking()
+            .Where(o => o.EncounterId == encounterId);
+
+        if (!string.IsNullOrEmpty(code))
+            query = query.Where(o => o.ObservationCode == code);
+
+        if (from.HasValue)
+            query = query.Where(o => o.RecordedAt >= from.Value);
+
+        if (to.HasValue)
+            query = query.Where(o => o.RecordedAt <= to.Value);
+
+        if (cursor is not null)
+        {
+            // Keyset condition for ORDER BY recorded_at DESC, id DESC:
+            // next page starts just below the cursor position
+            var cursorTime = cursor.RecordedAt;
+            var cursorId = cursor.Id;
+            query = query.Where(o =>
+                o.RecordedAt < cursorTime ||
+                (o.RecordedAt == cursorTime && o.Id.CompareTo(cursorId) < 0));
+        }
+
+        var items = await query
+            .OrderByDescending(o => o.RecordedAt)
+            .ThenByDescending(o => o.Id)
+            .Take(limit + 1)   // fetch one extra to know if there is a next page
+            .ToListAsync();
+
+        var hasMore = items.Count > limit;
+        if (hasMore) items.RemoveAt(limit);
+
+        var nextCursor = hasMore
+            ? new ObservationCursor(items[^1].RecordedAt, items[^1].Id).Encode()
+            : null;
+
+        return new CursorPage<Observation>(items, nextCursor, hasMore);
+    }
+}
@@ -0,0 +1,215 @@
+using System.Text.Json;
+using Microsoft.EntityFrameworkCore;
+using StackExchange.Redis;
+
+public class ObservationService : IObservationService
+{
+    private readonly AppDbContext _db;
+    private readonly IConnectionMultiplexer _redis;
+    private readonly ILogger<ObservationService> _logger;
+
+    public ObservationService(
+        AppDbContext db,
+        IConnectionMultiplexer redis,
+        ILogger<ObservationService> logger)
+    {
+        _db = db;
+        _redis = redis;
+        _logger = logger;
+    }
+
+    public async Task<IngestResult> IngestAsync(Guid encounterId, IngestObservationRequest req)
+    {
+        // Step 1 — encounter must be active
+        var encounter = await _db.Encounters
+            .AsNoTracking()
+            .FirstOrDefaultAsync(e => e.Id == encounterId);
+
+        if (encounter is null)
+            throw new NotFoundException("Encounter not found.", "ENCOUNTER_NOT_FOUND");
+
+        if (encounter.Status != EncounterStatus.Active)
+            throw new ConflictException(
+                $"Cannot record observations for an encounter with status '{encounter.Status}'.",
+                "ENCOUNTER_NOT_ACTIVE");
+
+        // Step 2 — idempotency check before entering the transaction
+        // The unique partial index is the database safety net for concurrent retries.
+        // The pre-check here avoids the exception-and-rollback path for the common retry case.
+        if (!string.IsNullOrEmpty(req.IdempotencyKey))
+        {
+            var existing = await _db.Observations
+                .AsNoTracking()
+                .FirstOrDefaultAsync(o => o.IdempotencyKey == req.IdempotencyKey);
+
+            if (existing is not null)
+            {
+                _logger.LogInformation(
+                    "Duplicate idempotency key {Key} for encounter {EncounterId} — returning original",
+                    req.IdempotencyKey, encounterId);
+                return IngestResult.Duplicate(existing);
+            }
+        }
+
+        // Step 3 — plausibility check
+        if (!PlausibilityValidator.IsPlausible(req.ObservationCode, req.Value, out var reason))
+            throw new ValidationException(reason!, "OBSERVATION_OUT_OF_PLAUSIBLE_RANGE");
+
+        // Steps 4–8 are one atomic transaction
+        await using var tx = await _db.Database.BeginTransactionAsync();
+        try
+        {
+            // Step 4 — insert observation
+            var observation = new Observation
+            {
+                Id = Guid.NewGuid(),
+                EncounterId = encounterId,
+                ObservationCode = req.ObservationCode,
+                Value = req.Value,
+                Unit = req.Unit,
+                Source = req.Source,
+                IdempotencyKey = req.IdempotencyKey,
+                RecordedAt = req.RecordedAt,
+                CreatedAt = DateTimeOffset.UtcNow
+            };
+            _db.Observations.Add(observation);
+
+            // Step 5 — load threshold from Redis; fall back to PostgreSQL on miss
+            var threshold = await LoadThresholdAsync(req.ObservationCode);
+
+            if (threshold is null)
+                throw new ValidationException(
+                    $"No alert threshold is configured for observation code '{req.ObservationCode}'. " +
+                    "Register a threshold before recording observations for this code.",
+                    "UNKNOWN_OBSERVATION_CODE");
+
+            ClinicalAlert? alert = null;
+
+            // Step 6 — critical threshold detection (synchronous)
+            // WARNING detection is intentionally deferred to the Kafka consumer.
+            // A critical potassium of 2.1 mEq/L is immediately life-threatening — the alert
+            // must exist before this API call returns. A warning heart rate of 95 bpm warrants
+            // attention but not an emergency page; the additional Kafka latency is clinically safe.
+            if (IsCriticalBreach(req.Value, threshold))
+            {
+                alert = new ClinicalAlert
+                {
+                    Id = Guid.NewGuid(),
+                    EncounterId = encounterId,
+                    PatientId = encounter.PatientId,
+                    ObservationId = observation.Id,
+                    AlertType = AlertTypeExtensions.CriticalFor(req.ObservationCode),
+                    Severity = AlertSeverity.Critical,
+                    Details = BuildCriticalDetails(req, threshold),
+                    Status = AlertStatus.Open,
+                    TriggeredAt = DateTimeOffset.UtcNow
+                };
+                _db.ClinicalAlerts.Add(alert);
+
+                // Step 6b — outbox event for the alert (relay picks this up in Phase 3)
+                _db.OutboxEvents.Add(BuildOutboxEvent("alert.generated", new
+                {
+                    alertId = alert.Id,
+                    encounterId,
+                    patientId = encounter.PatientId,
+                    alertType = alert.AlertType.ToDbString(),
+                    severity = alert.Severity.ToDbString(),
+                    triggeredAt = alert.TriggeredAt,
+                    partitionKey = encounterId.ToString()
+                }));
+            }
+
+            // Step 7 — outbox event for the observation (always; Kafka consumer handles warnings)
+            _db.OutboxEvents.Add(BuildOutboxEvent("observation.recorded", new
+            {
+                observationId = observation.Id,
+                encounterId,
+                patientId = encounter.PatientId,
+                observationCode = req.ObservationCode,
+                value = req.Value,
+                unit = req.Unit,
+                source = req.Source.ToDbString(),
+                recordedAt = req.RecordedAt,
+                partitionKey = encounterId.ToString()
+            }));
+
+            // Step 8 — COMMIT
+            await _db.SaveChangesAsync();
+            await tx.CommitAsync();
+
+            _logger.LogInformation(
+                "Observation {ObservationId} ingested for encounter {EncounterId}. AlertCreated={AlertCreated}",
+                observation.Id, encounterId, alert is not null);
+
+            return IngestResult.Created(observation, alert);
+        }
+        catch (DbUpdateException ex) when (IsUniqueViolation(ex))
+        {
+            // Race condition: two concurrent retries both passed the pre-check above.
+            // The unique partial index caught it. Roll back and return the existing row.
+            await tx.RollbackAsync();
+            var existing = await _db.Observations
+                .AsNoTracking()
+                .FirstOrDefaultAsync(o => o.IdempotencyKey == req.IdempotencyKey);
+            if (existing is not null)
+                return IngestResult.Duplicate(existing);
+            throw new ConflictException("Concurrent duplicate submission.", "CONCURRENT_DUPLICATE");
+        }
+        catch
+        {
+            await tx.RollbackAsync();
+            throw;
+        }
+    }
+
+    private async Task<ThresholdCacheEntry?> LoadThresholdAsync(string observationCode)
+    {
+        var cache = _redis.GetDatabase();
+        var cacheKey = $"threshold:{observationCode}";
+
+        var cached = await cache.StringGetAsync(cacheKey);
+        if (cached.HasValue)
+            return JsonSerializer.Deserialize<ThresholdCacheEntry>(cached!);
+
+        // Cache miss — read from PostgreSQL and write back
+        var threshold = await _db.AlertThresholds
+            .AsNoTracking()
+            .FirstOrDefaultAsync(t => t.ObservationCode == observationCode);
+
+        if (threshold is null) return null;
+
+        var entry = new ThresholdCacheEntry(
+            threshold.ObservationCode,
+            threshold.CriticalLow,
+            threshold.WarningLow,
+            threshold.WarningHigh,
+            threshold.CriticalHigh);
+
+        await cache.StringSetAsync(cacheKey, JsonSerializer.Serialize(entry));
+
+        _logger.LogDebug("Cache miss for threshold {Code} — loaded from PostgreSQL", observationCode);
+        return entry;
+    }
+
+    private static bool IsCriticalBreach(decimal value, ThresholdCacheEntry t) =>
+        (t.CriticalLow.HasValue && value < t.CriticalLow.Value) ||
+        (t.CriticalHigh.HasValue && value > t.CriticalHigh.Value);
+
+    private static string BuildCriticalDetails(IngestObservationRequest req, ThresholdCacheEntry t)
+    {
+        if (t.CriticalLow.HasValue && req.Value < t.CriticalLow.Value)
+            return $"{req.ObservationCode} value {req.Value} {req.Unit} is below critical low of {t.CriticalLow} {req.Unit}.";
+        return $"{req.ObservationCode} value {req.Value} {req.Unit} is above critical high of {t.CriticalHigh} {req.Unit}.";
+    }
+
+    private static OutboxEvent BuildOutboxEvent(string topic, object payload) => new()
+    {
+        Id = Guid.NewGuid(),
+        Topic = topic,
+        Payload = JsonSerializer.Serialize(payload),
+        CreatedAt = DateTimeOffset.UtcNow
+    };
+
+    private static bool IsUniqueViolation(DbUpdateException ex) =>
+        ex.InnerException is Npgsql.PostgresException pg && pg.SqlState == "23505";
+}
@@ -0,0 +1,35 @@
+public static class PlausibilityValidator
+{
+    // Plausible ranges define the outer boundary of physically possible values.
+    // These are NOT clinical thresholds — they catch device malfunctions and typos.
+    // A heart rate of 300 is clinically impossible; 150 is critical but possible.
+    private static readonly Dictionary<string, (decimal Min, decimal Max)> _ranges = new()
+    {
+        ["HEART_RATE"]       = (1,    300),
+        ["TEMP_C"]           = (20,   50),
+        ["POTASSIUM_MEQ_L"]  = (0.1m, 15),
+        ["SPO2"]             = (50,   100),
+        ["RESP_RATE"]        = (1,    80),
+        ["WBC_K_UL"]         = (0.1m, 500),
+        ["GLUCOSE_MG_DL"]    = (10,   1500),
+    };
+
+    public static bool IsPlausible(string observationCode, decimal value, out string? reason)
+    {
+        if (!_ranges.TryGetValue(observationCode, out var range))
+        {
+            // Unknown codes pass plausibility — threshold lookup will validate the code
+            reason = null;
+            return true;
+        }
+
+        if (value < range.Min || value > range.Max)
+        {
+            reason = $"Value {value} is outside the plausible range [{range.Min}–{range.Max}] for {observationCode}.";
+            return false;
+        }
+
+        reason = null;
+        return true;
+    }
+}