Skip to content

Contrato — Flashcards

Contrato — Flashcards

Status: Implementado Termos: Prática com Flashcards, Flashcards Acumulados, Desempenho da Prática com Flashcards, Sessão de Flashcards Controller: flashcard_api_controller Service: flashcard_view_service UC: UC-010 — Flashcards

Endpoints

Método Caminho Descrição
GET /api/v1/platform/study/{enrolment_id}/flashcards Browse: Disciplinas → Unidades com cards_available em cada nível
GET /api/v1/platform/study/{enrolment_id}/flashcards/disciplines/{discipline_id} Cards agregados de uma Disciplina (todas as Unidades)
GET /api/v1/platform/study/{enrolment_id}/flashcards/units/{unit_id} Cards de uma Unidade (granularidade fina)

Sessão de prática dentro do Roteiro (slot flashcard_practice) é operada via study.md — POST …/slots/{slot_id}/session action=start devolve os cards agregados pela Disciplina do slot.scope.

GET /study/{enrolment_id}/flashcards — Browse

Visão hierárquica: cada Disciplina expõe sua lista de Unidades, e cada Unidade expõe seu próprio cards_available + Action open_flashcards com unit_id.

Response 200

{
  "enrolment_id": 12,
  "total_cards": 240,
  "total_sessions": 12,
  "overall_accuracy": 73,
  "disciplines": [
    {
      "discipline_id": 5,
      "name": "Direito Constitucional",
      "cards_available": 80,
      "cards_reviewed": 60,
      "accuracy": 75,
      "last_session_at": "2026-04-28T15:00:00+00:00",
      "action": {
        "kind": "open_flashcards",
        "label": "Praticar",
        "params": { "discipline_id": "5" }
      },
      "units": [
        {
          "unit_id": 1234,
          "shortname": "constitucional_controle",
          "name": "Controle de Constitucionalidade",
          "cards_available": 25,
          "action": {
            "kind": "open_flashcards",
            "label": "Praticar",
            "params": { "unit_id": "1234" }
          }
        },
        {
          "unit_id": 1235,
          "shortname": "constitucional_direitos",
          "name": "Direitos Fundamentais",
          "cards_available": 55,
          "action": {
            "kind": "open_flashcards",
            "label": "Praticar",
            "params": { "unit_id": "1235" }
          }
        }
      ]
    }
  ]
}

Campos — root

Campo Tipo Origem
enrolment_id integer Matrícula do contexto
total_cards integer Σ cards_available cross-disciplinas (Flashcards Acumulados)
total_sessions integer consolidation_engine.flashcard_practice.sessions_total
overall_accuracy integer consolidation_engine.flashcard_practice.accuracy (0-100)
disciplines[] array Uma entrada por Disciplina presente no Plano do Aluno

Campos — disciplines[]

Campo Tipo Descrição
discipline_id integer ID canônico da Disciplina
name string discipline.fullname
cards_available integer Σ cards_available das Unidades
cards_reviewed integer Σ score_breakdown.total_questions de sessões flashcard_practice na Disciplina
accuracy integer (Σ correct_count / Σ total_questions) × 100, 0-100
last_session_at string | null ISO-8601 do max(result.completed_at) na Disciplina
action object Action open_flashcards com params.discipline_id (string)
units[] array Unidades da Disciplina presentes no Plano

Campos — disciplines[].units[]

Campo Tipo Descrição
unit_id integer Moodle course id da Unidade (usado em /flashcards/units/{unit_id} e na Action)
shortname string Moodle course shortname
name string unit.fullname
cards_available integer unit_content.total_flashcards (fallback: count(get_flashcards()))
action object Action open_flashcards com params.unit_id (string)

GET /study/{enrolment_id}/flashcards/disciplines/{discipline_id} — Cards agregados

Lista os cards de todas as Unidades de uma Disciplina concatenados.

Path parameters

Parâmetro Tipo Descrição
enrolment_id integer Matrícula do contexto
discipline_id integer Disciplina alvo

Response 200

{
  "enrolment_id": 12,
  "discipline": { "id": 5, "name": "Direito Constitucional" },
  "total": 80,
  "cards": [
    {
      "id": 1,
      "front": "O que é controle difuso?",
      "back": "Qualquer juiz ou tribunal pode reconhecer a inconstitucionalidade...",
      "tags": ["review"],
      "unit": {
        "shortname": "constitucional_controle",
        "name": "Controle de Constitucionalidade"
      }
    }
  ]
}

Cards trazem unit embarcado pra permitir agrupamento secundário.

GET /study/{enrolment_id}/flashcards/units/{unit_id} — Cards de uma Unidade

Path parameters

Parâmetro Tipo Descrição
enrolment_id integer Matrícula do contexto
unit_id integer Moodle course id da Unidade

Response 200

{
  "enrolment_id": 12,
  "unit": {
    "id": 1234,
    "shortname": "constitucional_controle",
    "name": "Controle de Constitucionalidade"
  },
  "discipline": { "id": 5, "name": "Direito Constitucional" },
  "total": 25,
  "cards": [
    {
      "id": 1,
      "front": "O que é controle difuso?",
      "back": "Qualquer juiz ou tribunal pode reconhecer...",
      "tags": ["review"]
    }
  ]
}

Cards SEM unit embarcado — a Unidade é o envelope.

Campos — cards[]

Campo Tipo Descrição
id integer ID canônico do card dentro do unit_content.flashcard. Usado no submit
front string Frente do card
back string Verso do card
tags string[] Tags do card (default ["review"])

Unidade fora do Plano → total = 0, cards = [], envelope com strings vazias.

Sessão de prática (slot flashcard_practice)

No Bloco de Revisão do Módulo, a Trilha gera 1 slot flashcard_practice por Unidade alocada ao Aluno no Módulo + 1 slot flashcard_practice_random agregado para Sessão Aleatória cross-Unit. O recorte das Unidades vem de study_block.unit_ids do primeiro bloco do Flow (saída do dynamic_module_sizing_service: weekly_hours / workload_reference).

Quando a prática rola dentro do Roteiro, o Aluno passa pelo slot_api_controller:

POST /api/v1/platform/study/{enrolment_id}/slots/{slot_id}/session

Request — start

{ "action": "start", "data": {} }

data pode ser objeto vazio. Backend resolve session.data lendo slot.scope.unit_id e chamando flashcard_view_service::get_cards_by_unit. Cards carregam unit_id, incidence e importance por card (Critério de Unidade configurado na Trilha).

Response 200 — start

{
  "success": true,
  "session": {
    "id": 8765,
    "status": "in_progress",
    "started_at": 1714579200,
    "data": {
      "unit": {
        "id": 401,
        "name": "Unidade 1",
        "shortname": "UN_DIR_INF_001",
        "incidence": "INCIDENCIA_ALTA",
        "importance": "RELEVANCIA_ALTA"
      },
      "discipline": {
        "id": 7,
        "name": "Direito Infância"
      },
      "cards": [
        {
          "id": 1,
          "unit_id": 401,
          "front": "...",
          "back": "...",
          "tags": ["review"],
          "incidence": "INCIDENCIA_ALTA",
          "importance": "RELEVANCIA_ALTA"
        }
      ],
      "cards_total": 12
    }
  }
}

Submit

POST /api/v1/platform/study/{enrolment_id}/slots/{slot_id}/session
{
  "action": "submit",
  "data": {
    "responses": [
      { "card_id": 1, "knew": true,  "timems": 4200 },
      { "card_id": 2, "knew": false, "timems": 7100 }
    ]
  }
}
Campo Tipo Descrição
card_id integer ID do card (do session.data.cards[].id)
knew boolean true = soube, false = não soube
timems integer Tempo em ms. Alias aceito: time_ms. Opcional

responses[] deve conter exatamente os cards entregues em session.data — backend valida e gera result com cards_reviewed + accuracy.

Sessão Aleatória (slot flashcard_practice_random)

Slot agregado por Bloco que cobre todas as Unidades em escopo. Aluno responde tudo em UMA execução com cards embaralhados cross-Unit / cross-Disciplina.

Endpoint canônico

POST /api/v1/platform/study/{enrolment_id}/flashcard/random/session

Pre-check: Bloco Atual precisa ser module_review. Em outros blocos, 422 (block_not_module_review). Endpoint resolve internamente o slot virtual flashcard_practice_random do Bloco — Frontend não precisa do UUID.

Response 200 — start

{
  "success": true,
  "session": {
    "id": 9100,
    "slot_id": "uuid-RND-do-slot-virtual",
    "status": "in_progress",
    "started_at": 1714579500,
    "data": {
      "unit_ids": [401, 402, 501],
      "cards_total": 35,
      "cards": [
        { "id": 27, "unit_id": 501, "front": "...", "back": "...", "incidence": "INCIDENCIA_ALTA",  "importance": "RELEVANCIA_MEDIA" },
        { "id":  3, "unit_id": 401, "front": "...", "back": "...", "incidence": "INCIDENCIA_ALTA",  "importance": "RELEVANCIA_ALTA"  },
        { "id": 19, "unit_id": 402, "front": "...", "back": "...", "incidence": "INCIDENCIA_MEDIA", "importance": "RELEVANCIA_BAIXA" }
      ]
    }
  }
}

Submit (canônico via slot virtual)

POST /api/v1/platform/study/{enrolment_id}/slots/{slot_id}/session
{
  "action": "submit",
  "data": {
    "responses": [
      { "card_id": 27, "unit_id": 501, "knew": true,  "timems": 3800 },
      { "card_id":  3, "unit_id": 401, "knew": false, "timems": 5100 }
    ]
  }
}

Cada response carrega unit_id além de card_id + knew. Backend agrupa por Unidade e marca os slots flashcard_practice (per-Unit) do mesmo Bloco como completed quando o número de cards únicos respondidos para a Unidade for >= total_flashcards da unit_content corrente. Unidades parcialmente respondidas ficam inalteradas.

Response 200 — submit

{
  "success": true,
  "slot_id": "uuid-RND-do-slot-virtual",
  "session_id": 9100,
  "status": "completed",
  "extra": {
    "completed_unit_slots": [
      { "slot_id": "uuid-A", "unit_id": 401, "cards_answered": 12, "cards_total": 12 },
      { "slot_id": "uuid-B", "unit_id": 402, "cards_answered":  8, "cards_total":  8 }
    ],
    "partial_unit_slots": [
      { "slot_id": "uuid-C", "unit_id": 501, "cards_answered": 10, "cards_total": 15 }
    ]
  }
}

Erros específicos

HTTP error Causa
404 student_plan_not_found Aluno sem Plano para a Matrícula
404 no_current_flow Plano sem Fluxo Atual
404 no_current_block Fluxo sem Bloco Atual
404 random_slot_not_found Bloco é module_review mas slot RANDOM ausente
422 block_not_module_review Bloco Atual existe mas não é Bloco de Revisão

Action open_flashcards

Vocabulário em actions.md. Aceita dois formatos de params:

Params Mapeamento Frontend Backend equivalente
{discipline_id: string} /flashcards?discipline_id={id} GET /flashcards/disciplines/{discipline_id}
{unit_id: string} /flashcards?unit_id={id} GET /flashcards/units/{unit_id}

Erros

HTTP error Causa
401 unauthorized wstoken ausente/inválido
404 enrolment_not_found Matrícula não pertence ao usuário
404 slot_not_found Slot da sessão não existe
409 slot_already_completed Slot já submetido

Referências

  • Controller: classes/extensions/platform/controller/flashcard_api_controller.php
  • Slot helper: slot_api_controller::resolve_flashcard_practice_session_data
  • Service: classes/extensions/platform/service/flashcard_view_service.php
  • DTOs: flashcard_view_dto, flashcard_discipline_view_dto, flashcard_unit_view_dto
  • Action vocabulary: actions.md
  • UC-010 — Flashcards
Navigation

Type to search…

↑↓ navigate↵ selectEsc close