Health Microservice API

Um microsserviço FastAPI para operações relacionadas à saúde, com autenticação JWT e banco de dados PostgreSQL com migrações Alembic.

GitHub
5
Experimente este MCPPatrocinado

Documentação

Health Microservice API

Um microserviço FastAPI abrangente para operações relacionadas à saúde com autenticação JWT, banco de dados PostgreSQL e migrações Alembic. É suportado por um servidor MCP usando FastApiMCP

Demonstração Funcional

health-api-mcp-server-with-fastapi-demo.webm

Recursos

  • Autenticação baseada em JWT
  • Banco de dados PostgreSQL com SQLAlchemy assíncrono
  • Migrações de banco de dados com Alembic
  • Modelos abrangentes de domínio de saúde (Paciente, Médico, Consulta, Prontuário Médico)
  • Endpoints de API RESTful
  • Documentação interativa da API (Swagger UI)
  • Estrutura de projeto modular
  • Middleware CORS
  • Suporte a async/await
  • Gerenciador de pacotes UV para resolução rápida de dependências
  • Suíte de testes abrangente

Pré-requisitos

  • Python 3.13.3+
  • PostgreSQL
  • Gerenciador de pacotes UV

Estrutura do Projeto

O projeto segue uma estrutura modular adequada para aplicações grandes, com clara separação de responsabilidades entre modelos, schemas, rotas e lógica de negócio.

project_structure

Instalação

Instalar UV

# On macOS and Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# On Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# Or with pip
pip install uv

Configuração do Projeto

Clone o repositório:

git clone <repository-url>
cd health-api

Instale as dependências:

uv sync

Configure as variáveis de ambiente:

cp .env.example .env
# Edit .env with your database credentials and secret key

Migrações de Banco de Dados com Alembic (usando UV)

O Alembic é usado para lidar com migrações de banco de dados. Todos os comandos abaixo assumem que você está no diretório raiz do projeto.

Mas antes de tudo, crie um banco de dados PostgreSQL:

CREATE DATABASE health_db;

Gerar uma Nova Migração (Autogeração)

uv run alembic revision --autogenerate -m "Your migration message"

Aplicar Migrações (Atualizar Banco de Dados)

uv run alembic upgrade head

Inicie a aplicação (escolha uma opção):

uv run uvicorn app.main:app --host 0.0.0.0 --port 5000 --reload
# Or use the convenience script
chmod +x scripts/start.sh
./scripts/start.sh

Alguns comandos adicionais de migração do Alembic

Esses comandos não são necessários durante a configuração, mas são úteis para gerenciar migrações no futuro durante o desenvolvimento.

Reverter Banco de Dados (Reverter Última Migração)

uv run alembic downgrade -1

Ver Status Atual da Migração

uv run alembic current

Mostrar Histórico de Migrações

uv run alembic history

Para mais comandos e uso do Alembic, consulte a documentação do Alembic.

Desenvolvimento

Instale as dependências de desenvolvimento:

uv sync --group dev

Execute os testes:

uv run pytest
# Or use the test script
chmod +x scripts/test.sh
./scripts/test.sh

Formatação de código:

uv run black app/ tests/
uv run isort app/ tests/

Verificação de tipos:

uv run mypy app/

Docker

Construa e execute com Docker Compose:

docker-compose up --build

Isso iniciará tanto o banco de dados PostgreSQL quanto a aplicação FastAPI.

Documentação da API

Quando a aplicação estiver em execução, visite:

curl -H "Authorization: Bearer <your_bearer_token>" 
-H "Accept: text/event-stream" http://localhost:5000/mcp

Migrações de Banco de Dados

Crie uma nova migração:

uv run alembic revision --autogenerate -m "Description of changes"
# Or use the migration script
chmod +x scripts/migrate.sh
./scripts/migrate.sh "Description of changes"

Aplique as migrações:

uv run alembic upgrade head

Autenticação

  • Registrar um novo usuário: POST /auth/register
  • Fazer login para obter token de acesso: POST /auth/login
  • Usar o token no cabeçalho Authorization: Bearer <token>

Principais Endpoints da API (após autenticação)

Após obter um token de acesso JWT, você pode acessar os seguintes endpoints:

Health-Microservice-API-Swagger-UI

🖼️ Clique para ver os endpoints da Health Microservice API

Médicos

  • GET /doctors — Listar todos os médicos
  • GET /doctors/{doctor_id} — Obter um médico específico por ID
  • POST /doctors — Criar um novo médico
  • PUT /doctors/{doctor_id} — Atualizar as informações de um médico
  • DELETE /doctors/{doctor_id} — Excluir um médico

Pacientes

  • GET /patients — Listar todos os pacientes
  • GET /patients/{patient_id} — Obter um paciente específico por ID
  • POST /patients — Criar um novo paciente
  • PUT /patients/{patient_id} — Atualizar as informações de um paciente
  • DELETE /patients/{patient_id} — Excluir um paciente

Prontuários Médicos

  • GET /medical-records — Listar todos os prontuários médicos (opcionalmente filtrar por paciente)
  • GET /medical-records/{record_id} — Obter um prontuário médico específico por ID
  • POST /medical-records — Criar um novo prontuário médico
  • PUT /medical-records/{record_id} — Atualizar um prontuário médico
  • DELETE /medical-records/{record_id} — Excluir um prontuário médico

Consultas

  • GET /appointments — Listar todas as consultas
  • GET /appointments/{appointment_id} — Obter uma consulta específica por ID
  • POST /appointments — Criar uma nova consulta
  • PUT /appointments/{appointment_id} — Atualizar uma consulta
  • DELETE /appointments/{appointment_id} — Excluir uma consulta

Telemedicina

  • POST /telemedicine/visits/ — Criar uma nova visita virtual
  • GET /telemedicine/visits/ — Listar todas as visitas virtuais
  • GET /telemedicine/visits/{visit_id} — Obter uma visita virtual específica por ID
  • POST /telemedicine/chats/ — Criar um novo registro de chat
  • GET /telemedicine/chats/ — Listar todos os registros de chat
  • GET /telemedicine/chats/{chat_id} — Obter um registro de chat específico por ID
  • POST /telemedicine/videos/ — Criar uma nova sessão de vídeo
  • GET /telemedicine/videos/ — Listar todas as sessões de vídeo
  • GET /telemedicine/videos/{video_id} — Obter uma sessão de vídeo específica por ID

Laboratório

  • POST /lab/orders/ — Criar um novo pedido de laboratório
  • GET /lab/orders/ — Listar todos os pedidos de laboratório
  • GET /lab/orders/{order_id} — Obter um pedido de laboratório específico por ID
  • POST /lab/results/ — Criar um novo resultado de laboratório
  • GET /lab/results/ — Listar todos os resultados de laboratório
  • GET /lab/results/{result_id} — Obter um resultado de laboratório específico por ID
  • POST /lab/images/ — Criar uma nova imagem diagnóstica
  • GET /lab/images/ — Listar todas as imagens diagnósticas
  • GET /lab/images/{image_id} — Obter uma imagem diagnóstica específica por ID

Encaminhamento

  • POST /referral/requests/ — Criar uma nova solicitação de encaminhamento
  • GET /referral/requests/ — Listar todas as solicitações de encaminhamento
  • GET /referral/requests/{request_id} — Obter uma solicitação de encaminhamento específica por ID
  • POST /referral/statuses/ — Criar um novo status de encaminhamento
  • GET /referral/statuses/ — Listar todos os status de encaminhamento
  • GET /referral/statuses/{status_id} — Obter um status de encaminhamento específico por ID
  • POST /referral/notes/ — Criar uma nova nota de especialista
  • GET /referral/notes/ — Listar todas as notas de especialista
  • GET /referral/notes/{note_id} — Obter uma nota de especialista específica por ID

Farmácia

  • POST /pharmacy/medications/ — Criar um novo medicamento
  • GET /pharmacy/medications/ — Listar todos os medicamentos
  • GET /pharmacy/medications/{med_id} — Obter um medicamento específico por ID
  • POST /pharmacy/prescriptions/ — Criar uma nova prescrição
  • GET /pharmacy/prescriptions/ — Listar todas as prescrições
  • GET /pharmacy/prescriptions/{pres_id} — Obter uma prescrição específica por ID
  • POST /pharmacy/orders/ — Criar um novo pedido de farmácia
  • GET /pharmacy/orders/ — Listar todos os pedidos de farmácia
  • GET /pharmacy/orders/{order_id} — Obter um pedido de farmácia específico por ID

Seguro

  • POST /insurance/plans/ — Criar um novo plano de seguro
  • GET /insurance/plans/ — Listar todos os planos de seguro
  • GET /insurance/plans/{plan_id} — Obter um plano de seguro específico por ID
  • POST /insurance/claims/ — Criar uma nova reivindicação de seguro
  • GET /insurance/claims/ — Listar todas as reivindicações de seguro
  • GET /insurance/claims/{claim_id} — Obter uma reivindicação de seguro específica por ID
  • POST /insurance/payments/ — Criar um novo pagamento
  • GET /insurance/payments/ — Listar todos os pagamentos
  • GET /insurance/payments/{payment_id} — Obter um pagamento específico por ID
  • POST /insurance/invoices/ — Criar uma nova fatura
  • GET /insurance/invoices/ — Listar todas as faturas
  • GET /insurance/invoices/{invoice_id} — Obter uma fatura específica por ID

Todos esses endpoints exigem o cabeçalho Authorization: Bearer . Consulte a documentação interativa da API em /docs para esquemas detalhados de solicitação/resposta e experimente os endpoints interativamente.

Gerenciamento de Pacotes com UV

O UV fornece resolução e instalação rápidas de dependências. Comandos úteis:

  • uv sync - Instalar dependências do arquivo de bloqueio
  • uv add <package> - Adicionar uma nova dependência
  • uv remove <package> - Remover uma dependência
  • uv run <command> - Executar comando no ambiente virtual
  • uv lock - Atualizar o arquivo de bloqueio

Integração MCP

A integração com MCP é feita usando a classe FastApiMCP do pacote fastapi_mcp. O servidor MCP é montado na aplicação FastAPI usando o método mount.

Configurações windsurf,

{
  "mcpServers": {
    "health-api": {
      "serverUrl": "http://localhost:5000/mcp",
      "headers": {
        "Authorization": "Bearer 
        <put_your_bearer_token_here>"
      } 
    }
  }
}

Configurações vscode ou cursor,

{
  "servers": {
    "health-api": {
      "url": "http://localhost:5000/mcp",
      "headers": {
        "Authorization": "Bearer 
        <put_your_bearer_token_here>"
      }
    }
  }
}

Nota: Ainda não testei em vscode ou cursor.

Licença

Licença MIT

TODOs

  • Adicionar mais casos de teste
  • Adicionar mais recursos
  • Adicionar mais documentação
  • Adicionar mais recursos de segurança
  • Adicionar mais logging
  • Adicionar mais monitoramento
  • Adicionar mais otimização de desempenho

Contribuindo

  1. Instale as dependências de desenvolvimento: uv sync --group dev
  2. Faça suas alterações
  3. Execute os testes: uv run pytest
  4. Formate o código: uv run black app/ tests/
  5. Envie um pull request

Veja mais em [Contribuindo](https://github.com/ AlwaysSany/health-api/blob/main/CONTRIBUTING.md).

Contato

Referências