Serviço de Integração HubSoft ⇄ GLPI

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)

npm install -g pm2

---

Variáveis de Ambiente

Criar arquivos:

.env.development
.env.production

Exemplo:

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:

npm run dev:api

Rodar apenas o worker (cron):

npm run dev:worker

---

Produção (PM2)

Rodar apenas a API:

pm2 start npm --name hubxglpi-api -- start:api

Rodar apenas o Worker:

pm2 start npm --name hubxglpi-worker -- start:worker

Rodarr API e Worker:

pm2 start ecosystem.config.js --env production

Ver status:
```bash
pm2 status

Logs:

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