bigtux/hefesto
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
90c7a2cacb2901400b970e7c570bb82cfc3cc17c
hefesto/docs/MANUAL-TECNICO.md

28 KiB
Raw Blame History

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

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
│       ├── 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

# 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
17 esg_metricas Métricas ambientais ESG id, local_id, tipo (energia/agua/residuos/emissoes_co2), valor, unidade_medida, periodo, observacoes, created_at
18 esg_metas Metas ESG id, local_id, tipo, descricao, valor_alvo, valor_atual, percentual_atingido, status, prazo, created_at
19 kpis Indicadores de performance calculados id, nome, valor, unidade, status_semaforo, centro_custo_id, periodo, calculated_at
20 metas Metas por centro de custo id, centro_custo_id, tipo (orcamento/operacional/esg), descricao, valor_alvo, valor_atual, percentual_atingido, status, prazo, created_at
21 alertas_config Configuração de alertas inteligentes id, tipo, centro_custo_id, categoria_id, limite_percentual, notificar_usuarios (JSON), ativo, 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

5.14 ESG / Sustentabilidade (/api/esg)

Método Rota Descrição
GET /api/esg/metricas Listar métricas ambientais (filtros: unidade, período, tipo)
POST /api/esg/metricas Registrar métrica ambiental
PATCH /api/esg/metricas/:id Atualizar métrica
DELETE /api/esg/metricas/:id Remover métrica
GET /api/esg/dashboard Dashboard consolidado ESG por unidade/período
GET /api/esg/metas Listar metas ESG
POST /api/esg/metas Criar meta ESG
PATCH /api/esg/metas/:id Atualizar meta ESG
GET /api/esg/metas/:id/progresso Progresso da meta 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)

Método Rota Descrição
GET /api/kpis Listar KPIs calculados (filtros: categoria, ano, centro_custo)
GET /api/kpis/dashboard Dashboard de KPIs com status semáforo

KPIs calculados automaticamente:

KPI Fórmula Verde Amarelo Vermelho
% Orçamento Consumido realizado / planejado × 100 ≤ 80% 81–100% > 100%
Tempo Médio de OS média(data_fim_real - data_inicio) ≤ SLA SLA+20% > SLA+20%
Rating Fornecedores média das avaliações ≥ 4.0 3.0–3.9 < 3.0
Taxa Conclusão Demandas concluídas / total × 100 ≥ 90% 70–89% < 70%

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)

Método Rota Descrição
GET /api/audit/logs Trilha de auditoria completa (filtros: usuario, entidade, período, ação)
GET /api/audit/compliance-report Relatório de conformidade por período
GET /api/audit/export Exportação de logs em CSV ou JSON (?format=csv|json)

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)

Método Rota Descrição
POST /api/import/excel Upload de planilha Excel/CSV com validação automática

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)

Método Rota Descrição
GET /api/relatorios/orcamento-mensal Relatório de orçamento mensal (filtros: ano, mês, local)
GET /api/relatorios/demandas-periodo Demandas por período com status e valores
GET /api/relatorios/fornecedores-ranking Ranking de fornecedores com nota, valor e volume
GET /api/relatorios/os-performance Performance de OS (SLA, tempo médio, conclusão)

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)

Método Rota Descrição
GET /api/metas Listar metas (filtros: centro_custo, tipo, status)
POST /api/metas Criar meta
PATCH /api/metas/:id Atualizar meta
DELETE /api/metas/:id Remover meta
GET /api/metas/progresso Progresso geral de todas as metas
GET /api/metas/:id/progresso Progresso de meta específica

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.

Método Rota Descrição
POST /api/alertas/configurar Configurar regra de alerta inteligente
GET /api/alertas/configurar Listar configurações de alertas
PATCH /api/alertas/configurar/:id Atualizar configuração
DELETE /api/alertas/configurar/:id Remover configuração
POST /api/alertas/verificar Disparar verificação manual de todos os alertas

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

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

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

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)

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 v2.0

Reference in New Issue View Git Blame Copy Permalink