Rota Pirapemas — Sistema de gestão (São Luís ⇄ Pirapemas)
Sistema de agendamento, agenda operacional, financeiro e operação para
empresa de transporte, com backend PostgreSQL/Supabase e integração real
com WhatsApp Business API.
Vai colocar no ar? Comece por SETUP.md — o checklist
mestre do que falta fazer, na ordem.
Estrutura do repositório
.
├── database/
│ ├── DATABASE.md # Arquitetura de dados, decisões e migração V2→V3
│ ├── 01-schema.sql # Tabelas, enums, índices, triggers (rodar 1º)
│ ├── 02-rls-policies.sql # Row Level Security por papel (rodar 2º)
│ ├── 03-rpc-functions.sql # Funções atômicas (criar/confirmar/mover reserva) (rodar 3º)
│ ├── 04-frontend-views.sql# View de leitura + índices de FK (rodar 4º)
│ ├── 05-seed.sql # Veículos, pontos de embarque, bairros, config (rodar 5º)
│ ├── 06-whatsapp.sql # Conversas/mensagens do WhatsApp + modo IA|HUMANO (rodar 6º)
│ ├── 07-scheduling.sql # pg_cron: "motorista a caminho" + lembrete de viagem (rodar 7º)
│ ├── 08-realtime.sql # Publica as tabelas de negócio no Supabase Realtime (rodar 8º)
│ ├── 09-daily-trips.sql # pg_cron: cria Ida/Volta de cada dia (Agenda nunca vazia) (rodar 9º)
│ ├── 10-dropoff-plan.sql # Campos de desembarque + RPCs p/ a rota do motorista (rodar 10º)
│ ├── 11-dropoff-on-create.sql # rpc_create_reservation grava dropoff_area/detail (rodar 11º)
│ ├── 12-write-guards.sql # GRANT UPDATE por coluna + REVOKE DELETE (anti-adulteração) (rodar 12º)
│ ├── 15-fix-capacity-on-reservation-move.sql # Trigger de capacidade em reservations.trip_id (rodar 15º)
│ ├── 16-timezone-sao-luis.sql # Fuso do banco = America/Fortaleza (current_date/now()) (rodar 16º)
│ ├── 17-backup-completo.sql # Backup completo (todas as tabelas) + cron diário automático (rodar 17º)
│ ├── 18-receita-automatica-contas-a-receber.sql # Receita auto ao confirmar/pagar, estorno ao cancelar, contas a receber (rodar 18º)
│ ├── 19-gestao-operacional.sql # Custos recorrentes (salários, impostos, taxas, seguro, IPVA...) + lançamento automático (cron) + resultado líquido (rodar 19º)
│ └── retrofit-security-hardening.sql # Correções dos advisors do Supabase —
│ # rodar 1x só se o banco foi criado antes de 31/08/2026
├── supabase/functions/ # Edge Functions (backend real do WhatsApp — nunca no frontend)
│ ├── _shared/
│ │ ├── supabaseAdmin.ts # cliente com service_role (só existe no servidor)
│ │ ├── whatsappClient.ts # envia pelo Chatwoot (texto; opções numeradas)
│ │ ├── whatsappService.ts # regras de negócio: nunca inventa vaga/preço/pagamento
│ │ ├── conversationEngine.ts # máquina de estados do atendimento (menus/botões)
│ │ └── nluService.ts # interpreta texto livre (extração estruturada via Claude)
│ └── chatwoot-bot/ # recebe os webhooks do Agent Bot do Chatwoot (bot + espelho da fila)
├── WHATSAPP.md # guia de deploy da integração WhatsApp, passo a passo
├── SETUP.md # checklist mestre para ir ao ar
├── frontend/ # App (Vite + React). Ver AGENTS.md §2.
│ ├── package.json # scripts: dev, build, lint, test, test:e2e…
│ ├── vercel.json # Config de deploy (Vercel) — ver DEPLOY.md
│ ├── DEPLOY.md # Passo a passo do deploy
│ ├── INTEGRATION.md # O que foi criado/removido e como o fluxo de reserva funciona
│ ├── .env.example # Variáveis de ambiente (Supabase, Sentry, OTel, RUM…)
│ ├── e2e/ # Testes end-to-end (Playwright)
│ └── src/
│ ├── app/App.jsx # Protótipo funcional — agenda, reservas, CRM,
│ │ financeiro, operação, dashboard (migração p/
│ │ services/hooks = issue #10)
│ ├── domain/ # Regras puras + testes (vagas, preços, diagnóstico)
│ ├── lib/ # Cliente Supabase único, storageShim (dev)
│ ├── services/ # 8 services (reservations, trips, customers, payments,
│ │ finance, operation, vehicles, users)
│ ├── hooks/ # Hooks React (loading/error/retry/tempo real)
│ ├── observability/ # Sentry + OpenTelemetry + RUM + eventos nomeados
│ ├── ui/motion/ # Sistema de movimento reutilizável (issue #2)
│ └── INTEGRATION-EXAMPLE.jsx # Exemplo real de integração (Reservar → Agenda)
├── docs/
│ └── ISSUES-INICIAIS.md # Backlog inicial pronto para virar Issues do GitHub
└── AGENTS.md # Padrão de trabalho (Issues → PR, qualidade, observabilidade)
Ordem de setup (do zero)
- Criar um projeto no Supabase.
- No SQL Editor do projeto, rodar nesta ordem exata:
database/01-schema.sql → 02-rls-policies.sql → 03-rpc-functions.sql
→ 04-frontend-views.sql → 05-seed.sql.
Bancos criados antes de 31/08/2026 devem rodar também
database/retrofit-security-hardening.sql (uma vez) para aplicar as
correções de segurança dos advisors do Supabase.
- Para a integração de WhatsApp: rodar
database/06-whatsapp.sql →
07-scheduling.sql e fazer o deploy das Edge Functions — passo a passo
completo em WHATSAPP.md.
- Copiar
frontend/.env.example para frontend/.env e preencher com a
URL e a anon key do projeto (Project Settings → API no Supabase).
- Instalar e rodar o app:
cd frontend
npm install
npm run dev
- Antes de abrir um PR, rodar os gates (ver
AGENTS.md §0):
npm run lint && npm run knip && npm run arch && npm run test && npm run build.
- Seguir
frontend/INTEGRATION.md para trocar a persistência local do
src/app/App.jsx pelos services/hooks de frontend/src/.
Estado atual
- ✅ Protótipo funcional completo (agenda, reservas, financeiro, operação, CRM).
- ✅ Schema PostgreSQL normalizado, com RLS por papel e proteção de
overbooking garantida por trigger no banco (não apenas no frontend).
- ✅ Camada de services/hooks pronta para conectar o frontend ao Supabase,
com tempo real e retry seguro.
- ✅ Integração real com WhatsApp Business API (webhook + Edge Functions +
máquina de estados + NLU), com auditoria de toda ação da IA e modo
IA|HUMANO por conversa — ver
WHATSAPP.md.
- ⏳ GPS/rastreamento contínuo de viagem — planejada, não iniciada.
- ⏳ Aplicar os hooks dentro de
src/app/App.jsx aba por aba (o padrão já
está demonstrado em frontend/src/INTEGRATION-EXAMPLE.jsx) — issue #10.
- 🏗️ Fundação de build/lint/testes/CI e observabilidade — em andamento
(issues #1, #3, #4); sistema de motion unificado — issue #2.
Veja AGENTS.md para o padrão de Issues/PRs, qualidade, testes,
observabilidade e motion. O backlog está em docs/ISSUES-INICIAIS.md e
nas Issues #1–#15 do GitHub.
