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}/sessionRequest — 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/sessionPre-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