openapi: 3.0.0
servers:
  -
    url: /local/helico/ajax.php
paths:
  /api/v1/platform/admin/corrections/pending:
    get:
      tags:
        - Admin/Correction
      summary: 'Fila de Simulados Escritos aguardando correção.'
      operationId: 4a6589a4853b3b5e42f18298304a44a5
      parameters:
        -
          name: limit
          in: query
          description: 'Quantidade máxima de itens (default 50).'
          required: false
          schema:
            type: integer
            default: 50
      responses:
        '200':
          description: 'Lista de exam_submission com status=pending.'
          content:
            application/json:
              schema:
                properties:
                  count: { type: integer }
                  submissions: { type: array, items: { properties: { id: { type: integer }, slot_id: { type: integer }, student_plan_id: { type: integer }, submitted_at: { type: integer }, preview: { type: string } }, type: object } }
                type: object
        '401':
          description: 'Token inválido ou expirado.'
          content:
            application/json:
              schema:
                properties:
                  error: { type: string, example: unauthorized }
                type: object
        '403':
          description: 'Permissão insuficiente.'
          content:
            application/json:
              schema:
                properties:
                  error: { type: string, example: forbidden }
                type: object
  '/api/v1/platform/admin/corrections/{submission_id}':
    get:
      tags:
        - Admin/Correction
      summary: 'Detalhe de uma submission textual aguardando ou em correção.'
      operationId: f1735a292cc8149557be6ed566a8361a
      parameters:
        -
          name: submission_id
          in: path
          description: 'ID da exam_submission.'
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: 'Submission completa com texto.'
          content:
            application/json:
              schema:
                properties:
                  id: { type: integer }
                  slot_id: { type: integer }
                  session_id: { type: integer }
                  student_plan_id: { type: integer }
                  submitted_text: { type: string }
                  submitted_at: { type: integer }
                  correction_status: { type: string, enum: [pending, in_review, corrected, discarded] }
                  corrected_by: { type: integer, nullable: true }
                  corrected_at: { type: integer, nullable: true }
                type: object
        '404':
          description: 'Submission não encontrada.'
          content:
            application/json:
              schema:
                properties:
                  error: { type: string, example: submission_not_found }
                type: object
    post:
      tags:
        - Admin/Correction
      summary: 'Submete correção do Simulado Escrito (transição → corrected).'
      operationId: e6e9bd005acc9d121df13cb7d9a17fe5
      parameters:
        -
          name: submission_id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                feedback_html:
                  type: string
                criteria:
                  type: array
                  items: { properties: { criterion_name: { type: string }, score: { type: number, format: float }, max: { type: number, format: float }, weight: { type: number, format: float }, comment: { type: string } }, type: object }
              type: object
            example:
              feedback_html: '<p>Excelente argumentação. Atenção à coesão entre os parágrafos.</p>'
              criteria:
                -
                  criterion_name: Clareza
                  score: 8.5
                  max: 10
                  weight: 0.3
                  comment: ''
                -
                  criterion_name: 'Argumentação jurídica'
                  score: 7
                  max: 10
                  weight: 0.5
                  comment: 'Aprofundar fundamento constitucional.'
                -
                  criterion_name: Coesão
                  score: 9
                  max: 10
                  weight: 0.2
                  comment: ''
      responses:
        '200':
          description: 'Correção persistida; activity_result retroativo é gerado pelo listener.'
          content:
            application/json:
              schema:
                properties:
                  submission_id: { type: integer }
                  correction_id: { type: integer }
                  correction_status: { type: string, enum: [corrected] }
                  corrected_by: { type: integer }
                  corrected_at: { type: integer }
                  totals: { properties: { total_score: { type: number }, max_score: { type: number }, percentage: { type: number }, criteria_count: { type: integer } }, type: object }
                type: object
        '400':
          description: 'Payload inválido.'
          content:
            application/json:
              schema:
                properties:
                  error: { type: string, example: invalid_payload }
                type: object
        '404':
          description: 'Submission não encontrada.'
          content:
            application/json:
              schema:
                properties:
                  error: { type: string, example: submission_not_found }
                type: object
        '409':
          description: 'Submission já corrigida.'
          content:
            application/json:
              schema:
                properties:
                  error: { type: string, example: already_corrected }
                type: object
  '/api/v1/platform/admin/corrections/{submission_id}/claim':
    post:
      tags:
        - Admin/Correction
      summary: 'Tutor reivindica a submission para correção (transição pending → in_review).'
      operationId: aea8bb20331fcab425a0b15be8ecccdb
      parameters:
        -
          name: submission_id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: 'Status atualizado para in_review.'
          content:
            application/json:
              schema:
                properties:
                  submission_id: { type: integer }
                  correction_status: { type: string, enum: [in_review] }
                  corrected_by: { type: integer }
                type: object
        '404':
          description: 'Submission não encontrada.'
          content:
            application/json:
              schema:
                properties:
                  error: { type: string, example: submission_not_found }
                type: object
        '409':
          description: 'Submission já corrigida.'
          content:
            application/json:
              schema:
                properties:
                  error: { type: string, example: already_corrected }
                type: object
  /api/v1/platform/dashboard:
    get:
      tags:
        - Dashboard
      summary: 'Resumo geral do Aluno (cross-product).'
      description: "Resumo cross-product do Aluno.\n\nDados gerais que não dependem do produto/matrícula selecionado.\nFrontend usa para montar header, badges e indicadores gerais."
      operationId: ccdc3e42b789b0ad0b91a70cab9e9333
      responses:
        '200':
          description: 'Resumo cross-product.'
          content:
            application/json:
              schema:
                properties:
                  enrolments_active: { description: 'Quantidade de inscrições ativas.', type: integer }
                  has_pending_onboarding: { description: 'Alguma inscrição com onboarding pendente?', type: boolean }
                  unread_notifications: { description: 'Contagem de notificações não lidas.', type: integer }
                  last_activity: { description: 'Timestamp da última atividade do aluno.', type: string, format: date-time, nullable: true }
                type: object
        '401':
          description: 'Token inválido ou expirado.'
          content:
            application/json:
              schema:
                properties:
                  error: { type: string, example: unauthorized }
                type: object
  /api/v1/platform/enrolments:
    get:
      tags:
        - Platform
      summary: 'Inscrições do Aluno com estado do ciclo.'
      description: "Lista inscrições (Matrículas) do Aluno autenticado.\n\nRetorna user info embutido + array de enrolments com:\n- Produto Comercial e Trilha Pedagógica (objetos aninhados)\n- Estado do Onboarding (per-enrolment, fases geral/complemento)\n- Status do Plano do Aluno (6 estados canônicos)\n- Vigência de Acesso (datas)\n\nO Frontend usa `onboarding.completed` e `student_plan.status`\npara decidir o roteamento após login."
      operationId: 99ac96edaed38ad4f866b1ce57523400
      parameters:
        -
          name: status
          in: query
          description: 'Filtro por Status da Matrícula. Default: active.'
          required: false
          schema:
            type: string
            default: active
            enum:
              - active
              - suspended
              - inactive
              - all
      responses:
        '200':
          description: 'User info + inscrições com estado do ciclo.'
          content:
            application/json:
              schema:
                properties:
                  user: { properties: { id: { type: integer, example: 42 }, fullname: { type: string, example: 'Maria Silva' }, email: { type: string, example: aluno@email.com }, avatar_url: { type: string } }, type: object }
                  enrolments: { type: array, items: { properties: { id: { description: 'ID da Matrícula', type: integer }, course_id: { description: 'ID do Curso-Produto (Moodle)', type: integer }, status: { type: string, enum: [active, suspended, inactive] }, product: { properties: { id: { type: integer }, fullname: { type: string }, shortname: { type: string } }, type: object }, trail: { properties: { id: { type: integer }, fullname: { type: string } }, type: object }, study_plan_id: { type: integer, nullable: true }, onboarding: { properties: { completed: { type: boolean }, general_completed: { type: boolean }, complement_required: { type: boolean }, complement_completed: { type: boolean } }, type: object }, student_plan: { properties: { id: { type: integer, nullable: true }, status: { type: string, enum: [not_started, active, blocked, interrupted, completed, closed], nullable: true } }, type: object }, validity: { properties: { start: { type: string, format: date }, end: { type: string, format: date } }, type: object } }, type: object } }
                type: object
        '401':
          description: 'Token inválido ou expirado.'
          content:
            application/json:
              schema:
                properties:
                  error: { type: string, example: unauthorized }
                type: object
  '/api/v1/platform/study/{enrolment_id}/exams':
    get:
      tags:
        - Exam
      summary: 'Lista de simulados (legado quando type ausente; shape por tipo quando type informado).'
      description: "Lista de simulados realizados pelo Aluno.\n\nFiltra slots de tipo avaliativo: diagnostic_initial, diagnostic_verify,\nexam_objective, exam_written, exam_truefalse. Cross-blocos."
      operationId: 5167163277eb379647a60f5f71f1c3bd
      parameters:
        -
          name: enrolment_id
          in: path
          description: 'ID da Matrícula (contexto ativo).'
          required: true
          schema:
            type: integer
        -
          name: type
          in: query
          description: 'Filtra por tipo de simulado e altera o shape da resposta. Sem este parâmetro, retorna o shape legado de 3 buckets (available/pending_correction/corrected).'
          required: false
          schema:
            type: string
            enum:
              - truefalse
              - objective
              - written
      responses:
        '200':
          description: "Shape varia conforme `type`:\n- **sem `type`** (legado): 3 buckets `available`/`pending_correction`/`corrected` cross-tipo.\n- **`type=truefalse`**: `groups[]` (DI/SVD completados) com `disciplines[]`. Sem pendentes.\n- **`type=objective`**: `exams[]` (completados) com `level` + `disciplines[]`. Sem pendentes.\n- **`type=written`**: `exams[]` com `status` do pipeline de correção."
          content:
            application/json:
              schema:
                oneOf:
                  - { title: 'Legacy (sem type)', description: '3 buckets cross-tipo. Frontend antigo. Será deprecado após migração.', properties: { enrolment_id: { type: integer }, available: { description: 'Slots prontos pro Aluno (não bloqueados).', type: array, items: { type: object } }, pending_correction: { description: 'Simulados Escritos aguardando correção.', type: array, items: { type: object } }, corrected: { description: 'Simulados concluídos.', type: array, items: { type: object } } }, type: object }
                  - { title: type=truefalse, description: 'Simulados V/F particionados em Diagnóstico Inicial e Verificação de Desempenho.', properties: { enrolment_id: { type: integer }, type: { type: string, enum: [truefalse] }, groups: { description: 'Lista FLAT — 1 group por combinação (category × módulo) COMPLETADA. DIs de módulos diferentes ocupam groups distintos; idem para SVD. Ordem: todos diagnostic_initial primeiro, depois todos diagnostic_verify. Slots pendentes não entram aqui (badge em /exams/pending-summary). **`items[]` agrega disciplines de TODOS slots daquela combinação** — não há slot_id no payload.', type: array, items: { properties: { category: { type: string, enum: [diagnostic_initial, diagnostic_verify] }, module: { type: string, example: 'Módulo 1' }, module_id: { type: integer }, module_ref: { type: string }, submitted_at: { description: 'Data do submit mais recente entre os slots agregados.', type: string, format: date-time, nullable: true }, overall_score: { description: 'Percentual (0-100) derivado de sum(correct)/sum(total)*100 cross-slots.', type: number, format: float }, items: { description: 'Disciplinas agregadas. Cada item soma correct+total de todas as ocorrências da disciplina nos slots desse group.', type: array, items: { $ref: '#/components/schemas/ExamDisciplineBreakdown' } } }, type: object } } }, type: object }
                  - { title: type=objective, description: 'Simulados Objetivos COMPLETADOS. Cada item carrega `level` (basico/intermediario/avancado) via thresholds 50/80. Slots pendentes não entram (badge em /exams/pending-summary).', properties: { enrolment_id: { type: integer }, type: { type: string, enum: [objective] }, exams: { type: array, items: { properties: { slot_id: { type: string, format: uuid }, label: { type: string }, module: { type: string }, submitted_at: { type: string, format: date-time, nullable: true }, overall_score: { type: number, format: float }, level: { type: string, enum: [basico, intermediario, avancado] }, disciplines: { type: array, items: { $ref: '#/components/schemas/ExamDisciplineBreakdown' } } }, type: object } } }, type: object }
                  - { title: type=written, description: 'Simulados Escritos. `status` é status público derivado de `correction_status` interno. Sem `disciplines[]` — correção é por critérios.', properties: { enrolment_id: { type: integer }, type: { type: string, enum: [written] }, exams: { type: array, items: { properties: { slot_id: { type: string, format: uuid }, label: { type: string }, module: { type: string }, status: { description: '**pending**: aluno ainda não enviou. **in_correction**: submetido, pipeline de correção (IA/Tutor) em andamento. **corrected**: devolutiva disponível.', type: string, enum: [pending, in_correction, corrected] }, started_at: { description: 'ISO 8601 da session ativa do slot (criada quando o Aluno abre a tela). Null quando ainda sem session.', type: string, format: date-time, nullable: true }, submitted_at: { type: string, format: date-time, nullable: true }, deadline: { description: 'Prazo de envio (ISO 8601 fuso servidor). Cálculo placeholder = slot.timecreated + 7 dias enquanto a fonte canônica (study_block/sequence config) não é definida (TODO).', type: string, format: date-time, nullable: true }, overall_score: { description: 'Percentual (0-100). Só presente quando status=corrected.', type: number, format: float, nullable: true } }, type: object } } }, type: object }
        '400':
          description: 'Valor de `type` inválido.'
          content:
            application/json:
              schema:
                properties:
                  error: { type: string, example: invalid_type }
                type: object
        '401':
          description: 'Token inválido ou expirado.'
          content:
            application/json:
              schema:
                properties:
                  error: { type: string, example: unauthorized }
                type: object
        '404':
          description: 'Matrícula não encontrada.'
          content:
            application/json:
              schema:
                properties:
                  error: { type: string, example: enrolment_not_found }
                type: object
  '/api/v1/platform/study/{enrolment_id}/exams/pending-summary':
    get:
      tags:
        - Exam
      summary: 'Contagens de simulados pendentes por tipo (badge data).'
      description: "Contagens de simulados pendentes por tipo para badges na UI.\n\nCritérios de \"pendente\":\n- `truefalse`: DI/SVD com status `not_started`/`in_progress`/`skipped`\n- `objective`: `exam_objective` mesmos status\n- `written`: `exam_written` sem submission registrada"
      operationId: fefe148a1c6fa4c8eb171db7f0195641
      parameters:
        -
          name: enrolment_id
          in: path
          description: 'ID da Matrícula (contexto ativo).'
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: 'Contagens por tipo + total agregado.'
          content:
            application/json:
              schema:
                properties:
                  enrolment_id: { type: integer }
                  truefalse: { description: 'DI + SVD pendentes', type: integer, example: 2 }
                  objective: { description: 'Simulados Objetivos pendentes', type: integer, example: 1 }
                  written: { description: 'Simulados Escritos sem submission', type: integer, example: 3 }
                  total: { type: integer, example: 6 }
                type: object
        '401':
          description: 'Token inválido ou expirado.'
          content:
            application/json:
              schema:
                properties:
                  error: { type: string, example: unauthorized }
                type: object
        '404':
          description: 'Matrícula não encontrada.'
          content:
            application/json:
              schema:
                properties:
                  error: { type: string, example: enrolment_not_found }
                type: object
  '/api/v1/platform/study/{enrolment_id}/exams/truefalse/review':
    get:
      tags:
        - Exam
      summary: 'Revisão dos slots V/F (DI ou SVD) de UM módulo.'
      description: "Revisão dos slots V/F (DI ou SVD) de UM módulo.\n\nCada slot retornado expõe questões com enunciado, alternativas,\nresposta do aluno, gabarito e comentário (justificativa)."
      operationId: dac34dc3920cb69a689880da74088220
      parameters:
        -
          name: enrolment_id
          in: path
          required: true
          schema:
            type: integer
        -
          name: module_id
          in: query
          description: 'ID do study_flow (Módulo).'
          required: true
          schema:
            type: integer
        -
          name: category
          in: query
          description: 'Categoria diagnóstica.'
          required: true
          schema:
            type: string
            enum:
              - diagnostic_initial
              - diagnostic_verify
      responses:
        '200':
          description: 'Revisão V/F com slots separados. Cada slot expõe questões + respostas + justificativa.'
          content:
            application/json:
              schema:
                properties:
                  enrolment_id: { type: integer }
                  module_id: { type: integer }
                  module: { type: string, example: 'Módulo 1' }
                  module_ref: { type: string }
                  category: { type: string, enum: [diagnostic_initial, diagnostic_verify] }
                  label: { type: string, example: 'Diagnóstico Inicial' }
                  overall_score: { description: 'Score cross-slots: sum(correct)/sum(total)*100.', type: number, format: float }
                  slots: { type: array, items: { properties: { slot_id: { type: string, format: uuid }, submitted_at: { type: string, format: date-time, nullable: true }, overall_score: { type: number, format: float }, stats: { properties: { correct: { type: integer }, incorrect: { type: integer }, not_sure: { type: integer }, total: { type: integer } }, type: object }, questions: { type: array, items: { properties: { id: { type: integer }, unit_id: { type: integer, nullable: true }, statement_html: { type: string }, alternatives: { type: array, items: { properties: { key: { type: string, example: V }, label: { type: string, example: Verdadeiro } }, type: object } }, student_answer: { type: string, nullable: true }, correct_answer: { type: string }, is_correct: { type: boolean }, not_sure: { type: boolean }, comment_html: { description: 'Justificativa/comentário da questão (HTML).', type: string } }, type: object } } }, type: object } }
                type: object
        '400':
          description: 'Parâmetros inválidos.'
          content:
            application/json:
              schema:
                properties:
                  error: { type: string, example: invalid_params }
                type: object
        '401':
          description: 'Token inválido.'
          content:
            application/json:
              schema:
                properties:
                  error: { type: string, example: unauthorized }
                type: object
        '404':
          description: 'Matrícula ou módulo não encontrado.'
          content:
            application/json:
              schema:
                properties:
                  error: { type: string, example: not_found }
                type: object
  '/api/v1/platform/study/{enrolment_id}/exams/objective/review':
    get:
      tags:
        - Exam
      summary: 'Revisão dos Simulados Objetivos de UM módulo.'
      description: "Revisão dos slots Simulado Objetivo de UM módulo. Cada slot expõe\nquestões com alternativas múltiplas, resposta, gabarito e justificativa."
      operationId: da59050280e45c6aec0397c7c8254e7c
      parameters:
        -
          name: enrolment_id
          in: path
          required: true
          schema:
            type: integer
        -
          name: module_id
          in: query
          description: 'ID do study_flow.'
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: 'Revisão Obj — slots[] com questions[] + comment_html.'
          content:
            application/json:
              schema:
                type: object
        '400':
          description: invalid_params
          content:
            application/json:
              schema:
                properties:
                  error: { type: string }
                type: object
        '404':
          description: not_found
          content:
            application/json:
              schema:
                properties:
                  error: { type: string }
                type: object
  '/api/v1/platform/study/{enrolment_id}/exams/objective/{slot_id}/review':
    get:
      tags:
        - Exam
      summary: 'Revisão de UM Simulado Objetivo (slot).'
      description: 'Revisão de UM Simulado Objetivo (slot), particionada por Disciplina.'
      operationId: 9019f031ec9b0483ab29707ccf3c6e8c
      parameters:
        -
          name: enrolment_id
          in: path
          required: true
          schema:
            type: integer
        -
          name: slot_id
          in: path
          description: 'UUID do slot exam_objective.'
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: 'Revisão Objetivo do slot — disciplines[] com questions[] + cda_level.'
          content:
            application/json:
              schema:
                type: object
        '404':
          description: not_found
          content:
            application/json:
              schema:
                properties:
                  error: { type: string }
                type: object
  '/api/v1/platform/study/{enrolment_id}/exams/written/review':
    get:
      tags:
        - Exam
      summary: 'Revisão dos Simulados Escritos de UM módulo.'
      description: "Revisão dos slots Simulado Escrito de UM módulo. Cada slot expõe\nstatus, submission, feedback HTML, critérios e totais."
      operationId: 535ec62ce0f4ab9e4f29aafe460768b0
      parameters:
        -
          name: enrolment_id
          in: path
          required: true
          schema:
            type: integer
        -
          name: module_id
          in: query
          description: 'ID do study_flow.'
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: 'Revisão Escrito — slots[] com feedback + critérios.'
          content:
            application/json:
              schema:
                type: object
        '400':
          description: invalid_params
          content:
            application/json:
              schema:
                properties:
                  error: { type: string }
                type: object
        '404':
          description: not_found
          content:
            application/json:
              schema:
                properties:
                  error: { type: string }
                type: object
  '/api/v1/platform/study/{enrolment_id}/exams/written/{slot_id}/review':
    get:
      tags:
        - Exam
      summary: 'Revisão de UM Simulado Escrito (slot).'
      description: "Revisão de UM Simulado Escrito (slot). Espelho de resposta, folhas\nenviadas pelo Aluno e placeholders de correção IA/Tutor."
      operationId: ea00888a20849286a4e4a4cf7d117e12
      parameters:
        -
          name: enrolment_id
          in: path
          required: true
          schema:
            type: integer
        -
          name: slot_id
          in: path
          description: 'UUID do slot exam_written.'
          required: true
          schema:
            type: string
            format: uuid
        -
          name: unit_id
          in: query
          description: 'Filtra as Questões a uma Unidade específica (opcional).'
          required: false
          schema:
            type: integer
      responses:
        '200':
          description: 'Revisão do Escrito — answer_key[], answer_images[], ai_correction/tutor_correction (null enquanto pipeline de correção não implementado).'
          content:
            application/json:
              schema:
                type: object
        '404':
          description: not_found
          content:
            application/json:
              schema:
                properties:
                  error: { type: string }
                type: object
  '/api/v1/platform/study/{enrolment_id}/exams/{slot_id}':
    get:
      tags:
        - Exam
      summary: 'Detalhe do simulado com revisão/devolutiva.'
      description: "Detalhe do simulado com revisão ou devolutiva.\n\nQuestionários (DI/SVD/Objetivo): review com questões + gabarito.\nSimulado Escrito: feedback (Devolutiva) com nota e comentários."
      operationId: 5af39229f8dc3850a9dd0ac69a50d322
      parameters:
        -
          name: enrolment_id
          in: path
          description: 'ID da Matrícula (contexto ativo).'
          required: true
          schema:
            type: integer
        -
          name: slot_id
          in: path
          description: 'UUID do slot de simulado.'
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: 'Simulado com review (questões+gabarito) ou feedback (devolutiva).'
          content:
            application/json:
              schema:
                properties:
                  slot_id: { type: string, format: uuid }
                  type: { type: string }
                  label: { type: string }
                  result: { properties: { score: { type: number }, level: { type: string, nullable: true }, completed_at: { type: string, format: date-time } }, type: object }
                  review: { properties: { questions: { type: array, items: { properties: { id: { type: integer }, statement_html: { type: string }, alternatives: { type: array, items: { properties: { key: { type: string }, label: { type: string } }, type: object } }, student_answer: { type: string, nullable: true }, correct_answer: { type: string }, is_correct: { type: boolean } }, type: object } }, stats: { properties: { correct: { type: integer }, incorrect: { type: integer }, not_sure: { type: integer }, total: { type: integer } }, type: object } }, type: object, nullable: true }
                  feedback: { properties: { feedback_html: { type: string }, criteria: { type: array, items: { type: object } }, totals: { type: object } }, type: object, nullable: true }
                type: object
        '401':
          description: 'Token inválido ou expirado.'
          content:
            application/json:
              schema:
                properties:
                  error: { type: string, example: unauthorized }
                type: object
        '404':
          description: 'Matrícula ou simulado não encontrado.'
          content:
            application/json:
              schema:
                properties:
                  error: { type: string, example: exam_not_found }
                type: object
  '/api/v1/platform/study/{enrolment_id}/flashcards':
    get:
      tags:
        - Flashcard
      summary: 'Flashcards disponíveis por disciplina (browse + stats).'
      description: "Flashcards disponíveis agrupados por disciplina.\n\nRetorna cards acumulados de unidades já estudadas, estatísticas\nde prática e ação para iniciar sessão avulsa por disciplina."
      operationId: a36c0007fcb63acfbcd4600935bda50b
      parameters:
        -
          name: enrolment_id
          in: path
          description: 'ID da Matrícula (contexto ativo).'
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: 'Stats globais + disciplinas com cards disponíveis e ação.'
          content:
            application/json:
              schema:
                properties:
                  total_cards: { type: integer }
                  total_sessions: { type: integer }
                  total_reviewed: { description: 'Total de cards revisados (Estatísticas Gerais de Flashcards).', type: integer }
                  total_correct: { description: 'Acertos acumulados (Estatísticas Gerais de Flashcards).', type: integer }
                  total_incorrect: { description: 'Erros acumulados (Estatísticas Gerais de Flashcards).', type: integer }
                  overall_accuracy: { type: integer }
                  disciplines: { type: array, items: { properties: { discipline_id: { type: integer }, name: { type: string }, cards_available: { type: integer }, cards_reviewed: { type: integer }, cards_correct: { description: 'Acertos por Disciplina (Estatísticas de Flashcards por Disciplina).', type: integer }, cards_incorrect: { description: 'Erros por Disciplina (Estatísticas de Flashcards por Disciplina).', type: integer }, accuracy: { type: integer }, last_session_at: { type: string, format: date-time, nullable: true }, action: { description: 'Semantic action — see contratos/actions.md.', properties: { kind: { type: string, enum: [open_flashcards, open_discipline] }, label: { type: string }, params: { type: object, nullable: true } }, type: object }, units: { description: 'Unidades da Disciplina presentes no Plano com cards_available e Estatísticas de Flashcards por Unidade.', type: array, items: { properties: { unit_id: { description: 'Moodle course id da Unidade.', type: integer }, shortname: { type: string }, name: { type: string }, cards_available: { type: integer }, cards_reviewed: { type: integer }, cards_correct: { description: 'Acertos por Unidade (Estatísticas de Flashcards por Unidade).', type: integer }, cards_incorrect: { description: 'Erros por Unidade (Estatísticas de Flashcards por Unidade).', type: integer }, accuracy: { type: integer }, last_session_at: { type: string, format: date-time, nullable: true }, incidence: { description: 'Critério de Unidade — Incidência configurada na Trilha. Valor cru persistido.', type: string, enum: [INCIDENCIA_BAIXA, INCIDENCIA_MEDIA, INCIDENCIA_ALTA, ''] }, importance: { description: 'Critério de Unidade — Importância configurada na Trilha. Valor cru persistido.', type: string, enum: [RELEVANCIA_BAIXA, RELEVANCIA_MEDIA, RELEVANCIA_ALTA, ''] }, action: { properties: { kind: { type: string, enum: [open_flashcards] }, label: { type: string }, params: { type: object } }, type: object } }, type: object } } }, type: object } }
                type: object
        '401':
          description: 'Token inválido ou expirado.'
          content:
            application/json:
              schema:
                properties:
                  error: { type: string, example: unauthorized }
                type: object
        '404':
          description: 'Matrícula não encontrada.'
          content:
            application/json:
              schema:
                properties:
                  error: { type: string, example: enrolment_not_found }
                type: object
  '/api/v1/platform/study/{enrolment_id}/flashcards/disciplines/{discipline_id}':
    get:
      tags:
        - Flashcard
      summary: 'Cards de uma Disciplina (prática livre).'
      description: "Cards de uma Disciplina (prática livre).\n\nAgrega `unit_content.flashcard` de todas as Unidades da Disciplina\npresentes no Plano do Aluno. Cada card carrega a Unidade de origem\npra permitir agrupamento secundário no Frontend.\n\nAction `open_flashcards` (emitida pela view de listagem) mapeia pra\nesta rota — Frontend chama com discipline_id pra iniciar prática."
      operationId: 2726065a69a48e69c73dbfab0e5a0d4b
      parameters:
        -
          name: enrolment_id
          in: path
          description: 'ID da Matrícula (contexto ativo).'
          required: true
          schema:
            type: integer
        -
          name: discipline_id
          in: path
          description: 'ID canônico da Disciplina.'
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: 'Cards da Disciplina com unidade de origem.'
          content:
            application/json:
              schema:
                properties:
                  enrolment_id: { type: integer }
                  discipline: { properties: { id: { type: integer }, name: { type: string } }, type: object }
                  total: { type: integer }
                  cards: { type: array, items: { properties: { id: { type: integer }, front: { type: string }, back: { type: string }, tags: { type: array, items: { type: string } }, unit: { properties: { shortname: { type: string }, name: { type: string } }, type: object } }, type: object } }
                type: object
        '401':
          description: 'Token inválido ou expirado.'
          content:
            application/json:
              schema:
                properties:
                  error: { type: string, example: unauthorized }
                type: object
  '/api/v1/platform/study/{enrolment_id}/flashcards/units/{unit_id}':
    get:
      tags:
        - Flashcard
      summary: 'Cards de uma Unidade (prática livre granular).'
      description: "Cards de uma Unidade (prática livre granular).\n\n`unit_id` é o Moodle course id da Unidade (mesmo valor exposto em\n`disciplines[].units[].unit_id` do browse). Cards retornam sem\n`unit` embarcado porque a Unidade é o envelope."
      operationId: 5fe9f0f99bd81656640516a751a98628
      parameters:
        -
          name: enrolment_id
          in: path
          description: 'ID da Matrícula (contexto ativo).'
          required: true
          schema:
            type: integer
        -
          name: unit_id
          in: path
          description: 'Moodle course id da Unidade.'
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: 'Cards da Unidade.'
          content:
            application/json:
              schema:
                properties:
                  enrolment_id: { type: integer }
                  unit: { properties: { id: { type: integer }, shortname: { type: string }, name: { type: string } }, type: object }
                  discipline: { properties: { id: { type: integer }, name: { type: string } }, type: object }
                  total: { type: integer }
                  cards: { type: array, items: { properties: { id: { type: integer }, front: { type: string }, back: { type: string }, tags: { type: array, items: { type: string } } }, type: object } }
                type: object
        '401':
          description: 'Token inválido ou expirado.'
          content:
            application/json:
              schema:
                properties:
                  error: { type: string, example: unauthorized }
                type: object
  '/api/v1/platform/study/{enrolment_id}/flashcard/random/session':
    post:
      tags:
        - Flashcard
      summary: 'Inicia Sessão Aleatória de Flashcards (Revisão do Módulo cross-Unit).'
      description: "Inicia Sessão Aleatória de Flashcards (Bloco de Revisão do Módulo).\n\nPre-check: Bloco Atual do Plano do Aluno precisa ser `module_review`.\nEm qualquer outro Bloco retorna 422 (`block_not_module_review`) sem\ncriar sessão. Quando válido, resolve o slot virtual\n`flashcard_practice_random` do Bloco e cria a session via\n`session_questionnaire_service::start`, embarcando cards cross-Unit\nembaralhados em `session.data` (via\n`slot_api_controller::resolve_flashcard_practice_random_session_data`)."
      operationId: 316d572339f6ef12bb14afa4d6d85572
      parameters:
        -
          name: enrolment_id
          in: path
          description: 'ID da Matrícula (contexto ativo).'
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: 'Sessão iniciada com cards embaralhados cross-Unit.'
          content:
            application/json:
              schema:
                properties:
                  success: { type: boolean }
                  session: { properties: { id: { type: integer }, slot_id: { description: 'UUID do slot virtual flashcard_practice_random.', type: string }, status: { type: string }, started_at: { type: integer, nullable: true }, data: { type: object } }, type: object }
                type: object
        '404':
          description: 'Plano do Aluno, Fluxo, Bloco ou slot RANDOM não encontrado.'
          content:
            application/json:
              schema:
                properties:
                  error: { type: string, enum: [student_plan_not_found, no_current_flow, no_current_block, random_slot_not_found] }
                type: object
        '422':
          description: 'Bloco Atual não é Bloco de Revisão do Módulo.'
          content:
            application/json:
              schema:
                properties:
                  error: { type: string, example: block_not_module_review }
                type: object
  /api/v1/platform/me:
    get:
      tags:
        - Platform
      summary: 'Dados do usuário autenticado.'
      description: "Retorna dados do usuário autenticado.\n\nTerm: Perfil do Sistema — dados básicos do usuário logado."
      operationId: 29911be74d99da624caff5c13a495fae
      responses:
        '200':
          description: 'Dados do usuário.'
          content:
            application/json:
              schema:
                properties:
                  id: { type: integer, example: 42 }
                  fullname: { type: string, example: 'Maria Silva' }
                  email: { type: string, example: aluno@email.com }
                  avatar_url: { type: string, example: 'https://plataforma.helico.com.br/avatar/42.jpg' }
                type: object
        '401':
          description: 'Token inválido ou expirado.'
          content:
            application/json:
              schema:
                properties:
                  error: { type: string, example: unauthorized }
                type: object
  '/api/v1/platform/study/{enrolment_id}/notebook':
    get:
      tags:
        - Notebook
      summary: 'Artefatos do Caderno Online agrupados por disciplina.'
      description: "Artefatos do Caderno Online agrupados por disciplina.\n\nRetorna apenas artefatos de atividades concluídas (não do Bloco Atual).\nAgrupamento por disciplina feito no Backend (REF-90-A §16)."
      operationId: 3584cd8de7262824e80c9daa005242b8
      parameters:
        -
          name: enrolment_id
          in: path
          description: 'ID da Matrícula (contexto ativo).'
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: 'Artefatos agrupados por disciplina com preview.'
          content:
            application/json:
              schema:
                properties:
                  artifacts_count: { type: integer }
                  disciplines: { type: array, items: { properties: { id: { type: integer }, name: { type: string }, artifacts: { type: array, items: { properties: { id: { type: integer }, title: { type: string }, type: { type: string, enum: [resumo, leitura, reforco, hibrido] }, preview: { type: string }, updated_at: { type: integer } }, type: object } } }, type: object } }
                type: object
        '401':
          description: 'Token inválido ou expirado.'
          content:
            application/json:
              schema:
                properties:
                  error: { type: string, example: unauthorized }
                type: object
        '404':
          description: 'Matrícula não encontrada.'
          content:
            application/json:
              schema:
                properties:
                  error: { type: string, example: enrolment_not_found }
                type: object
  '/api/v1/platform/study/{enrolment_id}/notebook/{artifact_id}':
    get:
      tags:
        - Notebook
      summary: 'Conteúdo completo de um artefato do Caderno Online.'
      description: 'Conteúdo completo de um artefato do Caderno Online.'
      operationId: 9f4b40f674663773f767c63c02045a72
      parameters:
        -
          name: enrolment_id
          in: path
          description: 'ID da Matrícula (contexto ativo).'
          required: true
          schema:
            type: integer
        -
          name: artifact_id
          in: path
          description: 'ID do artefato.'
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: 'Artefato com conteúdo HTML completo.'
          content:
            application/json:
              schema:
                properties:
                  id: { type: integer }
                  type: { type: string, enum: [resumo, leitura, reforco, hibrido] }
                  title: { type: string }
                  discipline: { properties: { id: { type: integer, nullable: true }, name: { type: string } }, type: object }
                  unit: { properties: { id: { type: integer, nullable: true }, name: { type: string } }, type: object }
                  content_html: { type: string }
                  word_count: { type: integer }
                  status: { type: string, enum: [current_block, notebook, archived] }
                  origin: { type: string, enum: [student, helico, merged] }
                  updated_at: { type: integer }
                  source_activity: { properties: { slot_id: { type: integer, nullable: true }, session_id: { type: integer, nullable: true }, type: { type: string }, format: { type: string } }, type: object }
                type: object
        '401':
          description: 'Token inválido ou expirado.'
          content:
            application/json:
              schema:
                properties:
                  error: { type: string, example: unauthorized }
                type: object
        '404':
          description: 'Matrícula ou artefato não encontrado.'
          content:
            application/json:
              schema:
                properties:
                  error: { type: string, example: artifact_not_found }
                type: object
  '/api/v1/platform/study/{enrolment_id}/notebook/disciplines':
    get:
      tags:
        - Notebook
      summary: 'Index leve do Caderno por Disciplina (counts agregados).'
      description: "Index leve do Caderno por Disciplina — counts agregados, sem detalhe\npor Unidade. Lista apenas Disciplinas cobertas pelos Módulos já\natravessados pelo Aluno (`sort_order ≤ current_module.sort_order`)."
      operationId: 60ca8d44b63e1d25530b4a98e85451f9
      parameters:
        -
          name: enrolment_id
          in: path
          description: 'ID da Matrícula.'
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: 'Disciplinas com contagem de Unidades e Artefatos.'
        '401':
          description: 'Token inválido ou expirado.'
        '404':
          description: 'Matrícula não pertence ao usuário.'
  '/api/v1/platform/study/{enrolment_id}/notebook/disciplines/{discipline_id}/units':
    get:
      tags:
        - Notebook
      summary: 'Primeira Unidade completa + sumário das demais.'
      description: "Detalhe completo da primeira Unidade da Disciplina + sumário das demais.\nOrdem definida pelo `student_plan.sequence` (canon pedagógico)."
      operationId: 9245f0d2988e062eb4c5ef4106b39781
      parameters:
        -
          name: enrolment_id
          in: path
          description: 'ID da Matrícula.'
          required: true
          schema:
            type: integer
        -
          name: discipline_id
          in: path
          description: 'ID da Disciplina.'
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: 'Disciplina + primeira Unidade detalhada + sumário das demais.'
        '401':
          description: 'Token inválido ou expirado.'
        '404':
          description: 'Matrícula ou Disciplina não atravessada.'
  '/api/v1/platform/study/{enrolment_id}/notebook/disciplines/{discipline_id}/units/{unit_id}':
    get:
      tags:
        - Notebook
      summary: 'Drill completo da Unidade no Caderno Online.'
      description: "Drill completo da Unidade: classification CDA, performance por simulado\n(reuso de `general_review_performance_view_service`), tópicos com\nartifacts/anotações, e summary de Flashcards."
      operationId: 61147bb7cfed0a351bb22241095310a8
      parameters:
        -
          name: enrolment_id
          in: path
          description: 'ID da Matrícula.'
          required: true
          schema:
            type: integer
        -
          name: discipline_id
          in: path
          description: 'ID da Disciplina.'
          required: true
          schema:
            type: integer
        -
          name: unit_id
          in: path
          description: 'ID da Unidade.'
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: 'Unidade com classification, performance, topics e flashcards.'
        '401':
          description: 'Token inválido ou expirado.'
        '404':
          description: 'Matrícula, Disciplina ou Unidade fora do escopo atravessado.'
  '/api/v1/platform/study/{enrolment_id}/notebook/disciplines/{discipline_id}/units/{unit_id}/topics/{topic_id}':
    post:
      tags:
        - Notebook
      summary: 'Autosave de artefato do Caderno Online (full ou patch incremental).'
      description: 'Full save (Content-Type application/json): editor_state completo + annotations. Cria o artifact (escopo notebook) quando o Tópico ainda não tem um, ou atualiza preservando identidade. Patch incremental (Content-Type application/json-patch+json): patch_editor_state + annotations_delta + base_version, com optimistic concurrency (409 em conflito); exige artifact existente.'
      operationId: bc6e056d62a4c07e8af769758b7e4752
      parameters:
        -
          name: enrolment_id
          in: path
          required: true
          schema:
            type: integer
        -
          name: discipline_id
          in: path
          required: true
          schema:
            type: integer
        -
          name: unit_id
          in: path
          required: true
          schema:
            type: integer
        -
          name: topic_id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                action:
                  type: string
                  enum: [autosave]
                data:
                  properties: { editor_state: { description: 'Estado Lexical completo (full save).', type: object }, annotations: { type: array, items: { properties: { id: { type: string, example: obs_10944568 }, mark_id: { type: string, example: obs_10944568 }, note: { type: string, example: DSD }, x_pct: { type: number, format: float, example: 10.25 }, y_pct: { type: number, format: float, example: 17.87 } }, type: object } }, content_html: { type: string, nullable: true }, scenario: { type: string, enum: [resumo, leitura, reforco], nullable: true }, patch_editor_state: { description: 'JSON Patch ops (modo patch).', type: array, items: { type: object } }, annotations_delta: { description: 'upsert[]/remove[] (modo patch).', type: object }, base_version: { description: 'Versão base esperada (modo patch).', type: integer } }
                  type: object
              type: object
      responses:
        '200':
          description: 'Draft consolidado (artifact_id, version, editor_state, annotations).'
        '401':
          description: 'Token inválido ou expirado.'
        '404':
          description: 'Matrícula fora do escopo do usuário.'
        '409':
          description: 'Conflito de versão (patch) ou artifact inexistente para patch.'
        '422':
          description: 'Payload inválido (editor_state/annotations).'
  /api/v1/platform/notifications:
    get:
      tags:
        - Notifications
      summary: 'Notificações do sistema (bell icon).'
      description: "Lista notificações do Aluno.\n\nNotificações do sistema exibidas no bell icon (Header).\nInclui: alteração de conteúdo, devolutivas, lembretes,\ncomunicados e outros avisos operacionais/pedagógicos."
      operationId: 335956de24f589f0e326d7444740ce05
      parameters:
        -
          name: unread_only
          in: query
          description: 'Filtrar apenas não lidas. Default: false.'
          required: false
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: 'Lista de notificações.'
          content:
            application/json:
              schema:
                properties:
                  unread_count: { type: integer }
                  notifications: { type: array, items: { properties: { id: { type: string }, title: { type: string }, body: { type: string, nullable: true }, read: { type: boolean }, created_at: { type: string, format: date-time }, action: { description: 'Semantic action — see contratos/actions.md.', properties: { kind: { type: string, enum: [open_slot, open_study_roadmap, open_block, open_discipline, open_flashcards, open_exam, open_notebook, open_modal, open_external, dismiss] }, label: { type: string }, params: { type: object, nullable: true } }, type: object, nullable: true } }, type: object } }
                type: object
        '401':
          description: 'Token inválido ou expirado.'
          content:
            application/json:
              schema:
                properties:
                  error: { type: string, example: unauthorized }
                type: object
  '/api/v1/platform/onboarding/{enrolment_id}':
    get:
      tags:
        - Platform
      summary: 'Configuração do Onboarding (steps e perguntas).'
      description: "Retorna a configuração do Onboarding (steps + perguntas) para a fase\npendente da Matrícula. O Frontend renderiza genericamente — não\nhardcoda steps.\n\nTipos de input no nível do step:\n- multi_select  : múltipla escolha (com max_selections)\n- single_select : escolha única\n- slider        : valor numérico em faixa (min/max/step)\n\nCada `option` pode opcionalmente declarar `label_template` (com\nplaceholders `{key}`) + `inputs[]` para inputs embarcados (text,\ninteger). O Frontend renderiza inputs inline na posição do\nplaceholder, em qualquer ponto da frase."
      operationId: 7ef95c0e8e055a5675cf4b21c4fff27c
      parameters:
        -
          name: enrolment_id
          in: path
          description: 'ID da Matrícula (enrolment).'
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: 'Configuração dos steps do Onboarding.'
          content:
            application/json:
              schema:
                properties:
                  enrolment_id: { type: integer }
                  phase: { type: string, enum: [general, complement] }
                  completed: { type: boolean }
                  steps: { type: array, items: { properties: { key: { description: 'Identificador semântico do step.', type: string }, type: { type: string, enum: [info, question] }, title: { type: string }, subtitle: { type: string, nullable: true }, description: { type: string, nullable: true }, hint: { type: string, nullable: true }, action: { type: string, nullable: true }, input: { properties: { type: { type: string, enum: [multi_select, single_select, slider] }, max_selections: { type: integer, nullable: true }, min: { type: integer, nullable: true }, max: { type: integer, nullable: true }, step: { type: integer, nullable: true }, unit: { type: string, nullable: true }, options: { type: array, items: { properties: { value: { type: string }, label: { type: string, nullable: true }, label_template: { description: 'Template com placeholders `{key}` substituídos pelos inputs[].', type: string, nullable: true }, icon: { type: string, nullable: true }, inputs: { description: 'Inputs embarcados no label_template — renderizados inline.', type: array, items: { properties: { key: { type: string }, type: { type: string, enum: [text, integer] }, min: { type: integer, nullable: true }, max: { type: integer, nullable: true }, placeholder: { type: string, nullable: true }, required: { type: boolean } }, type: object }, nullable: true } }, type: object }, nullable: true } }, type: object, nullable: true } }, type: object } }
                type: object
        '401':
          description: 'Token inválido ou expirado.'
          content:
            application/json:
              schema:
                properties:
                  error: { type: string, example: unauthorized }
                type: object
        '404':
          description: 'Inscrição não encontrada ou não pertence ao usuário.'
          content:
            application/json:
              schema:
                properties:
                  error: { type: string, example: enrolment_not_found }
                type: object
        '409':
          description: 'Onboarding já concluído para esta inscrição.'
          content:
            application/json:
              schema:
                properties:
                  error: { type: string, example: onboarding_already_completed }
                type: object
  '/api/v1/platform/onboarding/{enrolment_id}/submit':
    post:
      tags:
        - Platform
      summary: 'Envia respostas do Onboarding.'
      description: "Recebe respostas do Onboarding e conclui a fase atual.\n\nForma do `value` em `answers[]` (heterogêneo conforme input.type):\n- slider:        number  ex: 25\n- single_select: string OU {option, inputs?} quando a option escolhida\ndeclara `inputs[]`     ex: \"never\" | {option:\"yes\", inputs:{count:3}}\n- multi_select:  string[] OU array<{option, inputs?}>\n\nQuando o Onboarding fica completo (última fase aplicável submetida):\n- Backend emite `onboarding_completed_signal` (async)\n- Resposta retorna `student_plan = {id: null, status: \"creating\"}`\n- Frontend faz polling em GET /platform/enrolments até `student_plan.id` aparecer"
      operationId: 0011053a0f222db48aadf9994892aabe
      parameters:
        -
          name: enrolment_id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                answers:
                  type: array
                  items: { properties: { key: { type: string }, value: { description: 'Tipo depende do input.type do step. Pode ser primitivo ou objeto {option, inputs}.' } }, type: object }
              type: object
            example:
              answers:
                -
                  key: step1
                  value: [promotor, juiz]
                -
                  key: step2
                  value: { option: prestei, inputs: { count: 3 } }
                -
                  key: step3
                  value: PasseiMasNaoAvancei
                -
                  key: step4
                  value: faseObjetiva
                -
                  key: step5
                  value: entre1AnoE2Anos
                -
                  key: step6
                  value: 25
      responses:
        '200':
          description: 'Respostas salvas. Indica próxima fase ou conclusão (com Plano do Aluno em criação assíncrona).'
          content:
            application/json:
              schema:
                properties:
                  success: { type: boolean }
                  phase_completed: { type: string, enum: [general, complement] }
                  next_phase: { type: string, enum: [complement], nullable: true }
                  onboarding_completed: { type: boolean }
                  first_access: { description: 'Sempre false neste response — first_access conceitual ocorre quando o handler async cria o Plano do Aluno.', type: boolean }
                  student_plan: { properties: { id: { description: 'null enquanto o handler async não criou — Frontend faz polling.', type: integer, nullable: true }, status: { type: string, enum: [creating], nullable: true } }, type: object }
                  redirect: { type: string, nullable: true }
                type: object
        '401':
          description: 'Token inválido ou expirado.'
          content:
            application/json:
              schema:
                properties:
                  error: { type: string, example: unauthorized }
                type: object
        '404':
          description: 'Inscrição não encontrada ou não pertence ao usuário.'
          content:
            application/json:
              schema:
                properties:
                  error: { type: string, example: enrolment_not_found }
                type: object
        '409':
          description: 'Onboarding já concluído.'
          content:
            application/json:
              schema:
                properties:
                  error: { type: string, example: onboarding_already_completed }
                type: object
        '422':
          description: 'Respostas incompletas, fora de schema ou fora dos limites.'
          content:
            application/json:
              schema:
                properties:
                  error: { type: string, example: validation_error }
                  message: { type: string }
                  errors: { type: array, items: { properties: { step_key: { type: string }, field: { type: string, nullable: true }, message: { type: string } }, type: object } }
                type: object
  '/api/v1/platform/study/{enrolment_id}/performance':
    get:
      tags:
        - Performance
      summary: 'Desempenho agregado do Aluno (todas as dimensões).'
      description: "Desempenho agregado do Aluno — todas as dimensões.\n\nRetorna overall, by_discipline, by_module, by_source,\nby_exam_type, flashcard_practice, progress e weekly em uma única resposta."
      operationId: 96ad25605ddf3f84a7135642edb7e733
      parameters:
        -
          name: enrolment_id
          in: path
          description: 'ID da Matrícula (contexto ativo).'
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: 'Métricas: overall, by_discipline, by_module, by_source, by_exam_type, flashcard_practice, progress, weekly.'
          content:
            application/json:
              schema:
                properties:
                  enrolment_id: { type: integer }
                  overall: { properties: { score: { type: number }, trend: { type: string, enum: [up, down, stable] }, total_activities: { type: integer }, total_time_minutes: { type: integer } }, type: object }
                  by_discipline: { type: array, items: { type: object } }
                  by_module: { description: 'Desempenho por Módulo: score, units_studied, by_discipline[] e by_exam_type[] (Objetivo/VF/Escrito por Módulo, com placeholder score=null quando não realizado).', type: array, items: { type: object } }
                  by_exam_type: { type: array, items: { type: object } }
                  by_source: { description: 'Desempenho por Tipo de Fonte: {source: legislation|doctrine|jurisprudence, total, correct, score}.', type: array, items: { type: object } }
                  flashcard_practice: { properties: { sessions_total: { type: integer }, cards_reviewed: { type: integer }, cards_correct: { description: 'Acertos acumulados (Estatísticas Gerais de Flashcards).', type: integer }, cards_incorrect: { description: 'Erros acumulados (Estatísticas Gerais de Flashcards).', type: integer }, accuracy: { type: integer }, trend: { type: string, enum: [up, down, stable] } }, type: object }
                  progress: { properties: { percentage: { type: number }, units_studied: { type: integer }, units_total: { type: integer }, units_exempted: { description: 'Unidades Economizadas via Dispensa (total cumulativo).', type: integer } }, type: object }
                  weekly: { description: 'Semana calendário atual vs anterior: {current,previous,deltas} com avg_score, avg_exam_time_min, units_completed, units_reviewed.', properties: { current: { type: object }, previous: { type: object }, deltas: { type: object } }, type: object }
                type: object
        '401':
          description: 'Token inválido ou expirado.'
          content:
            application/json:
              schema:
                properties:
                  error: { type: string, example: unauthorized }
                type: object
        '404':
          description: 'Matrícula não encontrada.'
          content:
            application/json:
              schema:
                properties:
                  error: { type: string, example: enrolment_not_found }
                type: object
  '/api/v1/platform/study/{enrolment_id}/slots/{slot_id}':
    get:
      tags:
        - Slot
      summary: 'Detalhe do slot (context enriquecido para execução).'
      description: "Detalhe do slot com context enriquecido para execução.\n\nRetorna a estrutura agnóstica do slot (REF-90-A §7) com context{}\ncompleto pelo tipo de atividade: questões, flashcards, conteúdo, etc.\nO Frontend renderiza genericamente com base em slot.type."
      operationId: 98c0359cec696166ec1b5a684cd1dcb7
      parameters:
        -
          name: enrolment_id
          in: path
          description: 'ID da Matrícula (contexto ativo).'
          required: true
          schema:
            type: integer
        -
          name: slot_id
          in: path
          description: 'UUID do slot (pré-gerado pelo Motor de Execução).'
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: 'Slot com context enriquecido pelo tipo de atividade.'
          content:
            application/json:
              schema:
                properties:
                  id: { description: 'UUID do Slot.', type: string, format: uuid }
                  order: { type: integer }
                  type: { type: string, enum: [diagnostic_initial, diagnostic_verify, guided_study, exam_written, exam_objective, exam_truefalse, flashcard_practice, general_review] }
                  status: { type: string, enum: [not_started, in_progress, completed, locked, skipped, dispensed] }
                  label: { type: string }
                  scope: { description: 'JSON: disciplines + units no escopo.', type: object, nullable: true }
                  context: { description: 'Metadados estáticos por tipo. Para diagnostic_initial/diagnostic_verify inclui has_not_sure_option, feedback_criteria e progresso (questions_done, questions_total, progress_percent). Questões selecionadas vêm em session.data após start.', type: object }
                  result: { type: object, nullable: true }
                  locked: { type: object, nullable: true }
                  action: { type: object, nullable: true }
                type: object
        '401':
          description: 'Token inválido ou expirado.'
          content:
            application/json:
              schema:
                properties:
                  error: { type: string, example: unauthorized }
                type: object
        '403':
          description: 'Slot locked — não acessível.'
          content:
            application/json:
              schema:
                properties:
                  error: { type: string, example: slot_locked }
                type: object
        '404':
          description: 'Matrícula ou slot não encontrado.'
          content:
            application/json:
              schema:
                properties:
                  error: { type: string, example: slot_not_found }
                type: object
    post:
      tags:
        - Slot
      summary: 'Submissão final de atividade no slot.'
      description: "Submissão final de uma atividade no slot.\n\nTransiciona o slot para completed e retorna result + effects[].\nA session correspondente também transiciona para completed.\nIdempotência: 409 se slot já completed."
      operationId: 5f79d5068edfe8085b4bcd38da885bf3
      parameters:
        -
          name: enrolment_id
          in: path
          description: 'ID da Matrícula (contexto ativo).'
          required: true
          schema:
            type: integer
        -
          name: slot_id
          in: path
          description: 'UUID do slot.'
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        description: 'Shape de `data` varia por slot.type. Frontend descobre o tipo via GET prévio do slot e escolhe o schema correspondente entre os 4 alternativos abaixo.'
        required: true
        content:
          application/json:
            schema:
              required:
                - action
                - data
              properties:
                action:
                  type: string
                  enum: [submit]
                data:
                  description: 'Dados de submissão. Schema concreto depende de slot.type (ver `oneOf`).'
                  oneOf: [{ title: SlotDiagnosticSubmitData, description: 'diagnostic_initial e diagnostic_verify — agrupado por unit_id.', required: [units], properties: { units: { type: array, items: { required: [unit_id, responses], properties: { unit_id: { type: integer, example: 12 }, responses: { type: array, items: { properties: { question_id: { type: integer, example: 101 }, answer: { description: '"V" ou "F".', type: string, example: V }, not_sure: { description: 'Aluno marcou "não tenho certeza".', type: boolean, default: false } }, type: object } } }, type: object } } }, type: object }, { title: SlotObjectiveResponsesSubmitData, description: 'exam_objective, exam_truefalse, general_review — questões com gabarito server-side.', required: [responses], properties: { responses: { type: array, items: { properties: { question_id: { type: integer, example: 201 }, answer: { description: '"A"-"E" para objetivas; "V"/"F" para VF.', type: string, example: B }, not_sure: { type: boolean, default: false }, timems: { description: 'Tempo gasto na questão em ms.', type: integer, nullable: true } }, type: object } }, rg_number: { description: 'Específico de general_review — número de identificação do simulado de revisão (RG1-RG6+), opcional.', type: string, nullable: true } }, type: object }, { title: SlotFlashcardSubmitData, description: 'flashcard_practice — auto-avaliação: aluno marca soube/não soube por card.', required: [responses], properties: { responses: { type: array, items: { properties: { card_id: { description: 'ID do flashcard.', type: integer, example: 4201 }, knew: { description: 'true = soube; false = não soube.', type: boolean }, timems: { description: 'Tempo gasto em ms (`time_ms` também aceito).', type: integer, nullable: true } }, type: object } } }, type: object }, { title: SlotWrittenSubmitData, description: 'exam_written — texto da redação. Após submit, slot transiciona para pending_correction (aguarda Tutor).', required: [text], properties: { text: { description: 'Texto completo da redação do Aluno.', type: string } }, type: object }, { title: SlotGuidedStudySubmitData, description: 'guided_study — resumo / artefato produzido pelo Aluno durante estudo dirigido.', required: [content_html], properties: { content_html: { description: 'Conteúdo HTML produzido pelo Aluno.', type: string }, scenario: { description: 'Modalidade da prática.', type: string, default: resumo }, source_origin: { description: 'Origem do artefato.', type: string, default: student }, unit_id: { type: integer, nullable: true } }, type: object }]
              type: object
            examples:
              diagnostic:
                summary: 'Diagnóstico Inicial / Verificação (V/F por unidade)'
                value:
                  action: submit
                  data: { units: [{ unit_id: 12, responses: [{ question_id: 101, answer: V, not_sure: false }, { question_id: 102, answer: F, not_sure: true }] }] }
              objective:
                summary: 'Simulado Objetivo / VF / General Review'
                value:
                  action: submit
                  data: { responses: [{ question_id: 301, answer: B, not_sure: false }, { question_id: 302, answer: A }] }
              flashcard:
                summary: 'Prática com Flashcards — soube/não soube por card'
                value:
                  action: submit
                  data: { responses: [{ card_id: 4201, knew: true, timems: 4500 }, { card_id: 4202, knew: false, timems: 7200 }] }
              written:
                summary: 'Simulado Escrito (redação) — texto livre'
                value:
                  action: submit
                  data: { text: 'Texto completo da redação do Aluno...' }
              guided_study:
                summary: 'Estudo Dirigido — resumo HTML do Aluno'
                value:
                  action: submit
                  data: { content_html: '<p>Resumo do Aluno em HTML...</p>', scenario: resumo, source_origin: student, unit_id: 12 }
      responses:
        '200':
          description: 'Slot finalizado. `slot.result` carrega `activity_submit_result_dto` serializado pelo handler do tipo.'
          content:
            application/json:
              schema:
                properties:
                  success: { type: boolean }
                  slot: { properties: { id: { description: 'UUID do Slot.', type: string, format: uuid }, status: { description: 'Estado pós-submit: `completed` para objetivos/VF/flashcards/diagnósticos/guided_study; `pending_correction` para simulado escrito (aguarda Tutor); `exempted` quando handler dispensa.', type: string, enum: [completed, pending_correction, exempted] }, result: { description: 'activity_submit_result_dto. `extra` carrega payload type-specific (ex.: diagnostic → units[] + cda_status; written → submission_id).', properties: { slot_id: { type: integer, example: 12345 }, session_id: { type: integer, example: 999 }, result_id: { description: 'Null quando pending_correction (ainda não há activity_result).', type: integer, example: 7777, nullable: true }, nota_real: { description: 'Nota Real (0-100). Null para escrito antes da correção e para guided_study.', type: number, format: float, example: 80, nullable: true }, completion_status: { type: string, enum: [completed, pending_correction, exempted] }, signals_emitted: { description: 'Slugs canônicos dispatched durante o submit (ex.: `cda_classification_done`, `activity_completed`).', type: array, items: { type: string } }, extra: { description: 'Payload type-specific. Diagnóstico: {units[], cda_status, completed_at}. Escrito: {submission_id}. Demais: vazio.', type: object } }, type: object } }, type: object }
                  effects: { description: 'Espelha `result.signals_emitted`. Frontend pode usar para optimistic UI (slot_unlocked, block_progress) sem refetch.', type: array, items: { type: string } }
                type: object
        '401':
          description: 'Token inválido ou expirado.'
          content:
            application/json:
              schema:
                properties:
                  error: { type: string, example: unauthorized }
                type: object
        '404':
          description: 'Matrícula ou slot não encontrado.'
          content:
            application/json:
              schema:
                properties:
                  error: { type: string, example: slot_not_found }
                type: object
        '409':
          description: 'Slot já completed (idempotência).'
          content:
            application/json:
              schema:
                properties:
                  error: { type: string, example: slot_already_completed }
                type: object
        '422':
          description: 'Dados de submissão inválidos.'
          content:
            application/json:
              schema:
                properties:
                  error: { type: string, example: validation_failed }
                  details: { type: object, nullable: true }
                type: object
  '/api/v1/platform/study/{enrolment_id}/slots/{slot_id}/session':
    get:
      tags:
        - Slot
      summary: 'Estado da sessão de execução do Aluno.'
      description: "Estado da sessão de execução do Aluno no slot.\n\nRetorna o estado dinâmico: respostas dadas, progresso, tempo gasto.\nA session é criada via POST action=start e persiste até o submit.\nPause/resume opera na mesma session — 1 session por slot por vez.\n\nTerms: Sessão de Execução, Sessão de Questionário, Sessão de Flashcards."
      operationId: a9831747f2e448ddbc5aed4f6d59e145
      parameters:
        -
          name: enrolment_id
          in: path
          description: 'ID da Matrícula (contexto ativo).'
          required: true
          schema:
            type: integer
        -
          name: slot_id
          in: path
          description: 'UUID do slot.'
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: 'Estado da sessão: respostas, progresso, tempo.'
          content:
            application/json:
              schema:
                properties:
                  id: { description: 'ID da Sessão (helico_items.id).', type: integer }
                  status: { type: string, enum: [not_started, in_progress, paused, completed] }
                  started_at: { type: integer, nullable: true }
                  paused_at: { type: integer, nullable: true }
                  time_spent_seconds: { type: integer }
                  data: { description: 'Payload inicial (questões selecionadas no DI/SVD).', type: object, nullable: true }
                  answers: { type: array, items: { properties: { question_id: { type: integer, nullable: true }, answer: { type: string, nullable: true }, not_sure: { type: boolean }, sortorder: { type: integer } }, type: object } }
                type: object
        '401':
          description: 'Token inválido ou expirado.'
          content:
            application/json:
              schema:
                properties:
                  error: { type: string, example: unauthorized }
                type: object
        '404':
          description: 'Matrícula, slot ou session não encontrado.'
          content:
            application/json:
              schema:
                properties:
                  error: { type: string, enum: [slot_not_found, session_not_found] }
                type: object
    post:
      tags:
        - Slot
      summary: 'Ações operacionais na sessão (start, save, pause, resume).'
      description: "Ações operacionais na sessão de execução.\n\nActions: start (criar session), save (progresso), pause, resume.\nTransições: start → in_progress, pause → paused, resume → in_progress.\nSave não altera status — apenas persiste progresso intermediário."
      operationId: ba4ca5625e0ed64391705ff088eb1733
      parameters:
        -
          name: enrolment_id
          in: path
          description: 'ID da Matrícula (contexto ativo).'
          required: true
          schema:
            type: integer
        -
          name: slot_id
          in: path
          description: 'UUID do slot.'
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                action:
                  type: string
                  enum: [start, save, pause, resume]
                data:
                  description: 'Dados de progresso (varia por type e action).'
                  type: object
              type: object
            example:
              action: start
              data: []
      responses:
        '200':
          description: 'Session atualizada (apenas action=start implementado nesta versão).'
          content:
            application/json:
              schema:
                properties:
                  success: { type: boolean }
                  session: { properties: { id: { description: 'ID da Sessão criada.', type: integer }, status: { type: string, enum: [in_progress] }, started_at: { type: integer }, data: { description: 'Para DI/SVD: lista de Unidades + questões V/F selecionadas.', type: object, nullable: true } }, type: object }
                type: object
        '401':
          description: 'Token inválido ou expirado.'
          content:
            application/json:
              schema:
                properties:
                  error: { type: string, example: unauthorized }
                type: object
        '404':
          description: 'Matrícula ou slot não encontrado.'
          content:
            application/json:
              schema:
                properties:
                  error: { type: string, example: slot_not_found }
                type: object
        '409':
          description: 'Session já ativa (start) ou slot completed.'
          content:
            application/json:
              schema:
                properties:
                  error: { type: string, enum: [session_already_active, slot_already_completed] }
                type: object
        '422':
          description: 'Ação inválida para o estado atual.'
          content:
            application/json:
              schema:
                properties:
                  error: { type: string, example: invalid_action_for_state }
                type: object
  '/api/v1/platform/study/{enrolment_id}/slots/{slot_id}/topics/{topic_id}':
    get:
      tags:
        - Slot
      summary: 'Estado atual de um Tópico (Estudo Dirigido — ADR-91).'
      description: "Estado atual de um Tópico em slot `guided_study`. Retorna metadata do\nTópico (title, synthesis HÉLICO) + draft persistido (artifact_id,\nversion, editor_state, content_html, annotation_count, last_saved_at)\nquando Aluno já salvou. `draft = null` quando Tópico nunca foi salvo."
      operationId: 39eda7ecd39671a774d98bea37ca09e4
      parameters:
        -
          name: enrolment_id
          in: path
          required: true
          schema:
            type: integer
        -
          name: slot_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        -
          name: topic_id
          in: path
          required: true
          schema:
            type: integer
  '/api/v1/platform/study/{enrolment_id}':
    get:
      tags:
        - Study
      summary: 'Roteiro de Estudos (bloco atual + slots).'
      description: "Roteiro de Estudos — bloco atual com slots pré-gerados.\n\nRetorna o Fluxo Atual, Bloco Atual, etapa, plano (disciplinas/unidades),\nresultado agregado do bloco e slots com estrutura agnóstica.\nSlots são pré-gerados pelo Motor de Execução — idempotência por UUID."
      operationId: a86206b239124b2080172c961539292f
      parameters:
        -
          name: enrolment_id
          in: path
          description: 'ID da Matrícula (contexto ativo).'
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: 'Roteiro: fluxo atual, bloco atual, plano, result agregado, slots.'
          content:
            application/json:
              schema:
                properties:
                  current_flow: { properties: { id: { type: integer }, flowref: { description: 'Identificador estável do Fluxo na sequência. Módulos: `<plan_ref>_rN`. Fluxos Revisionais: `revisional_N`.', type: string }, name: { description: 'Nome amigável apresentado ao Aluno. Módulos: "Módulo N" (vem de `module_number`). Fluxos Revisionais: "Revisão Geral".', type: string }, type: { type: string, enum: [module, revisional] }, status: { type: string, enum: [atual, futuro, concluido] }, sort_order: { description: 'Ordem monotônica única do Fluxo no Plano (Módulos + Revisionais). NÃO é ordinal apresentável de Módulo — use `module_number` ou o `name`.', type: integer }, context: { type: object } }, type: object }
                  current_block: { properties: { id: { type: integer }, blockref: { type: string }, type: { type: string, enum: [cda, exam_written, module_review, general_review, objective_exam, reading] }, name: { type: string }, status: { type: string, enum: [atual, futuro, concluido] }, sort_order: { type: integer }, context: { description: "Metadados por tipo de Bloco:\n\n- `exam_written`: `{ completion_deadline: string|null (ISO 8601), info_html: string }`.\n- `general_review` (Bloco de Revisão Geral dentro do Fluxo Revisional):\n  `{ dispensed_units_count: int, info_html: string }`.\n  `dispensed_units_count` conta Unidades da Janela de Revisão dispensadas\n  (`slot.status = dispensed`).\n  `info_html` interpola `rg_number` (Etapa) na orientação ao Aluno.\n- `objective_exam` em Fluxo Revisional:\n  `{ info_html: string, recommended_duration_seconds: int }`.\n  Tempo recomendado em segundos (default 14400 = 4h00).\n- Demais tipos: objeto vazio `{}`.", type: object } }, type: object }
                  next_flow: { description: 'Preview do próximo Fluxo (null no último). Leitura — não muta estado. Quando ainda não materializado, `id` vem null e payload carrega só o esqueleto (`name`, `flow_type`, `sort_order`, `status`, `blocks=[]`).', properties: { id: { type: integer, nullable: true }, flowref: { type: string }, name: { type: string }, flow_type: { type: string, enum: [module, revisional] }, status: { type: string, enum: [atual, futuro, concluido] }, sort_order: { type: integer }, blocks: { type: array, items: { type: object } } }, type: object, nullable: true }
                  stage: { properties: { stage_number: { type: integer }, modules_per_stage: { type: integer }, flow_ids: { type: array, items: { type: string } } }, type: object, nullable: true }
                  plan: { properties: { disciplines: { description: 'Disciplinas do Bloco. Para `module_review`, cada Disciplina retorna apenas com Unidades que têm Flashcards no Plano; Disciplinas sem Flashcards são omitidas. Demais tipos: `units` = [] (preservado).', type: array, items: { properties: { id: { type: string }, idnumber: { type: string }, name: { type: string }, units: { description: 'Unidades enriquecidas no `module_review` (unit_id, unit_shortname, unit_name, flashcards_total). Outros Blocos retornam lista vazia.', type: array, items: { properties: { unit_id: { type: integer }, unit_shortname: { type: string }, unit_name: { type: string }, flashcards_total: { type: integer } }, type: object } } }, type: object } } }, type: object }
                  result: { properties: { slots_total: { type: integer }, slots_completed: { type: integer }, slots_in_progress: { type: integer }, slots_locked: { type: integer }, slots_skipped: { type: integer }, slots_dispensed: { type: integer }, slots_not_started: { type: integer }, completion_percentage: { type: integer } }, type: object }
                  slots: { type: array, items: { properties: { id: { description: 'UUID do Slot.', type: string, format: uuid }, order: { type: integer }, type: { type: string, enum: [diagnostic_initial, diagnostic_verify, guided_study, exam_written, exam_objective, exam_truefalse, flashcard_practice, general_review] }, status: { type: string, enum: [not_started, in_progress, completed, locked, skipped, dispensed] }, label: { type: string }, scope: { type: object, nullable: true }, context: { description: "Metadados por tipo de Slot:\n\n- `diagnostic_initial` / `diagnostic_verify`: `{ questions_done: int, questions_total: int, progress_percent: int (0-100) }`.\n- `exam_written`: slot único por Fluxo (agrega Disciplinas com Questão\n  Escrita). `questions_total` vem do pool cross-Disciplina persistido em\n  `ctx_questions_total`. Inclui `questions_done`, `progress_percent`.\n- `exam_objective` em Fluxo Revisional (Bloco de Simulado Objetivo\n  pós-Revisão Geral): `{ rg_number, phase (crescimento|deslizamento|cumulativo),\n  window_module_ids: int[], questions: [{id, correct_answer}, ...],\n  questions_total: int }`. Pool de 100 questões selecionadas pelo\n  Critério de Priorização do Simulado Objetivo (`objective_priority_service`)\n  sobre o escopo da Janela de Revisão.\n- `general_review` (per:unit, 1 slot por Unidade da Janela):\n  ```\n  {\n    \"rg_number\": int,\n    \"phase\": \"crescimento|deslizamento|cumulativo\",\n    \"unit_meta\": {\n      \"incidence\": \"INCIDENCIA_BAIXA|MEDIA|ALTA\",\n      \"importance\": \"RELEVANCIA_BAIXA|MEDIA|ALTA\",\n      \"cda_level\": \"basico|intermediario|avancado|''\",\n      \"cda_source\": \"unit_combined|di|svd|''\",\n      \"cda_score\": float\n    },\n    \"material\": {\n      \"topics\": [{id, order, title, subtitle, synthesis, observations, tags[]}],\n      \"video\": { id, title, url, duration } | null,\n      \"legislation\": \"html string\",\n      \"jurisprudence\": \"html string\",\n      \"flashcards_endpoint\": \"/local/helico/platform/v1/study/flashcards?student_plan_id=X&unit_id=Y\"\n    },\n    \"siblings_in_discipline\": [\n      { slot_id (uuid), unit_id, unit_name, status }\n    ],\n    \"revision_completed\": bool,\n    \"performance\": {\n      \"exam_truefalse\": [],\n      \"exam_objective\": [],\n      \"exam_written\": []\n    }\n  }\n  ```\n  `performance` carrega histórico do Aluno na Unidade (3 buckets:\n  Simulado VF / Objetivo / Escrito). Estrutura definida; data wiring\n  pendente — buckets vazios até PR seguinte. `revision_completed`\n  reflete `slot.status === completed`.\n- `flashcard_practice`: `{ rg_number, phase }` em Fluxo Revisional;\n  vazio em `module_review`.\n- Demais tipos: objeto vazio `{}`.", type: object }, result: { type: object, nullable: true }, locked: { type: object, nullable: true }, action: { type: object, nullable: true } }, type: object } }
                type: object
        '401':
          description: 'Token inválido ou expirado.'
          content:
            application/json:
              schema:
                properties:
                  error: { type: string, example: unauthorized }
                type: object
        '404':
          description: 'Matrícula, plano, fluxo ou bloco atual não encontrado.'
          content:
            application/json:
              schema:
                properties:
                  error: { type: string, enum: [student_plan_not_found, no_current_flow, no_current_block] }
                type: object
  '/api/v1/platform/study/{enrolment_id}/current-block/skip':
    post:
      tags:
        - Study
      summary: 'Pula o Bloco Atual (module_review, exam_written, general_review ou objective_exam).'
      description: "Pula o Bloco Atual do Aluno (`module_review`, `exam_written`,\n`general_review` ou `objective_exam`).\n\nMarca todos os slots do Bloco como `skipped`, dispara avanço via\n`block_advance_service` e devolve o Roteiro recomposto sobre o novo\nBloco/Fluxo atual."
      operationId: bd8a3e572d6028d3163501bf68e072f6
      parameters:
        -
          name: enrolment_id
          in: path
          description: 'ID da Matrícula (contexto ativo).'
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: 'Roteiro recomposto após o skip.'
          content:
            application/json:
              schema:
                type: object
        '404':
          description: 'Matrícula, Plano, Fluxo ou Bloco atual ausente.'
          content:
            application/json:
              schema:
                properties:
                  error: { type: string, enum: [student_plan_not_found, no_current_flow, no_current_block] }
                type: object
        '409':
          description: 'Bloco Atual não suporta skip (ex: CDA, reading).'
          content:
            application/json:
              schema:
                properties:
                  error: { type: string, example: block_not_skippable }
                type: object
  '/api/v1/platform/study/{enrolment_id}/results':
    get:
      tags:
        - Study
      summary: 'Resultados detalhados do estudo (histórico).'
      description: "Resultados detalhados do estudo (histórico cross-blocos).\n\nRetorna summary agregado e lista de blocos concluídos com seus slots."
      operationId: 409cfece1cca9215d3c79693eb5916ed
      parameters:
        -
          name: enrolment_id
          in: path
          description: 'ID da Matrícula (contexto ativo).'
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: 'Summary + blocos concluídos com slots.'
          content:
            application/json:
              schema:
                properties:
                  summary: { properties: { blocks_completed: { type: integer }, blocks_total: { type: integer } }, type: object }
                  blocks: { type: array, items: { properties: { block_id: { type: integer }, block_type: { type: string }, flow_name: { type: string }, status: { type: string, enum: [atual, futuro, concluido] }, slots: { type: array, items: { properties: { slot_id: { description: 'UUID do Slot.', type: string, format: uuid }, type: { type: string }, label: { type: string }, status: { type: string }, result: { type: object, nullable: true } }, type: object } } }, type: object } }
                type: object
        '401':
          description: 'Token inválido ou expirado.'
          content:
            application/json:
              schema:
                properties:
                  error: { type: string, example: unauthorized }
                type: object
        '404':
          description: 'Matrícula não encontrada.'
          content:
            application/json:
              schema:
                properties:
                  error: { type: string, example: student_plan_not_found }
                type: object
  '/api/v1/platform/study/{enrolment_id}/progress':
    get:
      tags:
        - Study
      summary: 'Progresso atual do Aluno no produto ativo.'
      description: "Progresso atual do Aluno (\"Seu Andamento\").\n\nRetorna módulo atual, nome da trilha (cargo/carreira),\nporcentagem de progresso e ação para continuar estudo.\nDados derivados do Plano do Aluno (autônomo)."
      operationId: 918052b7368e8d551dd278b8d9b8b7b3
      parameters:
        -
          name: enrolment_id
          in: path
          description: 'ID da Matrícula (contexto ativo).'
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: 'Progresso: módulo atual, trilha, % e ação.'
          content:
            application/json:
              schema:
                properties:
                  student_plan: { properties: { id: { type: integer }, status: { type: string, enum: [not_started, active, blocked, interrupted, completed, closed] } }, type: object }
                  current_module: { properties: { id: { description: 'ID do Fluxo Atual (apresentado como Módulo).', type: integer }, name: { description: 'Nome amigável do Módulo.', type: string }, block_id: { description: 'ID do Bloco Atual.', type: integer } }, type: object }
                  trail_name: { description: 'Nome amigável da Trilha (cargo/carreira).', type: string }
                  progress: { properties: { percentage: { type: integer }, completed_blocks: { type: integer }, total_blocks: { type: integer } }, type: object }
                  action: { description: 'Semantic action — see contratos/actions.md', properties: { kind: { type: string, enum: [open_study_roadmap] }, label: { type: string }, params: { type: object, nullable: true } }, type: object }
                type: object
        '401':
          description: 'Token inválido ou expirado.'
          content:
            application/json:
              schema:
                properties:
                  error: { type: string, example: unauthorized }
                type: object
        '404':
          description: 'Matrícula não encontrada.'
          content:
            application/json:
              schema:
                properties:
                  error: { type: string, example: student_plan_not_found }
                type: object
  '/api/v1/platform/study/{enrolment_id}/disciplines':
    get:
      tags:
        - Study
      summary: 'Disciplinas do fluxo atual agrupadas por status.'
      description: "Disciplinas do fluxo atual, agrupadas pelo Backend.\n\nBackend agrupa unidades do fluxo atual por disciplina\n(corte pela carga horária do aluno). Frontend renderiza\ncards por disciplina: \"Em andamento\" e \"Não Iniciadas\".\n\nStatus da Disciplina no Roteiro:\n- not_started → Não Iniciada\n- in_progress → Em Execução\n- blocked → Bloqueada\n- completed → Concluída (disponível, omitido no Frontend atual)"
      operationId: 6bb615f4b3212efb108c8fb3d1a7ad77
      parameters:
        -
          name: enrolment_id
          in: path
          description: 'ID da Matrícula (contexto ativo).'
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: 'Disciplinas com contagem de unidades.'
          content:
            application/json:
              schema:
                properties:
                  disciplines: { type: array, items: { properties: { id: { description: 'ID canônico da Disciplina (string).', type: string }, name: { type: string }, status: { type: string, enum: [not_started, in_progress, blocked, completed] }, units_total: { type: integer }, units_completed: { type: integer } }, type: object } }
                type: object
        '401':
          description: 'Token inválido ou expirado.'
          content:
            application/json:
              schema:
                properties:
                  error: { type: string, example: unauthorized }
                type: object
        '404':
          description: 'Matrícula não encontrada.'
          content:
            application/json:
              schema:
                properties:
                  error: { type: string, example: student_plan_not_found }
                type: object
  '/api/v1/platform/study/{enrolment_id}/alerts':
    get:
      tags:
        - Study
      summary: 'Alertas acionáveis do estudo (per-enrollment).'
      description: "Alertas acionáveis do estudo (per-enrollment).\n\nTarefas pendentes vinculadas ao produto/matrícula ativa:\ncorreções disponíveis, simulados para revisão, desempenho mensal, etc.\nDiferente de Notificações (/platform/notifications) que são\navisos do sistema no bell icon do Header.\n\nCada alerta tem `action.type` para ação dinâmica no Frontend:\n- navigate: página interna simples\n- navigate_with_context: página interna com dados\n- modal: abre modal no Frontend\n- external: link externo\n- dismiss: apenas dispensar"
      operationId: 8b7e84d92ade1ed893ca843e7ef9ef5a
      parameters:
        -
          name: enrolment_id
          in: path
          description: 'ID da Matrícula (contexto ativo).'
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: 'Lista de alertas com ações dinâmicas.'
          content:
            application/json:
              schema:
                properties:
                  alerts: { type: array, items: { properties: { id: { type: string }, title: { type: string }, variant: { type: string, enum: [info, success, warning, error] }, popup_pending: { type: boolean }, action: { description: 'Semantic action — see contratos/actions.md.', properties: { kind: { type: string, enum: [open_slot, open_study_roadmap, open_block, open_discipline, open_flashcards, open_exam, open_exams, open_notebook, open_modal, open_external, open_retrospective, dismiss] }, label: { type: string }, params: { type: object, nullable: true } }, type: object } }, type: object } }
                type: object
        '401':
          description: 'Token inválido ou expirado.'
          content:
            application/json:
              schema:
                properties:
                  error: { type: string, example: unauthorized }
                type: object
        '404':
          description: 'Matrícula não encontrada.'
          content:
            application/json:
              schema:
                properties:
                  error: { type: string, example: student_plan_not_found }
                type: object
  '/api/v1/platform/study/{enrolment_id}/retrospective':
    get:
      tags:
        - Retrospective
      summary: 'Retrospectiva de conclusão do plano de estudos.'
      description: "Retrospectiva de conclusão do plano de estudos.\n\nRetorna 404 quando a feature está desligada ou o Plano do Aluno da\nmatrícula ainda não está `completed`."
      operationId: retrospective_get_enrolment_id_retrospective
      parameters:
        -
          name: enrolment_id
          in: path
          description: 'ID da Matrícula (contexto ativo).'
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: 'Dados da retrospectiva do ciclo de estudo concluído.'
          content:
            application/json:
              schema:
                type: object
        '401':
          description: 'Token inválido ou expirado.'
          content:
            application/json:
              schema:
                properties:
                  error: { type: string, example: unauthorized }
                type: object
        '404':
          description: 'Matrícula não pertence ao usuário, feature desligada ou plano ainda não concluído.'
          content:
            application/json:
              schema:
                properties:
                  error: { type: string, enum: [enrolment_not_found, retrospective_disabled, plan_not_completed] }
                type: object
  '/api/v1/platform/study/{enrolment_id}/retrospective/ack':
    post:
      tags:
        - Retrospective
      summary: 'Marca o popup de retrospectiva como já exibido (idempotente).'
      description: "Marca o popup de retrospectiva como já exibido para a matrícula.\n\nIdempotente: chamar mais de uma vez não falha nem sobrescreve o\ntimestamp original."
      operationId: retrospective_post_enrolment_id_retrospective_ack
      parameters:
        -
          name: enrolment_id
          in: path
          description: 'ID da Matrícula (contexto ativo).'
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: 'Popup marcado como exibido.'
          content:
            application/json:
              schema:
                properties:
                  success: { type: boolean, example: true }
                type: object
        '401':
          description: 'Token inválido ou expirado.'
          content:
            application/json:
              schema:
                properties:
                  error: { type: string, example: unauthorized }
                type: object
        '404':
          description: 'Matrícula não pertence ao usuário ou feature desligada.'
          content:
            application/json:
              schema:
                properties:
                  error: { type: string, enum: [enrolment_not_found, retrospective_disabled] }
                type: object
components:
  schemas:
    ExamDisciplineBreakdown:
      title: 'Desempenho por disciplina em um simulado'
      properties:
        discipline_id:
          type: integer
        name:
          type: string
          example: 'Direito Civil'
        correct:
          type: integer
          example: 8
        total:
          type: integer
          example: 10
        percentage:
          type: number
          format: float
          example: 80
      type: object
tags:
  -
    name: Admin/Correction
    description: 'Correção de Simulados Escritos pelo Tutor.'
  -
    name: Dashboard
    description: 'Resumo cross-product do Aluno.'
  -
    name: Exam
    description: 'Histórico de simulados e revisões/devolutivas.'
  -
    name: Flashcard
    description: 'Flashcards — browse por disciplina e prática livre.'
  -
    name: Platform
    description: 'Endpoints da plataforma HÉLICO para o Aluno.'
  -
    name: Notebook
    description: 'Caderno Online — artefatos produtivos do Aluno.'
  -
    name: Notifications
    description: 'Notificações do sistema para o Aluno.'
  -
    name: Performance
    description: 'Métricas agregadas de desempenho do Aluno.'
  -
    name: Retrospective
    description: 'Retrospectiva de conclusão do plano de estudos.'
  -
    name: Slot
    description: 'Detalhe do slot e session — execução de atividades.'
  -
    name: Study
    description: 'Endpoints de estudo contextualizados por matrícula.'
