# SPEC — KDS Operacional do Pizzaiolo (Modelo B) **Status:** aprovado para implementação **Produto:** Pizzaza / Pizza Digital **Data:** 2026-10-25 **Referência visual:** mock operacional (cards por pizza, áreas coloridas, botões grandes) **Arquitetura de fluxo:** Modelo B — montagem e forno com responsáveis independentes --- ## 1. Objetivo Separar completamente: | Camada | Público | Natureza | |--------|---------|----------| | **KDS operacional (pizzaiolo)** | Role `kds` (e futuros papéis montagem/forno) | Estação de produção touch, unidade = **pizza** | | **KDS / Ops administrativo** | `gestor` / admin | Kanban de pedidos, Pooling, faturamento, metas | O pizzaiolo **não** vê Pedidos, PDV, Pooling financeiro, relatórios nem configurações. Esconder menu não basta: rotas e APIs administrativas devem rejeitar role `kds`. --- ## 2. Unidade de trabalho - **Unidade:** `PrepTask` (uma pizza / unidade de preparo). - Um pedido com N pizzas pode ter pizzas em estágios e com pizzaiolos diferentes. - Marcar pizza pronta **não** marca o pedido pronto. - Pedido só segue para liberação quando **todas** as pizzas e itens obrigatórios (bebidas, sobremesas, adicionais) forem conferidos na expedição. Identificação no card: `#PEDIDO · Pizza seq/total` (ex.: `#N16 · Pizza 1/2`). --- ## 3. Estados da pizza (máquina oficial) ``` disponivel │ PEGAR ▼ em_montagem (responsável montagem) │ FINALIZAR MONTAGEM ▼ aguardando_forno (sem forneiro ainda) │ ASSUMIR FORNO (+ INICIAR FORNO) ▼ no_forno (responsável forno) │ MARCAR PRONTA ▼ pronta → fila de expedição (automático) ``` ### Transições e botões | Botão | De → Para | Efeito | |-------|-----------|--------| | **PEGAR** | disponivel → em_montagem | Atribui montagem ao usuário; inicia cronômetro da etapa; atômico no servidor | | **DEVOLVER À FILA** | em_montagem → disponivel | Remove responsável; preserva tempo já consumido; motivo opcional/obrigatório conforme config | | **FINALIZAR MONTAGEM** / **ENVIAR AO FORNO** | em_montagem → aguardando_forno | Encerra tempo de montagem; **não** atribui forneiro | | **ASSUMIR FORNO** | aguardando_forno → no_forno (aguardando início) | Identifica forneiro | | **INICIAR FORNO** | (opcional explícito) marca `fornoStartedAt` | Se omitido na v1, ASSUMIR FORNO também inicia cocção | | **MARCAR PRONTA** | no_forno → pronta | Encerra cocção; envia à expedição automaticamente | | **TRANSFERIR** | qualquer etapa atribuída | Troca responsável com motivo; histórico preservado | | **REPORTAR PROBLEMA** | qualquer | Registra ocorrência sem apagar histórico | ### Dupla atribuição Claim/assume é **atômico** (`UPDATE … WHERE status = X AND claimedById IS NULL`). Se dois usuários competirem, só um vence; o outro recebe conflito 409. --- ## 4. Layout do KDS pizzaiolo (Kanban operacional) Quatro colunas Kanban (cards grandes, touch), unidade = pizza: 1. **Disponíveis** — sem responsável → **PEGAR** 2. **Montagem** — em preparo → **ENVIAR AO FORNO** (+ Devolver) 3. **Forno** — fila (`aguardando_forno`) + cocção (`no_forno`) → **PRONTA → CHECAGEM** Qualquer pizzaiolo/forneiro autorizado pode marcar pronta (não só quem assumiu). 4. **Checagem** — pizzas já prontas na 1ª checagem; daí seguem para **expedição** (etiqueta/embalagem/liberação) ### Fluxo Forno → Checagem → Expedição `PRONTA` na coluna Forno encerra a cocção e coloca a pizza na **primeira checagem**. Quando todas as pizzas do pedido estiverem prontas, o pedido fica `pronto` (pronto cozinha) para a expedição conferir, etiquetar e liberar. ### O que NÃO aparece para o pizzaiolo - Pooling / faturamento / ticket médio - Coluna Expedição administrativa - Links Pedidos, PDV, Setup, Demo, Relatórios - Indicadores financeiros ### Header operacional `Pizzaza` · badge `KDS` · `Cozinha` · AO VIVO · hora · nome do usuário Sem menu administrativo completo. ### Rodapé “Pizzas concluídas recentemente” — thumbs + código + horário + nome (não pedidos financeiros). --- ## 5. Conteúdo do card (pizza) - Código do pedido + fração `seq/total` - Badge do estágio + tempo total (vermelho se atraso) - Tempo da etapa atual (quando atribuída) - Foto realista do produto - Nome / tamanho / componentes (metades, bordas) - Canal / cliente / bairro (compacto) - Responsável montagem e/ou forno (iniciais + nome), sem sobrescrever o outro - Botão primário full-width da etapa + secundário (Devolver / Transferir / Ver pedido) - Trilho lateral grosso na cor da **etapa** (não do canal financeiro): azul disponível, laranja montagem, âmbar fila forno, vermelho forno, verde pronta Ordenação: prioridade operacional (atraso, tempo de espera, horário prometido) — não só `createdAt`. --- ## 6. Cronômetros - **Tempo total:** `now - order.arrivedAt|queuedAt` (servidor) - **Tempo da etapa:** `now - stageStartedAt` da etapa atual - Cálculo sempre a partir de timestamps do servidor (sobrevive a refresh/offline) Metas por etapa (config gestor, defaults): | Etapa | Meta sugerida | |-------|----------------| | Montagem | 6–8 min | | Espera forno | 3 min | | Forno | 8–12 min | | Total produção | 15–20 min | Atraso: destaque visual automático ao ultrapassar meta. --- ## 7. Perfis e permissões | Ação | Pizzaiolo montagem | Forneiro | Expedição | Gestor | |------|--------------------|----------|-----------|--------| | Ver disponíveis / pegar | Sim | Não* | Não | Sim | | Finalizar montagem | Sim (suas) | Não | Não | Sim | | Assumir / marcar forno | Não* | Sim | Não | Sim | | Ver responsável | Sim | Sim | Sim | Sim | | Transferir | Restrito | Restrito | — | Sim | | Pooling / Pedidos / PDV | Não | Não | Não | Sim | | Conferir / etiqueta / liberar | Não | Não | Sim | Sim | \* Mesmo usuário pode ter as duas caps; registros de montagem e forno permanecem separados. ### Backend - `GET/POST` administrativos (`/api/orders/stats/today`, etc.) → 403 para `kds` - `GET /pedidos` (web) → redirect `/kds/producao` para role `kds` - Nav: pizzaiolo só vê KDS (+ logout) --- ## 8. Expedição (fora da tela do pizzaiolo) Ao **MARCAR PRONTA**, a pizza entra na fila de expedição automaticamente. Expedição: conferência, etiqueta, embalagem, liberação do **pedido completo** (todas as pizzas + itens). O pizzaiolo não usa botão “Enviada p/ Expedição” manual. --- ## 9. API proposta (v1) Prefixo: `/api/kds/pizzas` | Método | Rota | Descrição | |--------|------|-----------| | GET | `/board` | Board pizzaiolo: disponíveis, montagem, aguardando_forno, no_forno, recentes | | POST | `/:taskId/pegar` | disponivel → em_montagem | | POST | `/:taskId/devolver` | em_montagem → disponivel (+ motivo) | | POST | `/:taskId/enviar-forno` | em_montagem → aguardando_forno | | POST | `/:taskId/assumir-forno` | aguardando_forno → no_forno | | POST | `/:taskId/marcar-pronta` | no_forno → pronta (+ evento expedição) | | POST | `/:taskId/transferir` | troca responsável (+ motivo) | Eventos socket: `pizza.updated`, `pizza.claimed`, `pizza.ready` (payload por PrepTask). ### Modelo de dados (evolução) `PrepTaskStatus`: adicionar `aguardando_forno`, `no_forno` (manter `em_preparo` = em_montagem). Campos: `montagemById`, `montagemStartedAt`, `montagemDoneAt`, `fornoById`, `fornoStartedAt`, `fornoDoneAt`. Histórico: tabela `PrepTaskEvent` (opcional v1.1) ou log append-only. --- ## 10. Critérios de aceitação 1. Role `kds` não vê menus/admin/Pooling/Pedidos; URL `/pedidos` redireciona; API stats 403. 2. Tela abre direto na produção autorizada. 3. Cards são **pizzas**, com foto, 2 cronômetros e responsável(is). 4. PEGAR / ENVIAR AO FORNO / ASSUMIR FORNO / MARCAR PRONTA seguem a máquina de estados. 5. Fila aguardando forno ≠ cocção iniciada. 6. Dupla atribuição impossível (409). 7. MARCAR PRONTA encaminha à expedição sem liberar pedido incompleto. 8. Touch: botões grandes, contraste alto, atualização realtime. 9. Modelo B: montagem e forno com responsáveis e tempos independentes. --- ## 11. Fora de escopo desta etapa - QR/etiqueta individual por pizza (recomendado v2) - Relatórios de produtividade detalhados (gestor) - App nativo; esta SPEC é web touch KDS --- ## 12. Relação com o KDS gestor O Kanban de pedidos (Novo / Montagem / Forno / Prontas / Expedição) permanece disponível **apenas** para gestor/admin como visão de supervisão. Não é a home do pizzaiolo.