hz/step3

Files

T

hz 1860e6ede6 Add an RZ Coin slot machine

Adds a spend-coins-for-a-random-reward mini-game reachable from the
shop. Backend mirrors the store's existing atomic/idempotent purchase
pattern (SpinAsync in CreditStore.cs) with a server-authoritative,
weighted reward roll and a rolling per-user spin-rate guard; odds are
served from GET /api/credits/spin-config so the client never hardcodes
numbers that could drift from the real payout table. The mockup's
"Streak Protector" reward was swapped for a real Exam Simulation Token
since streaks aren't currently a persisted, protectable concept.

Also fixes two latent bugs surfaced while building this:
- credits_service.gd's operation-id builder referenced a nonexistent
  AuthState.user_id (should be .username), throwing on every credit
  action.
- _post() silently no-op'd with no signal when signed out, which
  combined with a GDScript closure gotcha (lambdas capture outer
  locals by value, so reassigning inside one never reached the
  caller) meant a spin attempted while unauthenticated could hang
  forever instead of surfacing an error.

2026-07-30 00:29:49 -05:00

Controllers

Add an RZ Coin slot machine

2026-07-30 00:29:49 -05:00

k8s

Add isolated UAT and production environments

2026-07-20 20:32:22 -05:00

load

Scale unique answer tracking

2026-07-13 02:11:54 -05:00

Models

Add an RZ Coin slot machine

2026-07-30 00:29:49 -05:00

Services

Add an RZ Coin slot machine

2026-07-30 00:29:49 -05:00

appsettings.Development.json

Merge authentication into Questions API

2026-07-20 17:21:15 -05:00

appsettings.json

Merge authentication into Questions API

2026-07-20 17:21:15 -05:00

Dockerfile

Publish dynamic questions during UAT deploy

2026-07-23 13:30:22 -05:00

Program.cs

Add Rz Coin utility store

2026-07-29 18:34:54 -05:00

QuestionsApi.csproj

Add flashcards feature with spaced repetition scheduling

2026-07-21 15:08:52 -05:00

README.md

Implement persistent review queue

2026-07-19 12:51:24 -05:00

README.md

QuestionsApi

STEP-style question bank service for study games and clients.

Endpoints

GET /healthz Health check.
GET /api/questions/systems List available systems.
POST /api/questions/search Search or build a block of questions.
GET /api/questions/admin/export Cursor-paginated full-bank export (SUPER only).
GET /api/questions/{id} Get one question.
POST /api/questions Create question (SUPER only).
POST /api/questions/bulk Upsert questions by externalId (SUPER only).
POST /api/questions/admin/references/bulk Update only embedded verification references by externalId (SUPER only).
PUT /api/questions/{id} Update question (SUPER only).
DELETE /api/questions/{id} Delete question (SUPER only).
POST /api/question-reports Submit a categorized question report (USER or SUPER).
GET /api/question-reports List and filter reports, newest first (SUPER only).
GET /api/question-reports/{id} Get a report and its question snapshot (SUPER only).
PATCH /api/question-reports/{id}/status Resolve or dismiss an open report (SUPER only).
POST /api/app-feedback Submit general feedback with safe client context (USER or SUPER).
GET /api/app-feedback List and filter app feedback, newest first (SUPER only).
GET /api/app-feedback/{id} Get one app feedback report (SUPER only).
PATCH /api/app-feedback/{id}/status Resolve or dismiss app feedback (SUPER only).
POST /api/review-queue/next Get one random pending review question, excluding IDs already shown in the current pass.
POST /api/review-queue/attempts Idempotently record the first answer for a review cycle.

Player reads require USER or SUPER JWT auth. Authoring endpoints require SUPER.

Answer tracking

The QuestionAttempts collection is the immutable source of truth and enforces one first attempt per question and user with a unique compound index. Updated clients submit the five choice IDs that were presented. Choice rates are the percentage of presentations that resulted in selection, served from 32-way materialized counter buckets and cached for up to five minutes. These rates are independent and are not expected to sum to 100% when users see different distractor subsets.

Submitted incorrect first attempts are materialized in ReviewQueueItems. Skips are excluded. Review attempts are stored separately, do not affect Elo or first-attempt statistics, and clear an item only when the first answer in a review cycle is correct. Per-user incremental backfill checkpoints populate the queue from historical first attempts without requiring a manual migration.

A background service snapshots the original choice IDs, backfills historical attempts into v2 exposure counters, and reconciles recently active questions every five minutes. The metric step3_answer_statistics_v2_backfill_complete must equal 1 before adding extra distractors to existing questions.

Search clients that set supportsChoicePools: true receive each complete choice pool. Older clients receive five server-selected choices that always include the correct answer. Published questions require 5-20 unique choices, an explanation for every choice, a follow-up for every incorrect choice, and at least one embedded authoritative verification reference. Legacy published questions without references remain readable but must add references before a future authoring update.

GET /readyz verifies MongoDB connectivity for readiness checks.
GET /metrics exposes Prometheus-format service and reconciliation metrics.

The manifests in k8s/ configure 2-10 API replicas. The cluster must have Kubernetes Metrics Server installed before applying them with kubectl apply -k k8s/.

Questions submitted through authoring endpoints must have authoritative direct reference links recorded as described in the repository's Question Verification References policy. The references must verify the keyed answer and the material claims in the explanation; search-result links are not acceptable.