# 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)

```text
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