280 lines
5.4 KiB
Markdown
280 lines
5.4 KiB
Markdown
# 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)
|
|
|
|
```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
|