Hoteis & Pousadas¶

Sistema completo de gestao hoteleira — reservas, quartos, hospedes, check-in/out, pagamentos e comunicacao via WhatsApp.

Visao Geral¶

O sistema de Hoteis & Pousadas e uma plataforma SaaS multi-tenant para gestao hoteleira completa. Cada hotel opera de forma isolada com seus proprios quartos, reservas, clientes e configuracoes.

Funcionalidades Principais¶

Modulo	Descricao
Quartos	CRUD, status (disponivel, ocupado, manutencao, limpeza), precificacao dinamica
Reservas	Criacao, confirmacao, check-in/out, cancelamento, pagamento parcial
Hospedes	Cadastro, historico, documentos, avaliacao
Pagamentos	PIX, cartao, boleto via CoinKeeper, cupons de desconto
Cafe da Manha	Modos (incluso, extra, nenhum), pedidos diarios, restaurantes
Limpeza	Tarefas de housekeeping com workflow (pendente → em andamento → concluido → verificado)
Ambientes	Gestao de espacos para eventos (saloes, areas de lazer)
Financeiro	Ledger, DRE, centros de custo
NFS-e	Emissao de notas fiscais via Tax Collector
Comunicacao	Email SMTP personalizado + WhatsApp via Herald
Canais	Sincronizacao iCal com Airbnb, Booking e outros

Stack¶

Camada	Tecnologia
Backend	Quarkus 3.17 + Java 21 + PostgreSQL 16
Frontend	React 18 + Vite + TypeScript + Tailwind CSS
Auth	JWT via OATH + roles via Guild
Pagamentos	CoinKeeper (Stripe + AbacatePay)
Arquivos	Vault (MinIO/S3)
Email	Herald (SMTP customizavel por hotel)
WhatsApp	Herald + Evolution API

Multi-Tenancy¶

Cada hotel e um tenant isolado. Um usuario pode ter acesso a multiplos hoteis com roles diferentes.

graph LR
    U[Usuario] --> H1[Hotel A<br/>ADMIN]
    U --> H2[Hotel B<br/>GERENTE]
    U --> H3[Hotel C<br/>SECRETARIA]

Modelo de Isolamento¶

Todas as entidades possuem hotel_id como chave estrangeira
Queries filtradas pelo hotel selecionado no contexto
Header X-Hotel-Id em todas as requisicoes do frontend
UserHotelAssignment mapeia usuarios a hoteis com roles

Roles e Permissoes¶

Role	Nivel	Acesso
`MASTER`	Sistema	Acesso total (superusuario OATH)
`HOTEL_ADMIN`	Hotel	Administracao completa do hotel
`HOTEL_GERENTE`	Hotel	Gestao operacional (sem exclusoes)
`HOTEL_SECRETARIA_BALCAO`	Hotel	Recepcao: reservas, check-in/out, clientes
`HOTEL_BAR`	Hotel	Apenas visualizacao (bar/restaurante)

Alem dos roles, cada usuario pode ter permissoes customizadas por hotel via UserCustomPermission.

Fluxo de Reserva¶

stateDiagram-v2
    [*] --> PENDING: Reserva criada
    PENDING --> CONFIRMED: Confirmacao
    CONFIRMED --> CHECKED_IN: Check-in
    CHECKED_IN --> CHECKED_OUT: Check-out
    PENDING --> CANCELLED: Cancelamento
    CONFIRMED --> CANCELLED: Cancelamento

Fontes de Reserva¶

DIRECT — Reserva direta pelo sistema
AIRBNB — Sincronizacao via iCal
BOOKING — Sincronizacao via iCal
CHANNEL_SYNC — Outras plataformas

Pagamentos¶

sequenceDiagram
    participant FE as Frontend
    participant BE as Backend
    participant CK as CoinKeeper
    participant S as Stripe/PIX

    FE->>BE: Criar pagamento
    BE->>CK: POST /checkout ou /pix
    CK->>S: Processar
    S-->>CK: Resultado
    CK-->>BE: URL/QR Code
    BE-->>FE: Link de pagamento

    Note over CK,BE: Webhook de confirmacao
    CK->>BE: POST /payments/webhook
    BE->>BE: Atualiza pagamento + reserva

Configuracao de Pagamento por Hotel¶

Percentual de deposito: Padrao 50%
Primeiro pagamento: Na confirmacao ou check-in
Segundo pagamento: No check-in ou check-out

Comunicacao¶

Email¶

Cada hotel pode configurar SMTP proprio:

smtpHost, smtpPort, smtpUsername, smtpPassword (criptografado AES-256)
Fallback para SMTP padrao da aplicacao
Templates de email para confirmacao, lembrete e agradecimento

WhatsApp¶

Numero de WhatsApp por hotel (whatsappNumber)
Templates de mensagem configuraveis
Notificacoes automaticas de check-in, reserva e lembrete
Gerenciado via Herald + Evolution API

Integracao com Canais (iCal)¶

sequenceDiagram
    participant S as Scheduler<br/>(30 min)
    participant BE as Backend
    participant CH as Airbnb/Booking

    S->>BE: Trigger sync
    BE->>CH: GET iCal feed
    CH-->>BE: Eventos iCal
    BE->>BE: Parse + mapear quartos
    BE->>BE: Criar/atualizar reservas

ChannelSyncScheduler roda a cada 30 minutos
Channel configura URL do iCal por plataforma
ChannelRoomMapping mapeia quartos locais para listagens externas