Ir para o conteúdo

Como extrair campos de formulário para um novo mapeamento

Esta guia mostra como acelerar a criação de mapeamentos para sistemas SUS (e-SUS APS PEC, SISREG III, SEI, etc) usando scripts/extract-form-fields.py.

Quando usar

Quando você precisa adicionar suporte da extensão Anotae a um novo sistema (ou nova tela do mesmo sistema), e quer obter automaticamente os seletores DOM (id, name, label, aria-label, placeholder) dos campos de formulário em vez de inspecionar manualmente um por um.

Caminho A — A partir de HTML estático

Passo 1: capturar HTML

Em qualquer formulário aberto no navegador:

  1. Abra o DevTools (F12)
  2. Aba Console
  3. Cole: copy(document.documentElement.outerHTML) e pressione Enter
  4. Crie um arquivo formulario.html em qualquer pasta e cole o conteúdo

Passo 2: rodar extração

python scripts/extract-form-fields.py \
    --input formulario.html \
    --target-system "esus-aps-pec" \
    --mapping-id "esus-novo-formulario" \
    --output vocabularies/mappings/esus-novo-formulario.json

Saída: arquivo JSON pronto para virar mapping. Revise o campo source de cada entry (default "TBD" quando a heurística não reconhece) e edite vocabularies/mappings/esus-novo-formulario.json com os caminhos corretos do encounter (ex: encounter.soap.subjective).

Caminho B — A partir de HAR (HTTP Archive)

HAR é mais rico que HTML — registra todas as respostas HTML que o navegador recebeu durante uma sessão. Útil quando o formulário só aparece após login.

Passo 1: capturar HAR

  1. Abra DevTools (F12)
  2. Aba Network
  3. Limpe (🚫 Clear) e ative o gravador (●)
  4. Faça login + navegue até o formulário-alvo
  5. Botão direito em qualquer requisição → Save HAR with content
  6. Salva como sessao.har

Passo 2: anonimizar o HAR (recomendado)

HAR contém cookies, tokens de auth e talvez body de POST com dados do paciente. Antes de versionar ou compartilhar:

python scripts/extract-form-fields.py \
    --input sessao.har \
    --anonymize-har \
    --output sessao-anonimizada.har

O script remove: - Todos os cookies (request e response) - Headers Authorization, Cookie, Set-Cookie, X-Auth-Token, X-CSRF-Token - Query params com nome token, password, senha, cpf, cns, auth, session - Conteúdo de postData.text (substitui por <REDACTED>, mantém estrutura)

⚠️ Revise manualmente o HAR anonimizado antes de compartilhar — heurísticas podem não cobrir todos os campos sensíveis específicos do sistema.

Passo 3: extrair campos

python scripts/extract-form-fields.py \
    --input sessao-anonimizada.har \
    --target-system "sisreg" \
    --mapping-id "sisreg-solicitacao" \
    --output vocabularies/mappings/sisreg-solicitacao.json

O que sai

Arquivo JSON compatível com o resto do vocabularies/mappings/:

{
  "id": "esus-novo-formulario",
  "name": "TBD Mapping",
  "target_system": "esus-aps-pec",
  "target_version": "x.x",
  "version": "0.1.0-draft",
  "description": "Mapping rascunho gerado por scripts/extract-form-fields.py — REVISE 'source' e 'required' antes de usar.",
  "fields": [
    {
      "source": "soap.subjective",
      "target_selectors": [
        {"type": "id", "value": "subjetivo"},
        {"type": "label", "value": "Subjetivo"},
        {"type": "name", "value": "subjetivo"},
        {"type": "placeholder", "value": "Queixa..."}
      ],
      "required": false,
      "transform": null,
      "_extractor_hints": {"tag": "textarea", "input_type": ""}
    }
  ]
}

Heurísticas de propósito

O script tenta inferir o source (mapeamento para campo do encounter) por palavra-chave em id/name/aria-label/placeholder/label/title. Cobertura inicial (PT-BR + APS):

Palavra-chave Inferred purpose
subjetivo, queixa, anamnese, hda, antecedentes soap.subjective
objetivo, exame físico, sinais vitais soap.objective
avaliação, hipótese, diagnóstico soap.assessment
conduta, plano, prescrição, orientação soap.plan
cid / cid-10 cid10_codes
ciap / ciap-2 ciap2_codes
cns professional_cns
cpf professional_cpf
cnes professional.cnes
nome completo patient.full_name
nome (da) mãe patient.mother_name
data (de) nascimento patient.birth_date
prontuário patient.record_number
justificativa encounter.justification

Quando a heurística falha, o script grava source: "TBD" — você revisa manualmente.

Para adicionar novas heurísticas, edite _PURPOSE_HEURISTICS em scripts/extract-form-fields.py.

Limitações

  • Não executa JavaScript: campos renderizados dinamicamente (React/Angular após mount) só aparecem se você capturar HTML pós-render
  • Não captura listeners: eventos onChange, validações pattern etc não vão para o JSON
  • Heurísticas em PT-BR: campos com nomes em outras línguas viram source: "TBD"
  • <iframe>: HTML dentro de iframe não é seguido — capture o iframe separadamente

Próximos passos depois de gerar o mapping

  1. Renomear o arquivo para algo claro (esus-aps-pec-atendimento-individual.json)
  2. Revisar cada source — substituir "TBD" pelo caminho correto do encounter
  3. Marcar required: true nos campos críticos (CIAP-2, conduta)
  4. Remover _extractor_hints (são só pistas para você; o engine não usa)
  5. Testar: rodar a extensão Anotae no sistema-alvo e tentar injetar
  6. Se algo não bate → atualizar o mapping; se bate → commitar com mensagem feat(mapping): suporte a <sistema/tela>

Mais