62a20a2573
Mirror all SPECs and construction docs from pizza-digital, add hub/sidebar links and bidirectional sync scripts.
232 lines
6.9 KiB
Markdown
232 lines
6.9 KiB
Markdown
# 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
|
||
|
||
```text
|
||
# 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
|
||
|
||
```text
|
||
/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)
|
||
|
||
```text
|
||
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**:
|
||
|
||
```text
|
||
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)
|
||
|
||
- [x] fail2ban sshd
|
||
- [x] 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
|
||
|
||
- [x] VM criada e running (VMID 125, Debian 12, 4 vCPU / 8 GB / 80 GB)
|
||
- [x] Ping `10.10.10.125` a partir do BIG (`vmbr4000`)
|
||
- [x] SSH `root@` / `mini@10.10.10.125` OK (senha `805353`)
|
||
- [x] Docker Compose S0: `postgres` + `redis` + `api` + `web` + `gateway` (:3000) UP
|
||
- [x] `GET /api/health` → redis up · `GET /` → 200
|
||
- [x] `fail2ban` sshd ativo
|
||
- [x] Docker + Compose + Node 22 + pnpm + TypeScript/tsx
|
||
- [x] `sshd -T` → `passwordauthentication yes` · `permitrootlogin yes`
|
||
- [x] 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
|
||
|
||
```bash
|
||
# 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)
|