HEFESTO v1.0 - Sistema de Controle Orçamentário para Facilities

- Backend NestJS com 12 módulos - Frontend React com dashboard e gestão - Manuais técnico e de negócios (MD + PDF) - Workflow de aprovação com alçadas - RBAC com 6 perfis de acesso
2026-02-09 14:53:01 -03:00
commit d8ca580acb
107 changed files with 22657 additions and 0 deletions
--- a/docs/MANUAL-NEGOCIOS.md
+++ b/docs/MANUAL-NEGOCIOS.md
@@ -0,0 +1,304 @@
+# HEFESTO — Manual de Negócios
+
+**Sistema de Controle Orçamentário para Facilities**
+
+Versão 1.0 | Fevereiro 2025
+
+---
+
+## 1. Visão Geral do Produto
+
+O **HEFESTO** é uma plataforma web para gestão integrada de Facilities, cobrindo todo o ciclo de vida de uma demanda de serviço — da abertura até a avaliação pós-execução — com controle orçamentário, workflow de aprovações e gestão de fornecedores.
+
+O nome faz referência a **Hefesto**, o deus grego da forja e da construção, simbolizando a solidez e precisão que o sistema traz à gestão de instalações e infraestrutura.
+
+## 2. Problema que Resolve
+
+### Cenário Atual (sem HEFESTO)
+
+A gestão de Facilities em empresas de médio e grande porte sofre com:
+
+- **Demandas por e-mail e WhatsApp:** Solicitações de manutenção, reformas e serviços chegam de forma desorganizada, sem rastreabilidade
+- **Propostas em planilhas Excel:** Comparação manual de cotações, sujeita a erros e vieses
+- **Orçamento sem visibilidade:** Gestores não sabem quanto já gastaram vs. quanto planejaram até consultar o financeiro
+- **Aprovações por e-mail:** Cadeia de aprovação informal, sem registro de quem aprovou o quê e quando
+- **Fornecedores sem controle:** Certidões vencidas, avaliações subjetivas, concentração em poucos prestadores
+- **Zero rastreabilidade:** Impossível saber o status de uma demanda sem ligar para alguém
+
+### Com o HEFESTO
+
+| Antes | Depois |
+|---|---|
+| Demanda por e-mail | Formulário digital com SLA automático |
+| Planilha de cotação | Comparativo automático com equalização |
+| Aprovação informal | Workflow com alçadas e registro completo |
+| Orçamento no escuro | Dashboard em tempo real, planejado vs. realizado |
+| Fornecedor sem controle | Cadastro com certidões, rating e histórico |
+| Sem visibilidade | Painel executivo com KPIs e alertas |
+
+## 3. Perfis de Usuário e Jornadas
+
+### 3.1 Solicitante
+
+**Quem é:** Gerente de unidade, coordenador, colaborador que identifica uma necessidade.
+
+**Jornada típica:**
+1. Faz login no HEFESTO
+2. Abre nova demanda descrevendo o serviço necessário
+3. Seleciona local, categoria e prioridade
+4. Acompanha o status da demanda em tempo real
+5. Recebe notificações de cada mudança de status
+6. Avalia o serviço após conclusão
+
+### 3.2 Gestor de Facilities
+
+**Quem é:** Profissional responsável pela operação de Facilities.
+
+**Jornada típica:**
+1. Visualiza dashboard com demandas pendentes e indicadores
+2. Analisa e complementa o escopo das demandas recebidas
+3. Seleciona fornecedores e envia pedidos de cotação
+4. Recebe e compara propostas (com auxílio de OCR e equalização)
+5. Seleciona a melhor proposta e encaminha para aprovação
+6. Após aprovação, emite Ordem de Serviço
+7. Acompanha execução e prazos
+8. Registra conclusão e solicita avaliação
+
+### 3.3 Aprovador Financeiro
+
+**Quem é:** Controller, gerente financeiro, analista de orçamento.
+
+**Jornada típica:**
+1. Recebe notificação de demanda aguardando aprovação financeira
+2. Analisa valor vs. orçamento disponível no centro de custo
+3. Consulta comparativo de propostas e justificativa
+4. Aprova, rejeita ou devolve para correção
+5. Monitora orçamento planejado vs. realizado
+
+### 3.4 Diretoria
+
+**Quem é:** Diretor de operações, CFO, CEO.
+
+**Jornada típica:**
+1. Aprova demandas de alto valor (acima da alçada do financeiro)
+2. Acompanha dashboard executivo com visão macro
+3. Analisa tendências de gastos e projeções
+
+### 3.5 Fornecedor
+
+**Quem é:** Prestador de serviços cadastrado no sistema.
+
+**Jornada típica:**
+1. Recebe convite de cotação por e-mail
+2. Acessa o HEFESTO e submete proposta com valores e documentos
+3. Acompanha se foi selecionado
+4. Recebe Ordem de Serviço
+5. Registra conclusão do trabalho
+
+### 3.6 Admin
+
+**Quem é:** Administrador do sistema (TI ou gestor principal).
+
+**Jornada típica:**
+1. Configura locais, centros de custo e categorias
+2. Gerencia usuários e perfis de acesso
+3. Define alçadas de aprovação
+4. Monitora audit log e saúde do sistema
+
+## 4. Fluxo Completo de uma Demanda
+
+```
+┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────────┐
+│ ABERTURA │───►│  ESCOPO  │───►│ COTAÇÃO  │───►│  PROPOSTAS   │
+│          │    │          │    │          │    │  RECEBIDAS   │
+└──────────┘    └──────────┘    └──────────┘    └──────┬───────┘
+Solicitante     Gestor Fac.     Gestor Fac.           │
+                                                       ▼
+┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────────┐
+│AVALIAÇÃO │◄───│CONCLUÍDA │◄───│EXECUÇÃO  │◄───│  APROVAÇÃO   │
+│          │    │          │    │          │    │  (Workflow)   │
+└──────────┘    └──────────┘    └──────────┘    └──────────────┘
+Solicitante     Gestor Fac.     Fornecedor      Financ./Diret.
+```
+
+### Etapas Detalhadas
+
+1. **Abertura:** Solicitante descreve a necessidade, seleciona local, categoria e prioridade
+2. **Escopo:** Gestor de Facilities detalha os itens de linha, quantidades e especificações técnicas
+3. **Cotação:** Gestor seleciona 3+ fornecedores e envia convite de cotação
+4. **Propostas Recebidas:** Fornecedores submetem suas propostas com valores e documentos
+5. **Comparação:** Sistema gera quadro comparativo automático com equalização de itens
+6. **Aprovação:** Demanda segue workflow de alçadas conforme valor total
+7. **Ordem de Serviço:** Após aprovação, OS é emitida automaticamente para o fornecedor selecionado
+8. **Execução:** Fornecedor executa o serviço; gestor acompanha prazos e SLA
+9. **Avaliação:** Solicitante e gestor avaliam qualidade, prazo e comunicação do fornecedor
+
+## 5. Funcionalidades por Módulo
+
+### 5.1 Dashboard
+- KPIs em tempo real (demandas abertas, em aprovação, gastos do mês)
+- Gráfico de gastos por local e categoria
+- Evolução mensal de gastos (planejado vs. realizado)
+- Ranking de fornecedores por nota
+- Indicadores de SLA (% dentro do prazo)
+- Alertas de certidões vencendo e orçamento estourando
+
+### 5.2 Demandas
+- Criação com formulário guiado (wizard)
+- Itens de linha com quantidade, unidade e valor estimado
+- Filtros por status, local, categoria, período e responsável
+- Timeline visual de cada demanda
+- Anexos e comentários
+
+### 5.3 Propostas
+- Submissão pelo fornecedor com upload de documentos
+- **OCR automático:** Extração de valores de propostas em PDF/imagem
+- **Equalização automática:** Normalização de itens para comparação justa
+- Quadro comparativo lado a lado
+- Seleção com justificativa obrigatória
+
+### 5.4 Orçamento
+- Planejamento anual por centro de custo e mês
+- Acompanhamento realizado vs. planejado em tempo real
+- Projeção de gastos com base no pipeline de demandas
+- Alertas automáticos ao atingir 80% e 100% do orçamento
+- Remanejamento entre centros de custo (com aprovação)
+
+### 5.5 Fornecedores
+- Cadastro completo (razão social, CNPJ, contato, especialidades)
+- Gestão de certidões com alerta de vencimento
+- Rating automático baseado em avaliações
+- Histórico de OS e valores contratados
+- Blacklist e restrições
+
+### 5.6 Workflow
+- Configuração de alçadas por faixa de valor
+- Aprovação em cadeia (sequencial) ou paralela
+- Notificações por e-mail e no sistema
+- Prazo para aprovação com escalação automática
+- Histórico completo de aprovações e rejeições
+
+### 5.7 Ordens de Serviço
+- Emissão automática após aprovação
+- Número sequencial por ano
+- Controle de datas (início, previsão, conclusão real)
+- Status: Emitida → Em Execução → Concluída → Avaliada
+
+### 5.8 Relatórios
+- Gastos por local, categoria e fornecedor
+- Economia gerada (valor estimado vs. contratado)
+- Tempo médio de ciclo por etapa
+- Exportação em PDF e Excel
+
+## 6. Modelo de Negócio
+
+### 6.1 Formato
+
+**SaaS B2B** (Software as a Service) com cobrança recorrente mensal.
+
+### 6.2 Pricing
+
+| Plano | Unidades | Usuários | Preço/mês |
+|---|---|---|---|
+| **Starter** | Até 5 | Até 20 | R$ 1.500 |
+| **Professional** | Até 20 | Até 100 | R$ 4.500 |
+| **Enterprise** | Ilimitado | Ilimitado | Sob consulta |
+
+**Adicional por unidade:** R$ 200/mês (plano Starter e Professional)
+**Adicional por usuário:** R$ 50/mês
+
+### 6.3 Modelo de Receita
+
+- Assinatura mensal recorrente (MRR)
+- Setup fee (implantação e treinamento): 2x o valor mensal
+- Customizações sob demanda (hora técnica)
+
+### 6.4 Mercado-Alvo
+
+- Empresas com 10+ unidades (shoppings, escritórios, fábricas, hospitais)
+- Áreas de Facilities / Manutenção / Infraestrutura
+- Empresas de administração de condomínios corporativos
+- Redes de varejo com muitas lojas
+
+## 7. Diferenciais Competitivos
+
+### 7.1 OCR em Propostas
+Tecnologia de reconhecimento óptico para extrair valores de propostas enviadas em PDF ou imagem. Elimina a digitação manual e reduz erros.
+
+### 7.2 Equalização Automática
+Algoritmo que normaliza itens de diferentes propostas para comparação justa, mesmo quando fornecedores usam unidades, descrições ou agrupamentos diferentes.
+
+### 7.3 Workflow de Alçadas
+Motor de aprovação configurável por faixa de valor, com escalação automática, prazos e notificações. Garante conformidade e rastreabilidade total.
+
+### 7.4 Orçamento em Tempo Real
+Visão instantânea de planejado vs. realizado, com projeções baseadas no pipeline de demandas aprovadas e em andamento.
+
+### 7.5 Rating de Fornecedores
+Sistema de avaliação baseado em critérios objetivos (prazo, qualidade, comunicação) que alimenta o ranking automaticamente.
+
+### 7.6 Audit Trail Completo
+Toda ação no sistema é registrada com timestamp, usuário, IP e dados antes/depois. Compliance total para auditorias.
+
+## 8. Roadmap de Evolução
+
+### Fase 1 — MVP (Atual) ✅
+- [x] Autenticação e RBAC
+- [x] CRUD de demandas, fornecedores, propostas
+- [x] Workflow de aprovação com alçadas
+- [x] Dashboard com KPIs básicos
+- [x] Orçamento planejado vs. realizado
+- [x] Ordens de serviço
+
+### Fase 2 — Q2 2025
+- [ ] OCR para extração de valores de propostas
+- [ ] App mobile (React Native) para aprovações rápidas
+- [ ] Integração com ERP (SAP, TOTVS) via API
+- [ ] Notificações push
+
+### Fase 3 — Q3 2025
+- [ ] Módulo de contratos (gestão de contratos recorrentes)
+- [ ] Equalização automática de propostas com IA
+- [ ] Portal do fornecedor (self-service)
+- [ ] Multi-idioma (PT/EN/ES)
+
+### Fase 4 — Q4 2025
+- [ ] BI avançado com drill-down
+- [ ] Predição de manutenção (ML)
+- [ ] Marketplace de fornecedores
+- [ ] White-label para revendas
+
+## 9. Métricas de Sucesso
+
+### 9.1 Métricas de Produto
+
+| Métrica | Meta | Como medir |
+|---|---|---|
+| Tempo médio de ciclo da demanda | < 15 dias | Média de created_at até status CONCLUÍDA |
+| % de demandas com 3+ propostas | > 80% | Demandas com 3+ propostas / total |
+| % de aprovações no prazo | > 95% | Aprovações dentro do SLA configurado |
+| Economia média por demanda | > 12% | (Valor estimado - valor contratado) / estimado |
+| NPS do solicitante | > 70 | Pesquisa trimestral |
+
+### 9.2 Métricas de Negócio
+
+| Métrica | Meta Ano 1 | Meta Ano 2 |
+|---|---|---|
+| MRR (Receita Mensal Recorrente) | R$ 30.000 | R$ 150.000 |
+| Clientes ativos | 10 | 40 |
+| Churn mensal | < 3% | < 2% |
+| CAC (Custo de Aquisição) | < R$ 5.000 | < R$ 4.000 |
+| LTV (Lifetime Value) | > R$ 50.000 | > R$ 80.000 |
+| LTV/CAC | > 10x | > 20x |
+
+### 9.3 Métricas de Impacto no Cliente
+
+- **Redução de 70%** no tempo gasto com gestão manual de cotações
+- **Redução de 40%** no ciclo de aprovação
+- **Economia média de 15%** em contratações por comparação efetiva
+- **100% de rastreabilidade** em auditorias
+- **Zero** propostas perdidas ou esquecidas
+
+---
+
+*Documento gerado automaticamente — HEFESTO v1.0*