Major update: ESG, KPIs, metas, alertas, auditoria, documentos, importação, relatórios, subcategorias, dashboard orçamentos

2026-02-10 18:52:52 -03:00
parent d8ca580acb
commit 90c7a2cacb
92 changed files with 10265 additions and 1238 deletions
--- a/docs/MANUAL-TECNICO.md
+++ b/docs/MANUAL-TECNICO.md
@@ -2,7 +2,7 @@

 **Sistema de Controle Orçamentário para Facilities**

-Versão 1.0 | Fevereiro 2025
+Versão 2.0 | Fevereiro 2025

 ---

@@ -91,7 +91,14 @@ backend/
 │       ├── 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
+│       ├── 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
@@ -122,7 +129,13 @@ frontend/
 │   │   ├── 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
+│   │   ├── 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
@@ -137,7 +150,7 @@ frontend/

 ### 4.1 Diagrama de Entidades

-O sistema possui 16 entidades principais:
+O sistema possui 21 entidades principais:

 ```
 perfis ──< usuarios ──< demandas ──< itens_linha
@@ -158,6 +171,15 @@ 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
@@ -180,6 +202,11 @@ alertas (standalone)
 | 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)

@@ -341,7 +368,245 @@ alertas (standalone)
 | PATCH | `/api/alertas/:id/lido` | Marcar como lido |
 | DELETE | `/api/alertas/:id` | Remover alerta |

-**Total: 68 endpoints**
+### 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

@@ -505,4 +770,4 @@ pm2 startup

 ---

-*Documento gerado automaticamente — HEFESTO v1.0*
+*Documento gerado automaticamente — HEFESTO v2.0*