Especificação da funcionalidade: configuração pública da API no build¶

Branch da funcionalidade: 001-api-build-url

Criado em: 2026-08-04

Status: Rascunho

Entrada: “A aplicação web publicada deve chamar a API pública configurada, não localhost.”

Cenários de usuário e testes (obrigatório)¶

História de usuário 1 — Usar a API publicada (Prioridade: P1)¶

Como profissional usando o Prontuare em produção, preciso que as ações de conta e pacientes chamem o serviço público da API para que a aplicação funcione fora do computador do desenvolvedor.

Motivo da prioridade: um destino localhost torna todos os fluxos autenticados e clínicos inutilizáveis depois da publicação.

Teste independente: gerar a aplicação web com o endereço de produção da API e executar um cadastro ou login no navegador; o destino da requisição deve ser a API pública configurada e não pode conter localhost.

Cenários de aceitação:

Dado um deploy web de produção com endereço público da API configurado, Quando o usuário envia login ou cadastro, Então o navegador envia a requisição para esse endereço público.
Dada uma imagem web gerada para produção, Quando sua configuração é inspecionada, Então nenhuma requisição da API cliente recorre a um endereço localhost.

História de usuário 2 — Tornar falhas de configuração visíveis (Prioridade: P2)¶

Como responsável pelo deploy, preciso que a ausência do destino da API interrompa a entrega, em vez de publicar silenciosamente uma aplicação quebrada.

Motivo da prioridade: uma falha visível de entrega pode ser corrigida; um deploy aparentemente bem-sucedido que direciona usuários para localhost não pode.

Teste independente: tentar um build de produção sem endereço público da API e confirmar que a entrega para com erro claro de configuração.

Cenários de aceitação:

Dado um build de produção sem destino da API configurado, Quando o build começa, Então ele falha com mensagem acionável que identifica a configuração ausente.

Casos limítrofes¶

O endereço configurado tem barra final; as requisições continuam usando exatamente um separador de caminho.
Uma execução local não possui endereço público; ela pode usar o endereço local documentado.
Alterar o ambiente de runtime após gerar o cliente estático não muda silenciosamente o destino; o responsável é informado de que o valor pertence à configuração de build.

Requisitos (obrigatório)¶

Requisitos funcionais¶

FR-001: O build web de produção DEVE receber o destino da API por um valor explícito de configuração de build.
FR-002: O cliente de produção DEVE usar esse destino em todas as requisições à API.
FR-003: O build de produção DEVE falhar claramente quando o destino estiver ausente ou inválido.
FR-004: O desenvolvimento local DEVE preservar um destino local documentado sem afetar o artefato de produção.
FR-005: A documentação de deploy DEVE informar onde configurar o endereço e que sua alteração exige novo build.

Entidades principais¶

Destino da API: endereço-base selecionado durante o build web e usado pelas requisições do navegador durante a vida do artefato.
Configuração de deploy: valores de build fornecidos pelo responsável para uma publicação específica.

Critérios de sucesso (obrigatório)¶

Resultados mensuráveis¶

SC-001: 100% das requisições do navegador em um smoke test de produção usam o endereço público configurado.
SC-002: Um build de produção sem endereço obrigatório falha antes da publicação da imagem.
SC-003: O responsável consegue configurar o destino e concluir o smoke test usando uma única instrução documentada.

Premissas¶

O endereço público atual é https://prontuare-api.inviosat.com.
O Dokploy consegue fornecer configurações no momento do build da imagem web.
Esta correção não altera autenticação, política CORS ou propriedade de domínio da API.