pizza-digital/docs/SPEC-FASE1.md

SPEC Fase 1 — MVP Cozinha Digital (detalhamento)

Campo	Valor
Produto	Pizza Digital
Fase	1 — MVP Cozinha Digital
Versão	0.2.0 (ampliação da SPEC 0.1)
Data	2026-07-23
Host de desenvolvimento	Proxmox BIG · VM 125 · pizza-digital · 10.10.10.125
SO	Debian 12
Users	mini (sudo) · root
Referência rotas (fase 2)	rusterando (oficial) + CityFoods Gestor de Rotas / ORS
Referência KDS	CityFoods Cozinha Digital + kitchenOS / restaurant-pos
Sequência	SPEC §15 — S0…S9 · KDS antes de rotas · S1 ✅ · próximo S2

---

1. Objetivo da Fase 1

Entregar uma Cozinha Digital operacional para pizzaria piloto:

1. PDV web cria pedido
2. KDS multi-estação (Massa → Montagem → Forno → Expedição)
3. Timers / priorização
4. Etiqueta (ESC/POS ou PDF)
5. Dashboard de tempos
6. Gate para despacho (order.ready) — sem otimização de rotas ainda (Fase 2)

Fora da Fase 1: app motoboy, ORS, iFood, cardápio público, multi-loja.

---

2. Infraestrutura (BIG)

Item	Valor
Hypervisor	Proxmox BIG (big1-proxmox / 95.216.14.162)
VMID	125
Nome	pizza-digital
Bridge	vmbr4000
IP LAN	10.10.10.125/24
Gateway	10.10.10.1 (pfSense)
DNS	8.8.8.8 / 8.8.4.4
vCPU	4
RAM	8 GB
Disco	80 GB
Cloud-init	local:snippets/vm125-pizza-digital-init.yaml
Hardening	fail2ban (sshd) · PasswordAuthentication yes · PermitRootLogin yes
Stack base	Docker + Compose · Node 22 · pnpm · Git · build-essential · nginx · redis-tools · psql client

2.1 Acesso

# Via Proxmox BIG (LAN)
ssh mini@10.10.10.125

# Ou jump pelo host
ssh big1-proxmox
ssh mini@10.10.10.125

SSH externo (porta NAT tipo 2525) não está nesta fase — exige regra no pfSense + FORWARD no Proxmox (não alterar /etc/network/interfaces sem confirmação ×3).

2.2 Workspace na VM

/home/mini/pizza-digital/     # monorepo
/opt/pizza-digital/           # dados / runtime
/opt/pizza-digital/data/      # volumes locais

---

3. Entregáveis Fase 1 (Definition of Done)

#	Entregável	Critério de aceite
1	Monorepo bootstrap	apps/api, apps/web, packages/domain, docker-compose.yml
2	Auth + RBAC mínimo	login gestor / pdv / kds
3	Cardápio	CRUD item + modifiers + meia-a-meia + mapa → estações
4	PDV	criar pedido delivery/balcão com observação
5	Order state machine	confirmado → em_producao → pronto
6	KDS multi-estação	4 telas; WebSocket ≤ 500 ms
7	Timers SLA	verde/amarelo/vermelho
8	Priorização	reordenar / marcar urgente
9	Etiquetas	imprimir ou PDF com #CODE + obs
10	Dashboard	tempo médio por estação + fluxo do pedido
11	Seed pizzaria	dados demo (sabores, bordas, bebidas)

---

4. Estações (template Pizzaria) — freeze Fase 1

Código	Nome	SLA default	Recebe
massa	Massa	3 min	base / borda
montagem	Montagem	5 min	molho, queijo, toppings, meia-a-meia
forno	Forno	8 min	pizza assando
expedicao	Expedição	3 min	embalagem + etiqueta + conferência
bebidas	Bebidas (opc.)	2 min	refrigerante / água

Regra: pedido só pronto quando todas as estações obrigatórias do pedido concluírem; expedição é a última.

---

5. Stack Fase 1 (congelada para implementação)

Camada	Escolha
API	NestJS + TypeScript
Web	React + Vite + TypeScript (PWA)
Realtime	Socket.io
DB	PostgreSQL 16 (Docker)
Cache/pubsub	Redis 7 (Docker)
ORM	Prisma
Print	ESC/POS node + PDF fallback
Deploy local	Docker Compose na VM 125

Referências de implementação:

• KDS realtime → kitchenOS / Tasty-Station
• Estações → restaurant-pos
• Rotas (só na Fase 2) → rusterando + OpenRouteService

---

6. Apps / rotas web (Fase 1)

App	Path	Papel
PDV	/pdv	Caixa
KDS	/kds/:station	Cozinha
Despacho (lista)	/despacho	Fila pronto (sem ORS)
Admin	/admin	Cardápio, users, métricas

---

7. Eventos WebSocket (Fase 1)

order.created
order.updated
order.canceled
ticket.upserted
ticket.bumped
order.ready
label.printed

Rooms: store:{id} · store:{id}:station:{stationId}

---

8. Módulo Rotas — ponte para Fase 2 (não implementar agora)

Contrato mínimo que a Fase 1 já deve expor:

order.status === 'pronto'
  → aparece em /despacho
  → payload inclui: address, bairro, lat/lng (se houver), priority

Na Fase 2 (CityFoods-like):

1. Agrupar por bairro
2. Atribuir motoboy
3. ORS tour (rusterando)
4. PWA entregador + tracking
5. Comissão entregador

---

9. Sprints Fase 1 (na VM 125)

Sprint	Dias úteis	Entrega
S0	1	Repo + Docker Compose (Postgres/Redis) + domain types
S1	2	Auth + Store + Cardápio + estações
S2	2	Pedidos PDV + state machine
S3	3	KDS realtime multi-estação + timers
S4	2	Etiquetas + priorização + dashboard
S5	2	Seed + teste piloto + hardening

---

10. Segurança na VM (Fase 1)

• fail2ban sshd
• PasswordAuthentication + root (padrão iTecnologys / cloud-init)
• UFW: allow 22/tcp, 80/tcp, 443/tcp, 3000/tcp (dev) — aplicar após bootstrap
• Não expor Postgres/Redis na WAN
• Secrets em .env (não commit)

---

11. Checklist de bootstrap VM 125

• VM criada e running (VMID 125, Debian 12, 4 vCPU / 8 GB / 80 GB)
• Ping 10.10.10.125 a partir do BIG (vmbr4000)
• SSH root@ / mini@10.10.10.125 OK (senha 805353)
• Docker Compose S0: postgres + redis + api + web + gateway (:3000) UP
• GET /api/health → redis up · GET / → 200
• fail2ban sshd ativo
• Docker + Compose + Node 22 + pnpm + TypeScript/tsx
• sshd -T → passwordauthentication yes · permitrootlogin yes
• Workspace /home/mini/pizza-digital com SPEC
• Monorepo código (S0) — próximo passo
• SSH externo NAT (porta dedicada) — opcional; não altera /etc/network/interfaces sem 3 confirmações

Acesso rápido

# Do Windows (ProxyJump)
ssh pizza-digital

# Do BIG Proxmox (necessário route helper se dual-bridge)
/usr/local/bin/pizza-digital-route.sh
ssh mini@10.10.10.125

---

12. Changelog desta ampliação

0.2.0 — 2026-07-23

• Detalhamento completo da Fase 1
• Infra VM 125 no Proxmox BIG documentada
• Stack congelada (NestJS + React + Postgres + Redis + Socket.io)
• Definition of Done e sprints S0–S5
• Ponte explícita para Gestor de Rotas (Fase 2 / CityFoods + rusterando)