API RESTful e interface web para gerenciamento de profissionais da saúde e consultas médicas.

• Cadastro, edição, exclusão e listagem de profissionais da saúde
• Cadastro e edição de consultas médicas com vínculo ao profissional
• Busca por consultas utilizando o ID do profissional
• Interface web com estatísticas e visualização de consultas em tempo real
• Segurança e validação de dados

• Django 5.2.2
• Django REST Framework
• PostgreSQL
• Docker e Docker Compose
• Templates Django para renderização no lado do servidor
• JavaScript para interatividade na interface web
• Poetry para gerenciamento de dependências

1. Clone o repositório
2. Execute o script de configuração:

# Execução interativa com confirmações
./setup.sh

# Execução com configurações padrão (sem confirmações)
./setup.sh -y

# Mostrar opções de ajuda
./setup.sh -h

O script oferece duas opções de configuração:

1. Docker (recomendado): Inicia os containers e configura todo o ambiente
2. Local com Poetry: Instala dependências e configura o ambiente local

Funcionalidades do script:

• Verifica se o arquivo .env existe e o cria a partir do exemplo se necessário
• Detecta automaticamente o Docker Compose V2 ou V1
• Oferece opção para resetar o banco de dados e carregar dados iniciais
• Permite criar um superusuário para acesso ao admin
• Aguarda a inicialização do banco de dados para evitar erros
• Exibe links úteis para acessar a API e o painel administrativo

O script é compatível com Docker Compose V2 (comando docker compose) e Docker Compose V1 (comando docker-compose).

1. Clone o repositório
2. Crie um arquivo .env baseado no .env.example:

cp .env.example .env

3. Edite o arquivo .env com suas configurações
4. Instale as dependências:

poetry install

5. Execute as migrações:

poetry run python manage.py migrate

6. Crie um superusuário:

poetry run python manage.py createsuperuser

7. Inicie o servidor:

poetry run python manage.py runserver

1. Clone o repositório
2. Crie um arquivo .env baseado no .env.example
3. Execute:

# Para Docker Compose V2
docker compose up -d

# OU para Docker Compose V1
docker-compose up -d

4. Crie um superusuário para acessar o admin:

# Para Docker Compose V2
docker compose exec web python manage.py createsuperuser

# OU para Docker Compose V1
docker-compose exec web python manage.py createsuperuser

Para resetar o banco de dados e carregar dados iniciais quando estiver usando Docker:

# Executar o script auxiliar que gerencia o processo através do Docker
./reset_docker_db.sh

# Para pular a confirmação
./reset_docker_db.sh -y

# Para ver ajuda
./reset_docker_db.sh -h

Este script irá:

1. Verificar se o Docker e Docker Compose estão instalados
2. Detectar automaticamente a versão do Docker Compose (V1 ou V2)
3. Verificar se os containers estão rodando e iniciá-los se necessário
4. Executar o comando de reset do banco de dados dentro do container
5. Carregar dados iniciais

O script é compatível com Docker Compose V2 (comando docker compose) e Docker Compose V1 (comando docker-compose).

Se você estiver dentro do container ou configurou o ambiente manualmente:

# Comando básico
python manage.py reset_db

# Sem confirmação
python manage.py reset_db --no-input

# Sem carregar dados iniciais
python manage.py reset_db --no-seed

O reset do banco de dados:

1. Remove todas as tabelas
2. Recria as migrações
3. Cria um superusuário admin (senha definida em .env)
4. Cria 5 profissionais de exemplo
5. Cria 3 consultas para cada profissional

A documentação da API está disponível em:

• /api/docs/ - Interface Swagger
• /api/redoc/ - Interface ReDoc
• /api/schema/ - Schema OpenAPI

Exemplo de JSON para cadastro de profissional:

{
  "preferred_name": "Dr. Ana Silva",
  "profession": "Cardiologista",
  "specialty": "Cardiologia Pediátrica",
  "address": "Av. Paulista, 1000 - São Paulo/SP",
  "contact": "11987654321"
}

Parâmetros de filtro:

• ?search=termo - Busca pelo nome ou profissão
• ?ordering=field - Ordenação por campo (ex: preferred_name, -created_at para ordem decrescente)

Exemplo de JSON para cadastro de consulta:

{
  "date": "2025-06-15T14:30:00Z",
  "professional": 1
}

Parâmetros de filtro:

• ?professional=1 - Filtra por ID do profissional
• ?date=2025-06-15T14:30:00Z - Filtra por data exata
• ?date_start=2025-06-01T00:00:00Z - Filtra por data maior ou igual
• ?date_end=2025-06-30T23:59:59Z - Filtra por data menor ou igual
• ?ordering=date - Ordenação por data (use -date para ordem decrescente)

• Interface principal: http://localhost:8000/
• Painel Admin: http://localhost:8000/admin/
• Documentação API: http://localhost:8000/api/docs/

A interface web oferece:

1. Visão geral do sistema

   • Total de profissionais cadastrados
   • Total de consultas agendadas
   • Total de especialidades disponíveis

2. Seção de especialidades

   • Listagem de todas as especialidades disponíveis
   • Profissionais associados a cada especialidade

3. Próximas consultas

   • Tabela responsiva com as próximas consultas agendadas
   • Contador regressivo mostrando o tempo restante até cada consulta
   • Informações do profissional e especialidade

4. Formulário de contato

   • Interatividade com feedback visual
   • Validação de campos obrigatórios

5. Design responsivo

   • Adaptação para diferentes dispositivos e tamanhos de tela
   • Layout moderno e funcional

• preferred_name - Nome social
• profession - Profissão
• address - Endereço
• contact - Contato

• date - Data e hora da consulta
• professional - Profissional vinculado (chave estrangeira)

• Python 3.12+
• Poetry 1.7.1+
• Docker e Docker Compose (recomendado)
• PostgreSQL (se não estiver usando Docker)

Para um ambiente de desenvolvimento ideal, recomendamos usar o Docker:

# Instale o código e inicie os containers
./setup.sh

# Selecione a opção 1 (Docker)

# Iniciar os containers
docker compose up -d

# Ver logs em tempo real
docker compose logs -f

# Executar comando dentro do container web
docker compose exec web python manage.py comando

# Parar os containers
docker compose down

# Parar e remover volumes (apaga dados do banco)
docker compose down -v

# Ativar ambiente virtual do Poetry
poetry shell

# Instalar dependências
poetry install

# Executar migrations
python manage.py migrate

# Iniciar servidor de desenvolvimento
python manage.py runserver

# Criar superusuário
python manage.py createsuperuser

Se você instalou o Docker recentemente, provavelmente está usando o Docker Compose V2, que é integrado ao Docker CLI. Use:

docker compose

em vez de

docker-compose

O script setup.sh detecta automaticamente qual versão você está usando.

Verifique se:

1. O banco de dados está rodando:

docker compose ps

2. As configurações no arquivo .env correspondem às do docker-compose.yml

3. O container do banco de dados inicializou completamente (pode levar alguns segundos)

Execute o script de reset do banco de dados:

./reset_docker_db.sh -y

Se você receber o erro "Unknown command: 'reset_db'", verifique:

1. Se o app core está no INSTALLED_APPS (já configurado no projeto)
2. Reinicie o container web:

docker compose restart web

3. Verifique se os comandos estão disponíveis:

docker compose exec web python manage.py help

Se os scripts não executarem, verifique as permissões:

chmod +x setup.sh reset_docker_db.sh run_tests.sh

Instale o Poetry seguindo a documentação oficial.

# Limpe o cache e reinstale
poetry cache clear --all pypi
poetry install --no-cache

A API está organizada em três aplicações Django principais:

Contém configurações globais do projeto:

• settings.py: Configurações do Django
• urls.py: Roteamento principal da API
• management/commands/reset_db.py: Script para resetar o banco de dados

Gerencia os profissionais da saúde:

• models.py: Define o modelo Professional
• serializers.py: Serializa dados do modelo para JSON
• views.py: Define o ProfessionalViewSet com filtros
• urls.py: Configura as rotas da API para profissionais
• admin.py: Configura a interface administrativa

Gerencia as consultas médicas:

• models.py: Define o modelo Appointment
• serializers.py: Serializa dados do modelo para JSON
• views.py: Define o AppointmentViewSet com filtros
• urls.py: Configura as rotas da API para consultas
• admin.py: Configura a interface administrativa

• setup.sh: Configura o ambiente inicial
• reset_docker_db.sh: Reseta o banco de dados no Docker
• run_tests.sh: Executa os testes automaticamente
• docker-compose.yml: Configuração dos serviços Docker

O projeto inclui uma suíte abrangente de testes com cobertura de 72,82%, incluindo testes de API, modelos e integração.

# Executar testes (automático)
./run_tests.sh

# Forçar execução local
./run_tests.sh --local

# Ver ajuda
./run_tests.sh --help

O script run_tests.sh automaticamente:

• Detecta se o Docker está disponível e rodando
• Usa SQLite em memória para testes mais rápidos quando não está no Docker
• Executa testes no container se estiver rodando

O script detecta automaticamente qual ambiente usar:

1. Docker disponível + containers rodando:

   • ✅ Executa no container com PostgreSQL
   • ✅ Cria banco de teste temporário
   • ✅ Executa migrações e seeders
   • ✅ Remove banco após os testes

2. Docker indisponível ou containers parados:

   • ✅ Executa localmente com SQLite em memória
   • ✅ Mais rápido para desenvolvimento

Quando executa no container, o script segue estes passos:

1. 🔍 Verificar se containers estão rodando
2. 📊 Criar banco de teste temporário (test_medical_api)
3. 🔧 Executar migrações no banco de teste
4. 🌱 Popular com dados iniciais (opcional)
5. 🧪 Executar testes com pytest
6. 🧹 Remover banco de teste (cleanup automático)

1. Django test runner com SQLite (mais rápido):

python manage.py test --settings=core.settings.testing

2. Pytest com SQLite (mais informativo):

DJANGO_SETTINGS_MODULE=core.settings.testing pytest -v

3. Testes específicos por app:

python manage.py test appointments.tests --settings=core.settings.testing -v 2
DJANGO_SETTINGS_MODULE=core.settings.testing pytest professionals/tests.py -v

4. Testes dentro do container Docker:

docker compose exec web python manage.py test --settings=core.settings.testing

5. Cobertura detalhada com pytest:

DJANGO_SETTINGS_MODULE=core.settings.testing pytest --cov=appointments --cov=professionals --cov-report=html --cov-report=term-missing

6. Testes de integração específicos:

python manage.py test appointments.tests.AppointmentIntegrationTestCase --settings=core.settings.testing

O projeto utiliza diferentes configurações para testes:

• Arquivo: core/settings/development.py
• Banco: PostgreSQL no container Docker
• Database: test_medical_api (temporário)
• Vantagem: Mesmo ambiente que desenvolvimento

• Arquivo: core/settings/testing.py
• Banco: SQLite em memória (:memory:)
• Vantagem: Mais rápido, sem dependências

O projeto usa Factory Boy para criar dados de teste dinamicamente:

# Exemplo de uso nas classes de teste
from tests.factories import ProfessionalFactory, AppointmentFactory

# Criar dados únicos automaticamente
professional = ProfessionalFactory()

# Customizar campos específicos
professional = ProfessionalFactory(
    preferred_name="Dr. João Silva",
    profession="Cardiologista"
)

# Criar múltiplos registros
professionals = ProfessionalFactory.create_batch(5)

• Testes de CRUD completo
• Validação de dados
• Filtros e ordenação
• Autenticação e permissões

• Validação de campos obrigatórios
• Representação string
• Ordenação padrão
• Timestamps automáticos

• Relacionamentos entre modelos
• Cascade delete
• Integridade referencial

• Total de testes: 33 testes
• Cobertura: 72,82% (acima do mínimo exigido de 25%)
• Status: ✅ Todos os testes passando
• Tempo de execução: ~0.2-1.2 segundos (dependendo do método)

Os relatórios HTML de cobertura são gerados automaticamente na pasta htmlcov/. Abra htmlcov/index.html no navegador para visualizar detalhes da cobertura.

O projeto utiliza um arquivo .env para configurações sensíveis:

# Segurança
SECRET_KEY=sua_chave_secreta_aqui
DEBUG=True

# Configurações do Django
DJANGO_SETTINGS_MODULE=core.settings.development

# Banco de dados
DB_NAME=medical_db
DB_USER=user
DB_PASSWORD=password
DB_HOST=db  # Para Docker, use 'localhost' para ambiente local
DB_PORT=5432

# Superusuário automático
DJANGO_SUPERUSER_PASSWORD=admin123

# Hosts permitidos
ALLOWED_HOSTS=localhost,127.0.0.1

O projeto suporta múltiplos ambientes:

• development: Para desenvolvimento local com PostgreSQL
• testing: Para testes com SQLite em memória
• production: Para produção (configurações de segurança aprimoradas)

A API utiliza os seguintes códigos de status HTTP:

• 200 OK - Requisição bem-sucedida
• 201 Created - Recurso criado com sucesso
• 204 No Content - Recurso deletado com sucesso
• 400 Bad Request - Dados inválidos na requisição
• 404 Not Found - Recurso não encontrado
• 500 Internal Server Error - Erro interno do servidor

{
  "field_name": [
    "Mensagem de erro específica"
  ],
  "non_field_errors": [
    "Erro geral da validação"
  ]
}

• Índices automáticos em chaves estrangeiras
• Ordenação otimizada por timestamps
• Queries eficientes com select_related para profissionais

O projeto está preparado para implementação de cache:

• Cache de sessão configurado
• Middleware de cache disponível
• Suporte a Redis (configuração manual necessária)

• CSRF protection habilitado
• XFrame protection ativo
• Validação de hosts permitidos
• Middleware de segurança configurado

Todas as configurações sensíveis são gerenciadas via variáveis de ambiente:

• Chaves secretas
• Credenciais de banco de dados
• Configurações de debug

1. Fork o projeto
2. Crie uma branch para sua feature (git checkout -b feature/AmazingFeature)
3. Commit suas mudanças (git commit -m 'Add some AmazingFeature')
4. Push para a branch (git push origin feature/AmazingFeature)
5. Abra um Pull Request

• Siga o PEP 8 para Python
• Use type hints quando possível
• Mantenha cobertura de testes acima de 70%
• Documente APIs com docstrings
• Escreva testes para novas funcionalidades

# Execute todos os testes
./run_tests.sh

# Verifique a cobertura
DJANGO_SETTINGS_MODULE=core.settings.testing pytest --cov=. --cov-report=term-missing

# Verifique a formatação do código
poetry run black --check .
poetry run flake8 .

Este projeto está licenciado sob a MIT License - veja o arquivo LICENSE para detalhes.

Para dúvidas ou sugestões sobre o projeto, abra uma issue no GitHub.

Após a instalação, você pode verificar se tudo está funcionando:

curl http://localhost:8000/api/docs/

# Listar profissionais
curl http://localhost:8000/api/professionals/

# Listar consultas
curl http://localhost:8000/api/appointments/

./run_tests.sh

Vá para http://localhost:8000/admin/ e faça login com:

• Usuário: admin
• Senha: admin123 (ou a definida em .env)

• ✅ Interface web com renderização do lado do servidor
• ✅ Página inicial com estatísticas em tempo real
• ✅ Visualização de próximas consultas com contador regressivo
• ✅ Listagem de especialidades disponíveis
• ✅ Formulário de contato interativo
• ✅ Design responsivo e moderno

• ✅ CRUD completo para profissionais da saúde
• ✅ CRUD completo para consultas médicas
• ✅ Filtros e busca avançada
• ✅ Documentação OpenAPI/Swagger
• ✅ Testes abrangentes (72,82% cobertura)
• ✅ Scripts de automação (setup, reset, testes)
• ✅ Suporte completo ao Docker
• ✅ Configurações multi-ambiente

• Autenticação e autorização
• Sistema de notificações
• API de relatórios
• Cache com Redis
• Logs estruturados
• Expansão da interface web

• Listagem detalhada de profissionais
• Página de detalhes do profissional
• Agendamento online de consultas
• Integração com calendários
• Backup automático
• Métricas e monitoramento

Esta proposta apresenta uma visão conceitual da integração com o sistema de pagamentos Asaas para automatizar o processo de cobrança de consultas médicas com split de pagamentos entre profissionais e plataforma.

Implementar um sistema automatizado de pagamentos que divida valores de forma transparente entre profissionais da saúde e a plataforma, garantindo:

• Automatização completa do fluxo de cobrança
• Transparência financeira em todas as transações
• Escalabilidade para crescimento da plataforma
• Compliance com regulamentações do setor

✅ Redução de custos operacionais com processamento manual
✅ Melhoria na experiência de usuários e profissionais
✅ Aumento na conversão de consultas agendadas
✅ Rastreabilidade completa de transações financeiras
✅ Preparação para escala e novos mercados

• Operações financeiras executadas em background
• Interface responsiva durante processamento
• Sistema de retry automático para falhas temporárias

• Divisão configurável entre profissional e plataforma
• Cálculo automático de taxas e impostos
• Liquidação instantânea via Asaas

• Validação rigorosa de webhooks
• Log completo de todas as operações
• Controle de acesso baseado em perfis

• Métricas em tempo real de pagamentos
• Alertas para falhas críticas
• Dashboard administrativo completo

Consulta: R$ 100,00
├── Profissional: R$ 85,00 (85%)
└── Plataforma: R$ 15,00 (15%)

1. Agendamento: Cliente agenda consulta com valor definido
2. Cobrança: Sistema gera cobrança automática via Asaas
3. Pagamento: Cliente efetua pagamento (PIX, cartão, boleto)
4. Split: Valor é dividido automaticamente
5. Liquidação: Cada parte recebe sua parcela instantaneamente

graph TD
    A[Cliente agenda consulta] --> B[Sistema cria cobrança]
    B --> C[Asaas gera fatura]
    C --> D[Cliente efetua pagamento]
    D --> E[Webhook notifica sistema]
    E --> F[Split automático executado]
    F --> G[Profissional e plataforma recebem valores]
    
    style A fill:#e3f2fd
    style G fill:#e8f5e8
    style F fill:#fff3e0

• PENDING: Aguardando pagamento do cliente
• PROCESSING: Pagamento sendo processado
• PAID: Pagamento confirmado e split executado
• FAILED: Falha no processamento
• REFUNDED: Valor reembolsado

• Backend: Django REST Framework
• Pagamentos: API Asaas para cobrança e split
• Processamento Assíncrono: Celery com Redis/RabbitMQ
• Webhooks: Endpoints seguros para notificações
• Monitoramento: Logs estruturados e métricas

• Modelo de Dados: Extensão para campos de pagamento
• API Layer: Endpoints para gestão de cobranças
• Background Tasks: Processamento assíncrono
• Webhook Handler: Recepção de notificações Asaas
• Admin Interface: Dashboard de monitoramento

• Volume total de transações
• Taxa de conversão de pagamentos
• Tempo médio de processamento
• Taxa de falhas e reprocessamentos
• Distribuição por método de pagamento

• Disponibilidade da integração Asaas
• Performance de webhooks
• Status de tarefas assíncronas
• Alertas para falhas críticas

• Extensão dos modelos de dados
• Configuração do ambiente Asaas
• Implementação da camada de serviços básica
• Testes unitários iniciais

• Sistema de cobrança automatizada
• Processamento de webhooks
• Split de pagamento funcional
• Validação e tratamento de erros

• Dashboard administrativo
• Sistema de métricas
• Alertas e notificações
• Logs estruturados

• Performance e escalabilidade
• Testes de carga
• Documentação completa
• Treinamento da equipe

• Validação de Webhooks: Assinatura criptográfica obrigatória
• Sanitização de Dados: Validação rigorosa de entradas
• Auditoria Completa: Log de todas as operações financeiras
• Backup e Recovery: Estratégia de contingência definida

• Retenção de logs por 7 anos (regulamentação financeira)
• Criptografia de dados sensíveis
• Controle de acesso baseado em perfis
• Relatórios de auditoria automatizados

• Receita automatizada e previsível
• Redução de custos operacionais
• Escalabilidade para crescimento
• Dados para análise de negócio

• Recebimento instantâneo
• Transparência nos repasses
• Menos burocracia financeira
• Foco na atividade médica

• Múltiplas formas de pagamento
• Segurança nas transações
• Experiência simplificada
• Transparência nos valores

• 99% de disponibilidade do sistema
• Tempo médio de processamento < 60 segundos
• Taxa de falhas < 3%
• Cobertura de testes > 70%

• Receita incremental por split
• Redução de inadimplência
• Escalabilidade do modelo de cobrança
• Transparência financeira para parceiros
• Aumento na conversão
• Redução no processamento manual
• ROI positivo
• NPS alto de profissionais e clientes

Esta proposta conceitual serve como base para discussões estratégicas e planejamento detalhado da implementação, focando nos benefícios e arquitetura de alto nível rather than detalhes de implementação específicos.