# 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)
![PM2](https://img.shields.io/badge/Process%20Manager-PM2-blue)
![License](https://img.shields.io/badge/License-MIT-yellow.svg)

Este projeto é um **serviço de integração entre HubSoft e GLPI**, responsável por sincronizar **tickets, fechamentos e comentários**, utilizando **Node.js**, **PostgreSQL** e uma arquitetura baseada em **Clean Architecture**.

O foco do projeto é:
- confiabilidade
- idempotência
- isolamento de responsabilidades
- facilidade de manutenção e evolução

---

## ✨ Funcionalidades

- Criação automática de tickets no **GLPI** a partir de atendimentos do **HubSoft**
- Fechamento automático de atendimentos no **HubSoft** a partir de tickets encerrados no **GLPI**
- Sincronização de **comentários** do GLPI para o HubSoft
- Processamento assíncrono via **cron/worker**
- Controle de estado e idempotência via **banco intermediário**
- Prevenção de concorrência e duplicidade de eventos
- Execução separada de **API** e **Worker**
- Suporte a execução local, desenvolvimento e produção

---

## 🧱 Arquitetura

O projeto segue princípios da **Clean Architecture**, separando claramente:

```
Controller → UseCase → Repository → Infra
```

### Camadas

- **Controller**
  - Entrada HTTP (webhooks, endpoints)
  - Não contém regra de negócio
- **UseCases**
  - Regras de negócio
  - Orquestração dos fluxos
- **Repositories**
  - Contratos de acesso a dados e integrações
- **Infra**
  - Implementações técnicas (DB, APIs, cron, HTTP)

---

## 🔄 Fluxos de Integração

### 1. Criação de Tickets (HubSoft → GLPI)

Fluxo assíncrono executado por **worker (cron)**.

```
HubSoft DB
   ↓
Worker (Cron)
   ↓
Banco Intermediário
   ↓
API GLPI
```

**Passo a passo:**
1. Worker consulta novos atendimentos no HubSoft
2. Use case valida e transforma os dados
3. Registro é salvo no banco intermediário
4. Ticket é criado no GLPI
5. Status de sincronização é atualizado

---

### 2. Fechamento de Tickets (GLPI → HubSoft)

Fluxo síncrono iniciado via webhook.

```
GLPI Webhook
   ↓
API (Controller)
   ↓
UseCase
   ↓
API HubSoft
   ↓
Banco Intermediário
```

**Regras importantes:**
- Apenas tickets elegíveis (ex: tipo *Mundiale*)
- Controle de lock para evitar duplicidade
- Atualização de status após sucesso

---

### 3. Sincronização de Comentários (GLPI → HubSoft)

Fluxo acionado por webhook do GLPI.

```
GLPI Webhook
   ↓
API (Controller)
   ↓
UseCase
   ↓
API HubSoft
   ↓
Banco Intermediário
```

**Detalhes:**
- Sanitização de HTML/texto
- Controle por `comment_id` e `source_comment_id`
- Garantia de idempotência
- Comentários duplicados são ignorados

---

## 🗄️ Banco de Dados Intermediário

O banco intermediário é **fundamental** para a integração.

Ele é responsável por:
- Controle de estado dos tickets
- Idempotência de webhooks
- Lock de processamento
- Auditoria e rastreabilidade

### Exemplos de status

- `pending_create`
- `created`
- `processing_close`
- `closed`
- `synced`

---

## 📂 Estrutura do Projeto

```
src/
├── config/                # Configurações gerais
├── infra/                 # Infraestrutura
│   ├── api/               # Clientes de APIs externas
│   ├── cron/              # Workers / Jobs agendados
│   ├── db/
│   │   ├── connections/
│   │   └── repositories/
│   └── http/
│       └── routes/
├── modules/               # Domínio (Clean Architecture)
│   ├── close/
│   ├── comments/
│   ├── createTickets/
│   └── tickets/
├── shared/                # Código compartilhado
│   └── utils/
├── logs/                  # Logs da aplicação
└── server.js              # Bootstrap da aplicação
```

---

## 🚀 Execução do Projeto

### Pré-requisitos

- Node.js 18+
- NPM
- PostgreSQL
- PM2 (produção)

```bash
npm install -g pm2
```

---

### Variáveis de Ambiente

Criar arquivos:

```bash
.env.development
.env.production
```

Exemplo:

```ini
PORT=3000
NODE_ENV=development

HUBGLPI_DB_HOST=localhost
HUBGLPI_DB_PORT=5432
HUBGLPI_DB_USER=postgres
HUBGLPI_DB_PASSWORD=senha
HUBGLPI_DB_NAME=hubglpi

HUBSOFT_DB_HOST=ip
HUBSOFT_DB_PORT=5432
HUBSOFT_DB_USER=usuario
HUBSOFT_DB_PASSWORD=senha
HUBSOFT_DB_NAME=hubsoft

GLPI_API_URL=https://seu-glpi/apirest.php
GLPI_APP_TOKEN=token
GLPI_USER_TOKEN=token

HUBSOFT_API_URL=https://seu-hubsoft/api
HUBSOFT_API_TOKEN=token
```

---

## ▶️ Scripts NPM

### Desenvolvimento

Rodar **apenas a API**:
```bash
npm run dev:api
```

Rodar **apenas o worker (cron)**:
```bash
npm run dev:worker
```

---

### Produção (PM2)

Rodar apenas a **API**:
```bash
pm2 start npm --name hubxglpi-api -- start:api
```

Rodar apenas o **Worker**:
```bash
pm2 start npm --name hubxglpi-worker -- start:worker
```

Rodarr **API e Worker**:
```bash
pm2 start ecosystem.config.js --env production

Ver status:
```bash
pm2 status
```

Logs:
```bash
pm2 logs
```

---

## 🧠 Boas Práticas

- Sempre utilizar o banco intermediário para controle de estado
- Controllers não devem conter lógica de negócio
- UseCases não devem conhecer detalhes de infraestrutura

---

## 📜 Licença

MIT