hubxglpi/README.md

# Serviço de Integração HubSoft <> GLPI

![Node.js](https://img.shields.io/badge/Node.js-18.x-green) ![Express.js](https://img.shields.io/badge/Express.js-4.x-blue) ![PostgreSQL](https://img.shields.io/badge/Database-PostgreSQL-blue) ![License](https://img.shields.io/badge/License-MIT-yellow.svg)

Este serviço realiza a integração e sincronização de tickets entre as plataformas **HubSoft** e **GLPI**, garantindo que as informações fluam de maneira consistente e automatizada entre os dois sistemas.

## ✨ Funcionalidades Principais

-   **Sincronização Bidirecional Parcial**:
    -   **Criação**: Tickets abertos no HubSoft são automaticamente criados no GLPI.
    -   **Fechamento**: Tickets "Mundiale" fechados no GLPI disparam o fechamento do atendimento correspondente no HubSoft.
-   **Processamento Assíncrono**: Utiliza um cron job para processar a criação de tickets em segundo plano, sem impactar a performance da API.
-   **Banco de Dados Intermediário**: Usa um banco de dados PostgreSQL para gerenciar o estado da sincronização, garantindo resiliência e rastreabilidade.
-   **Mecanismo de Trava (Locking)**: Previne condições de corrida e processamento duplicado de webhooks.
-   **Configuração Flexível**: Todas as chaves de API e conexões de banco de dados são gerenciadas por variáveis de ambiente.
-   **Logging Detalhado**: Registra todas as operações e erros em arquivos de log para fácil depuração.

---

## 🏗️ Arquitetura e Fluxo de Dados

A aplicação opera com dois fluxos principais:

### 1. Fluxo de Criação de Tickets (Cron Job)

Este fluxo roda a cada 5 minutos para sincronizar novos atendimentos do HubSoft para o GLPI.

```
┌──────────────────┐      ┌───────────────────┐      ┌──────────────────┐      ┌──────────┐
│  DB do HubSoft   ├─────►│  Serviço (Cron)   ├─────►│  DB Intermediário  ├─────►│ API GLPI │
└──────────────────┘      └───────────────────┘      └──────────────────┘      └──────────┘
       (Lê)                 (Processa dados)          (Salva & Trava)          (Cria Ticket)
```

1.  O **Cron Job** é disparado.
2.  O serviço consulta o banco de dados do **HubSoft** em busca de novos atendimentos.
3.  Os dados são processados e salvos no **Banco de Dados Intermediário** com o status `pending_create`.
4.  O serviço lê os tickets pendentes, formata os dados e os envia para a **API do GLPI** para criar o ticket.
5.  Após a criação, o status no banco intermediário é atualizado para `created_glpi`.

### 2. Fluxo de Fechamento de Tickets (Webhook)

Este fluxo é iniciado por um evento de fechamento de ticket no GLPI.

```
┌──────────────┐      ┌──────────────────┐      ┌────────────────┐      ┌──────────────────┐
│ GLPI Webhook ├─────►│  Serviço (API)   ├─────►│ API do HubSoft ├─────►│  DB Intermediário│
└──────────────┘      └──────────────────┘      └────────────────┘      └──────────────────┘
   (Dispara)             (Valida e Trava)         (Fecha Atendimento)      (Atualiza Status)
```

1.  O **GLPI** dispara um webhook quando um ticket é fechado.
2.  A API do serviço recebe a requisição e verifica se o ticket é elegível (contém "Mundiale" no título).
3.  O serviço obtém uma **trava** no banco de dados intermediário, mudando o status para `processing_close` para evitar processamento duplicado.
4.  Uma chamada é feita para a **API do HubSoft** para fechar o atendimento correspondente.
5.  Após o sucesso, o status no banco intermediário é atualizado para `closed_glpi`.

---

## 🚀 Instalação e Execução

### Pré-requisitos

-   Node.js (versão 18.x ou superior)
-   NPM
-   Acesso a dois bancos de dados PostgreSQL (um para o HubSoft e outro para a aplicação).

### 1. Clone o Repositório

```bash
git clone <url-do-seu-repositorio>
cd <nome-do-repositorio>
```

### 2. Instale as Dependências

```bash
npm install
```

### 3. Configure as Variáveis de Ambiente

Crie um arquivo `.env` na raiz do projeto, copiando o exemplo de `.env.example`.

```bash
cp .env.example .env
```

Preencha o arquivo `.env` com as credenciais corretas:

```ini
# Configurações do Servidor
PORT=3000

# Banco de Dados da Aplicação (HubGLPI)
HUBGLPI_DB_HOST=localhost
HUBGLPI_DB_PORT=5432
HUBGLPI_DB_USER=postgres
HUBGLPI_DB_PASSWORD=sua_senha
HUBGLPI_DB_NAME=hubglpi

# Banco de Dados do HubSoft (Acesso de Leitura)
HUBSOFT_DB_HOST=ip_do_banco_hubsoft
HUBSOFT_DB_PORT=5432
HUBSOFT_DB_USER=usuario_leitura
HUBSOFT_DB_PASSWORD=senha_leitura
HUBSOFT_DB_NAME=hubsoft

# API do GLPI
GLPI_API_URL=https://seu-glpi.com/apirest.php
GLPI_APP_TOKEN=seu_app_token
GLPI_USER_TOKEN=seu_user_token

# API do HubSoft
HUBSOFT_API_URL=https://seu-hubsoft.com/api/v1
HUBSOFT_API_TOKEN=seu_token_hubsoft
```

### 4. Inicie a Aplicação

```bash
npm start
```

O servidor será iniciado, e o cron job começará a ser executado em segundo plano.

---

## 📂 Estrutura do Projeto

```
src/
├── app.js                 # Configuração da instância do Express.
├── server.js              # Ponto de entrada: inicia o servidor e o cron job.
├── routes.js              # Definição das rotas da API.
│
├── config/                # Arquivos de configuração.
│   ├── apiConfig.js       # Configuração das APIs externas.
│   ├── dbConfig.js        # Configuração dos bancos de dados.
│   └── envLoader.js       # Carregador de variáveis de ambiente.
│
├── controller/            # Camada que lida com requisições HTTP.
│   ├── ClosureController.js # Controller para o webhook de fechamento.
│   └── processController.js # Controller para o fluxo de criação via cron.
│
├── data/                  # Configuração da conexão com os bancos.
│   ├── hubglpiDataBase.js # Pool de conexão para o DB da aplicação.
│   └── hubsoftDataBase.js # Pool de conexão para o DB do HubSoft.
│
├── model/                 # Camada de acesso a dados.
│   ├── glpiModel.js       # Funções para interagir com a API do GLPI.
│   ├── hubglpiModel.js    # Funções para interagir com o DB da aplicação.
│   └── hubsoftModel.js    # Funções para interagir com o DB do HubSoft.
│
├── services/              # Camada de lógica de negócio.
│   ├── hubsoftService.js  # Lógica para interagir com a API do HubSoft.
│   └── ticketService.js   # Lógica de negócio para o fechamento de tickets.
│
└── utils/                 # Funções utilitárias.
    ├── commentSanitizer.js# Limpeza de texto e HTML.
    └── logger.js          # Configuração do sistema de logs (Winston).
```