Documentação do sistema
Tudo o que acontece entre a foto da receita e o texto organizado na tela: as tecnologias de leitura, os critérios de confiança, o tratamento dos dados e os limites da ferramenta.
1. O que o sistema faz (e o que não faz)
O Minha Receita transcreve e organiza o que está escrito em receitas médicas e em pedidos de exame fotografados. Ele transforma letra manuscrita e termos técnicos em texto legível, com um glossário em linguagem simples.
Ele não emite diagnóstico, não sugere tratamento, não verifica interação medicamentosa e não substitui o médico ou o farmacêutico. Toda decisão clínica continua sendo do profissional de saúde.
2. Fluxo completo de uma leitura
- Captura. Você escolhe o tipo de documento (receita ou exame) e tira a foto ou envia uma imagem da galeria.
- Pré-processamento no aparelho. A imagem é redimensionada e comprimida no próprio navegador (Canvas API) antes de sair do celular, o que reduz o tráfego e padroniza o tamanho enviado ao modelo.
- Medição de qualidade. Ainda no aparelho, calculamos resolução, nitidez e brilho da foto (detalhes no item 5).
- Armazenamento. A imagem vai para um bucket privado de arquivos, acessível apenas pela sua conta.
- Dupla leitura por IA. A imagem é processada duas vezes. Quando possível, a segunda execução começa por outro provedor. Cada leitura devolve a transcrição literal, os campos-chave estruturados e o glossário encontrado.
- Conferência automática. As duas leituras são comparadas campo a campo, as regras de formato são aplicadas e a confiança final é calculada por fórmula fixa.
- Resultado. Você vê a transcrição (editável), os campos-chave com marcação dos pontos duvidosos, o glossário e o detalhamento da confiança. Tudo fica no seu histórico.
3. Tecnologias usadas na leitura
A leitura não usa OCR tradicional (que falha muito com letra de médico). Usamos modelos de linguagem multimodais com capacidade de visão, que interpretam a imagem inteira e o contexto do documento — por isso conseguem lidar com manuscrito, carimbos e formulários fora de padrão.
| Provedor | Modelo e capacidade |
|---|---|
| Google AI | gemini-2.5-flash(visão e texto) |
| OpenAI | gpt-4.1-mini(visão e texto) |
| Anthropic | claude-sonnet-4-5(visão e texto) |
| OpenRouter | google/gemini-2.5-flash(visão e texto) |
| Groq | meta-llama/llama-4-scout-17b-16e-instruct(visão e texto) |
| DeepSeek | deepseek-v4-flash-vision-exp(visão e texto) |
Provedores somente texto podem apoiar resumos, perguntas e revisões textuais, mas não recebem a fotografia e não contam como uma leitura independente da caligrafia.
O administrador cadastra as chaves de API na área administrativa e define a ordem de prioridade. O sistema tenta o primeiro provedor ativo e, em caso de falha, erro de autenticação ou limite de requisições, passa automaticamente para o próximo (fallback em cascata). As chaves ficam apenas no servidor, nunca são enviadas ao navegador e aparecem mascaradas mesmo para o administrador.
O prompt enviado ao modelo é fixo e restritivo: instrui a transcrever literalmente, marcar trechos ilegíveis como [ilegível] em vez de adivinhar, responder somente em JSON válido e jamais oferecer diagnóstico, conselho clínico ou alerta de interação.
Infraestrutura: aplicação em React com TanStack Start (renderização no servidor), chamadas de IA executadas em funções de servidor — nunca no navegador —, banco de dados PostgreSQL com políticas de acesso por linha, autenticação por e-mail/senha ou Google, e armazenamento privado de arquivos.
4. Campos extraídos por tipo de documento
Receita: Medicamento, Via de administração, Frequência — um conjunto por medicamento prescrito. Quando constarem no documento, dose, concentração/apresentação, forma farmacêutica, ajuste do dispositivo, duração e quantidade dispensada são extraídos em campos separados.
Pedido de exame: Exame solicitado, além de preparo (jejum, por exemplo) e observações clínicas quando constarem no papel.
Cada termo técnico encontrado gera uma entrada de glossário explicada em linguagem simples, com indicação genérica de fonte (bulas e glossários médicos oficiais).
5. Critérios de confiança do resultado
O índice exibido resume sinais automáticos de qualidade. Ele é calculado por uma fórmula fixa e auditável, mas não é uma probabilidade calibrada de a transcrição estar correta.
Concordância entre as duas leituras — peso 30%
Cada campo da primeira leitura é pareado com o campo de mesmo rótulo na segunda leitura e comparado por similaridade de texto (coeficiente de Dice sobre bigramas, com os valores normalizados: minúsculas, sem acento e sem espaços extras). Similaridade igual ou acima de 0,85 conta como concordância. Isso mede repetibilidade; dois modelos ainda podem chegar à mesma leitura errada.
Concordância da transcrição completa — peso 25%
Comparamos também todo o texto das duas leituras, cobrindo observações e instruções que podem não ter sido convertidas em campos estruturados.
Validação por regra de formato — peso 15%
Regras fixas, sem julgamento clínico: dose precisa ter número + unidade (mg, mcg, g, ml, UI, %, gotas, comprimidos); frequência precisa seguir um padrão reconhecido (8/8h, 2x ao dia, de 12 em 12 horas, dose única); duração precisa indicar período (7 dias, uso contínuo); a via precisa estar em lista fechada (oral, sublingual, intramuscular, intravenosa, tópica, inalatória, entre outras); nomes de medicamento e exame precisam ter texto legível mínimo.
Cobertura dos campos obrigatórios — peso 15%
Proporção dos campos esperados para aquele tipo de documento que foram preenchidos com conteúdo válido. Campos faltando são listados explicitamente no resultado.
Qualidade da imagem — peso 15%
Medida no seu aparelho antes do envio: resolução (referência de 1600 px no maior lado), nitidez pela variância do Laplaciano (detecta foto tremida ou desfocada) e brilho médio (aponta foto escura demais ou estourada). A nota combina os três (45% nitidez, 35% resolução, 20% brilho) e os problemas encontrados aparecem escritos na tela.
Desconto por trechos ilegíveis
Cada marcação [ilegível] na transcrição desconta 4 pontos percentuais da nota final, limitado a 20 pontos.
Faixas exibidas: 85% ou mais qualidade alta; 60% a 84% qualidade média; abaixo de 60% qualidade baixa. A prescrição exige conferência humana em qualquer faixa. O detalhamento completo de cada documento fica guardado junto com ele, então é sempre possível auditar por que aquela nota foi dada. Ver a página de metodologia.
A confiança mede apenas o quanto conseguimos ler o papel. Ela não avalia se a prescrição está correta.
6. Contas, acesso e segurança dos dados
- O uso exige conta. Todo novo cadastro entra como pendente e só é liberado após aprovação do administrador.
- Cada pessoa vê exclusivamente os próprios documentos: as políticas de acesso no banco filtram por usuário, e as imagens ficam em armazenamento privado.
- Você pode editar a transcrição, copiar o texto e excluir qualquer documento a qualquer momento — a exclusão remove o registro e a imagem.
- As chaves de API dos provedores são gravadas em tabela restrita ao servidor e nunca trafegam para o navegador.
- Detalhes de base legal, retenção e direitos do titular estão na página de privacidade e LGPD.
7. Mensagens de erro mais comuns
- Imagem ilegível — foto escura, tremida ou com corte. Refaça em local iluminado, apoiando o papel em superfície plana.
- Sem texto detectado — a imagem não contém documento legível.
- Tipo incompatível — você escolheu "receita" e enviou um pedido de exame (ou o contrário).
- Nenhuma chave de API ativa — o administrador precisa cadastrar ou reativar uma chave na área administrativa.
- Conta em análise — o cadastro ainda não foi aprovado pelo administrador.