Vaga Viva

Sistema de visualização de dados sobre absenteísmo em consultas e análise de filas/contratos de exames para gestores de saúde pública da Prefeitura de São Carlos.

O Problema

Na saúde pública municipal, quando pacientes faltam a consultas, a Prefeitura perde vagas e o tempo dos médicos é desperdiçado. Já para os exames terceirizados, a Prefeitura paga por um volume fixo mensal contratado com laboratórios privados, e o não agendamento ou a não realização também representam dinheiro público gasto sem retorno para a população, gerando filas de espera intermináveis.

A Solução

O Vaga Viva é um painel de dados que mostra aos gestores (Prefeito, Secretário de Saúde) a taxa de aproveitamento das consultas nas Unidades Básicas e a taxa de realização dos exames frente à capacidade contratada. O painel identifica padrões de absenteísmo, gargalos nas filas e unidades com maiores tempos de espera — permitindo decisões baseadas em dados para reduzir o desperdício.

Stack Tecnológico

Camada	Tecnologia
Frontend	React + TypeScript + Vite + Tailwind CSS v4
Backend	Python + FastAPI
Pipeline / ETL	Prefect 3 (em pipelines/)
Banco de Dados	PostgreSQL 17
Infraestrutura	Docker + Docker Compose
CI/CD	GitHub Actions

---

Dependências para Rodar o Projeto

1. Docker e Docker Compose

O Docker empacota todos os serviços (frontend, backend, banco de dados) em containers. Você não precisa instalar Python, Node ou PostgreSQL na sua máquina — o Docker faz isso dentro dos containers.

# Adicionar o repositório oficial do Docker
sudo apt-get update
sudo apt-get install -y ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt-get update

# Instalar Docker Engine + Docker Compose
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# Permitir usar Docker sem sudo
sudo usermod -aG docker $USER

# IMPORTANTE: faça logout e login novamente para o grupo ter efeito
# Ou rode: newgrp docker

# Verificar instalação
docker --version
docker compose version

2. Git

sudo apt-get install -y git

# Configurar identidade (use seu nome e email do GitHub)
git config --global user.name "Seu Nome"
git config --global user.email "seu@email.com"

3. (Opcional) Node.js 20 — para desenvolvimento frontend fora do Docker

Se você quiser rodar o frontend diretamente na máquina (mais rápido para desenvolvimento):

# Instalar nvm (gerenciador de versões do Node)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

# Recarregar o terminal
source ~/.bashrc

# Instalar e usar Node 20
nvm install 20
nvm use 20

# Verificar
node --version  # v20.x.x
npm --version

4. (Opcional) Python 3.12 — para desenvolvimento backend fora do Docker

Se você quiser rodar o backend diretamente na máquina:

# Instalar pyenv (gerenciador de versões do Python)
sudo apt-get install -y make build-essential libssl-dev zlib1g-dev \
  libbz2-dev libreadline-dev libsqlite3-dev wget curl llvm \
  libncursesw5-dev xz-utils tk-dev libxml2-dev libxmlsec1-dev \
  libffi-dev liblzma-dev

curl https://pyenv.run | bash

# Adicionar ao .bashrc
echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bashrc
echo 'command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(pyenv init -)"' >> ~/.bashrc
source ~/.bashrc

# Instalar Python 3.12
pyenv install 3.12
pyenv global 3.12

# Verificar
python --version  # Python 3.12.x

---

Rodar o Projeto do Zero

1. Clonar o repositório

git clone https://github.com/seu-org/vaga-viva.git
cd vaga-viva

2. Configurar variáveis de ambiente

cp .env.example .env

Os valores de aplicação (DATABASE_URL, SECRET_KEY, JWT) já vêm prontos para desenvolvimento local. Você precisa preencher as credenciais do e-SUS e do Google Maps, usadas pelo pipeline de ETL e pelo geocoding:

• ESUS_HOST, ESUS_DBNAME, ESUS_USER, ESUS_PASSWORD — banco remoto do e-SUS.
• GOOGLE_MAPS_API — chave da Google Maps Geocoding API.

Caso não tenha esses valores, entre em contato com o Nicolas.

3. Subir os containers e instalar dependências

docker compose up --build -d

Na primeira vez demora alguns minutos (baixa imagens e instala dependências). Nas próximas, é rápido.

Um único docker compose up sobe todos os serviços: o banco (target-postgres, que provisiona o schema na primeira subida), o Prefect (prefect-server + prefect-worker), o backend e o frontend. Não há mais nenhum passo manual em outro repositório.

4. Popular com dados iniciais

O Vaga Viva possui um script que recria todas as tabelas do zero (usando o SQLAlchemy) e insere dados falsos realistas para você poder testar o painel localmente:

docker compose exec backend poetry run python -m seeds.create_mock_db --mock

Ou você pode apenas iniciar com os dados básicos (usuários, métricas básicas, etc) e popular com os dados reais do E-SUS pelo pipeline do Prefect (ver seção abaixo). Para iniciar os dados iniciais:

docker compose exec backend poetry run python -m seeds.create_mock_db --init

5. Acessar

Serviço	URL
Frontend	http://localhost:5173
Backend (Swagger/docs)	http://localhost:8000/docs
Prefect (UI do pipeline)	http://localhost:4200 (sem login)
Banco de dados	localhost:5434 (via DBeaver, pgAdmin, etc.)

6. Rodar o pipeline de ETL (opcional)

O pipeline sobe junto com o docker compose up. O flow de registros médicos roda automaticamente todo dia às 3h; para disparar manualmente:

docker compose exec prefect-worker python -m flows.medical_records_etl
docker compose exec prefect-worker python -m flows.health_units_etl

Detalhes em docs/pipeline.md.

7. Parar

# Parar os containers (mantém dados do banco)
docker compose down

# Parar E apagar dados do banco (reset completo)
docker compose down -v

---

Resolução de Problemas Comuns (Troubleshooting)

Erro de importação ou bibliotecas faltando (ex: ModuleNotFoundError) Como usamos Docker, caso você rode comandos Python na sua máquina real, uma pasta .venv pode ser criada e, quando montada no container, causar conflitos. Solução:

1. Apague a pasta .venv dentro de /backend no seu computador (rm -rf backend/.venv).
2. Reinstale as dependências diretamente dentro do container: docker compose exec backend poetry install
3. Rode seus comandos precedidos de poetry run (ex: docker compose exec backend poetry run python ...).

---

Documentação

Documento	Conteúdo
docs/produto.md	Problema de negócio, telas, KPIs, filtros
docs/design.md	Cores, tipografia, layout, componentes UI
docs/database.md	Modelo de dados, tabelas, relacionamentos, índices e boas práticas
docs/pipeline.md	Pipeline de ETL (Prefect): flows, FDW do e-SUS, geocoding
docs/metricas.md	Motor de métricas: estratégias, API de leitura, escape hatches, árvore de decisão
docs/git-flow.md	Branches, commits, fluxo de trabalho Git
docs/ci-cd.md	Pipelines de CI/CD, testes, GitHub Actions