feat: hospitais do SUS - peçonhentos, oncologia e doenças raras - #891

`tratamento` e `habilitacao` resolviam contra o mesmo vocabulário que
`atendimento` e devolviam resultados idênticos em todos os casos testados —
só triplicavam o que o usuário precisa decidir antes da primeira chamada.
Para restringir a uma vertical, `vertical=` já existe.

Busca principal: 9 -> 7 parâmetros. /proximos: 11 -> 10.

Também torna o merge do snapshot aditivo nos campos de lista (`verticals`,
`treatments`, `specialties`). O espalhamento anterior deixava a última coleta
sobrescrever o que as anteriores trouxeram. Não muda o dado hoje — os 5
hospitais com soro fora da vertical de peçonhentos vêm assim do MapaSUS, que
não os retorna em /v1/venomous-animals/hospitals — mas evita perda silenciosa
se o upstream passar a devolver `verticals` parcial por endpoint.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

…ixa de ser 500

A documentação descrevia o que cada rota retorna, não que pergunta ela
responde. Agora abre com uma tabela de perguntas reais mapeadas para a
requisição correspondente, explica para que serve cada uma das quatro rotas e
o que distingue as três verticais. Todos os exemplos foram executados contra o
servidor antes de entrar na doc.

O parâmetro `atendimento` ganhou a tabela das quatro famílias de valor que
aceita — nome popular do animal, nome do soro em PT ou EN, habilitação e
código de portaria — e `vertical` passou a dizer que é opcional e raramente
necessário.

fix: /proximos devolvia 500 para qualquer falha de CEP, vazando o
CepPromiseError cru. CEP malformado agora é 400 e CEP inexistente é 404,
usando a mesma tradução que pages/api/cep/v2/[cep].js já fazia.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

A revisão anterior tinha seções próprias de explicação — tabelas markdown,
títulos e blocos de código na descrição da tag —, coisa que nenhum outro
domínio do projeto faz. A tag ficou com 2.915 caracteres contra 316 da maior
das outras, quase 10x fora do padrão.

Reescrito na convenção da casa: tag em prosa curta com HTML (<b>, <code>,
<abbr>), operações em prosa de uma a três frases, e o detalhe do vocabulário
na descrição dos parâmetros — que é onde os outros domínios o colocam.

Medido contra o teto real do projeto, em texto visível sem tags:

  tag            348  (maior das outras: 316, em ISBN)
  atendimento    323  (maior parâmetro das outras: 321, em cep)
  operações  244-344  (maior das outras: 423, em cptec)

Também troca Itatiba por Campinas nos exemplos.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

…a campo traz

Faltavam duas coisas depois do ajuste ao padrão da casa.

A tag dizia "hospitais de referência do SUS" sem nunca explicar o que isso
significa. Agora abre pela definição, como a tag de ISBN faz com ISBN: são
estabelecimentos que o Ministério da Saúde habilitou por portaria para um
atendimento específico — a habilitação é oficial, não uma classificação nossa.

E 8 dos 14 campos de resposta não tinham descrição, que é justamente onde o
Redoc responde "o que dá para obter". Todos os campos de Hospital,
CiatoxCentro e HospitalProximo agora descrevem o que trazem, incluindo duas
ressalvas que faltavam: `address` pode vir incompleto, e `lat`/`lng` são
geocodificados a partir do endereço — não vêm da fonte oficial e estão
sujeitos a erro.

A tag ficou em 390 caracteres visíveis contra 316 da maior das outras. O
excedente é a definição do domínio e o aviso de emergência.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

"Encontra o hospital mais próximo que oferece um atendimento" dava a entender
que a rota alcança qualquer hospital do país. Não alcança: a base cobre
exclusivamente três habilitações do Ministério da Saúde.

Os quatro summaries agora nomeiam o escopo, e as duas rotas de busca dizem no
primeiro período que a base não é um cadastro geral de hospitais.

Cabe no padrão: os summaries ficaram entre 64 e 88 caracteres, contra 108 do
maior do projeto (cep v3).

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

… pública

Revisão de qualidade sobre a implementação. Quatro problemas reais.

Camadas invertidas: `query.js` — validação de entrada — importava de
`index.js`, o módulo que carrega 1,5 MB de snapshot, só para usar duas funções
puras. `VERTICAIS` e `resolverAtendimento` não tocam o dataset; são vocabulário
e foram para `vocabulario.js`. Agora `vocabulario.js` não tem nenhuma
dependência, `query.js` depende só dele, e `index.js` é o único que conhece o
snapshot.

Superfície pública inflada: dez exports em `vocabulario.js` e quatro constantes
exportadas em `index.js` e `query.js` que ninguém consumia de fora. Fechados —
`vocabulario.js` foi de dez exports para quatro.

Duplicação: `throw new BadRequestError({ message, type: 'validation_error' })`
aparecia seis vezes. Extraído para `invalido()`.

Coesão: `parseRaioEmMetros` era o único parser fora de `query.js`, definido
solto dentro do handler. Movido, junto com o `1000` mágico da conversão de
metros, agora `METROS_POR_KM`. `parseCoordenada(x, 'latitude', 90)` virou
`parseLatitude(x)`, tirando do handler o conhecimento dos limites.

`extrairCodigos` compilava uma RegExp nova a cada chamada, dentro do laço que
roda por hospital, e dependia de zerar `lastIndex` à mão entre chamadas de uma
regex global. As duas regex agora são compiladas uma vez e o casamento usa
`matchAll`, que não depende de `lastIndex`.

Comportamento inalterado: mesmas contagens em todas as buscas, 46 testes E2E
passando.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

…idade

Segunda passada de qualidade, aplicando o que a primeira tinha deixado na mesa.

Origem sai do handler: buscarCep e resolverOrigem fazem chamadas externas
(cep-promise, geocoding) e viviam em pages/api — o CLAUDE.md reserva handlers
para roteamento e resposta, e chamadas externas para services. Foram para
services/hospitais/origem.js, e o handler de /proximos caiu de 146 para 43
linhas: resolve origem, valida raio, consulta, pagina, responde.

Paginação num só lugar: o fatiamento slice(offset, offset + limit) e o
envelope {total, limit, offset, items} estavam duplicados nas duas rotas de
busca. paginar() em query.js encapsula os dois; parsePaginacao virou interno.

Contrato explícito: getHospitaisProximos repassava ...filtros por spread, o
que aceitaria silenciosamente qualquer filtro futuro sem registro. Agora nomeia
vertical e atendimento.

Retry deduplicado no script de snapshot: a chamada axios idêntica aparecia
duas vezes no caminho do 429.

Testes de unidade: vocabulario.js ficou puro e sem dependências na passada
anterior, mas a extração de códigos sobre texto sujo de OCR — a lógica mais
frágil do domínio — só era coberta de longe pelos E2E. 11 testes cobrem
aliases, equivalência de grafias, precedência, extração multi-código com
quebra de linha e ponto ausente, e a autoconsistência de /opcoes. Mais 3 para
o haversine (distância conhecida SP–Rio, zero e simetria).

Camadas agora numa direção só: vocabulario (zero deps) <- query <- origem;
index.js é o único módulo que conhece o snapshot.

Comportamento inalterado: mesmas contagens e mesmos códigos de erro em todas
as rotas. 60 testes passando (46 E2E + 14 de unidade).

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

…napshot

O script já chamava /v1/states e descartava tudo menos as siglas. Agora guarda
o que o MapaSUS reporta por UF no momento da coleta — status, synced_at
(última checagem da fonte) e updated_at (data publicada pelo gov.br) — em
`sincronia_da_fonte` no metrics-latest.json. Permite auditar de quando são os
dados de cada UF sem mudar o contrato da API.

Também documenta explicitamente que a coleta é completa, não incremental:
qualquer mudança de conteúdo na fonte entra no snapshot seguinte mesmo com o
número de registros inalterado — o guardrail de 80% só bloqueia encolhimento
abrupto, verificado por experimento com mock (mesmo tamanho, um nome
corrigido: a correção foi promovida).

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Fecha as duas lacunas apontadas na comparação com a API do MapaSUS:

- GET /hospitais/v1/cnes/{cnes}: localiza estabelecimento pelo
  identificador oficial nacional (mais estável que o id interno da
  fonte). Normaliza zeros à esquerda e separadores perdidos na extração
  dos PDFs e devolve lista — o mesmo CNES pode aparecer em mais de um
  registro quando a fonte não consolidou as verticais. 404 explica que
  a cobertura é parcial.
- GET /hospitais/v1/estados: totais por UF + frescor reportado pela
  fonte na coleta (status, synced_at, updated_at, do sincronia_da_fonte
  do metrics) — em dado de saúde, 'de quando é isso?' importa tanto
  quanto o dado.

Ambas servidas do snapshot em memória, com OpenAPI e E2E (10 testes
novos).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

…snapshot

A allowlist introduzida na rodada do Sonar usava os slugs da API em
português (peconhentos, oncologia, raras), mas hospital.verticals traz
as chaves de banco do MapaSUS (venomous_animals, oncology,
rare_diseases) — o by_vertical das métricas vinha vazio. A allowlist
agora deriva das chaves reais.

Snapshot regenerado com a coleta de 12/08: 2342 hospitais (2336
geocodificados), 32 ciatox e sincronia_da_fonte preenchido para as 27
UFs — é o que alimenta o /hospitais/v1/estados.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>