62a20a2573
Mirror all SPECs and construction docs from pizza-digital, add hub/sidebar links and bidirectional sync scripts.
221 lines
8.5 KiB
Markdown
221 lines
8.5 KiB
Markdown
# 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.
|