obsidian-vault/Pizza-Digital/docs/SPEC-KDS-PIZZAIOLO-MODELO-B.md

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.