Word Detail Panel Specification¶

1) Visão geral¶

A tela de detalhe da palavra é uma mini-wiki linguística + painel de engenharia editorial.

Objetivos: - centralizar tudo que define qualidade lexical/morfológica - acelerar revisão antes de publicação - alimentar engine de avaliação token-level

2) Seções obrigatórias da tela¶

2.1 Header¶

Campos: - lemma - pos - cefr_level - base_lang - status (assets/forms/coverage)

Indicadores sugeridos: - Assets OK - Forms OK - Grammar linked - Coverage (sentenças)

2.2 Forms¶

Lista completa de word_forms.
Origem visual: gerada por regra vs irregular override vs manual.
Filtros por tense/aspect/number/person/degree.

2.3 Translations¶

Lista de traduções por idioma.
Lang switch (ex.: pt-BR, es, en).

2.4 Grammar¶

Conceitos em grammar_concepts ligados via word_grammar.
Mostrar resumo didático usado no curso.

2.5 Tags¶

Tags semânticas/pedagógicas (tags + word_tags).

2.6 Semantic relations¶

synonyms, antonyms, phrasal_verbs, derived_from (via semantic_relations).

2.7 Assets¶

Imagem, áudio, TTS.
Presets (provider/style/voice) e cache keys quando houver.

2.8 Usage¶

Frases (sentences) em que o termo aparece via sentence_tokens.
Coverage: total de tokens e sentenças únicas.

2.9 Teaching notes¶

Campo editorial para observações didáticas.
Reuso em resumo de aula e instruções ao professor.

2.10 QA checklist¶

Conteúdo pronto para publicar?
Checklist mínimo:
lemma válido
POS definido
forms mínimas presentes
ao menos 1 tradução
ao menos 1 exemplo de uso
links gramaticais essenciais

3) Contrato do endpoint existente¶

Endpoint oficial: - GET /admin/content-bank/vocabulary/:id/detail

Resposta esperada (shape atual + extensões compatíveis):

{
  "ok": true,
  "word": {
    "id": "uuid",
    "lemma": "go",
    "pos": "verb",
    "cefr_level": "A1",
    "frequency_rank": 120,
    "introduced_chapter": 1,
    "base_lang": "en",
    "universal_concept_id": "motion_go",
    "created_at": "...",
    "updated_at": "..."
  },
  "forms": [
    {
      "id": "uuid",
      "word_id": "uuid",
      "form": "went",
      "features": { "tense": "past" },
      "is_irregular": true,
      "created_at": "..."
    }
  ],
  "translations": [
    {
      "id": "uuid",
      "word_id": "uuid",
      "lang": "pt-BR",
      "translation": "ir",
      "context_note": null
    }
  ],
  "tags": [
    { "id": "uuid", "name": "core-verb", "kind": "pedagogical" }
  ],
  "grammar_concepts": [
    {
      "id": "uuid",
      "code": "EN_V_SIMPLE_PRESENT",
      "title": "Simple Present",
      "description": "Uso de verbos no presente simples"
    }
  ],
  "semantic_relations": [
    {
      "id": "uuid",
      "relation_type": "phrasal_verb",
      "created_at": "...",
      "related_word": {
        "id": "uuid",
        "lemma": "up",
        "pos": "particle",
        "base_lang": "en"
      }
    }
  ],
  "sentence_coverage": {
    "token_count": 42,
    "sentence_ids": ["uuid-1", "uuid-2"]
  },
  "future_stats": {
    "skill_usage_count": null,
    "morphology_accuracy_score": null
  }
}

3.1 Regras de robustez para cliente¶

Seções podem vir vazias ([]) e ainda assim resposta é válida.
Cliente deve tratar future_stats como opcional/expansível.
Ordem visual sugerida: header → forms → grammar/usage → QA.

4) Ação integrada com geração morfológica¶

A tela deve ter CTA: “Gerar formas”.

Fluxo: 1. Usuário abre palavra. 2. Clica em gerar. 3. Vê preview de forms + features. 4. Edita irregularidades. 5. Salva (upsert em word_forms).

Sem alterar contrato de rota existente; novas ações podem usar endpoint dedicado futuro.

7) Endpoint adicional (implementado)¶

POST /admin/content-bank/vocabulary/:id/forms/generate
mode=suggest: gera preview em memória (generated, conflicts).
mode=save: persiste em word_forms de forma idempotente, respeitando overwrite_policy=keep_manual (política conservadora: não sobrescreve existentes; apenas insere ausentes).
forms pode ser enviado para salvar edições manuais feitas no preview antes do persist.

Grammar Cards Content Bank (coerência cruzada)¶

grammar_concepts continuam sendo a ontologia gramatical usada no Word Detail (word_grammar).
grammar_cards usam os mesmos conceitos para material didático publicável, com examples ligados em sentences e áudio EN reaproveitado de tts_assets.