Chronos¶

Sistema de agendamento para clinicas e profissionais — consultas, servicos, pagamentos, lembretes por email e confirmacao via WhatsApp.

Visao Geral¶

O Chronos e uma plataforma SaaS multi-tenant para agendamento online de servicos. Clinicas, consultorios e profissionais independentes podem gerenciar sua agenda, servicos, clientes e pagamentos.

Funcionalidades Principais¶

Modulo	Descricao
Agendamentos	Criacao, confirmacao, cancelamento, conclusao
Servicos	Catalogo com duracao, preco, categoria
Profissionais	Perfis, especialidades, servicos vinculados
Clientes	Cadastro, tags, historico de agendamentos
Agenda	Horarios por profissional, excecoes, feriados
Locais	Multiplas unidades de atendimento
Salas	Reserva de salas/consultorio com pricing
Promocoes	Codigos de desconto com regras complexas
Pagamentos	PIX, cartao via CoinKeeper
WhatsApp	Confirmacao 24h + cancelamento agendado
Email	Lembretes e confirmacoes automaticas
Pagina Publica	Booking online pelo cliente

Stack¶

Camada	Tecnologia
Backend	Quarkus 3.17 + Java 21 + MongoDB 7
Frontend	Next.js 16 + React 19 + TypeScript + Tailwind CSS
Auth	JWT via OATH + roles via Guild
Pagamentos	CoinKeeper (Stripe + AbacatePay)
WhatsApp	Herald + Evolution API
Email	Herald (SMTP)

Multi-Tenancy¶

Cada clinica/profissional e um tenant no Chronos:

tenantId (ObjectId) em todos os documentos MongoDB
Header X-Tenant-Id em todas as requisicoes
Configuracoes independentes por tenant (timezone, cor, logo, SMTP)
Pagina publica em /c/{slug}

Roles¶

Role	Descricao
`CHRONOS_ADMIN`	Administracao completa
`CHRONOS_MANAGER`	Gestao operacional
`CHRONOS_PROFESSIONAL`	Acesso limitado ao profissional
`CHRONOS_RECEPTIONIST`	Gestao de agendamentos

Fluxo de Agendamento¶

stateDiagram-v2
    [*] --> PENDING: Agendamento criado
    PENDING --> CONFIRMED: Confirmacao manual/auto/WhatsApp
    CONFIRMED --> IN_PROGRESS: Inicio do atendimento
    IN_PROGRESS --> COMPLETED: Atendimento concluido
    PENDING --> CANCELLED: Cancelamento
    CONFIRMED --> CANCELLED: Cancelamento
    CANCELLED --> CONFIRMED: Desfazer cancelamento

Criacao de Agendamento¶

Valida disponibilidade do profissional
Calcula duracao e preco dos servicos
Cria/atualiza cliente se necessario
Define status inicial (PENDING ou CONFIRMED conforme config do tenant)
Gera codigo do agendamento
Envia email de confirmacao

Pagina Publica de Booking¶

sequenceDiagram
    participant C as Cliente
    participant FE as Pagina Publica
    participant BE as Chronos API

    C->>FE: Acessa /c/{slug}
    FE->>BE: GET /bff/public/c/{slug}
    BE-->>FE: Info do tenant

    C->>FE: Seleciona servico
    FE->>BE: GET /availability
    BE-->>FE: Horarios disponiveis

    C->>FE: Preenche dados + confirma
    FE->>BE: POST /appointments
    BE-->>FE: Codigo do agendamento
    BE->>BE: Envia email de confirmacao

Passos do Booking (Frontend)¶

Selecionar servico — Lista de servicos com preco e duracao
Selecionar profissional — (Se habilitado pelo tenant)
Escolher data e horario — Calendar + slots disponiveis
Dados do cliente — Nome, email, telefone, observacoes
Confirmacao — Codigo do agendamento + validacao de promocao

Motor de Disponibilidade¶

O AvailabilityEngine calcula slots disponiveis:

Carrega agenda ativa do profissional para a data
Verifica excecoes (ferias, bloqueios)
Gera slots (modo INTERVALS ou FIXED_SLOTS)
Remove horarios ja ocupados
Retorna lista de TimeSlot com horarios formatados

Suporta calculo por profissional individual ou agregado (todos os profissionais).

WhatsApp — Confirmacao e Cancelamento¶

Confirmacao 24h antes¶

sequenceDiagram
    participant S as Scheduler<br/>(15 min)
    participant BE as Chronos
    participant H as Herald
    participant WA as WhatsApp

    S->>BE: Buscar agendamentos 23-25h
    BE->>H: Enviar msg confirmacao
    H->>WA: "Confirme respondendo CONFIRMAR"
    WA-->>H: Cliente responde "CONFIRMAR"
    H->>BE: Webhook /webhooks/whatsapp/incoming
    BE->>BE: Status → CONFIRMED
    BE->>H: Enviar ack "Confirmado!"

Cancelamento agendado (1h delay)¶

sequenceDiagram
    participant P as Profissional
    participant BE as Chronos
    participant S as Scheduler<br/>(5 min)
    participant WA as WhatsApp

    P->>BE: Cancelar agendamento
    BE->>BE: Criar ScheduledMessage (1h)
    BE->>BE: Enviar email imediato

    Note over P,WA: Se desfizer antes de 1h
    P->>BE: Desfazer cancelamento
    BE->>BE: Cancela ScheduledMessage

    Note over P,WA: Se nao desfizer
    S->>BE: ScheduledMessage due
    BE->>WA: Enviar msg cancelamento

Promocoes¶

O PromotionEngine suporta descontos complexos:

Tipo	Descricao
`PERCENT`	Percentual sobre o total
`FIXED`	Valor fixo de desconto
`ITEM_PERCENT`	Percentual por item
`ITEM_FIXED`	Valor fixo por item

Restricoes de Promocao¶

Limite de uso total e por cliente
Servicos e profissionais aplicaveis
Dias da semana permitidos
Valor minimo do pedido
Periodo de validade
Desconto maximo (cap)
Auto-apply (aplicacao automatica)

Configuracoes do Tenant¶

{
  showProfessionals: boolean      // Mostrar profissionais na pagina publica
  allowOnlineBooking: boolean     // Permitir agendamento online
  bookingWindowDays: number       // Janela de agendamento (dias)
  minNoticeMinutes: number        // Antecedencia minima
  cancellationWindowMinutes: number // Janela de cancelamento
  requirePaymentUpfront: boolean  // Exigir pagamento antecipado
  autoConfirmAppointments: boolean // Confirmar automaticamente
  defaultCurrency: string         // Moeda padrao (BRL)
  brandColor: string              // Cor da marca
}