Admin
e3da540b6e
Each PRD documents real UI/API processes, service methods, states and gaps. Co-authored-by: Cursor <cursoragent@cursor.com>
100 lines
3.4 KiB
Markdown
100 lines
3.4 KiB
Markdown
# 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
|