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_htmlflat 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(emdescription) é re-derivado doeditor_state(frontend pode pré-enviar como dica; backend trata como cache opcional).notebook_annotation(child items,type='notebook_annotation') é reconciliado walking o tree pormark.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, slotin_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_versionao qual o patch corresponde. - Backend valida
current_version == base_versionantes de aplicar. - 409
version_conflictquando 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_stateelimina 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_versionsnapshot 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-diffou 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é-enviacontent_htmlcomo dica; backend o trata como cache opcional. - Reconciliação por walker — backend precisa percorrer o tree do
editor_statea 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 reusarPOST /slots/{slot_id}comaction=autosave. Simetria comPOST /session(que já usaaction ∈ {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
- Contrato: study.md — Estudo Dirigido — Lexical state e autosave
- Domínio: ADR-80 — Activity
- Persistência: ADR-10 — EAV vs tabela própria
- Gateway: ADR-90 — Platform Gateway
- Versionamento: ADR-11 — Snapshot imutável
- Lexical mark plugin:
@lexical/mark(frontend HÉLICO) - JSON Patch: RFC 6902