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, simulated start, and standing orders. Use ordered historySections (code, title, text) for the HPI, medical history, medications, allergies, family/social history, and review of systems. The legacy history field remains the fallback.
• initialInterview optionally defines the graphical office interview. It contains a startNodeId and an acyclic set of dialogue nodes. Each node has stable id, authored patientText, isTerminal, and clinician choices with globally unique IDs and valid nextNodeId references. Every branch must reach a terminal node.
• allowedLocations controls patient movement.
• exams defines selectable examination components and their simulated duration.
• Catalog orders may define displayRoute, displayFrequency, and resultSection. These are presentation defaults, not user-entered dosing instructions.
• orderResponses maps reusable catalog codes to case-specific results, delays, vital-sign changes, and an optional result-section override.
• 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.

Valid result sections are lab, imaging, other_test, and treatment; progress notes, vital snapshots, and the order sheet are generated by the runtime.

Timing, scoring, and prediction

New CCS attempts are timed. realTimeMinutes is the total wall-clock allowance: the runtime reserves its final two minutes for final orders, so a 20-minute case has 18 minutes of active management plus two minutes of case-end orders. Opening dialogs count against this limit and reconnecting does not pause it.

Graphical interview choices are persisted as attempt actions and support reconnect/resume. They consume real deadline time but do not advance simulated time or contribute directly to scoring. Cases without initialInterview remain available in classic CCS and are omitted from CCS Cases 2.

Only the first completed timed attempt for each distinct case contributes to the CCS estimate. Legacy practice attempts remain reviewable but cannot be newly created. 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.