sm-quizzes-plugin/README.md

# golem15.quizzes

A reusable quiz plugin for SummerCMS applications: quizzes with single-choice, multiple-choice and self-check (flashcard) questions, scored attempts for signed-in users, an admin backend and a JSON importer.

```go
import _ "git.golem15.com/golem15/sm-quizzes-plugin"
```

Module `git.golem15.com/golem15/sm-quizzes-plugin`, package `quizzes`, plugin ID `golem15.quizzes`.

## Overview

The plugin is a compiled SummerCMS plugin. Its `init` registers it with the framework, so an application loads it by listing it in `summer.yaml`; `summer build` then emits the blank import above into the application's `plugins.gen.go`. It requires `golem15.user`: the API runs behind that plugin's `jwt.auth` middleware, and attempts reference its `users` table.

The plugin knows nothing about the application around it. A quiz links to a record of another plugin through an optional free-form `context` string, such as `acme.courses:course:12`; clients list the quizzes of a context with `GET /quizzes?context=...`.

It owns five tables:

| Table | Holds |
|-------|-------|
| `golem15_quizzes_quizzes` | Quizzes: title, unique slug, description, context, published flag, time limit, passing score, question shuffling and round size. |
| `golem15_quizzes_questions` | Questions of a quiz: text, type, category, model answer, explanation, sort order and points. |
| `golem15_quizzes_answers` | Answers of a single or multiple question, with `is_correct` and an explanation. |
| `golem15_quizzes_attempts` | One user's run through a quiz, or through one category of it, with the score once finished. |
| `golem15_quizzes_attempt_answers` | The user's answer to one question of an attempt; one row per attempt and question. |

Deleting a quiz deletes its questions, answers and attempts. Deleting a question deletes its answers and the attempt answers given to it. Deleting a user deletes their attempts.

## Features

- **Three question types.** `single` (one correct answer), `multiple` (one or more correct answers) and `self_check`, a flashcard: the client shows the question, the user reveals `answer_text` and marks themselves as knowing it or not.
- **Categories.** A question may carry a category. `GET /quizzes/{slug}?category=` returns one category, and an attempt can be limited to one category.
- **Rounds and shuffling.** `round_size` tells the client to present the questions in rounds of N; `shuffle_questions` shuffles the question order on every `GET /quizzes/{slug}`.
- **Attempts.** A user starts an attempt, answers questions in any order (answering again overwrites the earlier answer and returns fresh feedback) and finishes it. Answers are refused after the time limit; finishing is still allowed and counts the answers given in time.
- **Scoring.** A pure function in `classes` (`classes.Score`, `classes.Totals`) with optional partial credit for multiple questions and an optional penalty for wrong answers. See [Configuration](#configuration).
- **No solution leaks.** The quiz payload never contains `is_correct` or explanations, and `answer_text` only for `self_check` flashcards, which have nothing to hide. Feedback reveals the solution of the question just answered; a result reveals the solutions of answered questions, and of every question once the attempt is finished.
- **Admin backend.** Quizzes, Questions (filtered by quiz, category and type) and Answers (filtered by quiz) under the `golem15.quizzes.access_quizzes` permission, and a read-only Attempts list under `golem15.quizzes.access_attempts`. Polish and English labels.
- **Importer.** `quizzes:import` loads a quiz from a JSON file, idempotent by slug. See [CLI commands](#cli-commands).

## Usage

Mount the plugin in an application as a git submodule at `plugins/golem15/quizzes`, next to `plugins/golem15/user`, add it to the application's `go.work`, require it in the application's `go.mod` with a local replace, and list it in `summer.yaml` after `golem15.user`:

```yaml
plugins:
  - id: golem15.user
    module: git.golem15.com/golem15/sm-user-plugin
  - id: golem15.quizzes
    module: git.golem15.com/golem15/sm-quizzes-plugin
```

The plugin's own `go.mod` replaces the framework with `../../../../summercms.go` and `golem15.user` with `../user`, so it expects the framework checkout next to the application checkout.

Run `migrate` after `summer build` to create the tables, then import a quiz and publish it in the admin (or set `"is_published": true` in the file).

## API reference

All routes are mounted under `/_quizzes/api/v1` with the `jwt.auth` middleware of `golem15.user`: send `Authorization: Bearer <token>`. A missing or invalid token is a 401 from the guard. Every successful body wraps its payload in `data`. Timestamps are UTC in the form `2026-10-02T12:00:00+00:00`.

| Method and path | Handler | Does |
|-----------------|---------|------|
| `GET /quizzes` | `api.Handlers.ListQuizzes` | Published quizzes, by title, with the caller's statistics. Query: `context`. |
| `GET /quizzes/{slug}` | `api.Handlers.ShowQuiz` | A published quiz with its questions and answers, without solutions (a `self_check` question carries its `answer_text`). Query: `category`. |
| `POST /quizzes/{slug}/attempts` | `api.Handlers.StartAttempt` | Starts an attempt. Body (optional): `{"category": "..."}`. |
| `POST /attempts/{id}/answers` | `api.Handlers.Answer` | Saves or overwrites the answer to one question and returns feedback. |
| `POST /attempts/{id}/finish` | `api.Handlers.Finish` | Finishes the attempt and returns the result. |
| `GET /attempts/{id}` | `api.Handlers.ShowAttempt` | The result with per-question details. |
| `GET /attempts` | `api.Handlers.ListAttempts` | The caller's attempts, newest first. Query: `quiz` (slug), `page`, `per_page` (default 20, at most 100). |

`{slug}` matches `[a-z0-9-]+` and `{id}` matches `[0-9]+`; anything else is a 404.

### Errors

| Status | Body | When |
|--------|------|------|
| 401 | `{"error": true, "message": "Token not provided"}` | No or invalid token (from the guard). |
| 404 | `{"error": "Quiz not found"}` | Unknown or unpublished slug. |
| 404 | `{"error": "Attempt not found"}` | Unknown attempt, or another user's attempt. |
| 409 | `{"error": "The attempt is already completed."}` | Answering or finishing a finished attempt. |
| 409 | `{"error": "The time limit of this attempt has been exceeded."}` | Answering after `started_at + time_limit_seconds`. |
| 413 | `{"error": "Payload too large"}` | A body over the route's limit. |
| 422 | `{"error": "<first message>", "errors": {"<field>": ["<message>"]}}` | Invalid input, the shape `golem15.user` uses. Keys follow the rule order. |

The messages are translated into the request locale (`golem15.quizzes::lang.api.*`, Polish and English).

### GET /quizzes

```json
{"data": [{
  "id": 1,
  "slug": "security-basics",
  "title": "Security basics",
  "description": "Flashcards and checks.",
  "context": "acme.courses:course:12",
  "question_count": 54,
  "time_limit_seconds": null,
  "passing_score": 50,
  "round_size": 5,
  "shuffle_questions": false,
  "best_score_percent": 83.33,
  "attempts_count": 2
}]}
```

`attempts_count` counts the caller's finished attempts and `best_score_percent` is their best finished result (`null` before the first one).

### GET /quizzes/{slug}

```json
{"data": {
  "id": 1, "slug": "security-basics", "title": "Security basics", "description": null,
  "context": "acme.courses:course:12", "time_limit_seconds": null, "passing_score": 50,
  "round_size": 5, "shuffle_questions": false,
  "question_count": 2,
  "categories": ["Documents", "Theory"],
  "questions": [
    {"id": 10, "text": "What is societal resilience?", "type": "self_check", "category": "Theory",
     "points": 1, "sort_order": 1, "answer_text": "The ability of a society to withstand a crisis.", "answers": []},
    {"id": 11, "text": "Which is a strategy document?", "type": "single", "category": "Documents",
     "points": 1, "sort_order": 2, "answers": [{"id": 30, "text": "National Security Strategy"}, {"id": 31, "text": "Highway Code"}]}
  ]
}}
```

`categories` lists every category of the quiz; with `?category=` the questions are only that category's and `question_count` counts them. Questions come in `sort_order`, or shuffled when `shuffle_questions` is true. Answers come in their sort order.

### POST /quizzes/{slug}/attempts

Body, optional: `{"category": "Theory"}` limits the attempt to one category; a category without questions is a 422 on `category`. Answers status 201:

```json
{"data": {
  "id": 7, "quiz_id": 1, "quiz_slug": "security-basics", "quiz_title": "Security basics",
  "category": null,
  "started_at": "2026-10-02T12:00:00+00:00",
  "expires_at": null,
  "completed_at": null,
  "answered_count": 0,
  "score_points": 0, "max_points": 54, "score_percent": null,
  "passing_score": 50, "passed": null
}}
```

`expires_at` is `started_at + time_limit_seconds`, or `null` without a limit. `max_points` sums the points of the questions the attempt covers. This attempt shape is also each row of `GET /attempts`.

### POST /attempts/{id}/answers

Body:

| Field | Rules |
|-------|-------|
| `question_id` | Required integer; the question must belong to the attempt's quiz (and category). |
| `answer_ids` | Array of answer IDs. Required for `single` (exactly one) and `multiple`; every ID must belong to the question. |
| `known` | Boolean. Required for `self_check`. |

Checks run in this order: the body (422), the attempt belongs to the caller (404), it is not finished (409), it is within the time limit (409), the question belongs to it (422 on `question_id`), the answer fits the question (422 on `answer_ids` or `known`). Answering a question again overwrites the stored answer. Answers status 200:

```json
{"data": {
  "question_id": 11,
  "is_correct": false,
  "points": 0,
  "correct_answer_ids": [30],
  "explanation": "A strategy sets goals and the ways to reach them.",
  "answer_text": null,
  "answers": [
    {"id": 30, "text": "National Security Strategy", "is_correct": true, "explanation": null},
    {"id": 31, "text": "Highway Code", "is_correct": false, "explanation": "A traffic law."}
  ]
}}
```

`points` can be negative when `scoring.penalty_wrong` is set. For a `self_check` question `correct_answer_ids` and `answers` are empty and `answer_text` holds the model answer.

### POST /attempts/{id}/finish and GET /attempts/{id}

Finishing sums the stored points, floors the total at 0, sets `score_percent = score_points / max_points * 100` (two decimals) and `completed_at`. Finishing a finished attempt is a 409. Both routes answer the attempt shape plus `questions`:

```json
{"data": {
  "id": 7, "quiz_id": 1, "quiz_slug": "security-basics", "quiz_title": "Security basics", "category": null,
  "started_at": "2026-10-02T12:00:00+00:00", "expires_at": null, "completed_at": "2026-10-02T12:09:41+00:00",
  "answered_count": 2, "score_points": 1, "max_points": 2, "score_percent": 50,
  "passing_score": 50, "passed": true,
  "questions": [
    {"id": 10, "text": "What is societal resilience?", "type": "self_check", "category": "Theory", "points": 1,
     "answered": true, "answer_ids": [], "known": true, "is_correct": true, "points_earned": 1,
     "correct_answer_ids": [], "explanation": null, "answer_text": "The ability to withstand a crisis...", "answers": []},
    {"id": 11, "text": "Which is a strategy document?", "type": "single", "category": "Documents", "points": 1,
     "answered": true, "answer_ids": [31], "known": null, "is_correct": false, "points_earned": 0,
     "correct_answer_ids": [30], "explanation": "A strategy sets goals...", "answer_text": null,
     "answers": [{"id": 30, "text": "National Security Strategy", "is_correct": true, "explanation": null},
                 {"id": 31, "text": "Highway Code", "is_correct": false, "explanation": "A traffic law."}]}
  ]
}}
```

`passed` is `score_percent >= passing_score` once the attempt is finished, else `null`. While the attempt is open, an unanswered question has `correct_answer_ids`, `explanation` and `answer_text` set to `null` and `is_correct`/`explanation` of its answers set to `null`.

### GET /attempts

```json
{"data": [ /* attempt shapes, newest first */ ],
 "meta": {"current_page": 1, "last_page": 1, "per_page": 20, "total": 2}}
```

### Packages

- `classes`: `Score`, `Totals` and `ScoringConfigFrom` (scoring); `Service` (the API's queries and writes); `ParseImport` and `Import` (the importer).
- `controllers/api`: `Handlers`, the HTTP handlers.
- `controllers`: the admin controllers `QuizzesController`, `QuestionsController`, `AnswersController` and `AttemptsController`.
- `models`: `Quiz`, `Question`, `Answer`, `Attempt`, `AttemptAnswer` and `Slugify`.
- `console`: `ImportCommand`.

## Configuration

Defaults live in `config/config.yaml` and are merged under `golem15.quizzes.*`.

| Key | Default | Meaning |
|-----|---------|---------|
| `golem15.quizzes.scoring.multiple_partial` | `false` | Partial credit on `multiple` questions: `(correct chosen - wrong chosen) / correct answers` of the points, floored at 0. Without it only the exact set earns points. |
| `golem15.quizzes.scoring.penalty_wrong` | `0` | Fraction (0 to 1) of a question's points subtracted for a wrong answer: a non-empty `single` or `multiple` answer that earns nothing. `self_check` answers marked as unknown and empty answers are never penalised. An attempt's total never goes below 0. |

Scores are rounded to two decimals.

### Admin

| Controller | Path | Permission |
|------------|------|------------|
| Quizzes | `golem15/quizzes/quizzes` | `golem15.quizzes.access_quizzes` |
| Questions | `golem15/quizzes/questions` | `golem15.quizzes.access_quizzes` |
| Answers | `golem15/quizzes/answers` | `golem15.quizzes.access_quizzes` |
| Attempts (read-only) | `golem15/quizzes/attempts` | `golem15.quizzes.access_attempts` |

The navigation item is "Quizzes" ("Quizy" in Polish). The admin's relation manager links records through a pivot table only, so questions and answers have their own lists instead of being edited inside the quiz form; filter them by quiz.

## CLI commands

| Command | Purpose |
|---------|---------|
| `quizzes:import <file.json> [--replace]` | Import one quiz from a JSON file. |

The same import is served over HTTP as `POST /api/v1/quizzes/import` (add `?replace=1` for `--replace`), with the import document as the body. The route runs behind the application-wide API token of `golem15.user` (`user.api_token`, created with `user:token:create`): the token needs the `write` scope and its user the `golem15.quizzes.access_quizzes` permission in one of their user groups. It answers `{"data": {"id", "slug", "created", "questions", "answers"}}`, 422 with a `message` for a document that does not parse, and 409 for an existing slug without `replace`. It needs a `golem15.user` that ships the shared API tokens.

The import runs in one transaction and is idempotent by slug:

- a new slug creates the quiz;
- an existing slug is refused unless `--replace` is given;
- with `--replace` the quiz's fields are updated and all its questions are deleted and recreated. The attempts stay, but the attempt answers given to the old questions are deleted with them.

The file is checked before anything is written, and unknown keys are an error. Format:

```json
{
  "title": "Security basics",
  "slug": "security-basics",
  "description": "Flashcards and checks.",
  "context": "acme.courses:course:12",
  "is_published": true,
  "passing_score": 60,
  "round_size": 5,
  "time_limit_seconds": 1800,
  "shuffle_questions": false,
  "questions": [
    {"text": "What is societal resilience?", "type": "self_check", "category": "Theory",
     "answer_text": "The ability of a society to withstand a crisis and recover."},
    {"text": "Which is a strategy document?", "type": "single", "category": "Documents",
     "explanation": "A strategy sets goals and the ways to reach them.",
     "answers": [
       {"text": "National Security Strategy", "is_correct": true},
       {"text": "Highway Code", "is_correct": false, "explanation": "A traffic law."}
     ]},
    {"text": "Which countries are NATO members?", "type": "multiple", "points": 2,
     "answers": [
       {"text": "Poland", "is_correct": true},
       {"text": "Sweden", "is_correct": true},
       {"text": "Switzerland", "is_correct": false}
     ]}
  ]
}
```

| Field | Required | Notes |
|-------|----------|-------|
| `title` | yes | |
| `slug` | no | Normalised to lowercase ASCII with hyphens; built from the title when missing. |
| `description`, `context` | no | |
| `is_published` | no | Default `false`. |
| `passing_score` | no | 0 to 100, default 50. |
| `round_size`, `time_limit_seconds` | no | At least 1; `null` or missing for none. |
| `shuffle_questions` | no | Default `false`. |
| `questions` | yes | At least one. The file order becomes `sort_order`. |
| `questions[].text`, `questions[].type` | yes | `type` is `single`, `multiple` or `self_check`. |
| `questions[].category`, `answer_text`, `explanation` | no | |
| `questions[].points` | no | Default 1, not negative. |
| `questions[].answers` | for `single` and `multiple` | `single`: at least two answers, exactly one correct. `multiple`: at least two, one or more correct. `self_check`: none. |
| `answers[].text` | yes | |
| `answers[].is_correct`, `answers[].explanation` | no | |

`testdata/quiz.json` is a complete example.

## Dependencies

- The SummerCMS framework, `git.golem15.com/golem15/summercms` (modules `backpack`, `bonfire`, `bouncer`, `cabana`, `lagoon`, `pact`, `party`, `phrasebook`, `surf`, `wire`).
- `golem15.user`, `git.golem15.com/golem15/sm-user-plugin`: the `jwt.auth` middleware and the `users` table.
- gormigrate and GORM, as pinned in `go.mod`.
- testcontainers-go and pgx for the Postgres-backed tests.

## Testing

```sh
go test -short ./...    # fast run, no Docker
go test ./...           # full run, starts Postgres with testcontainers (needs Docker)
```

The unit tests cover scoring, request validation, the handlers without a database, the response shapes, the import parser and the admin schema compilation. The Postgres tests run the whole API flow, time limits, cascades, the admin lists and filters and the import command against a throwaway database per test.

Known framework limitations are marked `TODO: requires SummerCMS change` in the code: admin filter choices read the database through `models.FilterDB` because `pact.FilterOptions` receives no context or database; category filter values travel hex-encoded (`models.EncodeCategoryValue`) because the admin accepts only integer or identifier scope values; and the quiz form cannot embed its questions because the relation manager handles pivot relations only.