Manual do calendário (PMS)

1. Visão geral

O calendário mostra disponibilidade e reservas por propriedade, tipo ou unidade. A grelha desloca-se horizontalmente por datas; a coluna da esquerda (propriedade/unidade) fica fixa ao fazer scroll.

2. Barra de ferramentas

• Drag & drop / ALL / Filtros — definições de vista, canais e detalhes de linhas.
• Properties — mostrar ou ocultar propriedades e unidades.
• Resort · Tipo · Unidade — modo de agregação das linhas.
• Multi mensal — define um mínimo de dias (1 / 2 / 3 / 6 / 12 meses); a largura útil da área do calendário define quantos dias cabem com células de tamanho fixo — ecrã mais largo = mais colunas, sem alargar as células. O modo escolhido nunca mostra menos do que esse mínimo (pode ser preciso scroll horizontal em modos longos em ecrã estreito).
• Mês e setas — navegação no tempo. O menu do mês só lista o mês corrente e meses futuros; a seta «‹» não recua antes de hoje. Para ir a datas passadas, use o campo Ir para (data manual).
• Check-in — Check-out — intervalo destacado na grelha (linhas verticais) e uso em “Nova reserva” quando aplicável.
• Manual calendário — abre este documento.

3. Cores e cabeçalhos de dia

• Bordas por dia (cabeçalho e células vazias das unidades), com sombra interior para as riscas da grelha continuarem visíveis: esquerda — feriado (vermelho); direita — sábado ou domingo (azul); topo — período UK das férias escolares (magenta); base — período UE das férias escolares (laranja). Fundos: laranja claro (UE) e lilás (UK) nas férias escolares; rosado em feriados (feriado prevalece sobre férias quando coincidem).
• Férias escolares (UE / UK) — demo em schoolHolidayPeriodEu / schoolHolidayPeriodUk; tooltip (data-day-tip) com período nomeado. Se UE e UK coincidem na mesma época, uma linha fundida no tooltip. Linha resort: só faixa âmbar.
• Feriados — holidayInfoByIso (fixos MM-DD + móveis PT via easterSundayGregorian). Sem barra de feriado na linha resort.

4. Barras de reserva (“pills”)

Cada reserva aparece como uma barra horizontal com favicon oficial do canal (Airbnb, Booking.com; direto e interno com ícone dedicado) — imagem a cores sem desbotar — e nome do hóspede. Ficheiros em unified_messaging/assets/ota/.

4.1 Alinhamento nos dias (check-in / check-out)

A barra começa ao centro vertical da célula do primeiro dia (entrada) e termina ao centro da célula do último dia com noite (a data de saída no sistema é exclusiva). Assim, duas estadias consecutivas encontram-se a meio da coluna do dia de transição, como num Gantt clássico.

Se o check-in for antes do primeiro dia visível na grelha, a barra encosta à esquerda da célula, fica sem capuz redondo desse lado e mostra uma seta para a esquerda (“continua antes da vista”). Se a estadia prolongar para além do último dia visível, o mesmo na direita, com seta para a direita. Nesses casos a pílula preenche a altura da linha na área da reserva.

4.2 Altura

A barra ocupa cerca de 95% da altura da célula para melhor leitura e espaço para alertas futuros.

4.3 Barra de progresso de pagamento

Quando a reserva tem dados financeiros (ou valores balance / payout na demo):

• O fundo da barra fica vermelho no valor que falta liquidar;
• Um preenchimento verde, da esquerda para a direita, indica a percentagem já paga / liquidada;
• 100% verde quando não há saldo em falta (ex.: balance zero e valor recebido coerente).

A largura do trilho do medidor (faixa sob o nome) é proporcional ao número de noites da estadia, com referência máxima de 4 noites: 1 noite ocupa cerca de 25 % da largura máxima possível; 4 ou mais noites usam 100 % dessa referência. O preenchimento verde continua a refletir apenas a percentagem paga dentro desse trilho.

Para reservas de OTA, o saldo mostrado no canal pode referir-se à liquidação pela plataforma (ex. cartão virtual), e não a um pagamento que o hóspede deva fazer diretamente ao alojamento. No menu Canais: cor e liquidação, cada origem pode definir-se como OTA (cartão virtual / plataforma) ou Depende do hóspede. No primeiro caso, sem extras de limpeza agendados na reserva, a barra assume o estado normal (100 %) para a parte inferida só por payout/saldo; com extras, volta a aplicar-se a fração inferida (extras cobrados ao hóspede). Valores explícitos paymentPct, bookingTotal/amountPaid não são alterados por esta regra.

Campos opcionais na reserva (quando existir API): bookingTotal, amountPaid ou paymentPct (0–100) sobrepõem o cálculo estimado.

6. Interação na grelha

• Clique esquerdo — define intervalo (1.º check-in, 2.º check-out) e pode abrir Nova reserva com datas preenchidas (cliques sobre a barra da reserva não alteram o intervalo); Esc anula esse intervalo (marcas verde / vermelho nas bordas do cabeçalho das colunas, sem cobrir as pílulas da grelha), exceto com foco num campo de formulário ou com um modal aberto por cima.
• Clique direito — menu de ações do dia (reserva, bloqueio, tarefas, estados operacionais).
• Clicar na reserva — abre o painel de detalhe (ver 6.1). Voltar a clicar na mesma reserva fecha; Esc ou clique fora também fecham.

6.1 Detalhe da reserva (tooltip)

O painel abre junto à barra da reserva (não segue o cursor). Permanece aberto para usar os botões até fechar (Esc, clique fora ou novo clique na mesma reserva).

• Ações de contacto no cabeçalho (email, WhatsApp, SMS) usam os dados visíveis no detalhe como texto de rascunho;
• Abrir reserva abre o mesmo modal utilizado em Nova reserva, em modo edição: pode alterar datas, unidade, canal, hóspede, contactos, etc., e guardar sem sair do calendário;
• Adicionar tarefa e Limpeza e extras mantêm o comportamento descrito nas secções seguintes.

6.2 Edição de reserva e cálculo automático de preço (demo)

No modal de edição, ao mudar check-in, check-out ou unidade, o campo Valor líquido a receber é recalculado automaticamente com base em:

• Proporção de noites — relativamente à estadia que existia quando abriu o ecrã;
• Fator por unidade — na demonstração, cada unidade (CH-1 … CH-10) tem uma tarifa líquida de referência por noite usada só para escalonar valores entre quartos; não substitui tarifário real nem integrações de API.

É mostrada uma linha de ajuda sob o campo; o valor continua editável à mão. Ao guardar, na demo, payout, comissão, taxa de pagamento e saldo são ajustados na mesma proporção que o cálculo automático (para manter coerência com a barra de pagamento na grelha).

6.3 Arrastar reservas (drag & drop)

Quando a opção estiver ativa na barra do calendário, pode arrastar o bloco da reserva para outra unidade e/ou outras datas. Ao largar na grelha, não se aplica de imediato: abre-se o ecrã Confirmar alteração da reserva com o resumo Antes / Depois para validar ou cancelar.

Arrastar o modal: pode clicar no título, no subtítulo ou na área do aviso (mantendo de fora a tabela e os botões) e arrastar a janela para o lado — assim vê a grelha por baixo enquanto revê as alterações.

Se a nova posição se sobrepuser a outra reserva na mesma unidade, o modal indica conflito e o botão de confirmação fica indisponível até corrigir ou cancelar.

Após confirmar o movimento, o plano de limpeza e os extras guardados para essa reserva acompanham a nova posição na demonstração (mesma reserva, nova chave interna).

6.4 Limpeza e extras (toalhas, lençóis, limpeza adicional)

No detalhe da reserva (após clicar na barra), o botão Limpeza e extras abre um ecrã para:

• Alterar o plano de limpeza (texto livre, com modelos rápidos: saída padrão, limpeza durante a estadia, profunda a meio da estadia);
• Agendar serviços com custo extra: mudança de toalhas, mudança de lençóis ou limpeza adicional — cada linha tem data (dentro do período da reserva) e preço em euros, com nota opcional;
• Ver o total dos extras antes de guardar. Os dados persistem no navegador (demonstração).

Com extras guardados, a barra da reserva pode mostrar um indicador €+ no calendário.

7. Registos de depósitos e entregas em numerário

Para registo de depósitos bancários ou dinheiro entregue com assinatura no tablet ou telemóvel, use a página dedicada e o respetivo guia:

• Formulário de registo (abre num novo separador a partir do manual local);
• Manual — depósitos e entregas.

8. Manutenção deste manual

Ficheiro: unified_messaging/docs/calendario-manual.html. Ao alterar regras de negócio ou UI do calendário, atualize este HTML para manter uma única fonte de verdade para equipa e utilizadores.

Alterações recentes (março 2026): painel de detalhe da reserva mais estável e com Abrir reserva no calendário; modal Confirmar alteração da reserva arrastável; cálculo automático de preço ao editar reserva (demo).