# Identificador opaco: por que hierarquia por prefixo quebra terminologia clínica > Em um padrão o prefixo do código significa alguma coisa; no outro, significa nada. Tratar os dois igual faz uma regra aprovar o item errado sem acusar nenhum erro. Publicado em 2026-08-12 por Time Orion · Blog da Orion Versão canônica: https://orion.moe/blog/identificador-opaco-terminologia-clinica Índice do blog: https://orion.moe/blog --- 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](/blog/invariantes-de-arquitetura-no-ci): tornar explícito no código aquilo que hoje é conhecimento tácito de quem escreveu.