5. Payloads en datacontract

5.1 Configuratiepayload

Het onderstaande JSON-object beschrijft de functionele configuratie die bij een concrete oefening op basis van deze module opgeslagen kan worden. De exacte technische opslag mag base64-gecodeerd zijn, maar functioneel blijft de structuur leidend voor modulevalidatie en vraaggeneratie.

{
  "moduleKey": "OptellenAftrekken_Simple_v1",
  "schemaVersion": "0.9",
  "operationMode": "Both",
  "display": {
    "exerciseName": "Optellen en aftrekken t/m 20",
    "icon": "plus"
  },
  "addition": {
    "enabled": true,
    "number1": {
      "mode": "Range",
      "min": 1,
      "max": 20,
      "exactValues": []
    },
    "number2": {
      "mode": "ExactValues",
      "min": null,
      "max": null,
      "exactValues": [1, 2, 4, 6, 8]
    },
    "result": {
      "min": 2,
      "max": 40
    }
  },
  "subtraction": {
    "enabled": true,
    "number1": {
      "mode": "Range",
      "min": 5,
      "max": 20,
      "exactValues": []
    },
    "number2": {
      "mode": "Range",
      "min": 1,
      "max": 15,
      "exactValues": []
    },
    "result": {
      "min": 0,
      "max": 20
    },
    "avoidNegativeResults": true
  },
  "balance": {
    "additionMinimumPercentage": 40,
    "subtractionMinimumPercentage": 40,
    "fillRemainingRandomly": true
  },
  "questionCount": {
    "default": 15,
    "min": 10,
    "max": 40,
    "systemMax": 100
  },
  "generationRules": {
    "limitOneOperandQuestions": false,
    "maxOneOperandQuestions": 2,
    "limitRoundTensQuestions": false,
    "maxRoundTensQuestions": 4
  },
  "runtimeOptions": {
    "allowMarkAsDunno": false,
    "showAnswerAfterSubmit": false
  }
}

5.1.1 Functionele betekenis

JSON-pad	Betekenis
moduleKey	Technische modulesleutel waarmee de configuratie aan de juiste module-implementatie wordt gekoppeld.
schemaVersion	Versie van het modulespecifieke configuratieschema.
operationMode	Bepaalt of optellen, aftrekken of beide typen sommen gegenereerd mogen worden.
display.exerciseName	Functionele naam van de concrete oefening; deze waarde moet synchroon blijven met de generieke oefeningnaam wanneer beide apart worden vastgelegd.
display.icon	Icoonreferentie van de concrete oefening; deze waarde moet synchroon blijven met de generieke oefeningicoonkeuze wanneer beide apart worden vastgelegd.
addition.enabled	Afgeleide beschikbaarheid van optelvragen op basis van operationMode.
addition.number1	Configuratie voor het eerste getal bij optelsommen.
addition.number2	Configuratie voor het tweede getal bij optelsommen.
addition.result	Uitkomstgrenzen voor optelsommen.
subtraction.enabled	Afgeleide beschikbaarheid van aftrekvragen op basis van operationMode.
subtraction.number1	Configuratie voor het eerste getal bij aftreksommen.
subtraction.number2	Configuratie voor het tweede getal bij aftreksommen.
subtraction.result	Uitkomstgrenzen voor aftreksommen.
subtraction.avoidNegativeResults	Functionele afleiding uit minimale uitkomst; voorkomt het genereren van negatieve aftrekuitkomsten.
balance.additionMinimumPercentage	Minimumaandeel optelvragen bij gemengde oefeningen.
balance.subtractionMinimumPercentage	Minimumaandeel aftrekvragen bij gemengde oefeningen.
balance.fillRemainingRandomly	Bepaalt dat resterende vragen random worden ingevuld binnen alle geldige regels.
questionCount.default	Standaard aantal vragen bij het starten van een run.
questionCount.min	Minimum aantal vragen dat een leerling mag kiezen.
questionCount.max	Maximum aantal vragen dat een leerling mag kiezen.
questionCount.systemMax	Absoluut platformmaximum voor gegenereerde vragen.
generationRules.limitOneOperandQuestions	Beperkt het aantal vragen waarin 1 als operand voorkomt.
generationRules.limitRoundTensQuestions	Beperkt het aantal vragen waarin een heel tiental als operand voorkomt.
runtimeOptions.allowMarkAsDunno	Bepaalt of Geen idee beschikbaar is tijdens oefenen.
runtimeOptions.showAnswerAfterSubmit	Bepaalt of directe feedback zichtbaar wordt na beantwoording.

5.2 Vraag- en antwoordstate

De module moet per gegenereerde vraag voldoende state opslaan om vraagweergave, validatie, feedback, hervatten en live meekijken te ondersteunen. De generieke engine hoeft de betekenis van deze modulespecifieke state niet relationeel uit te splitsen.

{
  "questionId": "run-question-0001",
  "sequenceNumber": 1,
  "operator": "+",
  "operandA": 17,
  "operandB": 9,
  "correctAnswer": 26,
  "submittedAnswer": null,
  "isCorrect": null,
  "isDunno": false,
  "feedbackState": "Input",
  "firstShownAtUtc": null,
  "answeredAtUtc": null
}

JSON-pad	Betekenis
questionId	Modulespecifieke vraagidentificatie binnen de runpayload.
sequenceNumber	Volgnummer van de vraag binnen de run; moet overeenkomen met ExerciseRunProgress.SequenceNumber.
operator	+ of -, gegenereerd binnen de gekozen operation mode.
operandA	Eerste operand van de som.
operandB	Tweede operand van de som.
correctAnswer	Correcte uitkomst zoals door de module berekend.
submittedAnswer	Laatst bevestigde leerlinginvoer.
isCorrect	Modulespecifieke correctheidsuitkomst, uniform doorgezet naar ExerciseRunProgress.IsCorrect.
isDunno	Markering dat de leerling Geen idee heeft gebruikt, uniform doorgezet naar ExerciseRunProgress.IsDunno.
feedbackState	Weergavestate: Input, Correct, Incorrect of Dunno.
firstShownAtUtc	Moment waarop de vraag voor het eerst is getoond; uniform beschikbaar in ExerciseRunProgress.
answeredAtUtc	Moment waarop de vraag server-side is verwerkt; uniform beschikbaar in ExerciseRunProgress.