774 lines
28 KiB
Markdown
774 lines
28 KiB
Markdown
# 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`:**
|
||
```json
|
||
// 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`:**
|
||
```json
|
||
// 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`:**
|
||
```json
|
||
// 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):**
|
||
```json
|
||
// 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`:**
|
||
```json
|
||
// 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`:**
|
||
```json
|
||
// 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`:**
|
||
```json
|
||
// 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
|
||
|
||
```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 v2.0*
|