Identificador opaco: por que hierarquia por prefixo quebra terminologia clínica

Existe uma classe de bug que não quebra nada, não aparece no log e não falha em teste: o sistema continua funcionando e passa a responder errado.

Achamos um desses ao integrar terminologias clínicas — e a raiz era uma suposição que parecia inofensiva: que o prefixo de um código significa alguma coisa.

Dois padrões, duas naturezas

Em alguns padrões de classificação, o código é hierárquico: os primeiros caracteres identificam o grupo, e os seguintes vão refinando. Isso é uma propriedade útil e intencional — casar por prefixo é a maneira correta de dizer "qualquer código deste grupo".

Em outros padrões, o identificador é opaco: um número sem estrutura interna, atribuído por sequência. Dois conceitos com identificadores parecidos não têm nenhuma relação semântica. Os primeiros dígitos não significam absolutamente nada.

O erro é aplicar a regra do primeiro tipo ao segundo.

Por que isso é perigoso e não é visível

Imagine uma regra de negócio que decide se um item é elegível a partir do código clínico, escrita como "código que começa com tal prefixo".

No padrão hierárquico, isso seleciona um grupo bem definido.

No padrão opaco, isso seleciona todos os conceitos cujo número começa com aqueles dígitos — que podem ser dezenas de milhares de coisas sem relação nenhuma entre si. E o sistema não tem como perceber: ele encontrou correspondências, aplicou a regra e seguiu em frente. A validação aprova o item errado sem acusar nada.

O sintoma vai aparecer semanas depois, num relatório que não bate ou numa glosa — longe demais da causa.

A correção foi tornar a diferença explícita no código: cada terminologia declara se casa por prefixo ou exige igualdade exata, e a que é opaca vem marcada como não-hierárquica. Não é configuração; é propriedade do padrão.

Três regras que ficaram

1. O código é gravado cru, com a terminologia numa coluna ao lado.

A tentação é prefixar o código com o nome do padrão para desambiguar. Não dá: o prontuário assinado tem um hash do conteúdo, com valor médico-legal, e mudar o formato do que é gravado invalidaria o hash de todas as consultas já assinadas. Além disso, arquivos de troca com operadoras têm esquema definido e não aceitam o código adulterado.

Guardar codigo e terminologia em colunas separadas resolve sem tocar em nada disso.

2. Identificador longo é texto, não número.

Alguns desses identificadores têm 18 dígitos. Isso passa do maior inteiro representável com segurança em ponto flutuante — a linguagem aceita, converte e arredonda, silenciosamente. Um identificador arredondado aponta para outro conceito, se apontar para algum.

Regra geral: identificador que não é usado em aritmética é texto. Sempre.

3. Não se traduz termo clínico por conta própria.

Quando a terminologia publica rótulo em português, usa-se o rótulo publicado. Quando não publica, o termo fica no idioma original.

Traduzir por conta própria é a mesma falta que inventar código: cria um vocabulário que só existe na sua base, que ninguém mais consegue interpretar e que não sobrevive à primeira troca de dados com outra instituição.

O princípio geral

Antes de escrever qualquer regra que dependa da forma de um identificador, pergunte: este identificador tem estrutura garantida pelo padrão, ou eu estou inferindo estrutura de exemplos que eu vi?

Inferir estrutura de amostra é como se cria dependência de coincidência: funciona nos casos testados e falha nos que não foram.

O mesmo vale para outras suposições de formato — filtrar por texto entre parênteses, presumir tamanho fixo, assumir que letras maiúsculas significam categoria. Quando existir catálogo oficial, use lista explícita; quando não existir, trate como opaco.

O resumo

Prefixo só quer dizer alguma coisa quando o padrão promete que quer. Tratar identificador opaco como hierárquico produz o pior tipo de erro: o que não falha, só responde errado — e aparece longe da causa, quando já custou dinheiro.

É o mesmo espírito de transformar regra de arquitetura em teste: tornar explícito no código aquilo que hoje é conhecimento tácito de quem escreveu.