Files
step3/api/QuestionsApi/Models/CcsModels.cs
hz 34d283e213 Add rating snapshots, percentile, and exam readiness to the dashboard API
Backend half of the dashboard stat-card redesign. Three new data
points the old DashboardResponse had no way to compute:

- Week-over-week rating deltas: UserRating/CcsUserRating only ever
  stored the current Elo (mutated in place, UpdatedUtc just means
  "last touched"), so there was no way to know what a rating was 7
  days ago. Added UserRatingSnapshot (new collection, unique on
  UserId+DateUtc) and UserRatingSnapshotService, a BackgroundService
  following AnswerStatisticsMaintenanceService's exact shape (a
  PeriodicTimer plus a Mongo lease so replicas behind the HPA don't
  race), writing one snapshot per user per day. No historical
  backfill - deltas are simply null for a user's first ~7 days after
  this ships, which the DTO represents honestly via nullable ints
  rather than a fake "+0".
- Percentile rank: DashboardStore now counts how many users have a
  higher OverallElo/Elo than the current user out of the total.
- Exam Readiness + projected pass rate: reuses the existing, tested
  IRT-based ExamSimulationScore.PassProbability (a real normal-CDF
  estimate of scoring >=200, computed in ExamSimulationScoring.Calculate)
  rather than inventing a new prediction model. DashboardStore pulls
  the latest completed simulation's score directly and maps
  PassProbability to a High/Medium/Low label via tunable thresholds.
- Average Score's "+6% vs last 100" needed no new data source at all -
  just one more slice (Skip(100).Take(100)) over the QuestionAttempts
  already loaded for FirstAttemptAccuracy.

Added DashboardStore.Percentile/ReadinessLabel as pure static helpers
(matching the existing Percentage/CalculateCurrentStreak pattern) and
unit tests for both. Full backend suite: 165 passed, 0 failed.
2026-07-26 00:39:11 -05:00

406 lines
14 KiB
C#

using MongoDB.Bson;
using MongoDB.Bson.Serialization.Attributes;
namespace QuestionsApi.Models;
public static class CcsAttemptStates
{
public const string Active = "active";
public const string FinalOrders = "final_orders";
public const string Completed = "completed";
public const string Abandoned = "abandoned";
}
public static class CcsAttemptModes
{
public const string Practice = "practice";
public const string Timed = "timed";
}
public static class CcsChartCategories
{
public const string Orders = "orders";
public const string Progress = "progress";
public const string Vitals = "vitals";
public const string Lab = "lab";
public const string Imaging = "imaging";
public const string OtherTest = "other_test";
public const string Treatment = "treatment";
public static readonly IReadOnlySet<string> All = new HashSet<string>(StringComparer.OrdinalIgnoreCase)
{
Orders, Progress, Vitals, Lab, Imaging, OtherTest, Treatment
};
public static readonly IReadOnlySet<string> ResultSections = new HashSet<string>(StringComparer.OrdinalIgnoreCase)
{
Lab, Imaging, OtherTest, Treatment
};
}
public class CcsOrderDefinition
{
[BsonId] public string Code { get; set; } = "";
public string CanonicalName { get; set; } = "";
public string Category { get; set; } = "";
public List<string> Aliases { get; set; } = [];
public int DefaultTurnaroundMinutes { get; set; }
public List<string> AvailableLocations { get; set; } = [];
public string DisplayRoute { get; set; } = "";
public string DisplayFrequency { get; set; } = "";
public string ResultSection { get; set; } = "";
public DateTime UpdatedUtc { get; set; } = DateTime.UtcNow;
}
public class CcsCaseRevision
{
[BsonId, BsonRepresentation(BsonType.ObjectId)] public string? Id { get; set; }
public string ExternalId { get; set; } = "";
public int Version { get; set; } = 1;
public bool IsCurrent { get; set; } = true;
public bool IsPublished { get; set; }
public string Title { get; set; } = "";
public string System { get; set; } = "";
public string PresentingLocation { get; set; } = "";
public int RealTimeMinutes { get; set; } = 20;
public int Difficulty { get; set; } = 2;
public List<string> Tags { get; set; } = [];
public CcsInitialChart InitialChart { get; set; } = new();
public List<string> AllowedLocations { get; set; } = [];
public List<CcsExamDefinition> Exams { get; set; } = [];
public List<CcsCaseOrderDefinition> OrderResponses { get; set; } = [];
public List<CcsCaseEvent> Events { get; set; } = [];
public List<CcsScoringCriterion> ScoringCriteria { get; set; } = [];
public List<QuestionReference> References { get; set; } = [];
public DateTime CreatedUtc { get; set; } = DateTime.UtcNow;
}
public class CcsInitialChart
{
public string PatientSummary { get; set; } = "";
public string ReasonForEncounter { get; set; } = "";
public string Appearance { get; set; } = "";
public string History { get; set; } = "";
public List<CcsNarrativeSection> HistorySections { get; set; } = [];
public Dictionary<string, string> Vitals { get; set; } = [];
public DateTime SimulatedStartUtc { get; set; } = DateTime.UtcNow;
public List<string> InitialOrderCodes { get; set; } = [];
}
public class CcsNarrativeSection
{
public string Code { get; set; } = "";
public string Title { get; set; } = "";
public string Text { get; set; } = "";
}
public class CcsExamDefinition
{
public string Code { get; set; } = "";
public string Name { get; set; } = "";
public int DurationMinutes { get; set; } = 1;
public string Finding { get; set; } = "";
}
public class CcsCaseOrderDefinition
{
public string OrderCode { get; set; } = "";
public int? TurnaroundMinutes { get; set; }
public string Result { get; set; } = "";
public string ResultSection { get; set; } = "";
public Dictionary<string, string> VitalPatches { get; set; } = [];
}
public class CcsCaseEvent
{
public string Id { get; set; } = "";
public int TriggerMinute { get; set; }
public List<string> RequiresOrderCodes { get; set; } = [];
public List<string> RequiresAnyOrderCodes { get; set; } = [];
public string Message { get; set; } = "";
public Dictionary<string, string> VitalPatches { get; set; } = [];
public bool EndCase { get; set; }
}
public class CcsScoringCriterion
{
public string Id { get; set; } = "";
public string Title { get; set; } = "";
public string ActionType { get; set; } = "order";
public string TargetCode { get; set; } = "";
public List<string> TargetCodes { get; set; } = [];
public int Points { get; set; }
public int? EarliestMinute { get; set; }
public int? LatestMinute { get; set; }
public string AfterTargetCode { get; set; } = "";
public string Rationale { get; set; } = "";
}
public class CcsAttempt
{
[BsonId, BsonRepresentation(BsonType.ObjectId)] public string? Id { get; set; }
public string UserId { get; set; } = "";
[BsonIgnoreIfNull] public string? ActiveSlot { get; set; }
public string CaseExternalId { get; set; } = "";
[BsonRepresentation(BsonType.ObjectId)] public string CaseRevisionId { get; set; } = "";
public int CaseVersion { get; set; }
public string Mode { get; set; } = CcsAttemptModes.Timed;
public string State { get; set; } = CcsAttemptStates.Active;
public int Revision { get; set; }
public int SimulatedMinute { get; set; }
[BsonIgnoreIfNull] public bool? OpeningCompleted { get; set; }
public string Location { get; set; } = "";
public Dictionary<string, string> CurrentVitals { get; set; } = [];
public List<CcsAttemptAction> Actions { get; set; } = [];
public List<CcsPendingResult> PendingResults { get; set; } = [];
public List<CcsChartEntry> Chart { get; set; } = [];
public List<CcsVitalSnapshot> VitalHistory { get; set; } = [];
public List<string> ActiveOrderCodes { get; set; } = [];
public List<string> ProcessedEventIds { get; set; } = [];
public List<string> ProcessedCommandIds { get; set; } = [];
public DateTime? DeadlineUtc { get; set; }
public DateTime? HardDeadlineUtc { get; set; }
public DateTime? FinalOrdersDeadlineUtc { get; set; }
public DateTime CreatedUtc { get; set; } = DateTime.UtcNow;
public DateTime UpdatedUtc { get; set; } = DateTime.UtcNow;
public DateTime? CompletedUtc { get; set; }
public CcsCaseScore? Score { get; set; }
public bool RatingEligible { get; set; }
public CcsRatingChange? Rating { get; set; }
}
public class CcsAttemptAction
{
public string Type { get; set; } = "";
public string Code { get; set; } = "";
public int SimulatedMinute { get; set; }
public DateTime RealUtc { get; set; } = DateTime.UtcNow;
}
public class CcsPendingResult
{
public string OrderCode { get; set; } = "";
public string Category { get; set; } = "";
public string Title { get; set; } = "";
public int DueMinute { get; set; }
public string Result { get; set; } = "";
public Dictionary<string, string> VitalPatches { get; set; } = [];
}
public class CcsChartEntry
{
public string Category { get; set; } = "progress";
public int SimulatedMinute { get; set; }
public string Code { get; set; } = "";
public string Title { get; set; } = "";
public string Text { get; set; } = "";
}
public class CcsVitalSnapshot
{
public int SimulatedMinute { get; set; }
public Dictionary<string, string> Values { get; set; } = [];
}
public class CcsActiveOrder
{
public string Code { get; set; } = "";
public string Name { get; set; } = "";
public string Category { get; set; } = "";
public string Route { get; set; } = "";
public string Frequency { get; set; } = "";
public int OrderedMinute { get; set; }
public int? ReportMinute { get; set; }
public bool IsPending { get; set; }
public bool HasResult { get; set; }
}
public class CcsCaseScore
{
public double Percent { get; set; }
public int EarnedPoints { get; set; }
public int PossiblePoints { get; set; }
public List<CcsCriterionResult> Criteria { get; set; } = [];
}
public class CcsCriterionResult
{
public string CriterionId { get; set; } = "";
public string Title { get; set; } = "";
public string ActionType { get; set; } = "";
public string ExpectedAction { get; set; } = "";
public string ObservedAction { get; set; } = "";
public int? ObservedMinute { get; set; }
public string Status { get; set; } = "missed";
public int Points { get; set; }
public string Rationale { get; set; } = "";
}
public class CcsImportRequest
{
public List<CcsOrderDefinition> Orders { get; set; } = [];
public List<CcsCaseRevision> Cases { get; set; } = [];
public bool ValidateOnly { get; set; }
}
public class CcsImportResponse
{
public int OrdersUpserted { get; set; }
public int CasesCreated { get; set; }
public List<string> Errors { get; set; } = [];
}
public class CreateCcsAttemptRequest
{
public string CaseExternalId { get; set; } = "";
public string Mode { get; set; } = CcsAttemptModes.Timed;
}
public class CcsCommandRequest
{
public string CommandId { get; set; } = "";
public int ExpectedRevision { get; set; }
public string Type { get; set; } = "";
public string Code { get; set; } = "";
public int Minutes { get; set; }
}
public class CcsBatchCommandRequest
{
public string CommandId { get; set; } = "";
public int ExpectedRevision { get; set; }
public List<CcsBatchCommandItem> Commands { get; set; } = [];
}
public class CcsBatchCommandItem
{
public string Type { get; set; } = "";
public string Code { get; set; } = "";
public int Minutes { get; set; }
}
public class CcsCaseSummary
{
public string ExternalId { get; set; } = "";
public string Title { get; set; } = "";
public string System { get; set; } = "";
public string PresentingLocation { get; set; } = "";
public int RealTimeMinutes { get; set; }
public int Difficulty { get; set; }
public List<string> Tags { get; set; } = [];
}
public class CcsAttemptResponse
{
public string Id { get; set; } = "";
public string CaseExternalId { get; set; } = "";
public string CaseTitle { get; set; } = "";
public string Mode { get; set; } = "";
public string State { get; set; } = "";
public int Revision { get; set; }
public int SimulatedMinute { get; set; }
public DateTime SimulatedStartUtc { get; set; }
public bool OpeningCompleted { get; set; }
public string Location { get; set; } = "";
public DateTime? DeadlineUtc { get; set; }
public DateTime? HardDeadlineUtc { get; set; }
public DateTime? FinalOrdersDeadlineUtc { get; set; }
public DateTime CreatedUtc { get; set; }
public int RealTimeMinutes { get; set; }
public int ElapsedSeconds { get; set; }
public string PatientSummary { get; set; } = "";
public string ReasonForEncounter { get; set; } = "";
public string Appearance { get; set; } = "";
public string History { get; set; } = "";
public List<CcsNarrativeSection> HistorySections { get; set; } = [];
public Dictionary<string, string> Vitals { get; set; } = [];
public List<CcsChartEntry> Chart { get; set; } = [];
public List<string> ActiveOrderCodes { get; set; } = [];
public List<CcsActiveOrder> ActiveOrders { get; set; } = [];
public List<CcsVitalSnapshot> VitalHistory { get; set; } = [];
public List<CcsPendingResult> PendingResults { get; set; } = [];
public List<CcsExamDefinition> AvailableExams { get; set; } = [];
public List<string> AllowedLocations { get; set; } = [];
public CcsCaseScore? Score { get; set; }
public CcsRatingChange? Rating { get; set; }
public List<QuestionReference> References { get; set; } = [];
}
public class CcsHistoryItem
{
public string Id { get; set; } = "";
public string CaseExternalId { get; set; } = "";
public string CaseTitle { get; set; } = "";
public string Mode { get; set; } = "";
public string State { get; set; } = "";
public double? Score { get; set; }
public CcsRatingChange? Rating { get; set; }
public DateTime CreatedUtc { get; set; }
}
public class CcsHistoryPage
{
public List<CcsHistoryItem> Items { get; set; } = [];
public string? NextCursor { get; set; }
}
public class CcsUserRating
{
[BsonId, BsonRepresentation(BsonType.ObjectId)] public string? Id { get; set; }
public string UserId { get; set; } = "";
public int Elo { get; set; } = 1000;
public int RatedCaseCount { get; set; }
public int? HistoryBaselineElo { get; set; }
public DateTime? HistoryStartedUtc { get; set; }
public DateTime UpdatedUtc { get; set; } = DateTime.UtcNow;
}
public class CcsCaseRating
{
[BsonId, BsonRepresentation(BsonType.ObjectId)] public string? Id { get; set; }
public string CaseExternalId { get; set; } = "";
public int Elo { get; set; } = 1000;
public int RatedAttemptCount { get; set; }
public DateTime UpdatedUtc { get; set; } = DateTime.UtcNow;
}
public class CcsRatedCaseResult
{
[BsonId, BsonRepresentation(BsonType.ObjectId)] public string? Id { get; set; }
public string UserId { get; set; } = "";
public string CaseExternalId { get; set; } = "";
[BsonRepresentation(BsonType.ObjectId)] public string AttemptId { get; set; } = "";
public DateTime CreatedUtc { get; set; } = DateTime.UtcNow;
}
public class CcsRatingChange
{
public bool Rated { get; set; }
public string Reason { get; set; } = "";
public int UserEloBefore { get; set; }
public int UserElo { get; set; }
public int UserEloDelta { get; set; }
public int CaseEloBefore { get; set; }
public int CaseElo { get; set; }
public int CaseEloDelta { get; set; }
public double ActualScore { get; set; }
public DateTime? AppliedUtc { get; set; }
}
public class CcsRatingProfileResponse
{
public int Elo { get; set; } = 1000;
public int RatedCaseCount { get; set; }
}
public class CcsPredictionResponse
{
public double? CcsScore { get; set; }
public int ContributingCases { get; set; }
public int? McqPredictedScore { get; set; }
public int? CombinedPredictedScore { get; set; }
public int? RangeLow { get; set; }
public int? RangeHigh { get; set; }
public string ModelVersion { get; set; } = "combined-ccs-1";
public bool IsProvisional { get; set; } = true;
}