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
   • processGlpiClosureController (se habilitado)
   • processCommentsController
   • processStatusAndClosureController (somente legado, se habilitado)
3. Ha protecao para evitar execucao concorrente do mesmo ciclo no mesmo processo.

4. Feature flags e comportamento

1. ENABLE_STATUS_SYNC
   • true: executa sincronizacao legada de status bidirecional.
   • false: desliga fluxo legado de status.
2. ENABLE_GLPI_CLOSE_CRON
   • true: executa monitor de fechamento definitivo GLPI=6.
   • false: desliga monitor.
3. 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 legado, mas deve ser deprecado para decisao de status no modelo novo.

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

14.1 Fluxo novo (prioritario)

1. Fechamento definitivo GLPI status=6 e refletido no SN via monitor cron.
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.

14.2 Fluxo legado de status (quando habilitado)

1. Pode propagar estado entre SN e GLPI.
2. Usa regras de precedencia historicas com source_last.
3. Deve ser considerado transitorio e desligavel por flag.

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

Regra geral: closed e ignored 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.