Pular para conteúdo

Checklist — novo projeto OTIMUS

Use este checklist passo-a-passo ao criar um chatbot para uma clínica nova que usa OTIMUS. Marque cada item. Se algum não for aplicável, anote o motivo no commit.

Fase 1 — Preparação

  • [ ] Conversa com a clínica para levantar:
    • [ ] Nome da clínica, endereço, telefone principal
    • [ ] Horário de funcionamento
    • [ ] Lista de médicos com nome completo e especialidade
    • [ ] Lista de convênios aceitos e se cada um tem agendamento web
    • [ ] Lista de procedimentos/exames
    • [ ] Regras de preço (particular)
    • [ ] Regras especiais (médicos em licença, exames que transferem)
  • [ ] Credenciais OTIMUS:
    • [ ] OTIMUS_API_URL (subdomínio + porta)
    • [ ] OTIMUS_TOKEN (solicitado à clínica)
    • [ ] Teste manual via curl que o token funciona (Autenticação)
    • [ ] IDs de convênios (fornecidos pela clínica/OTIMUS)
    • [ ] IDs de agendas dos médicos
    • [ ] IDs de procedimentos e especialidades
  • [ ] Credenciais WTS Chat:
    • [ ] WTS_API_TOKEN
    • [ ] WTS_CHANNEL_ID
    • [ ] WTS_DEPARTMENT_HUMAN_ID
    • [ ] WTS_DEPARTMENT_AI_ID
    • [ ] ALLOWED_INSTANCE (número de WhatsApp)
    • [ ] ALLOWED_TEAM nome configurado no painel
  • [ ] Credenciais LLM:
    • [ ] OPENAI_API_KEY com tier suficiente
    • [ ] GEMINI_API_KEY

Fase 2 — Código

  • [ ] Clone do projeto mais próximo (MEDCENTER ou CLINFETO) como seed.
  • [ ] Criar scheduling.py / agendamento.py com:
    • [ ] _otimus_headers() lendo de env
    • [ ] PROCEDIMENTOS preenchido com IDs reais
    • [ ] CONVENIOS preenchido
    • [ ] _DOCTOR_KEYWORDS com primeiros nomes únicos validados
    • [ ] _validate_unique_first_names() travando no boot
    • [ ] guardian_validate (se > 5 procedimentos distintos)
    • [ ] Normalizadores (_normalize, _only_digits, _yyyymmdd_to_ddmmyyyy)
    • [ ] Helpers de slots (_filter_and_select_slots, _slot_disponivel)
    • [ ] Validação de agendaNome no response
  • [ ] agent.py:
    • [ ] LLM com modelo apropriado (gpt-4.1-mini default)
    • [ ] PostgresSaver com fallback MemorySaver
    • [ ] 3 tools: transferir_atendimento, consultar_horarios, agendar_consulta
    • [ ] Docstrings de tool explícitas sobre formato e FALHA_CONSULTA
    • [ ] Contextvars (session_id, phone_number, contact_name)
    • [ ] Tools in-process (não loopback HTTP)
    • [ ] Injeção de data/hora atual no run_agent
    • [ ] run_agent loga tokens e captura erros
  • [ ] workflow.py:
    • [ ] @entrypoint LangGraph
    • [ ] Filtros (plataforma, instância, equipe, status)
    • [ ] Processamento de mídia (IMAGE/AUDIO/DOCUMENT)
    • [ ] Debounce + anti-overlap (fetch_and_clear_queue)
    • [ ] Chama run_agent com session_id como thread_id
    • [ ] Split por \n\n no envio
  • [ ] wts_client.py:
    • [ ] get_session_by_id, send_message_in_session, transfer_session, add_tags
    • [ ] Token lido de env
  • [ ] processors.py:
    • [ ] process_image, process_document, process_audio
  • [ ] server.py:
    • [ ] POST /webhook/message (thread background, 202 rápido)
    • [ ] POST /webhook/transfer
    • [ ] GET /health
  • [ ] tracking.py — todas as funções de log
  • [ ] config.py — centralizar leitura de env
  • [ ] init.sql — schema completo
  • [ ] Dockerfile + docker-compose.yml + .env.template
  • [ ] CLAUDE.md — guia específico do projeto, apontando para OTIDOC

Fase 3 — System Prompt

  • [ ] Identidade (nome do bot, clínica, tom)
  • [ ] Saudação com menu numerado
  • [ ] Lista de médicos com especialidade
  • [ ] Lista de convênios com agendamento web + lista dos que transferem
  • [ ] Lista de procedimentos (apenas os suportados)
  • [ ] Processo de agendamento em etapas
  • [ ] Critérios de transferência para humano
  • [ ] Regras invioláveis: FALHA_CONSULTA, CPF 11 dígitos, data ISO, hora HH:MM, convênio por nome (não ID)
  • [ ] Formatação: mensagens curtas, \n\n entre parágrafos, sem markdown tabela, emojis com parcimônia
  • [ ] Regras de exceção (médicos indisponíveis, IG obstétrica, etc.)

Fase 4 — Testes

  • [ ] Cliente OTIMUS isolado:
    • [ ] _chamar_api_horarios retorna lista não-vazia para um médico com agenda ativa
    • [ ] _buscar_paciente_cpf retorna None para CPF inexistente e dict para existente
    • [ ] _validar_agenda_medico aceita match e rejeita divergência
  • [ ] Workflow ponta-a-ponta:
    • [ ] Mensagem texto simples → agente responde saudação
    • [ ] Pedido de agendamento → consulta horários → lista opções
    • [ ] Paciente escolhe opção + fornece dados → agendamento confirmado
    • [ ] Imagem de pedido médico → Gemini extrai dados → agente usa
    • [ ] Áudio → Whisper transcreve → agente responde coerente
    • [ ] Pedido fora de escopo → transfere
  • [ ] Cenários de erro:
    • [ ] OTIMUS lento/fora → FALHA_CONSULTA após 2 retries → transfere
    • [ ] Convênio desconhecido → FALHA_CONSULTA → transfere
    • [ ] Médico ambíguo/desconhecido → FALHA_CONSULTA → transfere
    • [ ] CPF mal formatado → normaliza ou rejeita com mensagem clara
    • [ ] Slot ocupado no pre-check → FALHA_CONSULTA → transfere
  • [ ] Concorrência:
    • [ ] 3 mensagens rápidas do mesmo paciente → um único invoke após debounce
    • [ ] Mensagens de 2 pacientes diferentes simultâneas → não misturam
  • [ ] Validação de primeiro nome único:
    • [ ] Adicionar "médico fake" com primeiro nome duplicado → container tira RuntimeError no boot (esperado)

Fase 5 — Infraestrutura

  • [ ] Postgres com volume persistente
  • [ ] Backup diário configurado
  • [ ] Reverse proxy (Caddy/nginx) expondo HTTPS
  • [ ] Webhook do WTS apontando para https://<host>/webhook/message
  • [ ] Health check do uptime configurado para /health
  • [ ] Logs do container acessíveis (docker logs ou journaling)
  • [ ] Alerta para dashboard_errors crescendo

Fase 6 — Entrega

  • [ ] CLAUDE.md no repositório do projeto
  • [ ] README com quick start
  • [ ] OTIDOC atualizado (adicionar o projeto em comparacao.md)
  • [ ] Treinamento da clínica:
    • [ ] Como acessar painel WTS
    • [ ] Como transferir manualmente
    • [ ] Como escalar para dev em caso de bug
  • [ ] Soft launch: ativar para 5-10 pacientes-teste antes de abrir geral.

Fase 7 — Pós-lançamento (primeiras 2 semanas)

  • [ ] Revisar dashboard_errors diariamente
  • [ ] Revisar gravações de conversas (WTS) para ajustes no prompt
  • [ ] Ajustar thresholds (debounce, número de slots) conforme feedback
  • [ ] Documentar bugs em aberto

Anti-checklist — o que NÃO fazer

Erros comuns ao iniciar projeto novo:

  • ❌ Copiar scheduling.py do Medcenter sem trocar IDs — vai chamar OTIMUS da clínica errada.
  • ❌ Deixar OTIMUS_TOKEN default hardcoded para não precisar setar env.
  • ❌ Reusar o mesmo ALLOWED_INSTANCE de outro projeto.
  • ❌ Carregar o prompt de outro projeto sem editar — o agente vai chamar pacientes pelo nome errado ("Mel do Medcenter").
  • ❌ Desligar _validate_unique_first_names para "sair rápido".
  • ❌ Usar loopback HTTP para tools (replicar CLINFETO). Prefira in-process.
  • ❌ Testar só a golden path. Teste FALHA_CONSULTA também.