pizza-digital/PRD/PRD-SPEC-FASE1.md

PRD — Fase 1 — MVP Cozinha Digital

Campo	Valor
Produto	Pizza Digital
Versão app auditada	v0.5.0
Ambiente	https://pizza.itecnologys.com · VM125 · loja pizza-digital-piloto
Spec de origem	docs/SPEC-FASE1.md
Módulo	PDV + KDS + Expedição (sem rotas ORS)
Rotas UI	/pdv /pedidos /kds/:station /etiqueta/:id
APIs	/api/orders/* /api/kds/*
Data	2026-11-09
Estilo	PRD operacional detalhado (visão de desenvolvedor)
Audiência	Dev / QA / Product

Como ler: cada seção descreve o processo real (o que o sistema faz hoje), com passos de usuário, chamadas de API, regras de negócio e estados. Status: ✅ construído · ⚠️ parcial · ⏳ especificado / não entregue · 🐛 gap observado.

1. Objetivo da Fase 1 (visão de implementação)

Entregar loop operacional pedido → produção → pronto, sem otimização de rotas. ORS/motoboy tour ficam para despacho (Specs posteriores).

Escopo entregue

1. PDV cria pedido
2. Central /pedidos vê fila
3. KDS multi-estação com claim/bump
4. Label/etiqueta
5. Gate order.ready quando tickets fecham

Fora

App motoboy avançado, iFood, multi-loja, ORS.

---

2. Processo ponta a ponta (dev walkthrough)

A) Criação do pedido (PDV)

1. POST /api/auth/login
2. Operador monta carrinho (cardápio)
3. POST /api/orders com origin, fulfillment, items, customer
4. Service cria Order + OrderItem + OrderTicket por estação mapeada
5. Emite eventos Socket.io para KDS/Central

B) Central de pedidos

1. GET /api/orders (+ filtros origin/status)
2. UI /pedidos mostra badges (Aplicativo/WhatsApp/Telefone/PDV)
3. PATCH /api/orders/:id/urgent · PATCH .../status · PATCH .../payment
4. Demo digital: POST /api/orders/demo-digital

C) Cozinha (KDS clássico)

1. GET /api/kds/:station → fila / comigo / bloqueados
2. POST /api/kds/:station/claim/:orderId → claim exclusivo
3. Trabalha item → POST .../bump avança ticket
4. Expedição só libera quando demais estações concluíram
5. Auto order.ready quando todos tickets fecham

D) Etiqueta

1. GET /api/orders/:id/label
2. UI /etiqueta/:id (ESC/POS ou PDF conforme implementação)

---

3. Máquina de estados (Order)

created/received → in_kitchen → ready → (despacho/entrega)
                 ↘ cancelled

Tickets por estação: pending → claimed → done (simplificado).

4. Aceite

• ✅ Loop PDV→KDS→ready
• ✅ Claim exclusivo
• ⚠️ SLA timers por categoria (SPEC menciona)
• ⏳ Rotas ORS (não Fase 1)

5. Camada de serviço (OrdersService) — o que o código faz

Arquivo: apps/api/src/orders/orders.service.ts (~811 linhas)

Método	Processo
create	Gera código (nextCode), persiste Order+Items, cria tickets KDS, emite realtime
list / get	Lista/detalhe com filtros para Central
transition	Muda status do pedido (máquina de estados)
setUrgent / setPayment	Flags operacionais/financeiras
label	Payload da etiqueta
trackByHash	Tracking público sem auth completa
createDemoDigital	Pedido sintético canal digital
dayPool	Pool do dia (agrupamento)

Erros que o dev deve tratar no front

• 401 sem JWT
• 400 validação items/fulfillment
• 409/422 transição ilegal de status