DOC: Documentação ajustada praa se adequar a mudanças
This commit is contained in:
parent
2382d2f8c0
commit
37205d7e23
369
README.md
369
README.md
@ -1,130 +1,146 @@
|
|||||||
# Serviço de Integração HubSoft <> GLPI
|
# Serviço de Integração HubSoft ⇄ GLPI
|
||||||
|
|
||||||
   
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
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.
|
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**.
|
||||||
|
|
||||||
## ✨ Funcionalidades Principais
|
O foco do projeto é:
|
||||||
|
- confiabilidade
|
||||||
- **Sincronização Bidirecional Parcial**:
|
- idempotência
|
||||||
- **Criação**: Tickets abertos no HubSoft são automaticamente criados no GLPI.
|
- isolamento de responsabilidades
|
||||||
- **Fechamento**: Tickets "Mundiale" fechados no GLPI disparam o fechamento do atendimento correspondente no HubSoft.
|
- facilidade de manutenção e evolução
|
||||||
- **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
|
## ✨ Funcionalidades
|
||||||
|
|
||||||
A aplicação opera com dois fluxos principais:
|
- 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**
|
||||||
### 1. Fluxo de Criação de Tickets (Cron Job)
|
- Sincronização de **comentários** do GLPI para o HubSoft
|
||||||
|
- Processamento assíncrono via **cron/worker**
|
||||||
Este fluxo roda a cada 5 minutos para sincronizar novos atendimentos do HubSoft para o GLPI.
|
- 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
|
||||||
│ 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
|
## 🧱 Arquitetura
|
||||||
|
|
||||||
### Pré-requisitos
|
O projeto segue princípios da **Clean Architecture**, separando claramente:
|
||||||
|
|
||||||
- Node.js (versão 18.x ou superior)
|
```
|
||||||
- NPM
|
Controller → UseCase → Repository → Infra
|
||||||
- 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 ssh://usuario.autorizado@10.0.120.75:60000/home/desenvolvimento/HUBXGLPI/HUBXGLPI.git
|
|
||||||
cd HUBXGLPI
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### 2. Instale as Dependências
|
### Camadas
|
||||||
|
|
||||||
```bash
|
- **Controller**
|
||||||
npm install
|
- 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
|
||||||
```
|
```
|
||||||
|
|
||||||
### 3. Configure as Variáveis de Ambiente
|
**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
|
||||||
|
|
||||||
Crie um arquivo `.env.production` e um `.env.development` na raiz do projeto, copiando o exemplo de `.env.example`.
|
---
|
||||||
|
|
||||||
```bash
|
### 2. Fechamento de Tickets (GLPI → HubSoft)
|
||||||
cp .env.example .env
|
|
||||||
|
Fluxo síncrono iniciado via webhook.
|
||||||
|
|
||||||
|
```
|
||||||
|
GLPI Webhook
|
||||||
|
↓
|
||||||
|
API (Controller)
|
||||||
|
↓
|
||||||
|
UseCase
|
||||||
|
↓
|
||||||
|
API HubSoft
|
||||||
|
↓
|
||||||
|
Banco Intermediário
|
||||||
```
|
```
|
||||||
|
|
||||||
Preencha o arquivo `.env` com as credenciais corretas:
|
**Regras importantes:**
|
||||||
|
- Apenas tickets elegíveis (ex: tipo *Mundiale*)
|
||||||
|
- Controle de lock para evitar duplicidade
|
||||||
|
- Atualização de status após sucesso
|
||||||
|
|
||||||
```ini
|
---
|
||||||
# Configurações do Servidor
|
|
||||||
PORT=3000
|
|
||||||
|
|
||||||
# Banco de Dados da Aplicação (HubGLPI)
|
### 3. Sincronização de Comentários (GLPI → HubSoft)
|
||||||
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)
|
Fluxo acionado por webhook do GLPI.
|
||||||
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 Webhook
|
||||||
GLPI_APP_TOKEN=seu_app_token
|
↓
|
||||||
GLPI_USER_TOKEN=seu_user_token
|
API (Controller)
|
||||||
|
↓
|
||||||
# API do HubSoft
|
UseCase
|
||||||
HUBSOFT_API_URL=https://seu-hubsoft.com/api/v1
|
↓
|
||||||
HUBSOFT_API_TOKEN=seu_token_hubsoft
|
API HubSoft
|
||||||
|
↓
|
||||||
|
Banco Intermediário
|
||||||
```
|
```
|
||||||
|
|
||||||
### 4. Inicie a Aplicação
|
**Detalhes:**
|
||||||
|
- Sanitização de HTML/texto
|
||||||
|
- Controle por `comment_id` e `source_comment_id`
|
||||||
|
- Garantia de idempotência
|
||||||
|
- Comentários duplicados são ignorados
|
||||||
|
|
||||||
```bash
|
---
|
||||||
NODE_ENV=development node src/server.js
|
|
||||||
ou
|
|
||||||
NODE_ENV=production node src/server.js
|
|
||||||
```
|
|
||||||
|
|
||||||
O servidor será iniciado, e o cron job começará a ser executado em segundo plano.
|
## 🗄️ 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`
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
@ -132,33 +148,132 @@ O servidor será iniciado, e o cron job começará a ser executado em segundo pl
|
|||||||
|
|
||||||
```
|
```
|
||||||
src/
|
src/
|
||||||
├── app.js # Configuração da instância do Express.
|
├── config/ # Configurações gerais
|
||||||
├── server.js # Ponto de entrada: inicia o servidor e o cron job.
|
├── infra/ # Infraestrutura
|
||||||
├── routes.js # Definição das rotas da API.
|
│ ├── api/ # Clientes de APIs externas
|
||||||
│
|
│ ├── cron/ # Workers / Jobs agendados
|
||||||
├── config/ # Arquivos de configuração.
|
│ ├── db/
|
||||||
│ ├── apiConfig.js # Configuração das APIs externas.
|
│ │ ├── connections/
|
||||||
│ ├── dbConfig.js # Configuração dos bancos de dados.
|
│ │ └── repositories/
|
||||||
│ └── envLoader.js # Carregador de variáveis de ambiente.
|
│ └── http/
|
||||||
│
|
│ └── routes/
|
||||||
├── controller/ # Camada que lida com requisições HTTP.
|
├── modules/ # Domínio (Clean Architecture)
|
||||||
│ ├── ClosureController.js # Controller para o webhook de fechamento.
|
│ ├── close/
|
||||||
│ └── processController.js # Controller para o fluxo de criação via cron.
|
│ ├── comments/
|
||||||
│
|
│ ├── createTickets/
|
||||||
├── data/ # Configuração da conexão com os bancos.
|
│ └── tickets/
|
||||||
│ ├── hubglpiDataBase.js # Pool de conexão para o DB da aplicação.
|
├── shared/ # Código compartilhado
|
||||||
│ └── hubsoftDataBase.js # Pool de conexão para o DB do HubSoft.
|
│ └── utils/
|
||||||
│
|
├── logs/ # Logs da aplicação
|
||||||
├── model/ # Camada de acesso a dados.
|
└── server.js # Bootstrap da aplicação
|
||||||
│ ├── 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).
|
|
||||||
```
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🚀 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
|
||||||
|
|||||||
@ -6,7 +6,7 @@ require('winston-daily-rotate-file');
|
|||||||
const fs = require('fs');
|
const fs = require('fs');
|
||||||
|
|
||||||
// verifica se a pasta de logs existe, se não, cria
|
// verifica se a pasta de logs existe, se não, cria
|
||||||
const logsDir = path.join(__dirname, '../../logs');
|
const logsDir = path.join(__dirname, '../../../logs');
|
||||||
if (!fs.existsSync(logsDir)) {
|
if (!fs.existsSync(logsDir)) {
|
||||||
fs.mkdirSync(logsDir, { recursive: true });
|
fs.mkdirSync(logsDir, { recursive: true });
|
||||||
}
|
}
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user