Ir para o conteúdo

Como atualizar vocabulários clínicos sem reinstalar o app

Diátaxis: how-to — resolver problema operacional.

O Anotae inclui vocabulários clínicos (CIAP-2, CID-10, SIGTAP, RENAME, exames laboratoriais) que podem ser atualizados sem reinstalar o aplicativo. Isso é útil quando o Ministério da Saúde publica uma nova tabela SIGTAP ou quando o repositório disponibiliza um vocabulário revisado.

Pré-requisitos

  • Anotae v0.16.0+
  • Arquivo .json do vocabulário atualizado (obtido de fonte confiável)
  • Terminal com acesso ao ambiente Python do Anotae

1. Verificar vocabulários instalados

Liste os vocabulários presentes e seu status de integridade:

anotae vocab list

Saída esperada:

status   versão       id
------------------------------------------------------------
OK       2.0.0        ciap2-pt-br-essencial
OK       2.0.0        cid10-pt-br-essencial
OK       2024.09.1    sigtap-aps-essencial
OK       2024.1       rename-ubs-2024
OK       1.0.0        labs-aps-essencial

[OK] 5 vocabulário(s) — SHA-256 verificado.

Se algum item mostrar FALHA, siga para o passo de verificação detalhada.

2. Verificar integridade (SHA-256)

anotae vocab verify

O comando compara o SHA-256 de cada arquivo em disco com o valor declarado no manifesto bundled (vocabularies/vocab-manifest.json). Uma saída normal:

[OK]    ciap2-pt-br-essencial
[OK]    cid10-pt-br-essencial
[OK]    sigtap-aps-essencial
[OK]    rename-ubs-2024
[OK]    labs-aps-essencial

[OK] Todos os 5 vocabulário(s) íntegros.

Código de saída: - 0 — todos os vocabulários íntegros - 1 — pelo menos um falhou na verificação

3. Instalar um vocabulário atualizado

Obtenha o arquivo .json do vocabulário atualizado — por exemplo, um novo sigtap-aps-essencial.json gerado por script a partir da tabela oficial do SIGTAP/DATASUS.

anotae vocab install sigtap-aps-essencial /caminho/para/sigtap-aps-essencial-novo.json

O comando: 1. Localiza o vocabulário no manifesto pelo ID informado 2. Valida o JSON do arquivo fonte 3. Verifica o SHA-256 contra o manifesto (se declarado) 4. Substitui o arquivo em vocabularies/sigtap/sigtap-aps-essencial.json de forma atômica (escreve em temporário → rename)

⚠️ Importante: se o manifesto declara um SHA-256 e o arquivo fornecido não bater, a instalação é abortada e o arquivo original permanece intacto.

4. Ver IDs disponíveis

Caso não saiba o ID exato:

anotae vocab list

Os IDs aparecem na coluna id. Exemplo: sigtap-aps-essencial.

Cenários comuns

Vocabulário corrompido (disco com erros)

[FALHA] sigtap-aps-essencial
        esperado : 681f063f8ab1bf07…
        calculado: 00000000000000000…

Reinstale o vocabulário a partir de um backup ou usando o instalador original do Anotae.

Vocabulário ausente (arquivo deletado acidentalmente)

[FALHA] ciap2-pt-br-essencial — arquivo ausente

Reinstale o Anotae ou copie o arquivo de uma instalação limpa para vocabularies/ciap-2/ciap2-pt-br-essencial.json.

Instalar vocabulário de USB / pasta compartilhada (sem rede)

Esta é a motivação principal do comando: clínicas sem internet podem receber atualizações via pendrive.

# Pendrive montado em /Volumes/UPDATE
anotae vocab install rename-ubs-2024 /Volumes/UPDATE/rename-ubs-2025.json

Formato do arquivo de vocabulário

O arquivo deve ser um JSON com este schema mínimo:

{
  "id": "rename-ubs-2024",
  "name": "RENAME UBS 2024",
  "version": "2025.1",
  "language": "pt-BR",
  "codes": [
    {
      "code": "01.01.001.001-0",
      "title": "Nome do medicamento",
      "synonyms": ["nome alternativo"]
    }
  ]
}

Campos obrigatórios: id, name, version, language, codes.

Manifesto de vocabulários (vocab-manifest.json)

O arquivo vocabularies/vocab-manifest.json declara os vocabulários bundled com suas versões e SHA-256. Ele é atualizado a cada release do Anotae. Para inspecioná-lo:

cat vocabularies/vocab-manifest.json

Ver também