snglpi/docs/regrasdenegocio.md

# Regras de Negocio Completas

## 1. Escopo funcional da integracao

1. A origem oficial de novos chamados e o ServiceNow (SN).
2. O GLPI recebe chamados criados no SN e passa a participar do atendimento.
3. A integracao cobre:
   - criacao/vinculo de chamados SN -> GLPI
   - sincronizacao de comentarios (SN <-> GLPI)
   - sincronizacao de tasks (SN -> GLPI via `work_notes`)
   - fechamento definitivo GLPI -> SN (status GLPI = 6)
4. Sincronizacao legada bidirecional de status existe, mas deve ficar desligada no modelo novo (por flag).

## 2. Governanca e responsabilidade entre sistemas

1. SN e a origem da demanda.
2. GLPI e o sistema tecnico de atendimento e encerramento final.
3. Banco intermediario (PostgreSQL) e a fonte de controle operacional da integracao.

## 3. Orquestracao do ciclo

1. O ciclo roda por `cron`.
2. Ordem de execucao:
   - `processErrorController`
   - `processTicketsController`
   - `processTicketLifecycleController` (motor de regras unico de status/fechamento/reabertura, se habilitado)
   - `processCommentsController`
3. Ha protecao para evitar execucao concorrente do mesmo ciclo no mesmo processo.
4. Nao ha mais dois controladores decidindo status do mesmo ticket — o fluxo legado
   (`processStatusController`) foi removido e sua logica util (nota SN->GLPI, fora de escopo) foi
   absorvida pelo motor unico.

## 4. Feature flags e comportamento

1. `ENABLE_GLPI_CLOSE_CRON`
   - `true`: executa o motor de regras de status/fechamento/reabertura (`processTicketLifecycleController`).
   - `false`: desliga o motor inteiro.
2. `ENABLE_GLPI_WEBHOOK`
   - reservado para rollout por evento (planejado), sem obrigatoriedade no fluxo atual.

## 5. Regras de coleta de tickets no ServiceNow

1. Busca incidentes e requisicoes por `assignment_group` e `sys_updated_on >= watermark`.
2. Watermark vem de `sync_control`.
3. Novo watermark usa maior `sys_updated_on` encontrado no ciclo.
4. Watermark salvo aplica margem de seguranca de 6 horas para tras.
5. Se nao houver tickets novos/atualizados, watermark nao e alterado.

## 6. Regras de persistencia local (`tickets_sn`)

1. UPSERT por `ticket_number`.
2. `sys_id` e unico.
3. Campos de incidente e requisicao tem mapeamento diferente.
4. Para requisicao, pode haver enriquecimento por variaveis de catalogo:
   - justificativa
   - telefone
5. `updated_at` e atualizado automaticamente (trigger no banco).

## 7. Regras de criacao de estado de sincronizacao (`ticket_sync`)

1. Novo ticket entra com `sn_ticket_id` vinculado.
2. Se status SN vier final (`Encerrado` ou `Encerrado - Omitido`):
   - `sn_sync_status = closed`
   - `glpi_sync_status = ignored`
3. Se status SN vier aberto:
   - `sn_sync_status = collected`
   - `glpi_sync_status = pending_check`
4. `source_last` existe no schema e continua sendo gravado como rastro de auditoria, mas nao e mais lido em nenhum lugar do codigo para decidir status.

## 8. Regras de criacao/vinculo no GLPI

1. Apenas tickets com `glpi_sync_status = pending_check` entram na criacao/vinculo.
2. Se `glpi_ticket_id` ja existir no banco intermediario:
   - manter `synced/synced`
3. Se nao houver `glpi_ticket_id` local:
   - procurar ticket no GLPI por numero SN no titulo/conteudo
4. Se encontrar ticket no GLPI:
   - vincular `glpi_ticket_id`
   - se status GLPI=6, marcar `ignored/closed` e nao monitorar
   - caso contrario, marcar `synced/synced`
5. Se nao encontrar:
   - criar ticket no GLPI
   - vincular e marcar `synced/synced`
6. Erro de criacao:
   - marcar estado de erro para reprocessamento.

## 9. Regras de formatacao ao criar ticket no GLPI

1. Titulo segue padrao: tipo + entidade + short_description.
2. Entidade vem de `location_mapping`; fallback para entidade padrao.
3. Descricao e montada em HTML com dados de solicitante.
4. Requisicao sem justificativa/descricao pode usar valores default configurados.
5. Prioridade, categoria e SLA usam mapeamentos predefinidos.

## 10. Regra do campo "Ticket Externo" no SN

1. Ao criar/vincular ticket no GLPI, escrever ID GLPI no SN.
2. Campo usado e configuravel por `SERVICENOW_EXTERNAL_TICKET_FIELD` (default `u_external_ticket`).
3. Se a escrita falhar, nao recriar ticket no GLPI.
4. Falha gera pendencia de retry idempotente em `ticket_updates` (`update_type=external_link`).
5. Retry processa pendencias com `destiny_id IS NULL`.
6. Ao sucesso, `destiny_id` da pendencia vira `done`.

## 11. Regras de sincronizacao de comentarios SN -> GLPI

1. Busca journal entries `comments` e `work_notes` do SN.
2. Ordena cronologicamente antes de enviar.
3. Idempotencia por `ticket_updates.source_id` (sys_id do journal).
4. `comments` viram followup no GLPI.
5. `work_notes` viram task no GLPI.
6. Conteudo enviado para GLPI e formatado com card visual e autor.
7. Em falha de envio, registra estado de erro para novo ciclo.

## 12. Regras de sincronizacao de comentarios GLPI -> SN

1. Busca followups do GLPI ignorando usuario padrao tecnico da integracao.
2. Sanitiza HTML, metadados e imagens.
3. Evita duplicidade com verificacao local e remota.
4. Atualiza mapeamento origem/destino em `ticket_updates.destiny_id`.
5. Ao final, evita deixar ticket preso em estado transitorio de comentario.

## 13. Regras de filtro de usuario padrao no SN (ambiente de teste)

1. `SERVICENOW_DEFAULT_USER` define usuario da integracao.
2. `SERVICENOW_IGNORE_DEFAULT_USER_JOURNAL`:
   - `true` (padrao): ignora journals desse usuario para evitar loop.
   - `false`: nao ignora (util para dev com usuario unico).

## 14. Regras de fechamento e resolucao

1. Fechamento definitivo GLPI `status=6` e refletido no SN via `processTicketLifecycleController`.
2. Ao detectar GLPI=6:
   - enviar comentario no SN:
     - "Chamado encerrado definitivamente. Reabertura deste chamado nao sera atendida. Caso necessario, abra um novo chamado."
   - nao alterar status do chamado no SN
   - marcar `ticket_sync` como `closed/closed` para retirar do monitoramento
3. Aviso de encerramento definitivo no SN e idempotente por `source_id` em `ticket_updates`.
4. Quando o SN resolve/encerra por conta propria e o GLPI ainda nao chegou em 5/6: nota idempotente
   no GLPI + aviso no SN (Sothis nao vai mais atender) + transferencia pra fila CAOA — ver
   `docs/fluxo.md` secao 4.3. Nao depende de `source_last` nem de nenhuma flag de sincronizacao
   legada (removida).

## 15. Regras de fora do escopo (Sothis)

1. Quando solucao no GLPI usa `solutiontypes_id = GLPI_OOS_SOLUTION_TYPE_ID`:
   - envia justificativa ao SN em nota
   - nao segue fluxo normal de atendimento
   - estado final esperado no intermediario:
     - `glpi_sync_status = closed`
     - `sn_sync_status = ignored`
2. Chamado sai do monitoramento automatico.

## 16. Regras de estados monitorados vs terminais

### 16.1 Monitorados

1. `pending_check`
2. `synced`
3. `solved`
4. `error` e variantes de erro para reprocesso

### 16.2 Terminais

1. `closed`
2. `ignored`
3. `error_permanent` — ticket excedeu `MAX_ERROR_RETRIES` tentativas automaticas de reprocessamento
   e exige intervencao manual.

Regra geral: `closed`, `ignored` e `error_permanent` nao participam das rotinas normais de
sincronizacao.

## 17. Regra de reabertura

1. Reabertura automatica permitida apenas quando GLPI estiver em `5` (solved).
2. Se GLPI estiver em `6` (fechado definitivo), reabertura automatica nao e permitida.

## 18. Regras de idempotencia e rastreabilidade

1. `ticket_updates.source_id` e unico.
2. Toda sincronizacao relevante registra origem e destino quando possivel.
3. `ticket_sync.last_sn_sync` e `last_glpi_sync` registram ultima interacao por sistema.

## 19. Regras de erro e reprocessamento

1. Inicio de ciclo executa reset de estados de erro processaveis.
2. Erro em etapa nao deve causar duplicidade de criacao.
3. Tickets em erro voltam para fila valida de processamento conforme tipo do erro.

## 20. Regras de monitoramento operacional

1. Logs devem permitir rastrear:
   - criacao de ticket
   - sincronizacao de comentario/task
   - fechamento definitivo
   - falhas e retries
2. Rollout deve ser faseado por flag e com possibilidade de rollback.

## 21. Regras de schema (situacao atual)

1. Nao remover colunas legadas neste momento.
2. Nao criar tabela nova para eventos nesta fase.
3. Reaproveitar `ticket_updates` para pendencias e idempotencia.

## 22. Criterios de sucesso de negocio

1. Ticket fechado definitivamente no GLPI nao permanece aberto no SN.
2. Comentarios e tasks nao duplicam.
3. Tickets fora do escopo saem de monitoramento com estado final correto.
4. Integracao nao entra em loop por status intermediario.

## 23. Regras de mandante (espelhamento de status intermediario)

1. Existe um sistema "mandante" configuravel via env `MANDANTE` (`GLPI`, `SNOW` ou vazio) cujo
   status intermediario (`Aguardando Atendimento`/`Em Atendimento`/`Em Espera` no SN, GLPI
   `1`/`2`/`3`/`4`) e espelhado automaticamente no outro sistema.
2. Nunca se aplica aos status finais (GLPI `5`/`6`, fora de escopo) - essas continuam sendo as
   regras fixas 10-15, sempre ativas independente do mandante.
3. `MANDANTE` vazio, ausente ou com valor invalido mantem o comportamento padrao: nenhum
   espelhamento de status intermediario (equivalente ao que a regra de contencao ja fazia antes do
   mandante existir).
4. O mandante e unidirecional: so escreve no sistema seguidor, nunca le o status do seguidor para
   decidir algo - evita loop de espelhamento entre os dois sistemas.
5. So escreve quando o valor espelhado realmente difere do atual, para nao gerar chamada de API
   desnecessaria a cada ciclo.