BeautyAppointment (Agendamento)

O BeautyAppointment representa um agendamento de servicos de estetica, controlando todo o fluxo desde a marcacao ate a conclusao.

Descricao

Um agendamento pode ser marcado (calendario) ou imediato (walk-in). Ele passa por um fluxo de check-in, execucao e checkout, com integracao automatica com vendas e financeiro.

Dados

Informacoes do Agendamento

Campo	Tipo	Obrigatorio	Descricao
status	Selecao	Sim	Estado atual do agendamento
schedule	Booleano	Sim	Se e agendado (true) ou imediato (false)
date_time	DataHora	Condicional	Data/hora do agendamento (obrigatorio se schedule=true)
end_time	DataHora	Calculado	Horario de termino (baseado na duracao)
done_time	DataHora	Auto	Horario de conclusao
service_time	Numero	Calculado	Tempo total em minutos
time_label	Texto	Auto	Representacao legivel do horario

Check-in/Checkout

Campo	Tipo	Descricao
checkin	Booleano	Se check-in foi realizado
checkin_date_time	DataHora	Horario do check-in
checkout	Booleano	Se checkout foi realizado
checkout_date_time	DataHora	Horario do checkout
paid	Booleano	Se todos os servicos estao pagos

Prioridade (Walk-in)

Campo	Tipo	Descricao
priority	Numero	Prioridade na fila (unico por loja)
priority_ordinal	Texto	Formato "Xo" (ex: "1o", "2o")

Recorrencia

Campo	Tipo	Descricao
schedule_frequency	Selecao	"one_time", "fixed", "session"
frequency	Selecao	Intervalo de recorrencia
frequency_end_date	Data	Data final (se fixed)
sessions	Numero	Numero de sessoes (se session)
current_session	Numero	Sessao atual (padrao: 1)
beauty_appointment_reference	Texto	ID do agendamento pai

Informacoes do Pet (Denormalizadas)

Campo	Tipo	Descricao
name	Texto	Formato "Cliente: Pet"
pet_breed	Texto	Raca do pet
pet_primary_color	Texto	Cor primaria
pet_secondary_color	Texto	Cor secundaria
pet_color_name	Texto	Nome da cor
pet_image_url	Texto	URL da foto do pet
pet_characteristic_ids	Array	Caracteristicas do pet

Taxidog

Campo	Tipo	Descricao
have_taxid_dog	Booleano	Se precisa de transporte

Relacionamentos

Pertence a

Entidade	Obrigatorio	Descricao
Account	Sim	Conta do petshop
Store	Sim	Filial
User	Sim	Operador que criou
Customer	Sim	Cliente
Pet	Nao	Pet (geralmente obrigatorio)
Cage	Condicional	Gaiola (obrigatorio se nao agendado)
Sale	Nao	Venda associada
BeautyScale	Condicional	Escala/profissional (obrigatorio se agendado)
CheckinForm	Condicional	Formulario de check-in
CheckoutForm	Condicional	Formulario de checkout
Address	Condicional	Endereco (obrigatorio se taxidog)

Possui

Entidade	Descricao
BeautyServices	Servicos executados
CheckinAnswers	Respostas do check-in
CheckoutAnswers	Respostas do checkout
Comments	Comentarios
WhatsappNotifications	Notificacoes enviadas
Deliveries	Entregas (taxidog)

Ciclo de Vida (Status)

Estados

Status	Descricao	Acoes Permitidas
scheduled	Agendado, aguardando	Check-in, Cancelar, Editar
checkin	Pet recebido, aguardando inicio	Iniciar, Voltar scheduled
running	Servico em execucao	Finalizar, Voltar check-in
checkout	Servico concluido, aguardando saida	Concluir, Voltar running
done	Concluido e finalizado	Nenhuma
canceled	Cancelado	Nenhuma

Regras de Transicao

De	Para	Condicoes
scheduled	checkin	Selecionar gaiola, preencher formulario
scheduled	canceled	Sempre permitido
checkin	running	Sempre permitido
checkin	scheduled	Pode reverter
running	checkout	Preencher formulario checkout
running	checkin	Pode reverter
checkout	done	Sempre permitido
checkout	running	Pode reverter

Check-in

Fluxo de Check-in

Formulario de Check-in

Campo	Tipo	Descricao
checkin_form_id	Referencia	Formulario a usar
checkin_answers	Array	Respostas as perguntas

Regras

1. Gaiola e obrigatoria para check-in
2. Gaiola deve estar vazia
3. Formulario de check-in e obrigatorio
4. Perguntas sao dinamicas por formulario

Checkout

Fluxo de Checkout

Formulario de Checkout

Campo	Tipo	Descricao
checkout_form_id	Referencia	Formulario a usar
checkout_answers	Array	Respostas as perguntas

Regras

1. Formulario de checkout e obrigatorio
2. Todos os servicos sao marcados como "done"
3. Venda e gerada automaticamente se servicos pendentes

Geracao de Venda

Quando Gera Venda

1. Ao marcar generate_sale = true no check-in
2. Ao mudar para checkout com servicos nao pagos

Logica

Gaiolas (Cage)

Ocupacao

• Gaiola marcada como empty: false quando atribuida
• Gaiola marcada como empty: true quando liberada

Liberacao Automatica

Gaiola e liberada quando:

• Status muda para "done"
• Agendamento e cancelado
• Agendamento e destruido
• Gaiola e trocada

Troca de Gaiola

Se gaiola e alterada:

1. Gaiola anterior: empty: true
2. Nova gaiola: empty: false

Recorrencia

Tipos de Recorrencia

Tipo	Descricao
one_time	Agendamento unico
fixed	Repete ate uma data final
session	Repete N vezes

Frequencias Disponiveis

Frequencia	Descricao
daily	Diario
weekly	Semanal
biweekly	Quinzenal
monthly	Mensal
bimonthly	Bimestral
quarterly	Trimestral
half_yearly	Semestral
yearly	Anual

Geracao de Agendamentos

Fixed

Cria agendamentos desde data inicial ate frequency_end_date
Todos compartilham mesmo beauty_appointment_reference

Session

Cria N agendamentos (sessions)
Cada um com current_session incrementado (1, 2, 3...)
Todos compartilham mesmo beauty_appointment_reference

Atualizacao de Serie

Opcao	Descricao
update_only	Atualiza apenas este agendamento
update_next	Atualiza este e futuros
update_all	Atualiza toda a serie

Prioridade (Walk-in)

Sistema de Fila

Para agendamentos nao agendados (walk-in):

1. Prioridade define ordem de atendimento
2. Deve ser unica por conta/loja/status
3. Valores menores ou iguais a 0 sao tratados como nulo
4. Exibida como ordinal (1o, 2o, 3o)

Ordenacao

ORDER BY priority EXISTS DESC, priority ASC

Agendamentos COM prioridade aparecem primeiro, depois por valor.

Taxidog

Quando Habilitado

Se have_taxid_dog = true:

• Endereco e obrigatorio
• Cria Delivery tipo "taxidog" para buscar o pet
• Cria Delivery de retorno ao mudar para checkout

Tipos de Delivery

Tipo	Quando Criado
get	Ao criar agendamento
delivery	Ao mudar para checkout

Notificacoes WhatsApp

Quando Enviado

Ao mudar para status "checkout":

• Se cliente tem WhatsApp
• Notificacao tipo "beauty_appointment_checkout"
• Status "queued"

Limpeza

Se status sai de "checkout": notificacoes pendentes sao removidas.

Automacoes

Ao Criar

1. Define checkin_date_time se walk-in
2. Copia caracteristicas do pet
3. Cria entregas taxidog (se aplicavel)
4. Gera agendamentos recorrentes (se aplicavel)
5. Vincula servicos

Ao Atualizar

1. Sincroniza status nos servicos
2. Atualiza gaiolas (ocupacao)
3. Propaga alteracoes para serie (se recorrente)
4. Cria delivery de retorno (se checkout + taxidog)
5. Envia notificacao WhatsApp (se checkout)

Ao Excluir

1. Libera gaiola
2. Servicos pagos voltam para "purchased"
3. Servicos nao pagos sao destruidos
4. Remove entregas taxidog

Validacoes

Campo	Regra	Quando
customer_id	Obrigatorio	Sempre
pet_id	Obrigatorio	Contextos especificos
date_time	Obrigatorio	Se schedule = true
beauty_scale_id	Obrigatorio	Se schedule = true
cage_id	Obrigatorio	Se status != scheduled e != done
new_services	Minimo 1 servico	Sempre
time	Slot disponivel	Se schedule = true
address_id	Obrigatorio	Se have_taxid_dog = true

Visualizacoes

Kanban

Colunas por status:

• scheduled, checkin, running, checkout, done
• Cards mostram: horario, foto pet, nome, raca, cliente, gaiola, prioridade, servicos

Calendario

• Titulo: nome (Cliente: Pet)
• Inicio/Fim: date_time / end_time
• Agrupado por BeautyScale

Tabela (Contexto Pet)

Colunas: cliente, servicos, data/hora, done_time, escala, status

Permissoes

Acao	Descricao
Criar	Criar novo agendamento
Editar	Apenas status = scheduled
Excluir	Apenas status = scheduled
Check-in	Mudar para checkin
Iniciar	Mudar para running
Checkout	Mudar para checkout
Concluir	Mudar para done
Reverter	Voltar status anterior