Documentação

Reparou — Funcionalidades (backlog mestre ordenado)

Lista completa e ordenada do que será implementado, derivada do blueprint-plataforma.md (50 módulos) e do visao-produto.md. A ordem é de construção — dependências técnicas primeiro, valor de venda o mais cedo possível.

Contrato de pronto (vale para TODOS os itens): cada funcionalidade sai completa e produtiva — validação Zod, tratamento de erros, multi-tenant (contaId/unidadeId), RBAC aplicado, audit log, eventos de domínio, UI RaceOS polida (estados vazios, carregamento, erro), responsiva, testada local. Não existe versão "mínima"; fases seguintes adicionam capacidades, nunca consertam o que já saiu.


ETAPA 0 — Fundação da plataforma (F1)

Nada disso é visível ao cliente final; tudo isso é impossível de retrofitar barato.

  1. Autenticação e onboarding da Conta — cadastro da oficina (Conta + 1ª Unidade + usuário OWNER), login JWT (access + refresh com rotação), Argon2, recuperação de senha por e-mail, gestão de sessões ativas, logout global.
  2. Tenancy hierárquico — middleware contaId/unidadeId em toda rota, seletor de unidade no shell, isolamento absoluto entre contas (testes de isolamento incluídos).
  3. RBAC e gestão de equipe — papéis OWNER/GESTOR/CONSULTOR/MECANICO com permissões granulares por recurso/ação, convite de usuários por e-mail, ativação/desativação, troca de papel.
  4. Audit log — toda mutação registrada (quem, o quê, quando, antes/depois) + tela de auditoria com filtros por entidade/usuário/período.
  5. Outbox de eventos de domínio — publicação transacional (os.criada, orcamento.aprovado, …) + worker de processamento com retry; é a espinha das automações e do futuro workflow engine.
  6. Armazenamento de mídia — upload de fotos/vídeos/PDFs atrelado a qualquer entidade, compressão, thumbnails, controle de acesso por tenant.
  7. App shell RaceOS — cockpit completo: navegação, design tokens dark/light, componentes base (TelemetryCard, PitProgressBar, BoxGrid, RaceTimeline), microinterações discretas, acessibilidade (estados nunca só por cor).
  8. Configurações da oficina — dados da empresa (CNPJ, endereço, logo), horários de funcionamento, parametrizações, templates de documentos.

ETAPA 1 — Cadastros vivos (F1)

  1. CRM de Clientes — PF/PJ/frotista, documento, contatos, busca/filtros, segmentação (VIP, inativo, frotista, particular), origem do cliente (como conheceu a oficina — atribuição de canal), timeline completa (técnico, financeiro, comercial), campos customizados.
  2. CRM de Veículos — placa/chassi/Renavam/motor/câmbio/KM, vínculo com cliente, timeline da vida útil do veículo (cada veículo tem vida própria), histórico de serviços, campos customizados.
  3. Catálogo de serviços e peças da oficina — tabela própria de serviços (preço fixo ou por hora, tempo padrão) e peças (custo, margem, aplicação), garantia e revisão por item em dias e km, teto de desconto por item (governança de preço), base para orçamentação consistente. → specs/catalogo-servicos-pecas.md

ETAPA 2 — Operação core (F1)

  1. Recepção, check-in e check-out digital — entrada do veículo com sequência fotográfica guiada (7 posições + vídeo) imutável após finalização, checklist visual com modelos reutilizáveis (carroceria, rodas, pneus, vidros, combustível, estepe), registro de danos pré-existentes, assinatura digital do cliente; check-out simétrico na entrega com comparação entrada × saída — evita conflitos na entrega e depois dela. → specs/checkin-vistoria-entrega.md
  2. Orçamentos — composição peças + serviços + pacotes, margem e lucro por item em tempo real, descontos governados pelo catálogo (teto por item + margem mínima), templates, PDF profissional, simulação de cenários, validade e versões. → specs/orcamento-os.md
  3. Aprovação remota — link público seguro do orçamento (portal), envio por WhatsApp, aprovação total/parcial item a item com trilha imutável (quem/quando/canal/hash), itens recusados registrados no documento, adiantamento/sinal na aprovação, conversão automática em OS. → specs/portal-cliente.md
  4. Ordem de Serviço — pipeline completo (aberta → em análise → aguardando aprovação → aguardando peças → em execução → finalizada → entregue) com gates explícitos (entregar exige check-out), peças/serviços/custos/responsáveis por item, timeline estilo corrida, anexos, observações internas × visíveis ao cliente. → specs/orcamento-os.md
  5. Agenda operacional — agendamento por mecânico/box/serviço, visões dia/semana, detecção de conflito, reagendamento por arrastar.
  6. Gestão de boxes (pit stops) — grid visual com ocupação em tempo real, status (executando/atenção/livre), tempo restante, drag-and-drop de veículos entre boxes, localização do veículo no pátio além do box (estacionamento, rua, terceiros).
  7. Portal do Cliente — acesso por magic-link (sem senha): status do carro em tempo real, fotos/vídeos, orçamento com aprovação, histórico do veículo, estilo "rastreio de encomenda premium".

ETAPA 3 — Dinheiro (F1)

  1. Financeiro — contas a pagar/receber, categorias, fluxo de caixa, vínculo automático com OS (receita) e compras (despesa), condições e formas de pagamento configuráveis, caixa por sessão com abertura/fechamento, sangria/suprimento e fechamento cego. → specs/financeiro.md
  2. Recebimentos — registro de pagamentos por OS (dinheiro, PIX com QR, cartão manual), parcial/total, parcelas com forma de pagamento e vencimento individuais, adiantamento/sinal com recibo próprio.
  3. Emissão fiscal — NFS-e/NF-e via FiscalProvider (Focus NFe): certificado A1 no cofre do provider, emissão orquestrada (NFS-e + NF-e numa ação) a partir da OS finalizada, rejeições traduzidas em ações guiadas, consulta de status, cancelamento, espelho/DANFE — incluída no plano, sem add-on surpresa. → specs/fiscal.md

ETAPA 4 — WhatsApp e automações (F1)

  1. WhatsApp nativo (inbox) — caixa de entrada omnichannel via MessagingProvider, conversas vinculadas a cliente/OS, atribuição a usuários, templates aprovados, histórico na timeline do cliente.
  2. Automações de relacionamento — carro pronto, lembrete de revisão dirigido pelo intervalo de cada serviço executado (dias e km — previsão de retorno), lembrete de troca de óleo, follow-up de orçamento não aprovado, reativação de cliente inativo — todas dirigidas pelos eventos de domínio, com opt-out por cliente.
  3. Notificações internas — sino in-app + resumo diário para o gestor (aprovações pendentes, atrasos, caixa).

ETAPA 5 — Telemetria (F1)

  1. Central de Operações — a "missão do dia": carros na oficina por status, receita do dia (▲/▼), eficiência da equipe, capacidade operacional, prontos para entrega; abre o sistema nela, não num menu.
  2. Relatórios operacionais — conversão de orçamentos, ticket médio, faturamento por período/serviço/mecânico, taxa de retorno de clientes, exportação CSV/PDF.

🏁 Fim da F1 = produto vendável completo para a cunha (pequena oficina, flat R$ 149–199/mês, usuários ilimitados, fiscal incluído).


ETAPA 6 — Profundidade operacional (F2)

  1. Inspeção técnica digital (DVI) — checklists personalizados por categoria (freios, suspensão, direção, motor), fotos/vídeos/áudios por item, classificação verde/amarelo/vermelho, relatório técnico (PDF/portal/WhatsApp) que vende serviço.
  2. Estoque — reserva na aprovação do orçamento e baixa na finalização da OS, kardex completo por peça (todo movimento com usuário/data/origem), inventário rotativo e geral, custo médio ponderado, curva ABC, alertas de mínimo. → specs/estoque-compras-balcao.md
  3. Compras — solicitação → cotação multi-fornecedor → pedido → recebimento por item → conferência, importação de XML de NF-e com matching de itens, rateio de frete/ST no custo, atualização assistida de custo e preço de venda.
  4. Fornecedores — cadastro, condições, performance/SLA, histórico de compras.
  5. Venda balcão (PDV) — venda de peças sem OS/veículo: tela única rápida, cliente opcional (consumidor não identificado), baixa imediata de estoque no fechamento, mesmo motor de pagamento/parcelas da OS, NFC-e/NF-e.
  6. Devoluções e estornos — devolução de venda balcão e de item de OS com reentrada no estoque e estorno financeiro vinculado; devolução ao fornecedor (saída + crédito); aprovação GESTOR+ com prazo configurável.
  7. Faturamento agrupado (fatura de frota) — consolidação de N OS de um cliente frotista em uma fatura única com vencimento corporativo.
  8. Gestão de técnicos — especialidades, certificações, capacidade; base da gamificação.
  9. Apontamento de mão de obra — cronômetro/check-in/check-out por OS, horas vendidas × trabalhadas, eficiência, ociosidade, retrabalho.
  10. Planejamento de capacidade — carga operacional, ocupação projetada, previsão de gargalos na agenda.
  11. Comissões — regras em camadas por mecânico/consultor/equipe, percentuais separados para peças e serviços, gatilho no recebimento, apuração automática com fechamento de período, visão "minha comissão" para cada um, relatório de fechamento. → specs/comissoes-apontamento.md
  12. Conciliação financeira — PIX automático, cartões (adquirentes) com taxas apuradas por operadora, boletos; conciliação bancária e centros de custo com rateios.
  13. Controladoria — DRE gerencial, demonstrativos, comparativos mês a mês.
  14. Garantias — registro por serviço/peça com prazo em dias e km (vence o que vier primeiro), acionamentos, custo de garantia, histórico.
  15. Assinatura digital com validade jurídica — documentos (orçamento, check-in, contrato) assinados conforme LGPD/ICP, trilha de evidências.
  16. Gestão documental — contratos, laudos e PDFs organizados por cliente/veículo/OS, com versões.
  17. App da Oficina (mobile) — Expo: um app único da oficina cuja experiência se adapta ao papel logado (sem app do cliente — o dono do veículo usa só o Portal web). Mecânico: minhas OS/agenda, execução item a item, checklist/DVI com fotos/vídeos, apontamento de horas, galeria — em modo pátio (alto contraste). Consultor: recepção e check-in/check-out guiado, orçamentos, aprovações, CRM. Gestor/Owner: Central de Operações, fila de aprovações, alertas e financeiro de leitura no bolso. Multi-tenant, captura offline-resiliente, push por eventos de domínio. → specs/app-oficina.md
  18. CRM comercial — leads, funil, oportunidades, propostas, conversão em cliente.
  19. Marketing e campanhas — segmentações avançadas, campanhas via WhatsApp/e-mail, jornadas, fidelização.
  20. Pesquisa de satisfação — NPS/CSAT pós-entrega automático, avaliações, alertas de detrator.
  21. Business Intelligence — dashboards por área, metas, comparativos, drill-down; Central de Comando completa do dono.
  22. Gamificação interna dos mecânicos — níveis (Júnior→Especialista), conquistas, indicadores individuais; nunca visível ao cliente.
  23. MFA — segundo fator para papéis administrativos.

ETAPA 7 — Diferencial defensável (F3)

  1. Chief Engineer (IA Copilot) — análise operacional contínua com recomendações acionáveis ("4 veículos com risco de atraso; realoque João para a OS #4821"), perguntas em linguagem natural ("por que o faturamento caiu?").
  2. IA de diagnóstico assistido — sintoma descrito → causas prováveis, procedimentos, tempo estimado, peças necessárias; base de conhecimento técnica + histórico próprio.
  3. IA de atendimento WhatsApp — chatbot que agenda, informa status, qualifica e transfere para humano; agentes (comercial, atendimento, financeiro, comprador, gestor).
  4. IA comercial — upsell/cross-sell por perfil, recuperação de clientes, sugestão de campanhas.
  5. IA financeira — previsão de caixa, risco de inadimplência, recomendações.
  6. Precificação inteligente — sugestão de preço por serviço com base em custo, mercado e conversão histórica.
  7. Workflow engine — fluxos e aprovações customizáveis (BPM) sobre o event bus, substituindo as automações fixas por regras configuráveis.
  8. Catálogo de peças centralizado — base cross-tenant de compatibilidade marca/modelo/motor, equivalências; alimenta o data lake.
  9. Marketplace de peças — busca por placa, comparação multi-fornecedor, compra sem sair da OS, tracking (estilo PartsTech; depende de API viável no BR).
  10. Multiunidade completo — UI de rede: dashboard consolidado, benchmark entre unidades, transferência de estoque, cadastros compartilhados, login único.
  11. Central de franqueadora — padrões operacionais (playbooks), auditoria de conformidade, governança.
  12. Gestão de frotas — empresas, contratos, motoristas, custo por veículo, faturamento corporativo.
  13. Verticais — pneus (vida útil, rodízio, desgaste), sinistros/seguradoras (orçamento, aprovação, integração), lavação/estética (pacotes, recorrência), centro automotivo (alinhamento, balanceamento, geometria).
  14. Data platform — data lake/warehouse, eventos históricos, ML; benchmark nacional por marca-modelo (falhas, custos, tempos) — o moat de longo prazo.

ETAPA 8 — Ecossistema e escala (F4)

  1. Open Platform — API pública documentada (a mesma da aplicação), webhooks, SDK, chaves por conta com escopos.
  2. Marketplace de serviços — rede de terceirização: guinchos, funilarias, especialistas.
  3. Rede de oficinas — compartilhamento, benchmarking setorial, compras coletivas.
  4. Universidade corporativa — treinamentos, trilhas, certificações para equipes das oficinas.
  5. SSO corporativo — SAML/OIDC para redes e franquias.

Ordem de ataque imediata (próximas implementações)

#ItemPor quê primeiro
1Auth + Conta/Unidade (itens 1–2)Nada existe sem tenant e login
2RBAC + audit + eventos (3–5)Fundações que não se retrofitam
3Shell RaceOS + configurações (7–8)Toda tela seguinte nasce dentro dele
4Clientes + Veículos + catálogo (9–11)Matéria-prima da operação
5Check-in → Orçamento → Aprovação → OS (12–15)O fluxo que vende o produto

Postgres no Railway entra junto do item 1 (primeira migration em produção).