Add question bank mastery paths and gap questions

api/QuestionsApi/Services/QuestionStore.cs

@@ -21,6 +21,10 @@ public class QuestionStore
         _col.Indexes.CreateOne(new CreateIndexModel<Question>(systemIndex));
         var tagsIndex = Builders<Question>.IndexKeys.Ascending(q => q.Tags);
         _col.Indexes.CreateOne(new CreateIndexModel<Question>(tagsIndex));
+        var step3SystemIndex = Builders<Question>.IndexKeys.Ascending(q => q.Step3System)
+            .Ascending(q => q.IsPublished).Ascending(q => q.FlaggedForReviewUtc).Ascending(q => q.Difficulty);
+        _col.Indexes.CreateOne(new CreateIndexModel<Question>(step3SystemIndex,
+            new CreateIndexOptions { Name = "step3_system_visibility_difficulty" }));
     }
 
     public async Task<List<Question>> SearchAsync(QuestionSearchRequest req, bool includeUnpublished)
@@ -55,10 +59,18 @@ public class QuestionStore
 
         var filter = filters.Count == 0 ? builder.Empty : builder.And(filters);
         var limit = Math.Clamp(req.Limit, 1, 80);
-        return await _col.Aggregate()
-            .Match(filter)
-            .Sample(limit)
-            .ToListAsync();
+        if (string.IsNullOrWhiteSpace(req.Step3System))
+            return await _col.Aggregate().Match(filter).Sample(limit).ToListAsync();
+
+        var requested = Step3SystemCatalog.Normalize(req.Step3System)
+            ?? throw new ArgumentException("step3System must be an official Step 3 system");
+        // Include legacy records until the idempotent Step3System backfill has run.
+        var systemFilter = builder.Eq(question => question.Step3System, requested)
+            | builder.Exists(nameof(Question.Step3System), false)
+            | builder.Eq(question => question.Step3System, "");
+        var candidates = await _col.Find(filter & systemFilter).ToListAsync();
+        return candidates.Where(question => Step3SystemCatalog.Normalize(question) == requested)
+            .OrderBy(_ => Random.Shared.Next()).Take(limit).ToList();
     }
 
     public async Task<Question?> GetByIdAsync(string id) =>
@@ -280,6 +292,11 @@ public class QuestionStore
         ChoiceSelectionPercentages = req.ChoiceSelectionPercentages,
         Discipline = req.Discipline.Trim(),
         System = req.System.Trim(),
+        Step3System = Step3SystemCatalog.Derive(new Question
+        {
+            ExternalId = req.ExternalId.Trim(), System = req.System.Trim(),
+            PerformanceCategory = req.PerformanceCategory.Trim(), Discipline = req.Discipline.Trim()
+        }) ?? "",
         PerformanceCategory = RatingCategory.Normalize(req.PerformanceCategory, req.System, req.Discipline),
         Difficulty = req.Difficulty,
         Labs = req.Labs,