Quiosque de Reservas de Autoatendimento
Um quiosque é um site de reservas com o modelo de confiança invertido: o cliente não é autenticado por design e é fisicamente compartilhado, então toda a confiança reside no servidor (preços, capacidade, idempotência) e todo o estado é descartável (em memória, reinicialização automática, nunca persistido). Tudo nesta habilidade decorre desses dois fatos.
Quando usar
- Construir um terminal de reservas para capacidade baseada em slots (estações × janelas de tempo) com opcionais de equipamentos e consumíveis.
- Adicionar modo quiosque a um aplicativo que já possui reservas online.
- Auditar um quiosque existente em relação às regras rígidas abaixo; provenance.md registra a razão por trás de cada uma.
Quando NÃO usar
- Servidor de failover offline local — essa é a habilidade irmã
island-mode-server; esta habilidade define apenas o contrato de failover do lado do cliente do quiosque. - Sinalização digital / telas de exibição — capacidade diferente (reprodução, sem entrada), habilidade diferente.
- Ferramentas de POS ou administração de reservas para a equipe — a equipe é autenticada e confiável; o modelo de confiança desta habilidade está errado para eles.
- Um site de reservas comum — aproveite a costura do backend se útil, mas a maquinaria do quiosque (teclado, temporizadores, endurecimento de toque) é peso morto lá.
Arquitetura
KioskProvider (redutor puro: etapas, seleções, carrinho, sessionId)
│ props: fatias de dicionário hooks: preços · equipamentos · disponibilidade
telas: serviço→data→horário→participantes→equipamentos→resumo→confirmação
│ └─ fluxo lateral: consulta-reserva → edição-reserva
▼ um wrapper de busca (chave do dispositivo + URL base de failover offline)
/api/kiosk/booking/{create,lookup,add-items,edit} ← todas as decisões de confiança
▼ Costura KioskBackend: preços do servidor · promoção · bloqueios de estoque (TTL 15 min)
re-verificação transacional de capacidade · pagamento no balcão/online · webhook
tempo real: location.lastBookingChangeAt → nova busca silenciosa → REFRESH_SLOT
Fatos críticos
- Toques do usuário navegam; atualizações em segundo plano nunca o fazem.
SET_SLOTvsREFRESH_SLOTé a diferença entre disponibilidade ao vivo e teletransportar um cliente para fora da tela de resumo no meio da compra. - O servidor precifica tudo. Nada que se pareça com dinheiro cruza o fio de entrada; o total do cliente é uma prévia.
- Pagamento no balcão é o caminho de resiliência — a reserva confirma com
PENDING_COUNTER_PAYMENT, sem integração de pagamento no loop; pagamento online em um quiosque significa um QR que o cliente escaneia, nunca navegando o quiosque para longe. - Toda entrada de texto abre o teclado na tela e define
inputMode="none". Um sem o outro é uma tela inutilizável. - Bloqueios de estoque são reservados com TTL (15 min) e liberados em todo caminho de falha — o trabalho de varredura é a rede de segurança, não o mecanismo.
- O sessionId do cliente é a chave de idempotência. Toque duplo, repetição, resposta perdida: no máximo uma reserva.
Regras rígidas
Nunca persista o estado da sessão do quiosque. O próximo cliente não deve ver o nome do anterior. Em memória + reinicialização por inatividade de 120 s + reinicialização de confirmação de 30 s, verificado em hardware.
Nunca confie no cliente para preços, capacidade ou validade de promoção. O servidor calcula cada valor e responde a uma promoção inválida com
PROMO_INVALID; um cliente em um quiosque não tem como verificar o valor.
Um wrapper de busca para cada requisição do quiosque. O wrapper carrega o cabeçalho do dispositivo, o envelope de erro e a URL base de failover, para que autenticação, erros e failover offline se apliquem a cada requisição de uma vez.
Se a chave do dispositivo estiver configurada, um cabeçalho ausente é um 401. Apenas rejeitar com chave errada é o mesmo que nenhuma autenticação.
Libere bloqueios de estoque em todo caminho de falha após adquiri-los. Um 409 que mantém a reserva congela o estoque pelo TTL completo.
Início rápido
- Leia state-machine.md; implemente o redutor e o provedor, execute seu conjunto de testes.
- Construa telas de acordo com o contrato em screens.md com o sistema de design do anfitrião — teclado, temporizadores, endurecimento de toque.
- Implemente as rotas de api-contract.md sobre a costura booking-backend.md.
- Conecte atualização + offline conforme realtime-offline.md.
- Implante e teste de fumaça conforme operations.md.
Contrato de Adaptação
| Costura | Esta habilidade fornece | O anfitrião fornece |
|---|---|---|
| Entidades de domínio | serviço/estação/equipamento/consumível + tabela de renomeação | seu vocabulário (quadra, kart, baía…) |
| Escopo do locatário | locationId na URL do quiosque, verificado pelo servidor | seu modelo de local/site |
| Autenticação do dispositivo | Contrato x-kiosk-api-key | gerenciamento de chaves; tokens opcionais por dispositivo |
| Acesso a dados | Interface KioskBackend; referência Firestore + esboço SQL | seu ORM/SDK |
| Pagamentos | status de balcão + contrato de sessão de checkout/webhook | Stripe ou equivalente |
| Tempo real | Interface SubscribeFreshness | Firestore/Supabase/SSE/polling |
| Offline | Contrato NetworkStatus | servidor LAN (island-mode-server) ou nenhum |
| Primitivas de UI | estrutura, estados, regras de interação | botões, diálogo, spinner, aparência |
| Estilização | intenção de layout, alvos de toque, um token --primary | seu sistema de design |
| Strings | árvore de chaves de dicionário, todas as chaves obrigatórias | seus arquivos i18n, todas as localidades |
| Validação | guardas sem dependências | sua biblioteca de esquemas, se houver |
Diretório de referência
| Cenário | Palavras-chave de gatilho | Referência |
|---|---|---|
| Estado, etapas, redutor, sessão, testes | etapa, redutor, GO_BACK, REFRESH_SLOT, sessionId, reset | state-machine.md |
| Telas, teclado, temporizadores, toque, chaves i18n | teclado na tela, inatividade, contagem regressiva, QR, alvo de toque, dicionário | screens.md |
| Rotas, autenticação, validação, idempotência, erros | x-kiosk-api-key, 401, 409, idempotência, PROMO_INVALID, consulta, PII | api-contract.md |
| Capacidade, estoque, pagamentos, webhook, crons | transação, bloqueio de estoque, TTL, PENDING_COUNTER_PAYMENT, webhook, reembolso | booking-backend.md |
| Atualização ao vivo, cache, failover offline | lastBookingChangeAt, onSnapshot, s-maxage, banner offline, LAN, sonda de saúde | realtime-offline.md |
| Implantação, controle de acesso, superfície do operador | Edge --kiosk, acesso atribuído, batimento cardíaco, feature gate, teste de fumaça | operations.md |
| Por que os modelos diferem da implementação anterior | auditoria, razão, mantido deliberadamente, adicionado | provenance.md |