# PRD — Despacho / Gestor de Rotas (CityFoods parity)

| 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-DESPACHO-CITYFOODS-PARITY.md` |
| **Módulo** | Rotas, motoboys, mapa |
| **Rotas UI** | `/despacho` `/motoboy` `/ops` |
| **APIs** | `/api/routes/*` `/api/drivers/*` `/api/ops/*` `/api/zones/*` |
| **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 implementado

Sair de “lista de prontos + SAIR” para fluxo:
**Montar rota → Despachar → mapa → status motoboy → fechar**.

## 2. Processo — montar e despachar rota
1. Pedidos `ready` no board
2. Operador em `/despacho` seleciona pedidos
3. `POST /api/routes/preview` (ordem sugerida)
4. `POST /api/routes` cria `DispatchBatch` + `DispatchStop`
5. `PATCH /api/routes/:id/driver` associa motoboy (`Driver`)
6. `POST /api/routes/:id/dispatch` sai para rua
7. Mapa acompanha; `POST /api/routes/:id/ping` atualiza lat/lng
8. Por stop: `POST /api/routes/:id/stops/:orderId/status` (a_caminho/entregue)
9. `POST /api/routes/:id/close` fecha batch

## 3. Processo — motoboy
1. UI `/motoboy`
2. `GET /api/routes/driver/:driverId` / `GET /api/routes/active`
3. Atualiza status das paradas

## 4. Cadastros apoio
- Drivers CRUD `/api/drivers`
- Zonas `/api/zones` · UI `/admin/zonas`
- Ops funnel/ranking/priority `/api/ops/*`

## 5. Aceite
- ✅ Routes API + Despacho/Motoboy pages
- ⚠️ Paridade mapa full-bleed (ver PRD vídeo)
- ⏳ ORS tour produção robusto


## 6. Camada de serviço (RoutesService)

Arquivo: `apps/api/src/routes/routes.service.ts` (~548 linhas)

| Método | Processo |
|--------|----------|
| `preview` | Ordena stops candidatos (sem persistir) |
| `buildStops` / `create` | Cria batch+stops |
| `assignDriver` | Liga Driver |
| `dispatch` | Status em rota |
| `ping` | GPS |
| `setStopStatus` | a_caminho / entregue / falha |
| `close` | Fecha batch |
| `listActive` / `activeForDriver` / `get` | Leituras UI |