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/ARQUITETURA-TECNICA.md
+++ b/docs/ARQUITETURA-TECNICA.md
--- a/docs/ESPECIFICACAO-FUNCIONAL.pdf
+++ b/docs/ESPECIFICACAO-FUNCIONAL.pdf
--- 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*
--- a/docs/MANUAL-NEGOCIOS.pdf
+++ b/docs/MANUAL-NEGOCIOS.pdf
--- a/docs/MANUAL-TECNICO.md
+++ b/docs/MANUAL-TECNICO.md
@@ -0,0 +1,508 @@
+# HEFESTO — Manual Técnico
+
+**Sistema de Controle Orçamentário para Facilities**
+
+Versão 1.0 | Fevereiro 2025
+
+---
+
+## 1. Visão Geral da Arquitetura
+
+O HEFESTO é uma aplicação web fullstack composta por:
+
+- **Backend:** API REST em NestJS (Node.js) com TypeORM
+- **Frontend:** SPA em React + TypeScript com Vite
+- **Banco de Dados:** SQLite (desenvolvimento) / PostgreSQL (produção)
+- **Autenticação:** JWT com RBAC (Role-Based Access Control)
+
+```
+┌─────────────────┐     HTTP/REST     ┌─────────────────┐
+│   React SPA     │ ◄──────────────► │  NestJS API     │
+│   (Vite)        │     JWT Bearer    │  (TypeORM)      │
+│   Port 5173     │                   │  Port 3000      │
+└─────────────────┘                   └────────┬────────┘
+                                               │
+                                      ┌────────▼────────┐
+                                      │  SQLite / PG    │
+                                      └─────────────────┘
+```
+
+## 2. Stack Completa
+
+| Componente | Tecnologia | Versão |
+|---|---|---|
+| Runtime | Node.js | 22.x LTS |
+| Backend Framework | NestJS | 10.x |
+| ORM | TypeORM | 0.3.x |
+| Frontend Framework | React | 18.x |
+| Build Tool | Vite | 5.x |
+| Linguagem | TypeScript | 5.x |
+| UI Components | Tailwind CSS | 3.x |
+| BD Desenvolvimento | SQLite3 | 5.x |
+| BD Produção | PostgreSQL | 16.x |
+| Auth | @nestjs/jwt + passport | 10.x |
+| HTTP Client | Axios | 1.x |
+| Validação | class-validator | 0.14.x |
+| Documentação API | @nestjs/swagger | 7.x |
+
+## 3. Estrutura de Pastas
+
+### 3.1 Backend
+
+```
+backend/
+├── src/
+│   ├── main.ts                    # Bootstrap da aplicação
+│   ├── app.module.ts              # Módulo raiz
+│   ├── common/                    # Guards, decorators, pipes, interceptors
+│   │   ├── guards/
+│   │   │   ├── jwt-auth.guard.ts
+│   │   │   └── roles.guard.ts
+│   │   ├── decorators/
+│   │   │   ├── roles.decorator.ts
+│   │   │   └── current-user.decorator.ts
+│   │   └── interceptors/
+│   │       └── audit.interceptor.ts
+│   ├── database/                  # Configuração TypeORM, migrations, seeds
+│   │   ├── database.module.ts
+│   │   ├── migrations/
+│   │   └── seeds/
+│   └── modules/
+│       ├── auth/                  # Autenticação JWT, login, refresh token
+│       │   ├── auth.controller.ts
+│       │   ├── auth.service.ts
+│       │   ├── auth.module.ts
+│       │   ├── strategies/
+│       │   │   └── jwt.strategy.ts
+│       │   └── dto/
+│       ├── users/                 # CRUD de usuários e perfis
+│       │   ├── users.controller.ts
+│       │   ├── users.service.ts
+│       │   ├── entities/
+│       │   │   ├── usuario.entity.ts
+│       │   │   └── perfil.entity.ts
+│       │   └── dto/
+│       ├── locais/                # Gestão de locais/unidades
+│       ├── centros-custo/         # Centros de custo vinculados a locais
+│       ├── categorias/            # Categorias de serviço
+│       ├── fornecedores/          # Cadastro de fornecedores e certidões
+│       ├── demandas/              # Abertura e gestão de demandas
+│       ├── propostas/             # Recebimento e comparação de propostas
+│       ├── orcamento/             # Orçamento planejado vs realizado
+│       ├── workflow/              # Máquina de estados de aprovação
+│       ├── dashboard/             # Indicadores e relatórios
+│       └── ordens-servico/        # Emissão e acompanhamento de OS
+├── test/
+├── nest-cli.json
+├── tsconfig.json
+└── package.json
+```
+
+### 3.2 Frontend
+
+```
+frontend/
+├── src/
+│   ├── main.tsx                   # Entry point
+│   ├── App.tsx                    # Router + Layout
+│   ├── assets/                    # Imagens, ícones
+│   ├── components/                # Componentes reutilizáveis
+│   │   ├── Layout/
+│   │   ├── Sidebar/
+│   │   ├── Header/
+│   │   ├── DataTable/
+│   │   ├── StatusBadge/
+│   │   └── Charts/
+│   ├── pages/
+│   │   ├── Login.tsx              # Tela de autenticação
+│   │   ├── Dashboard.tsx          # Painel de indicadores
+│   │   ├── Demandas.tsx           # Lista de demandas com filtros
+│   │   ├── Landing.tsx            # Página inicial / nova demanda
+│   │   ├── Fornecedores.tsx       # Gestão de fornecedores
+│   │   ├── Orcamentos.tsx         # Orçamento planejado vs realizado
+│   │   ├── OrdensServico.tsx      # Ordens de serviço
+│   │   ├── Relatorios.tsx         # Relatórios gerenciais
+│   │   └── Usuarios.tsx           # Administração de usuários
+│   ├── services/                  # Axios clients e API calls
+│   │   └── api.ts
+│   ├── types/                     # Interfaces TypeScript
+│   └── index.css                  # Tailwind directives
+├── vite.config.ts
+├── tailwind.config.js
+├── tsconfig.json
+└── package.json
+```
+
+## 4. Modelo de Dados
+
+### 4.1 Diagrama de Entidades
+
+O sistema possui 16 entidades principais:
+
+```
+perfis ──< usuarios ──< demandas ──< itens_linha
+                │              │
+                │              ├──< propostas
+                │              │
+                │              ├──< workflow_aprovacao
+                │              │
+                │              └──< ordens_servico ──< avaliacoes
+                │
+                └──< audit_log
+
+locais ──< centros_custo ──< orcamento_planejado
+
+categorias ──< demandas
+
+fornecedores ──< certidoes
+fornecedores ──< propostas
+
+alertas (standalone)
+```
+
+### 4.2 Descrição das Entidades
+
+| # | Entidade | Descrição | Campos Principais |
+|---|---|---|---|
+| 1 | **perfis** | Perfis de acesso (RBAC) | id, nome, descricao, permissoes (JSON) |
+| 2 | **usuarios** | Usuários do sistema | id, nome, email, senha_hash, perfil_id, ativo, ultimo_acesso |
+| 3 | **locais** | Unidades/edifícios | id, nome, endereco, cidade, estado, cnpj, ativo |
+| 4 | **centros_custo** | Centros de custo por local | id, codigo, descricao, local_id, ativo |
+| 5 | **categorias** | Categorias de serviço | id, nome, descricao, sla_dias, ativo |
+| 6 | **fornecedores** | Cadastro de fornecedores | id, razao_social, cnpj, contato, email, telefone, ativo, rating |
+| 7 | **certidoes** | Certidões de fornecedores | id, fornecedor_id, tipo, arquivo_url, validade, status |
+| 8 | **orcamento_planejado** | Budget por centro de custo/ano | id, centro_custo_id, ano, mes, valor_planejado, valor_realizado |
+| 9 | **demandas** | Demandas de serviço | id, titulo, descricao, local_id, categoria_id, solicitante_id, status, prioridade, valor_estimado, created_at |
+| 10 | **itens_linha** | Itens detalhados da demanda | id, demanda_id, descricao, quantidade, unidade, valor_unitario |
+| 11 | **propostas** | Propostas de fornecedores | id, demanda_id, fornecedor_id, valor_total, arquivo_url, data_validade, status, observacoes |
+| 12 | **workflow_aprovacao** | Etapas de aprovação | id, demanda_id, etapa, aprovador_id, status, comentario, data_acao |
+| 13 | **ordens_servico** | Ordens de serviço emitidas | id, demanda_id, proposta_id, numero_os, data_inicio, data_fim_prevista, data_fim_real, status |
+| 14 | **avaliacoes** | Avaliação pós-execução | id, ordem_servico_id, avaliador_id, nota, comentario, created_at |
+| 15 | **audit_log** | Log de auditoria | id, usuario_id, acao, entidade, entidade_id, dados_antes, dados_depois, ip, created_at |
+| 16 | **alertas** | Notificações e alertas | id, usuario_id, tipo, mensagem, lido, referencia_tipo, referencia_id, created_at |
+
+### 4.3 Perfis de Acesso (RBAC)
+
+| Perfil | Permissões |
+|---|---|
+| **Admin** | Acesso total ao sistema, gestão de usuários e configurações |
+| **Gestor Facilities** | CRUD de demandas, fornecedores, propostas, OS; aprovação nível 1 |
+| **Aprovador Financeiro** | Aprovação nível 2 (financeiro), visualização de orçamento |
+| **Diretoria** | Aprovação nível 3 (alçada máxima), dashboard executivo |
+| **Solicitante** | Abertura de demandas, acompanhamento do próprio pedido |
+| **Fornecedor** | Envio de propostas, acompanhamento de OS atribuídas |
+
+## 5. API — Endpoints
+
+### 5.1 Autenticação (`/api/auth`)
+
+| Método | Rota | Descrição |
+|---|---|---|
+| POST | `/api/auth/login` | Login com email/senha → JWT |
+| POST | `/api/auth/refresh` | Renovar token |
+| POST | `/api/auth/logout` | Invalidar token |
+| GET | `/api/auth/me` | Dados do usuário logado |
+| POST | `/api/auth/forgot-password` | Solicitar reset de senha |
+| POST | `/api/auth/reset-password` | Resetar senha com token |
+
+### 5.2 Usuários (`/api/users`)
+
+| Método | Rota | Descrição |
+|---|---|---|
+| GET | `/api/users` | Listar usuários (paginado) |
+| GET | `/api/users/:id` | Detalhes do usuário |
+| POST | `/api/users` | Criar usuário |
+| PATCH | `/api/users/:id` | Atualizar usuário |
+| DELETE | `/api/users/:id` | Desativar usuário |
+| GET | `/api/perfis` | Listar perfis |
+
+### 5.3 Locais (`/api/locais`)
+
+| Método | Rota | Descrição |
+|---|---|---|
+| GET | `/api/locais` | Listar locais |
+| GET | `/api/locais/:id` | Detalhes do local |
+| POST | `/api/locais` | Criar local |
+| PATCH | `/api/locais/:id` | Atualizar local |
+| DELETE | `/api/locais/:id` | Desativar local |
+
+### 5.4 Centros de Custo (`/api/centros-custo`)
+
+| Método | Rota | Descrição |
+|---|---|---|
+| GET | `/api/centros-custo` | Listar centros de custo |
+| GET | `/api/centros-custo/:id` | Detalhes |
+| POST | `/api/centros-custo` | Criar centro de custo |
+| PATCH | `/api/centros-custo/:id` | Atualizar |
+| DELETE | `/api/centros-custo/:id` | Desativar |
+
+### 5.5 Categorias (`/api/categorias`)
+
+| Método | Rota | Descrição |
+|---|---|---|
+| GET | `/api/categorias` | Listar categorias |
+| GET | `/api/categorias/:id` | Detalhes |
+| POST | `/api/categorias` | Criar categoria |
+| PATCH | `/api/categorias/:id` | Atualizar |
+| DELETE | `/api/categorias/:id` | Desativar |
+
+### 5.6 Fornecedores (`/api/fornecedores`)
+
+| Método | Rota | Descrição |
+|---|---|---|
+| GET | `/api/fornecedores` | Listar fornecedores |
+| GET | `/api/fornecedores/:id` | Detalhes com certidões |
+| POST | `/api/fornecedores` | Cadastrar fornecedor |
+| PATCH | `/api/fornecedores/:id` | Atualizar fornecedor |
+| DELETE | `/api/fornecedores/:id` | Desativar |
+| POST | `/api/fornecedores/:id/certidoes` | Upload de certidão |
+| GET | `/api/fornecedores/:id/certidoes` | Listar certidões |
+| DELETE | `/api/fornecedores/:id/certidoes/:certidaoId` | Remover certidão |
+
+### 5.7 Demandas (`/api/demandas`)
+
+| Método | Rota | Descrição |
+|---|---|---|
+| GET | `/api/demandas` | Listar demandas (filtros: status, local, categoria, período) |
+| GET | `/api/demandas/:id` | Detalhes completos da demanda |
+| POST | `/api/demandas` | Criar nova demanda |
+| PATCH | `/api/demandas/:id` | Atualizar demanda |
+| DELETE | `/api/demandas/:id` | Cancelar demanda |
+| POST | `/api/demandas/:id/itens` | Adicionar item de linha |
+| PATCH | `/api/demandas/:id/itens/:itemId` | Atualizar item |
+| DELETE | `/api/demandas/:id/itens/:itemId` | Remover item |
+| POST | `/api/demandas/:id/enviar-cotacao` | Enviar para cotação |
+| GET | `/api/demandas/:id/comparativo` | Comparativo de propostas |
+
+### 5.8 Propostas (`/api/propostas`)
+
+| Método | Rota | Descrição |
+|---|---|---|
+| GET | `/api/propostas` | Listar propostas |
+| GET | `/api/propostas/:id` | Detalhes da proposta |
+| POST | `/api/propostas` | Submeter proposta (fornecedor) |
+| PATCH | `/api/propostas/:id` | Atualizar proposta |
+| DELETE | `/api/propostas/:id` | Retirar proposta |
+| POST | `/api/propostas/:id/aceitar` | Aceitar proposta |
+| POST | `/api/propostas/:id/rejeitar` | Rejeitar proposta |
+| POST | `/api/propostas/:id/ocr` | Processar OCR do arquivo |
+
+### 5.9 Orçamento (`/api/orcamento`)
+
+| Método | Rota | Descrição |
+|---|---|---|
+| GET | `/api/orcamento` | Orçamento geral (filtros: ano, local, centro_custo) |
+| GET | `/api/orcamento/:id` | Detalhes da linha orçamentária |
+| POST | `/api/orcamento` | Criar linha orçamentária |
+| PATCH | `/api/orcamento/:id` | Atualizar valores |
+| GET | `/api/orcamento/resumo` | Resumo planejado vs realizado |
+| GET | `/api/orcamento/projecao` | Projeção de gastos |
+
+### 5.10 Workflow (`/api/workflow`)
+
+| Método | Rota | Descrição |
+|---|---|---|
+| GET | `/api/workflow/pendentes` | Aprovações pendentes do usuário logado |
+| GET | `/api/workflow/demanda/:demandaId` | Histórico de aprovações da demanda |
+| POST | `/api/workflow/aprovar` | Aprovar etapa |
+| POST | `/api/workflow/rejeitar` | Rejeitar etapa |
+| POST | `/api/workflow/devolver` | Devolver para correção |
+| GET | `/api/workflow/alçadas` | Consultar alçadas configuradas |
+
+### 5.11 Dashboard (`/api/dashboard`)
+
+| Método | Rota | Descrição |
+|---|---|---|
+| GET | `/api/dashboard/indicadores` | KPIs gerais |
+| GET | `/api/dashboard/demandas-por-status` | Demandas agrupadas por status |
+| GET | `/api/dashboard/gastos-por-local` | Gastos por unidade |
+| GET | `/api/dashboard/gastos-por-categoria` | Gastos por categoria |
+| GET | `/api/dashboard/evolucao-mensal` | Série temporal de gastos |
+| GET | `/api/dashboard/top-fornecedores` | Ranking de fornecedores |
+| GET | `/api/dashboard/sla` | Indicadores de SLA |
+
+### 5.12 Ordens de Serviço (`/api/ordens-servico`)
+
+| Método | Rota | Descrição |
+|---|---|---|
+| GET | `/api/ordens-servico` | Listar OS |
+| GET | `/api/ordens-servico/:id` | Detalhes da OS |
+| POST | `/api/ordens-servico` | Emitir OS |
+| PATCH | `/api/ordens-servico/:id` | Atualizar OS |
+| POST | `/api/ordens-servico/:id/iniciar` | Marcar início da execução |
+| POST | `/api/ordens-servico/:id/concluir` | Marcar conclusão |
+| POST | `/api/ordens-servico/:id/avaliar` | Avaliar serviço prestado |
+
+### 5.13 Alertas (`/api/alertas`)
+
+| Método | Rota | Descrição |
+|---|---|---|
+| GET | `/api/alertas` | Listar alertas do usuário |
+| PATCH | `/api/alertas/:id/lido` | Marcar como lido |
+| DELETE | `/api/alertas/:id` | Remover alerta |
+
+**Total: 68 endpoints**
+
+## 6. Autenticação e Autorização
+
+### 6.1 Fluxo JWT
+
+1. Usuário faz POST `/api/auth/login` com email e senha
+2. Backend valida credenciais e retorna `{ accessToken, refreshToken }`
+3. Frontend armazena tokens e envia `Authorization: Bearer <accessToken>` em todas as requests
+4. Token expira em 1h; refresh token expira em 7d
+5. Frontend usa `/api/auth/refresh` para renovar automaticamente
+
+### 6.2 Guards NestJS
+
+```typescript
+@UseGuards(JwtAuthGuard, RolesGuard)
+@Roles('admin', 'gestor_facilities')
+@Get('demandas')
+findAll() { ... }
+```
+
+- **JwtAuthGuard**: valida o token JWT
+- **RolesGuard**: verifica se o perfil do usuário está na lista de roles permitidas
+- **@CurrentUser()**: decorator customizado que injeta o usuário logado
+
+## 7. Workflow de Aprovação
+
+### 7.1 Máquina de Estados
+
+```
+RASCUNHO → EM_ESCOPO → EM_COTAÇÃO → PROPOSTAS_RECEBIDAS
+    → EM_COMPARAÇÃO → AGUARDANDO_APROVAÇÃO → APROVADA
+    → OS_EMITIDA → EM_EXECUÇÃO → CONCLUÍDA → AVALIADA
+
+Estados alternativos:
+    AGUARDANDO_APROVAÇÃO → REJEITADA
+    AGUARDANDO_APROVAÇÃO → DEVOLVIDA → EM_ESCOPO
+    Qualquer estado → CANCELADA
+```
+
+### 7.2 Alçadas de Aprovação
+
+| Faixa de Valor | Aprovador |
+|---|---|
+| Até R$ 5.000 | Gestor Facilities |
+| R$ 5.001 — R$ 50.000 | Gestor Facilities + Aprovador Financeiro |
+| R$ 50.001 — R$ 200.000 | Gestor + Financeiro + Diretoria |
+| Acima de R$ 200.000 | Gestor + Financeiro + Diretoria + CEO |
+
+Cada etapa gera um registro em `workflow_aprovacao` com timestamp, aprovador e comentário.
+
+## 8. Como Rodar Localmente
+
+### 8.1 Pré-requisitos
+
+- Node.js 22.x
+- npm 10.x
+- Git
+
+### 8.2 Backend
+
+```bash
+cd backend
+cp .env.example .env          # Ajustar variáveis
+npm install
+npm run build
+npm run migration:run         # Criar tabelas
+npm run seed                  # Dados iniciais
+npm start                     # Porta 3000
+```
+
+### 8.3 Frontend
+
+```bash
+cd frontend
+cp .env.example .env          # VITE_API_URL=http://localhost:3000/api
+npm install
+npm run dev                   # Porta 5173
+```
+
+### 8.4 Acesso Inicial
+
+- **Admin:** admin@hefesto.com.br / admin123
+- **Swagger:** http://localhost:3000/api/docs
+
+## 9. Deploy em Produção
+
+### 9.1 Infraestrutura
+
+- **Servidor:** DigitalOcean Droplet (Ubuntu 24.04, 2 vCPU, 4GB RAM)
+- **Proxy reverso:** Nginx
+- **SSL:** Let's Encrypt (Certbot)
+- **Processo:** PM2 (backend) / Nginx serve build estático (frontend)
+- **BD:** PostgreSQL 16
+
+### 9.2 Nginx Config
+
+```nginx
+server {
+    listen 443 ssl;
+    server_name hefesto.exemplo.com.br;
+
+    ssl_certificate /etc/letsencrypt/live/hefesto.exemplo.com.br/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/hefesto.exemplo.com.br/privkey.pem;
+
+    # Frontend (build estático)
+    location / {
+        root /var/www/hefesto/frontend/dist;
+        try_files $uri $uri/ /index.html;
+    }
+
+    # API Backend
+    location /api {
+        proxy_pass http://127.0.0.1:3000;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+    }
+}
+```
+
+### 9.3 PM2
+
+```bash
+cd /var/www/hefesto/backend
+pm2 start dist/main.js --name hefesto-api
+pm2 save
+pm2 startup
+```
+
+## 10. Variáveis de Ambiente
+
+### Backend (`.env`)
+
+| Variável | Descrição | Exemplo |
+|---|---|---|
+| `NODE_ENV` | Ambiente | `production` |
+| `PORT` | Porta da API | `3000` |
+| `DB_TYPE` | Tipo de banco | `postgres` |
+| `DB_HOST` | Host do banco | `localhost` |
+| `DB_PORT` | Porta do banco | `5432` |
+| `DB_USERNAME` | Usuário do banco | `hefesto` |
+| `DB_PASSWORD` | Senha do banco | `***` |
+| `DB_DATABASE` | Nome do banco | `hefesto_prod` |
+| `JWT_SECRET` | Chave secreta JWT | `minha-chave-secreta-256bits` |
+| `JWT_EXPIRATION` | Tempo de expiração do access token | `3600s` |
+| `JWT_REFRESH_EXPIRATION` | Tempo de expiração do refresh token | `7d` |
+| `CORS_ORIGIN` | Origem permitida | `https://hefesto.exemplo.com.br` |
+| `OCR_API_KEY` | Chave da API de OCR | `***` |
+| `SMTP_HOST` | Servidor SMTP | `smtp.gmail.com` |
+| `SMTP_PORT` | Porta SMTP | `587` |
+| `SMTP_USER` | Usuário SMTP | `noreply@hefesto.com.br` |
+| `SMTP_PASS` | Senha SMTP | `***` |
+
+### Frontend (`.env`)
+
+| Variável | Descrição | Exemplo |
+|---|---|---|
+| `VITE_API_URL` | URL base da API | `https://hefesto.exemplo.com.br/api` |
+| `VITE_APP_NAME` | Nome da aplicação | `HEFESTO` |
+
+---
+
+*Documento gerado automaticamente — HEFESTO v1.0*
--- a/docs/MANUAL-TECNICO.pdf
+++ b/docs/MANUAL-TECNICO.pdf
--- a/docs/PESQUISA-MERCADO.md
+++ b/docs/PESQUISA-MERCADO.md
@@ -0,0 +1,105 @@
+# PESQUISA DE MERCADO: HEFESTO (Facilities Management System)
+
+> **Nota:** Este documento foi gerado com base em conhecimento de mercado pré-existente e análise estratégica interna. Dados numéricos específicos em tempo real (2024-2025) podem requerer validação adicional, pois o acesso à pesquisa web estava indisponível no momento da criação.
+
+## 1. Visão Geral do Mercado
+
+O mercado de **Facilities Management (FM)** está em expansão acelerada, impulsionado pela necessidade de eficiência operacional, redução de custos e adaptação aos novos modelos de trabalho híbrido.
+
+### Tamanho e Crescimento
+*   **Global:** O mercado global de FM foi avaliado em aproximadamente **USD 1,2 trilhão em 2022** e projeta-se que alcance cerca de **USD 1,8 trilhão até 2028-2030**, com um CAGR (Taxa de Crescimento Anual Composta) estimado entre **5% e 7%**.
+*   **Brasil:** O Brasil representa o maior mercado da América Latina. O setor de serviços e terceirização (onde o FM se insere fortemente) continua sendo um dos pilares do PIB. A demanda por soluções de software (IWMS - Integrated Workplace Management Systems) está crescendo à medida que empresas buscam digitalizar processos manuais (planilhas/papel).
+
+### Tendências Principais
+1.  **Digitalização e IoT:** Uso de sensores para manutenção preditiva e gestão de energia.
+2.  **Sustentabilidade (ESG):** Pressão para que edifícios sejam "verdes" e eficientes energeticamente.
+3.  **Experiência do Ocupante:** O foco mudou da simples manutenção do prédio para o bem-estar e produtividade dos usuários (UX).
+4.  **Trabalho Híbrido:** Gestão flexível de espaços (hot-desking, reserva de salas) tornou-se crítica pós-pandemia.
+
+---
+
+## 2. Análise da Concorrência
+
+O mercado possui players consolidados (Enterprise) e soluções de nicho.
+
+### Principais Concorrentes
+
+| Software | Perfil | Pontos Fortes | Pontos Fracos / Gaps |
+| :--- | :--- | :--- | :--- |
+| **IBM Tririga** | Enterprise / Global | Robustez, integração com IoT/Watson, gestão imobiliária completa. | Custo proibitivo para médias empresas; implementação complexa e longa; curva de aprendizado alta. |
+| **Archibus** | Enterprise / Global | Líder tradicional em gestão de espaço e ativos; muito completo. | Interface pode parecer datada; excesso de funcionalidades que poluem a usabilidade (bloatware); alto custo. |
+| **Planon** | Enterprise / Europeu | Forte em sustentabilidade e compliance; boa interface web. | Preço elevado; customização pode ser rígida dependendo do módulo. |
+| **TrackVia** | Low-code / Flexível | Plataforma "faça você mesmo"; rapidez para criar formulários. | Não é um FM nativo; requer construção da lógica de facilities do zero; falta de "best practices" embutidas. |
+| **Optii** | Nicho (Hotelaria) | Otimização de housekeeping; muito focado em operações de limpeza. | Muito específico para hotéis; não atende bem escritórios corporativos ou indústrias com manutenção técnica complexa. |
+| **Software Local (BR)** | Pequenos Players | Preço em Reais; suporte local. | Geralmente limitados a gestão de ordens de serviço simples; falta de inteligência (IA/OCR) e workflows financeiros robustos. |
+
+### Gaps Identificados no Mercado
+*   **Complexidade Excessiva:** As soluções Enterprise (IBM, Archibus) são "canhões para matar moscas" para muitas empresas brasileiras.
+*   **Falta de Inteligência Financeira:** Muitos softwares focam apenas na Ordem de Serviço (técnica) e esquecem a dor da **compra/cotação** (financeira).
+*   **Usabilidade:** Interfaces legadas que dificultam a adoção por equipes operacionais em campo.
+
+---
+
+## 3. Diferenciais do HEFESTO
+
+O **HEFESTO** se posiciona para preencher o gap entre a "planilha de controle" e os "sistemas Enterprise caros", com foco em automação inteligente e controle financeiro.
+
+### 1. OCR Inteligente em Propostas (O "Game Changer")
+*   **O Problema:** O gestor de facilities recebe dezenas de orçamentos em PDF/Imagem de fornecedores (limpeza, elétrica, ar-condicionado). Digitar isso no sistema é lento e propenso a erros.
+*   **A Solução HEFESTO:** O sistema lê os PDFs dos fornecedores, extrai os itens, valores unitários e totais automaticamente, populando o comparativo.
+
+### 2. Equalização Automática de Propostas
+*   **Funcionalidade:** Após o OCR ler 3 orçamentos diferentes, o sistema gera um mapa de equalização (Mapa Comparativo) lado a lado, destacando o menor preço, o melhor prazo e discrepâncias técnicas.
+*   **Benefício:** Redução de 80% no tempo de análise de compras.
+
+### 3. Workflow de Alçadas Dinâmico
+*   **Funcionalidade:** Aprovações configuráveis por valor, centro de custo ou categoria. (Ex: "Manutenção acima de R$ 5k precisa do Gerente; acima de R$ 50k precisa do Diretor").
+*   **Benefício:** Compliance e agilidade, tudo via mobile ou web, sem depender de trocas de e-mail.
+
+### 4. Controle Orçamentário Integrado (Budget vs. Realizado)
+*   **Funcionalidade:** Cada aprovação ou OS executada desconta em tempo real do orçamento daquela conta (ex: Manutenção Predial).
+*   **Benefício:** O gestor sabe se tem verba *antes* de aprovar o serviço, evitando estouros de budget no fim do mês.
+
+---
+
+## 4. Modelo de Negócio
+
+**Formato:** SaaS (Software as a Service) B2B.
+
+### Estratégia de Pricing
+A precificação será híbrida para garantir escalabilidade e receita recorrente previsível.
+
+1.  **Por Unidade/Site (Predominante):** Valor base por prédio/escritório gerenciado. Incentiva o cliente a colocar todos os usuários do prédio no sistema sem medo de "custo por assento".
+2.  **Por Usuário Admin (Opcional):** Cobrança apenas para usuários "Power" (Gestores, Compradores). Técnicos de campo e solicitantes (abertura de chamados) são **ilimitados/gratuitos** para reduzir barreira de entrada.
+
+### Tiers (Planos) Sugeridos
+
+*   **IRON (Básico)**
+    *   Gestão de Ordens de Serviço (Preventiva/Corretiva).
+    *   App para Técnicos.
+    *   Solicitantes ilimitados.
+    *   *Ideal para: Pequenos escritórios, condomínios simples.*
+
+*   **STEEL (Intermediário)**
+    *   Tudo do IRON +
+    *   Gestão de Ativos (QR Code).
+    *   Controle de Estoque básico.
+    *   Relatórios de SLA.
+    *   *Ideal para: Médias empresas, redes de varejo.*
+
+*   **TITANIUM (Avançado - O "Hefesto Completo")**
+    *   Tudo do STEEL +
+    *   **Módulo de Compras (OCR + Equalização).**
+    *   Gestão Orçamentária (Budget Control).
+    *   Workflows de Aprovação complexos.
+    *   API para integração (ERP).
+    *   *Ideal para: Grandes corporações, hospitais, indústrias.*
+
+---
+
+## 5. Identidade do Projeto
+
+*   **Nome:** **HEFESTO**
+*   **Origem:** Deus grego dos ferreiros, artesãos, escultores, metalurgia, fogo e vulcões.
+*   **Simbologia:** Representa a construção, a manutenção, a técnica e a habilidade de criar ferramentas funcionais.
+*   **Slogan Sugerido:** "Forjando a eficiência na gestão de facilities." ou "O controle total da sua operação."