Skip to content

ADR-91: Lexical state + autosave incremental no Estudo Dirigido

ADR-91: Lexical state + autosave incremental no Estudo Dirigido

Status: Aceito Data: 2026-05-14 Pillar: Platform (Gateway API) Relacionados: ADR-10, ADR-80, ADR-90

Contexto

O contrato original de Estudo Dirigido (guided_study) aceitava no submit um único content_html flat por slot:

{ "content_html": "<resumo HTML>", "scenario": "resumo", "source_origin": "student", "unit_id": 12 }

Limitações:

  • Granularidade insuficiente — 1 Unidade tem N Tópicos (unit_content). Resumo, Leitura e Leitura de Reforço operam tópico-a-tópico na Metodologia, mas o backend não conseguia distinguir.
  • Sem autosave durante a escrita — qualquer crash/recarregamento perdia o trabalho do Aluno até o submit final.
  • Sem editor state estruturado — content_html flat impede preservar sublinhados, anotações marginais e estado do editor entre sessões.
  • Sem reconciliação semântica — sublinhados e anotações ficavam fora do modelo de domínio (impossível listar/consultar annotations do Aluno).

O frontend HÉLICO usa Lexical como editor rico em todas as superfícies de produção textual (Caderno Online, Estudo Dirigido). O Lexical já carrega sublinhados e anotações como nodes custom no editor_state (JSON). Faltava ao backend reconhecer essa fonte de verdade.

Decisão

1. Granularidade por Tópico

notebook_artifact passa a ser 1 por (enrolment × unit × topic) ao invés de 1 por (enrolment × unit). topic_id torna-se meta obrigatória, referenciando o unit_content com parent=unit_id.

idnumber canônico:

notebook_artifact:enrolment:{enrolment_id}:unit:{unit_id}:topic:{topic_id}

2. Lexical state como fonte canônica única

O editor_state (JSON Lexical) é a fonte de verdade. content_html e a lista de notebook_annotation são projeções derivadas — backend reconcilia a cada save:

  • content_html (em description) é re-derivado do editor_state (frontend pode pré-enviar como dica; backend trata como cache opcional).
  • notebook_annotation (child items, type='notebook_annotation') é reconciliado walking o tree por mark.ids[].

Não duplicamos storage. Persistimos 1 vez (Lexical), derivamos o resto.

3. Mark + Annotation pattern

Sublinhados ficam inline no tree como nodes type='mark' do pacote @lexical/mark. Cada mark referencia 1+ entradas top-level via ids[]. A key casa com notebook_annotation.annotation_key.

// node mark dentro do editor_state
{ "type": "mark", "ids": ["h-7f3a"], "children": [{ "type": "text", "text": "trecho" }] }

// metadata top-level (sidebar)
{ "key": "h-7f3a", "color": "yellow", "comment": "importante p/ prova" }

Reconciliação por save:

Situação Ação
key no tree e no payload Upsert annotation com color + comment do payload
key no tree mas não no payload Mantém annotation; cria se ausente (comment vazio)
key no payload mas não no tree Descarta (mark removido — annotation órfã)
Annotation persistida cuja key sumiu do tree atual Remove

Sublinhado sobreposto (mesma key em ranges distintos) é suportado: backend agrupa por key única.

4. Status de ciclo de vida do artifact

Novo enum artifact_status em notebook_artifact:

  • draft — Aluno ainda salvando (autosave em curso, slot in_progress)
  • published — Aluno submeteu o slot (consolidação final)

Transição draft → published acontece apenas no submit do slot. Cada publicação cria um artifact_version snapshot (histórico imutável).

5. Autosave incremental no mesmo endpoint do slot

Reusa POST /api/v1/platform/study/{enrolment_id}/slots/{slot_id} com nova action=autosave. Não cria rota dedicada. Discriminação:

action Estado pré Efeito
submit in_progress Consolidação final; slot → completed; artifacts → published
autosave in_progress Rascunho granular de 1 Tópico; slot continua in_progress

action=autosave aceito apenas em slots guided_study. Granularidade: 1 Tópico por request (sem batch — debounce no frontend cobre o caso).

6. Patch incremental via JSON Patch

Frontend envia apenas a mudança no editor_state como JSON Patch (RFC 6902) sobre o estado armazenado, mais delta opcional em annotations.

Discriminação por Content-Type:

  • application/json → full save (estado completo)
  • application/json-patch+json → patch save (delta)

Concorrência optimistic via base_version (inteiro monotônico no meta editor_state_version do artifact):

  • Cliente envia base_version ao qual o patch corresponde.
  • Backend valida current_version == base_version antes de aplicar.
  • 409 version_conflict quando desatualizado → cliente refaz GET full
    • reenvia full save.

7. Single-writer assumido

Modelo single-writer: 1 Aluno = 1 dispositivo ativo por vez. Multi-writer real (colaboração simultânea entre tabs/devices) não está no escopo desta versão. Caso necessite, migrar para Yjs/CRDT — editor_state_format no meta permite essa evolução (lexical-json agora, yjs-binary futuro).

Consequências

Positivas

  • Granularidade pedagógica correta — operações tópico-a-tópico que a Metodologia espera (Leitura por Tópico, Reforço por Tópico após SVD).
  • Resiliência — autosave evita perda de trabalho em crashes ou troca de aba; rascunho preservado entre sessões.
  • Fonte de verdade única — editor_state elimina divergência entre HTML renderizado, annotations e estado do editor.
  • Payload reduzido — patch incremental envia poucos bytes em vez do documento completo a cada autosave.
  • Histórico granular — artifact_version snapshot por publicação, permitindo auditoria do que foi publicado.
  • Sidebar e analytics de annotations — backend tem index queryable por (annotation_key, color, artifact_id) para tutor/dashboard.

Negativas / Custos

  • Frontend computa diff — Lexical já notifica mudanças no editor, mas precisa lib JSON diff cliente-side.
  • Backend precisa de validador de JSON Patch — adoção de lib PHP (swaggest/json-diff ou equivalente).
  • Conflict resolution manual — 409 exige GET full + reenvio. Não há merge automático (esperado para single-writer).
  • Derivação content_html — adia para job assíncrono ou exige parser HTML→Lexical→HTML síncrono. V1: frontend pré-envia content_html como dica; backend o trata como cache opcional.
  • Reconciliação por walker — backend precisa percorrer o tree do editor_state a cada save (custo O(N) sobre N nodes — aceitável para documentos pedagógicos típicos de até alguns KB).

Trade-offs descartados

  • Yjs/CRDT desde o início — descartado por complexidade vs valor: PHP não tem port maduro do Yjs; single-writer cobre o caso real. Permanece como caminho de evolução se aparecer multi-device.
  • Rota dedicada /topics/{topic_id}/save — descartado em favor de reusar POST /slots/{slot_id} com action=autosave. Simetria com POST /session (que já usa action ∈ {start, save, pause, resume}) e menos rotas no Gateway.
  • Operation log domain-specific (apply_mark, insert_text, etc.) — descartado por exigir mapeamento manual de ops Lexical para um schema próprio do backend. JSON Patch sobre o JSON nativo é mais direto e suporta qualquer operação do editor sem mudança no contrato.

Schema impactado

notebook_artifact — meta estendido

METADATA_FIELDS = [
  'enrolment_id', 'student_plan_id', 'unit_id', 'discipline_id',
  'topic_id',                  # NOVO — FK lógica p/ unit_content
  'slot_id', 'session_id',
  'source_type', 'source_origin', 'visibility_scope',
  'artifact_status',           # NOVO — draft | published
  'editor_state_version',      # NOVO — inteiro monotônico
  'editor_state_format',       # NOVO — 'lexical-json' (futuro: 'yjs-binary')
  'last_interaction_at',
]

description continua sendo content_html (HTML projetado). editor_state (JSON Lexical) vai em meta dedicada (editor_state_json) ou storage paralelo quando documento ultrapassar threshold de tamanho.

notebook_annotation — entity nova

TYPE = 'notebook_annotation'
parent = notebook_artifact.id

METADATA_FIELDS = [
  'artifact_id',     # = parent (redundância p/ query)
  'topic_id',
  'annotation_key',  # casa com mark.ids[]
  'color',           # yellow | green | pink | blue | null
  'created_at',
  'updated_at',
]
# description = comment (long text)

Constraint conceitual: (artifact_id, annotation_key) único.

Sem migração legacy

Por decisão explícita, não há migração de artifacts antigos para o novo shape. Registros pré-existentes coexistem (com topic_id=null no meta) e são tratados como histórico. Toda gravação nova segue o shape canônico.

Validações canônicas

Campo Regra
editor_state.root.type Deve ser "root"
annotation_key [a-z0-9-]+ máx 64 chars
annotation.color yellow | green | pink | blue | null
annotation.comment Máx 2000 caracteres
topic_id Pertence ao unit_content com parent=unit_id
unit_id no submit Pertence ao slot.scope.units

Falhas → 422 com error específico (ver contrato em study.md).

Referências

Navigation

Type to search…

↑↓ navigate↵ selectEsc close