hubxglpi/fluxoEntidade.md

# Fluxo de Resolução e Criação de Entidades (GLPI)

## Contexto

Quando um chamado de **Implantação** chega no Hub x GLPI, precisamos garantir que exista uma **Entidade** correta no GLPI para vincular o ticket.

Hoje, a resolução tenta encontrar a entidade pelo padrão de nome baseado em:
- `codigoCliente`
- `codigoServico`
- `nomeCliente`

Caso não encontre, entra a feature de **criação automática via API (GLPI v2 + OAuth)**.

> Regra importante: **criação/alteração de entidades sempre via API**, nunca via banco do GLPI.

---

## Convenções de Nome

### Entidade mãe (Cliente)
- **Formato:** `{codigoCliente} - {nomeCliente}`
- **Exemplo:** `12345 - ACME Telecom`

### Entidade filha (Serviço)
- **Formato:** `{codigoCliente} - {codigoServico} - {nomeCliente}`
- **Exemplo:** `12345 - 67890 - ACME Telecom`

> Observação: O `{nomeCliente}` é repetido na filha para manter legibilidade e facilitar busca manual no GLPI.

---

## Busca de Entidades

### Busca por Serviço (Entidade filha)
Procura por entidade que contenha:
- `{codigoCliente} - {codigoServico}` (prefixo/like)

### Busca por Cliente (Entidade mãe)
Procura por entidade que contenha:
- `{codigoCliente} -` (prefixo/like)

---

## Opção A — Criação hierárquica (Mãe + Filha quando necessário)

### Objetivo
Garantir hierarquia consistente no GLPI:
- Cliente como entidade mãe
- Serviço como entidade filha

### Fluxo (passo a passo)

1. **Tentar encontrar entidade por Serviço**
   - Busca: `{codigoCliente} - {codigoServico}*`
   - Se encontrou:
     - ✅ usar essa entidade (filha) e finalizar

2. **Se não encontrou por Serviço: tentar encontrar entidade por Cliente**
   - Busca: `{codigoCliente} -*`
   - Se encontrou:
     - ✅ criar **entidade filha** abaixo dessa mãe:
       - Nome: `{codigoCliente} - {codigoServico} - {nomeCliente}`
       - Parent: `{codigoCliente} - {nomeCliente}`
     - ✅ usar a entidade criada (filha) e finalizar

3. **Se não encontrou nem por Serviço nem por Cliente**
   - Criar **entidade mãe**:
     - Nome: `{codigoCliente} - {nomeCliente}`
     - Parent: raiz (definir entidade pai padrão, ex.: Root)
   - Criar **entidade filha** abaixo da mãe:
     - Nome: `{codigoCliente} - {codigoServico} - {nomeCliente}`
     - Parent: `{codigoCliente} - {nomeCliente}`
   - ✅ usar a entidade criada (filha) e finalizar

### Resultado final (Opção A)
- Ticket sempre fica na **entidade filha** (serviço)
- Sempre tenta manter **estrutura hierárquica** consistente

---

### Diagrama de Fluxo — Opção A (hierárquica: Mãe + Filha quando necessário)

```mermaid
flowchart TD
    A[Chamado de Implantação chega do Hub] --> B[Extrair dados<br/>codigoCliente<br/>codigoServico<br/>nomeCliente]

    B --> C{Existe entidade<br/>por Serviço?}
    C -->|Sim| D[Usar entidade de Serviço]
    D --> Z[Fim / Continua fluxo do ticket]

    C -->|Não| E{Existe entidade<br/>por Cliente?}

    E -->|Sim| F[Criar entidade de Serviço<br/>via API GLPI]
    F --> G[Parent = Entidade Cliente<br/>Nome = codigoCliente-codigoServico-nomeCliente]
    G --> Z

    E -->|Não| H[Criar entidade Cliente<br/>via API GLPI]
    H --> I[Parent = Contratos Ativos<br/>Nome = codigoCliente-nomeCliente]

    I --> J[Criar entidade de Serviço<br/>via API GLPI]
    J --> K[Parent = Entidade Cliente<br/>Nome = codigoCliente-codigoServico-nomeCliente]
    K --> Z
```






## Opção B — Criação simplificada (sem forçar hierarquia)

### Objetivo
Criar o mínimo possível e evitar duplicação de entidades.

### Fluxo (passo a passo)

1. **Tentar encontrar entidade por Serviço**
   - Busca: `{codigoCliente} - {codigoServico}*`
   - Se encontrou:
     - ✅ usar essa entidade e finalizar

2. **Se não encontrou por Serviço: tentar encontrar entidade por Cliente**
   - Busca: `{codigoCliente} -*`
   - Se encontrou:
     - ✅ usar essa entidade mãe
     - ❌ não cria entidade filha
     - Finaliza

3. **Se não encontrou nem por Serviço nem por Cliente**
   - Criar **uma entidade única (sem mãe)**:
     - Nome: `{codigoCliente} - {codigoServico} - {nomeCliente}`
     - Parent: raiz (ou padrão definido)
   - ✅ usar essa entidade e finalizar

### Resultado final (Opção B)
- Ticket pode ficar:
  - na entidade de serviço (se existir)
  - ou na entidade de cliente (se existir)
  - ou numa entidade única criada
- Não garante hierarquia “mãe → filha”

---

### Fluxo Opção B

```mermaid
flowchart TD
    A[Chamado de Implantação chega do Hub] --> B[Extrair dados<br/>codigoCliente<br/>codigoServico<br/>nomeCliente]

    B --> C{Existe entidade<br/>por Serviço?}
    C -->|Sim| D[Usar entidade de Serviço]
    D --> Z[Fim / Continua fluxo do ticket]

    C -->|Não| E{Existe entidade<br/>por Cliente?}

    E -->|Sim| F[Usar entidade de Cliente]
    F --> Z

    E -->|Não| G[Criar entidade Única<br/>via API GLPI]
    G --> H[Parent = Root<br/>Nome = codigoCliente-codigoServico-nomeCliente]
    H --> Z
```

## Opção C — Híbrida (Implantação cria; demais apenas resolvem)

### Objetivo
- Para **Implantação**: garantir estrutura correta criando entidades quando necessário (igual Opção A).
- Para **demais tipos de chamado**: **não criar entidades**, apenas resolver a melhor entidade existente; se não houver, usar fallback **Contratos Ativos**.

---

### Fluxo (passo a passo)

#### 1) Identificar tipo do chamado
- Se `tipo == Implantação` → executar **Fluxo A (criação hierárquica)**.
- Se `tipo != Implantação` → executar **Fluxo de Resolução sem criação**.

---

### Fluxo A (quando Implantação)
Segue exatamente a **Opção A**:
1. Buscar entidade por Serviço (`{codigoCliente} - {codigoServico}%`)
2. Se não achar, buscar por Cliente (`{codigoCliente} -%`)
3. Se achar Cliente, criar Serviço abaixo do Cliente
4. Se não achar nenhum, criar Cliente (embaixo de Contratos Ativos) e depois criar Serviço abaixo do Cliente
5. Retornar sempre a **entidade de Serviço**

---

### Fluxo de Resolução (quando NÃO é Implantação)
1. Buscar entidade por Serviço (`{codigoCliente} - {codigoServico}%`)
   - Se achou: ✅ usar e finalizar
2. Se não achou, buscar entidade por Cliente (`{codigoCliente} -%`)
   - Se achou: ✅ usar e finalizar
3. Se não achou nenhum dos dois:
   - ✅ usar entidade **Contratos Ativos** (fallback)
   - ❌ não criar nada

---

### Resultado final (Opção C)
- **Implantação**: sempre aponta para entidade de **Serviço**, criando Cliente/Serviço quando faltar.
- **Demais chamados**: nunca criam entidades; ficam na melhor existente (Serviço → Cliente → Contratos Ativos).

---

### Diagrama de Fluxo — Opção C (Híbrida)

```mermaid
flowchart TD
    A[Chega chamado do Hub] --> B[Extrair dados<br/>codigoCliente<br/>codigoServico<br/>nomeCliente<br/>tipoChamado]

    B --> C{Tipo é<br/>Implantação?}

    %% ========== RAMO IMPLANTAÇÃO (OPÇÃO A) ==========
    C -->|Sim| IA{Existe entidade<br/>por Serviço?}
    IA -->|Sim| I1[Usar entidade de Serviço] --> Z[Fim / Continua fluxo do ticket]

    IA -->|Não| IB{Existe entidade<br/>por Cliente?}
    IB -->|Sim| I2[Criar entidade de Serviço<br/>via API GLPI<br/>Parent = Cliente] --> I3[Usar entidade criada] --> Z

    IB -->|Não| I4[Criar entidade Cliente<br/>via API GLPI<br/>Parent = Contratos Ativos] --> I5[Criar entidade de Serviço<br/>via API GLPI<br/>Parent = Cliente] --> I6[Usar entidade criada] --> Z

    %% ========== RAMO NÃO IMPLANTAÇÃO (RESOLVE ONLY) ==========
    C -->|Não| NA{Existe entidade<br/>por Serviço?}
    NA -->|Sim| N1[Usar entidade de Serviço] --> Z

    NA -->|Não| NB{Existe entidade<br/>por Cliente?}
    NB -->|Sim| N2[Usar entidade de Cliente] --> Z

    NB -->|Não| N3[Usar entidade fallback<br/>Contratos Ativos] --> Z
```