ValvePath
Plataforma de apoio a pacientes e médicos no acompanhamento de valvopatias cardíacas: jornada do paciente, gestão de casos clínicos, biblioteca de referência, integrações FHIR com hospitais e apoio de IA clínica baseado em diretrizes (SBC, ACC/AHA, ESC).
Stack
Rodando localmente
Pré-requisitos: Node.js 20.19+ (exigido por Vite 8, ESLint 10 e React Router 7 — está travado em engines no package.json).
# instalar dependências
npm install
# copiar variáveis de ambiente e preencher com os valores do seu projeto Supabase
cp .env.example .env
# subir o servidor de desenvolvimento
npm run dev
O gerenciador de pacotes é o npm — o package-lock.json é a fonte de verdade e é o que o CI valida com npm ci.
Scripts disponíveis:
| Comando | Descrição |
|---|
dev | Servidor de desenvolvimento (Vite) |
build | Build de produção |
build:dev | Build em modo desenvolvimento |
preview | Preview local do build de produção |
typecheck | Checagem de tipos (app + configs de build) |
typecheck:strict | Checagem de tipos em modo strict no escopo já migrado (src/lib/) |
lint | ESLint |
test | Roda os testes uma vez (Vitest) |
test:watch | Testes em modo watch |
types:generate | Regenera os tipos do Supabase a partir do schema (ver abaixo) |
demo:seed | Popula a base fictícia de demonstração (ver abaixo) |
demo:limpar | Remove a base fictícia, sem tocar em dado real |
cnes:import | Importa o recorte cardiovascular da base pública CNES (ver abaixo) |
Recuperação
O weekly-export grava o banco inteiro num bucket privado toda segunda. O
procedimento para transformar aqueles arquivos em um sistema funcionando de
novo está em RECOVERY.md, junto com o registro do ensaio que o
executou de verdade — e dos três defeitos que só o ensaio encontrou.
Estrutura
src/
pages/
public/ páginas públicas (marketing, legal, conteúdo educativo)
auth/ login, cadastro, recuperação de senha
app/ área autenticada (paciente, médico, hospital, admin)
components/ componentes compartilhados (inclui components/ui, shadcn)
integrations/supabase/ cliente e tipos gerados do Supabase
lib/ utilitários (validação, exportação, labels clínicos)
supabase/
migrations/ migrations SQL versionadas
functions/ edge functions (Deno) — IA clínica, FHIR, integrações
Backend
O backend roda em Supabase: Postgres com Row Level Security em todas as tabelas de dados sensíveis, autenticação nativa (e-mail/senha + OAuth Google), e edge functions para integrações FHIR com hospitais parceiros, geração/consulta de chaves de API, e o assistente de IA clínica (clinical-ai), que usa a Gemini API tanto para geração de texto (gemini-3.5-flash) quanto para os embeddings da busca RAG na base de conhecimento (gemini-embedding-001).
Segredos necessários nas edge functions (Supabase Dashboard → Edge Functions → Secrets):
| Segredo | Usado por |
|---|
GEMINI_API_KEY | clinical-ai, knowledge-seed (geração de texto e embeddings) |
TURNSTILE_SITE_KEY | turnstile-config (entrega a site key ao frontend) |
RESEND_API_KEY | _shared/sendEmail.ts — boas-vindas e alertas operacionais |
ALERT_EMAIL_TO | destinatário dos alertas do job-watchdog; também vira o Reply-To das mensagens |
ALERT_EMAIL_FROM | remetente (opcional; o padrão é [email protected]) |
Além desses, o Supabase já provisiona automaticamente SUPABASE_URL, SUPABASE_ANON_KEY, SUPABASE_SERVICE_ROLE_KEY e SUPABASE_PUBLISHABLE_KEY.
O TURNSTILE_SECRET_KEY não é usado por edge function nenhuma: o captcha é validado pelo próprio servidor de autenticação do Supabase, configurado em Authentication → Attack Protection. Validar por conta própria seria impossível de qualquer forma — o token do Turnstile é de uso único, então quem valida primeiro impede o outro de validar.
E-mail
Duas coisas distintas saem por e-mail, e ambas passam pelo Resend com o domínio envio.valvepath.com.br:
- Autenticação (confirmação de cadastro, recuperação de senha, link de acesso): enviada pelo próprio Supabase Auth via SMTP do Resend, com os textos em português configurados em Authentication → Emails. O remetente padrão do Supabase não serve aqui: além de mandar texto em inglês que não pode ser trocado no plano gratuito, ele limita o envio a 2 e-mails por hora — a partir do terceiro cadastro na mesma hora, ninguém receberia o link de confirmação.
- Produto (boas-vindas, alertas de tarefa agendada): enviada pelas edge functions via
_shared/sendEmail.ts. Sem RESEND_API_KEY o envio fica inerte e devolve o motivo, sem lançar — nada quebra, só não sai e-mail.
Tipos gerados do Supabase
src/integrations/supabase/types.ts é gerado a partir do schema do banco, não escrito à mão. Sempre que uma migration adicionar ou alterar colunas/tabelas, regenere:
SUPABASE_ACCESS_TOKEN=sbp_xxx npm run types:generate
O token é um Personal Access Token da Management API — não confundir com a anon key nem com a service role key. Como ele tem poder praticamente total sobre o projeto, não deve ser commitado nem guardado como secret de CI. Esquecer esse passo faz o npm run typecheck falhar com erros do tipo '<coluna>' does not exist in type ....
Base pública CNES (conferência de CRM)
Não existe API aberta de CRM — medido: o portal do CFM é protegido por reCAPTCHA
e a API de dados abertos do SUS tem 87 rotas, nenhuma de profissionais. O que
existe é a base CNES do DATASUS, um ZIP mensal público.
SUPABASE_ACCESS_TOKEN=sbp_xxx npm run cnes:import -- --competencia 202606
SUPABASE_ACCESS_TOKEN=sbp_xxx node scripts/cnes-import.mjs --limpar
Traz 36.042 profissionais da família cardiovascular (cardiologista,
cirurgião cardiovascular, radiologista intervencionista, cirurgião vascular e
torácico), com nome, número e UF do registro. É script local, não edge function:
o ZIP tem ~730 MB e os dois CSV somam ~1,8 GB, muito além do limite de uma
function — a leitura é em fluxo, via unzip -p.
O que ela é e o que não é. O número de registro no CNES é declarado pelo
estabelecimento ao cadastrar o profissional, não validado pelo conselho. Ele
aparece na tela de aprovação para corroborar; a conferência que vale continua
sendo a do portal do CFM, feita por uma pessoa, e registrada com quem conferiu e
quando. A tabela é de leitura restrita a administrador, fica fora do backup
(reimportável em um comando) e nada dela é exibido a pacientes.
Base de demonstração
Para apresentar o produto com as telas cheias — painéis, gráficos, relatórios e
discussão de Heart Team — existe uma base fictícia de 12 casos, com exames
seriados, linha do tempo, compromissos e três médicos fictícios assinando as
decisões.
SUPABASE_ACCESS_TOKEN=sbp_xxx npm run demo:seed -- --medico [email protected]
SUPABASE_ACCESS_TOKEN=sbp_xxx npm run demo:limpar
O conteúdo está em scripts/demo-data.mjs; quem insere é scripts/demo-seed.mjs.
É script e não migration de propósito: uma migration levaria paciente inventado
para dentro de toda restauração de desastre.
Três coisas valem saber antes de usar:
- Nada disso conta como uso real. Os casos e os médicos fictícios ficam com
is_demo = true e são excluídos de admin_site_metrics() e do resumo semanal
do administrador, que passam a mostrá-los em linha própria.
- A marca acompanha o caso para fora do sistema. Selo na lista, faixa no
topo do caso, aviso no cabeçalho e no rodapé de toda página do PDF, e primeira
coluna do CSV e do
.xlsx.
- As contas fictícias nascem banidas e não conseguem sessão por caminho
nenhum — o link mágico responde
user_banned. Elas existem só para a
discussão ter autoria distinta.
--aplicar limpa antes de inserir, então rodar duas vezes não duplica, e
--limpar devolve o banco exatamente ao estado anterior (inclusive apagando os
laudos que o seed enviou ao bucket).
Deploy — são DOIS caminhos, e por muito tempo só um existia
O front vai para a Vercel a cada push na main. As edge functions vão para
o Supabase, por um workflow separado. Eram coisas distintas e só a primeira
existia: durante semanas, mexer em supabase/functions/ não mudava nada em
produção, e a CI continuava verde porque ela roda os checks, não publica.
O sintoma apareceu tarde. O seed da base de conhecimento devolveu
{ ok: true, total: 11 } com 18 trechos no repositório — e, com ele, a
descoberta de que a clinical-ai respondia pela ESC/EACTS 2021 enquanto o
painel de conduta do médico anunciava a de 2025, porque o prompt corrigido
estava no Git e não estava rodando.
Publicar as edge functions
.github/workflows/deploy-functions.yml publica todas as functions quando
supabase/functions/** ou supabase/config.toml mudam na main, e também sob
demanda (Actions → Deploy edge functions → Run workflow).
Ele exige o segredo SUPABASE_ACCESS_TOKEN em Settings → Secrets and
variables → Actions. O token sai de
https://supabase.com/dashboard/account/tokens.
Esse token é root sobre a conta inteira do Supabase, e este repositório é
público. Três coisas o protegem, e src/test/deployFunctions.test.ts reprova
se alguma cair:
- o workflow nunca roda em
pull_request — num repositório público, um PR
de fork executaria o job com o segredo no ambiente;
- o token só existe como variável de ambiente, nunca como argumento de comando
(que apareceria em log e em lista de processos);
permissions: contents: read, e nada mais.
O verify_jwt de cada função vem de supabase/config.toml e o CLI o respeita —
é o que mantém a clinical-ai exigindo JWT depois de cada deploy.
Conferir que o deploy pegou
Publicado não é conferido. Em Administração → Base da IA e FHIR, o botão
Popular / atualizar base RAG compara o total que a função devolve com o que
esta versão do site espera (src/data/baseDaIA.ts). Divergiu, a tela diz
"A função publicada está desatualizada" em vermelho — as duas metades sobem
por caminhos diferentes, e é essa divergência que denuncia a que ficou para
trás.
Deploy do front (Vercel)
O vercel.json da raiz existe por um motivo só, e não pode ser removido: o
preset de Vite da Vercel não adiciona o fallback de SPA sozinho. Sem o
rewrite de /(.*) para /index.html, qualquer caminho que não seja um arquivo
no disco devolve o 404 da própria Vercel, antes de chegar ao React.
Isso não aparece navegando pelo site — o React Router troca a rota no navegador,
sem passar pelo servidor. Quebra só quando o caminho é pedido à Vercel:
recarregar a página, abrir um favorito, ou clicar num link de e-mail. Foi assim
que o link de redefinir senha, o retorno do login com Google (/auth/callback)
e a confirmação de cadastro ficaram caindo em 404 sem ninguém perceber.
Os rewrites são aplicados depois da checagem de arquivos, então
/assets/*, /robots.txt e /favicon.ico continuam vindo do disco.
npm run smoke pede cada rota do app à URL de produção e falha listando as
quebradas — é a verificação que faltava, já que npm run dev tem o fallback
embutido e por isso nunca reproduz esse defeito localmente.
As rotas renderizam, e não só respondem
npm run rotas:renderizam abre cada uma das 61 rotas num navegador de
verdade e falha nas que não montam.
Existe porque o smoke acima confere o shell — e o shell é o mesmo
index.html para as 61. Uma tela que estoura ao montar devolve exatamente esse
shell, com HTTP 200, e o smoke passa. O resto da rede também não pega: os testes
de unidade cobrem funções e componentes isolados, e o ferramentas:verificar
dirige duas rotas. As outras 59 não eram abertas por nada automático — dava para
quebrar uma tela inteira com CI verde, smoke verde e quase mil testes passando.
Quatro reprovações distintas, porque cada uma aponta para causa diferente:
exceção não tratada; o error boundary global aparecendo (o pior de detectar — a
tela fica bonita, com texto educado, e o HTTP continua 200); #root vazio; e
recurso nosso que não carregou.
Redirecionada não é renderizada. A primeira versão marcava ✓ em toda rota
que não quebrasse — inclusive nas 39 de /app/*, que sem sessão param todas em
/auth/login. Ela abria a tela de login dezenas de vezes e relatava "61 de 61
renderizaram". Um verificador feito para pegar "sucesso relatado sem o trabalho
feito" fazendo exatamente isso.
São três estados, e o resumo traz os três. Hoje, sem sessão:
22 de 61 rotas renderizaram a tela pedida
39 redirecionaram (a tela pedida NÃO foi aberta)
0 quebraram
As 22 são as públicas. As 39 sem sessão continuam sem prova de que suas telas
montam — o redirecionamento é o app funcionando, mas quem renderizou foi o login.
O que ainda falta: sessão de verdade
Tentei cobrir as 39 plantando uma sessão sintética no localStorage. O
redirecionamento parava e o relatório passou a dizer "60 de 61 renderizaram" —
mas a inversão não reprovava: um throw no topo de MedicoHome, conferido no
bundle servido, e a rota levava ✓ assim mesmo.
Medindo com a tela íntegra: /app/medico fica dez segundos no spinner e
nunca mostra "Área médica". O cliente do Supabase não resolve a sessão
inventada, useAuth.loading nunca vira falso, o ProtectedRoute segura o
spinner, e a tela protegida não chega a montar. As 39 "renderizadas" eram 39
spinners.
O modo foi removido. Cobrir as 39 exige sessão real — um usuário no banco e um
login pelo fluxo normal —, e isso fica anotado como o que falta em vez de
disfarçado de feito.
Do episódio sobrou uma melhoria que fica: o script espera a tela, não o
spinner. Antes ele olhava 500 ms depois do domcontentloaded, e as telas de
/app/ são carregadas em chunk separado — o que ele media era o fallback de
Suspense. Agora espera o .animate-spin sumir, com teto de 8 s, e reprova a
rota que continuar carregando.
Layout mobile
npm run mobile abre um conjunto de páginas num viewport de celular (via
Playwright) e falha listando qualquer elemento mais largo que a tela. Existe
porque html, body tem overflow-x: hidden — necessário para não deixar a
página inteira arrastar de lado num toque acidental, mas isso tem um efeito
colateral sério: um elemento largo demais não vira barra de rolagem, vira
texto cortado no meio da palavra, sem aviso nenhum na tela. Já aconteceu com
um item de grid (min-width: auto por padrão) e com um botão de texto longo
(whitespace-nowrap por padrão, sem min-w-0 no container flex). Ambos os
casos deixam de existir com a rolagem visível, mas o corte silencioso é pior:
ninguém vê, e a mensagem clínica chega incompleta.
Exige o Playwright — não é dependência do projeto (seria peso para um script
sob demanda); instale com npm i -g playwright se ainda não tiver.
Assim como o smoke, fica fora do CI: exigiria Chromium em todo push, e o
ganho não paga esse custo aqui. Rode manualmente depois de qualquer mudança de
layout, sobretudo em grids e flexs com texto de tamanho variável.
CI
O workflow em .github/workflows/ci.yml roda a cada push e pull request, em Node 22, e falha o build se qualquer etapa quebrar:
npm ci → typecheck → typecheck:strict → lint → test → build
Nenhuma credencial do Supabase é necessária: o build é estático e o cliente só é instanciado em runtime, no navegador.
TypeScript strict — migração incremental
O tsconfig.app.json compartilhado ainda roda com strict: false (dívida herdada). Em vez de virar a chave de uma vez, existe um tsconfig.strict.json separado que roda como etapa própria do CI (typecheck:strict), então uma regressão de tipagem falha de forma específica e isolada.
Hoje ele cobre todo o src/ (exceto arquivos de teste) com strict mais noImplicitAny, noUnusedLocals, noUnusedParameters, noFallthroughCasesInSwitch, noImplicitReturns, noImplicitOverride e noPropertyAccessFromIndexSignature.
Atenção ao editar esse arquivo: ele estende o tsconfig.app.json, que desliga várias sub-flags de strict explicitamente. Uma flag explícita no config pai vence o strict: true do filho — por isso as quatro precisam ser religadas uma a uma. Confira com npx tsc -p tsconfig.strict.json --showConfig se tiver dúvida sobre o que está realmente valendo.
Flags ainda não adotadas, com o custo já medido: exactOptionalPropertyTypes (31 erros), verbatimModuleSyntax (20) e noUncheckedIndexedAccess (16).
