step3/docs/CCS_CASE_AUTHORING.md

CCS case authoring

CCS content is imported through POST /api/ccs/admin/import by a SUPER user. The import payload contains reusable order-catalog entries and one or more versioned cases. Published cases require complete embedded references and pass the same validation in dry-run and live imports.

Use content/ccs/dka-emergency-001.json as the canonical example. Set validateOnly to true first, then submit the same payload with false. Updating an existing externalId creates a new immutable revision; active and completed attempts remain attached to the revision they started with.

Case structure

• initialChart defines the opening history, appearance, vitals, location, simulated start, and standing orders.
• allowedLocations controls patient movement.
• exams defines selectable examination components and their simulated duration.
• orderResponses maps reusable catalog codes to case-specific results, delays, and vital-sign changes.
• events defines timed progression. requiresOrderCodes requires every listed order; requiresAnyOrderCodes supports equivalent alternatives.
• scoringCriteria awards or subtracts points for timing, sequence, and harmful care. targetCodes supports clinically equivalent actions; afterTargetCode enforces sequence.
• references stores the source title, publisher, HTTPS URL, supported claims, access date, and reviewer inside each case revision.

Order codes and event/criterion IDs must be stable lowercase identifiers. Case content should not expose the diagnosis in the opening chart or rely on unstructured text matching for scoring. Add aliases to the order catalog so users can find an order using common clinical wording.

Scoring and prediction

Practice attempts are scored for feedback but do not affect prediction. Only the first completed timed attempt for each distinct case contributes to the CCS estimate. The combined provisional prediction uses the latest Day 1 simulation and a separately reported CCS estimate; it is not presented as an official USMLE scoring formula.