HEFESTO — Manual Técnico

Sistema de Controle Orçamentário para Facilities

Versão 2.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

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
│       ├── esg/                   # Métricas ESG e sustentabilidade
│       ├── kpis/                  # Indicadores de performance
│       ├── audit/                 # Auditoria e compliance avançado
│       ├── import/                # Importação de dados Excel/CSV
│       ├── relatorios/            # Relatórios automatizados
│       ├── metas/                 # Metas e acompanhamento de progresso
│       └── alertas-inteligentes/  # Configuração e verificação de alertas
├── 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
│   │   ├── ESG.tsx                # Dashboard ESG e métricas ambientais
│   │   ├── KPIs.tsx               # Painel de indicadores de performance
│   │   ├── Auditoria.tsx          # Logs de auditoria e compliance
│   │   ├── Importacao.tsx         # Upload de planilhas Excel/CSV
│   │   ├── Metas.tsx              # Metas e progresso por centro de custo
│   │   └── Alertas.tsx            # Configuração de alertas inteligentes
│   ├── 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 21 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)

locais ──< esg_metricas
locais ──< esg_metas

centros_custo ──< kpis
centros_custo ──< metas

centros_custo ──< alertas_config
categorias ──< alertas_config

4.2 Descrição das Entidades

4.3 Perfis de Acesso (RBAC)

5. API — Endpoints

5.1 Autenticação (/api/auth)

5.2 Usuários (/api/users)

5.3 Locais (/api/locais)

5.4 Centros de Custo (/api/centros-custo)

5.5 Categorias (/api/categorias)

5.6 Fornecedores (/api/fornecedores)

5.7 Demandas (/api/demandas)

5.8 Propostas (/api/propostas)

5.9 Orçamento (/api/orcamento)

5.10 Workflow (/api/workflow)

5.11 Dashboard (/api/dashboard)

5.12 Ordens de Serviço (/api/ordens-servico)

5.13 Alertas (/api/alertas)

5.14 ESG / Sustentabilidade (/api/esg)

Exemplo — POST /api/esg/metricas:

// Request
{
  "local_id": 3,
  "tipo": "energia",
  "valor": 12500.50,
  "unidade_medida": "kWh",
  "periodo": "2025-06",
  "observacoes": "Consumo sede administrativa"
}
// Response 201
{
  "id": 42,
  "local_id": 3,
  "tipo": "energia",
  "valor": 12500.50,
  "unidade_medida": "kWh",
  "periodo": "2025-06",
  "created_at": "2025-06-30T14:00:00Z"
}

Tipos de métricas suportados: energia (kWh), agua (m³), residuos (kg), emissoes_co2 (tCO₂e).

5.15 KPIs — Indicadores de Performance (/api/kpis)

KPIs calculados automaticamente:

Exemplo — GET /api/kpis/dashboard:

// Response 200
{
  "periodo": "2025-06",
  "kpis": [
    {
      "nome": "orcamento_consumido",
      "valor": 78.5,
      "unidade": "%",
      "status": "verde",
      "centro_custo": "ADM-001"
    },
    {
      "nome": "tempo_medio_os",
      "valor": 12.3,
      "unidade": "dias",
      "status": "amarelo",
      "centro_custo": "ADM-001"
    }
  ]
}

5.16 Auditoria e Compliance (/api/audit)

Exemplo — GET /api/audit/logs?entidade=demandas&periodo_inicio=2025-06-01:

// Response 200
{
  "total": 245,
  "page": 1,
  "data": [
    {
      "id": 1023,
      "usuario": "joao.silva@empresa.com",
      "acao": "UPDATE",
      "entidade": "demandas",
      "entidade_id": 87,
      "dados_antes": { "status": "EM_COTACAO" },
      "dados_depois": { "status": "PROPOSTAS_RECEBIDAS" },
      "ip": "192.168.1.50",
      "created_at": "2025-06-15T10:32:00Z"
    }
  ]
}

5.17 Importação de Dados (/api/import)

Tipos de importação: orcamento, demandas.

Exemplo — POST /api/import/excel (multipart/form-data):

// Request: file=planilha.xlsx, tipo=orcamento
// Response 200
{
  "status": "success",
  "registros_importados": 48,
  "registros_com_erro": 2,
  "erros": [
    { "linha": 15, "campo": "valor_planejado", "mensagem": "Valor inválido" },
    { "linha": 32, "campo": "centro_custo_id", "mensagem": "Centro de custo não encontrado" }
  ]
}

5.18 Relatórios Automatizados (/api/relatorios)

Todos os relatórios suportam ?format=json|csv|pdf.

Exemplo — GET /api/relatorios/fornecedores-ranking?ano=2025&limit=10:

// Response 200
{
  "periodo": "2025",
  "ranking": [
    {
      "posicao": 1,
      "fornecedor": "TechServ Ltda",
      "rating": 4.8,
      "total_os": 23,
      "valor_total": 187500.00,
      "sla_cumprido": 95.6
    }
  ]
}

5.19 Metas e Progresso (/api/metas)

Tipos de meta: orcamento, operacional, esg.

Status: em_andamento, atingida, atrasada.

Exemplo — POST /api/metas:

// Request
{
  "centro_custo_id": 5,
  "tipo": "orcamento",
  "descricao": "Reduzir gastos com manutenção em 10%",
  "valor_alvo": 90,
  "unidade": "%",
  "prazo": "2025-12-31"
}
// Response 201
{
  "id": 12,
  "centro_custo_id": 5,
  "tipo": "orcamento",
  "descricao": "Reduzir gastos com manutenção em 10%",
  "valor_alvo": 90,
  "valor_atual": 0,
  "percentual_atingido": 0,
  "status": "em_andamento",
  "prazo": "2025-12-31",
  "created_at": "2025-02-09T15:00:00Z"
}

5.20 Alertas Inteligentes (/api/alertas)

Nota: Os endpoints abaixo complementam os alertas básicos da seção 5.13 com configuração avançada e verificação automática.

Tipos de alerta: orcamento_excedido, certidao_vencendo, os_atrasada, meta_em_risco.

Exemplo — POST /api/alertas/configurar:

// Request
{
  "tipo": "orcamento_excedido",
  "centro_custo_id": 5,
  "limite_percentual": 85,
  "notificar_usuarios": [1, 3, 7],
  "ativo": true
}
// Response 201
{
  "id": 8,
  "tipo": "orcamento_excedido",
  "centro_custo_id": 5,
  "limite_percentual": 85,
  "notificar_usuarios": [1, 3, 7],
  "ativo": true,
  "created_at": "2025-02-09T15:00:00Z"
}

Total: 95 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

@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

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

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

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

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

cd /var/www/hefesto/backend
pm2 start dist/main.js --name hefesto-api
pm2 save
pm2 startup

10. Variáveis de Ambiente

Backend (.env)

Frontend (.env)

Documento gerado automaticamente — HEFESTO v2.0