# Stage 2: Questions and Assessment ## Goal Allow an author to add well-designed, controllable questions to a converted PowerPoint course. Questions may appear as separate course steps or as popups over slides. SCORM 1.2 records answers, scores, progress, completion, and pass or fail status. This stage extends the existing PowerPoint-to-SCORM workflow without changing slide rendering. ## Authoring flow 1. Upload and process the PowerPoint presentation. 2. Configure the slide player. 3. Open the separate Questions category. 4. Add questions after selected slides or at the end. 5. Configure presentation, learner behavior, feedback, scoring, and completion. 6. Preview questions as slides or popups. 7. Generate the SCORM 1.2 package. ## Initial question types - Single choice with exactly one correct answer. - Multiple choice with one or more correct answers. - True or False. Every question supports question text, an optional description, answer options, correct-answer selection, points, required or optional status, feedback, an optional explanation, and placement after a selected slide or at the end. Questions are responsive HTML rather than images. This enables accessible controls, keyboard operation, validation, feedback animations, and accurate SCORM tracking. ## Presentation modes A global default controls question presentation. Each question can override it without rebuilding the question. ### Separate question slide - Display the question as a responsive course step. - Show Previous and Next controls. - Lock Next until a required answer is submitted. - Optionally show question number, points, and quiz progress. - Show a question icon in navigation instead of a slide thumbnail. - Allow Previous according to course navigation rules. This mode is recommended for important assessments and final quizzes. ### Popup question - Display a modal over the associated PowerPoint slide. - Dim the background while keeping the slide visible. - Support Small, Medium, and Large sizes. - Lock navigation while a required popup is unanswered. - Allow Skip or Close only for optional questions when configured. - Trap keyboard focus inside the popup. - Prevent Escape and backdrop dismissal for required unanswered questions. - Reopen an unanswered required popup after course resume. The recommended trigger is pressing Next after the associated slide. If the slide has a viewing timer, the popup opens only after that timer finishes. This mode is recommended for short knowledge checks. ## Dedicated Questions settings category Question controls remain separate from slide display, navigation, timers, and slide animations. Essential controls appear first; uncommon controls remain under collapsed **More options**. ### Question presentation - Default display: Question slide or Popup. - Popup size: Small, Medium, or Large. - Show or hide question numbers. - Show or hide points. - Show or hide quiz progress. - Question entrance animation. ### Learner behavior - Require an answer before continuing. - Allow skipping optional questions. - Allow or prevent answer changes after submission. - One whole-assessment attempt, unlimited whole-assessment attempts, or a configured maximum of 1-10. - Shuffle questions only within their placement group and only when enabled. - Shuffle answer options. - Allow review of submitted answers. ### Feedback - Show feedback immediately after submission. - Show feedback only after the complete quiz. - Show or hide correct answers. - Show or hide explanations. - Custom correct and incorrect messages. ### Scoring and completion - Passing score percentage. - Require all required questions to be answered. - Include or exclude optional questions from scoring. - Complete using slides only or slides plus required questions. - Report Completed, Passed, or Failed according to the selected rule. ## Per-question editor The editor uses a short sequence: 1. Choose placement. 2. Choose question type. 3. Enter the question and answers. 4. Mark the correct answer or answers. 5. Configure points and feedback. 6. Optionally override presentation and behavior defaults. Per-question options include presentation mode, popup size, required status, points, optional Skip behavior, and feedback. Attempts are never configured per question. Show a compact summary such as: > 8 questions - 20 total points - 70% passing score - 6 required ## Preview - Preview the current question as a slide or popup. - Demonstrate validation, feedback, attempts, and navigation locking. - Preview question and quiz progress without an LMS. - Inherit the player color and DocuDeck design language. - Maintain accessible contrast, labels, focus states, and keyboard support. ### Full SCORM preview before generation Before creating the ZIP, the author can open a full-screen learner preview using the current saved or unsaved settings. This preview runs the complete course sequence rather than only the selected question. It includes: - Actual converted slide images and configured slide transitions. - Vertical or horizontal scrollable navigation, including drag mode. - Display, progress, title, color, fullscreen, timer, and sequential-navigation settings. - Separate question steps and popup questions in their final placement. - Required-question locks, optional skipping, answer changes, and immediate or final feedback. - Final review, simulated Final Submit, scoring, Passed or Failed results, and allowed retries. - Reduced-motion behavior without writing anything to an LMS or generating a SCORM ZIP. ## Progress, scoring, and completion Slide progress and question progress remain separate: - Slide progress measures unique required slides viewed. - Question progress measures required questions answered. - Score measures earned points against available points. - Completion uses the configured slides-and-questions rule. - Pass or fail uses the configured passing percentage. Recommended default: > The learner must view all required slides and answer all required questions. The final score then determines Passed or Failed. Reaching a later slide must never complete an unanswered required question. ## Finalized attempt model - An attempt covers the complete assessment, not an individual question. - Learners may change answers until Final Submit when answer changes are enabled. - Final Submit is disabled until every required question is answered and always requires confirmation. - Final Submit records score and one `cmi.interactions` row per question for that attempt, then immediately reports `passed`, `failed`, or `completed` according to the assessment settings. - Starting an allowed retry clears current answers, increments the assessment attempt, reshuffles enabled placement groups and answer options deterministically, and changes status back to `incomplete`. - Previous attempt interaction records remain in the LMS. A later successful retry may change a prior `failed` status to `passed`. ## Persistence and API Stage 2 stores quiz settings, questions, and options in normalized conversion-scoped tables. Questions and options use UUID database IDs plus stable numeric tracking keys that are not reused after deletion. Deleting a conversion cascades to its quiz, questions, and options. Token-protected endpoints: - `GET /api/v1/powerpoint-to-scorm/conversions/{id}/quiz` - `PUT /api/v1/powerpoint-to-scorm/conversions/{id}/quiz` The PUT operation saves the complete quiz document in one transaction using a revision number. It assigns IDs and stable keys to new records, removes omitted records, increments the revision, returns `409` for stale revisions, and changes a completed conversion to `ready` so the SCORM package must be regenerated. ## SCORM 1.2 tracking The package should: - Save earned score in `cmi.core.score.raw`. - Save the range in `cmi.core.score.min` and `cmi.core.score.max`. - Keep `cmi.core.lesson_status` as `incomplete` until explicit Final Submit. - Set the final status to `passed` or `failed` after required work is scored. - Record supported question interactions through `cmi.interactions`. - Record stable question ID, type, learner response, result, time, and latency when available. - Store answers, attempts, and unfinished state compactly in `cmi.suspend_data`. - Restore unfinished answers and attempts after reopening. - Commit after submissions, navigation, completion, and course exit. Question IDs must remain stable when regenerating a package. ## Validation rules - Every question requires question text. - Single choice requires at least two answers and exactly one correct answer. - Multiple choice requires at least two answers and one or more correct answers. - True or False exposes exactly those two values with one correct value. - Points must be a valid non-negative number. - A limited maximum-attempt value must be a positive integer. - A popup must reference a valid slide unless placed at the end. - A required question cannot expose Skip or unrestricted Close. - Passing score must be between 0 and 100 percent. ## Acceptance criteria - Authors can add, edit, reorder, duplicate, and delete supported questions. - Questions can be placed after any slide or at the end. - Global presentation mode can be overridden per question. - Slide and popup modes share answers, scoring, feedback, and tracking. - Required questions block forward progress until submission requirements are met. - Required popups cannot be accidentally dismissed. - Preview accurately demonstrates both modes. - Scores and responses persist after closing and reopening. - SCORM status follows the configured completion and passing rules. - The package works with the Moodle-first SCORM 1.2 target. ## Deferred features - Essay and manually graded questions. - Matching, ordering, drag-and-drop, and short-answer questions. - Question banks and random pools. - Automatic question extraction from PowerPoint. - External quiz-format imports. - Branching scenarios and adaptive navigation. - Weighted groups and advanced grading. - SCORM 2004-specific behavior.