snglpi/README.md

# Sistema de Integracao ServiceNow <-> GLPI

Middleware Node.js para integrar chamados entre ServiceNow e GLPI, usando PostgreSQL como banco intermediario e acesso ao banco do GLPI.

## Estado atual

1. Coleta de tickets SN por watermark.
2. Criacao/vinculo de tickets no GLPI (grava `external_id` no GLPI com o numero do ticket SN).
3. Sincronizacao de comentarios e tasks em duas direcoes.
4. Preenchimento do campo "Ticket Externo" no SN com o ID GLPI.
5. Motor de regras unico (`processTicketLifecycleController`) para status/fechamento/reabertura:
   `status=5` (resolver SN), `status=6` (encerrar definitivamente no SN), nota no GLPI quando o SN
   resolve/encerra por conta propria (com aviso e troca de fila no SN), reabertura automatica e
   regra de fora de escopo.

## Fluxo do ciclo

Executado pelo `main()`:

1. `processErrorController`
2. `processTicketsController`
3. `processTicketLifecycleController` (quando `ENABLE_GLPI_CLOSE_CRON=true`)
4. `processCommentsController`

## Documentacao detalhada

1. Fluxo tecnico: [docs/fluxo.md](docs/fluxo.md)
2. Regras de negocio completas: [docs/regrasdenegocio.md](docs/regrasdenegocio.md)
3. Casos de uso: [docs/casosdeuso.md](docs/casosdeuso.md)
4. Manual do usuario (se eu fizer X, acontece Y): [docs/manualusuario.md](docs/manualusuario.md)
5. Plano e checklist de rollout: [docs/checklist.md](docs/checklist.md)

## Variaveis de ambiente importantes

### Feature flags

1. `ENABLE_GLPI_CLOSE_CRON`
   - `true`: liga o motor de regras de status/fechamento/reabertura (`processTicketLifecycleController`)
   - `false`: desliga o motor inteiro

### ServiceNow

1. `SERVICENOW_TABLE_INCIDENT_URL`
2. `SERVICENOW_TABLE_REQUEST_URL`
3. `SERVICENOW_TABLE_JOURNAL_URL`
4. `SERVICENOW_SC_ITEM_OPTION_URL`
5. `SERVICENOW_DEFAULT_USER`
6. `SERVICENOW_IGNORE_DEFAULT_USER_JOURNAL`
7. `SERVICENOW_EXTERNAL_TICKET_FIELD` (default: `u_external_ticket`)

### GLPI e banco intermediario

1. `GLPI_DB_*`
2. `SNGLPI_DB_*`
3. `GLPI_OOS_SOLUTION_TYPE_ID`

## Desenvolvimento

1. Instalar dependencias:
```bash
npm install
```
2. Criar env:
```bash
copy .env.example .env.development
```
3. Executar:
```bash
npm run dev
```

## Producao

### Deploy manual na VM

```bash
git pull origin master
npm ci --omit=dev
pm2 start ecosystem.config.js --env production
pm2 save
```

Se o processo ja estiver rodando:

```bash
pm2 restart sn-glpi-sync-cron --update-env
```

### Deploy via Gitea Actions

O workflow `.gitea/workflows/deploy-production.yml` roda no runner com rotulo `vm-prod`.

1. Configure a variavel do repositorio `PROD_DEPLOY_PATH` com o caminho da aplicacao na VM de producao. Se nao configurar, o workflow usa `/opt/sn-glpi-sync-new`.
2. Garanta que o arquivo `.env.production` exista nesse caminho na VM e contenha `SERVICENOW_CAOA_TI_GROUP_ID` preenchido.
3. Faça push na branch `master` ou execute o workflow manualmente em Actions.
4. Acompanhe pelo Gitea Actions ou na VM:

```bash
pm2 list
pm2 logs sn-glpi-sync-cron
```

### Onde fica o `.env.production`

O `.env.production` nunca e versionado no git — o rsync do deploy exclui `.env*` de proposito,
exatamente para nunca sobrescrever esse arquivo com o codigo. O proprio workflow ja materializa
esse arquivo a cada deploy a partir do secret `ENV_PRODUCTION` (Settings > Actions > Secrets no
Gitea), entao a fonte da verdade das credenciais de producao e esse secret, nao um arquivo mantido
a mao na VM. Detalhes:

1. Ele existe dentro da propria pasta de deploy (`$PROD_DEPLOY_PATH/.env.production`, ex.:
   `/opt/sn-glpi-sync-new/.env.production`) — nao na raiz de nenhum usuario (nem `dev`, nem
   `root`). `cron.js`/`src/app.js` resolvem o caminho do env relativo a propria raiz do repo, entao
   e ali que ele precisa estar.
2. O workflow ja aplica `chmod 600` nele apos escrever (dono = usuario que roda o PM2), evitando
   outro usuario local da VM lendo credencial de banco/API em texto puro.
3. Pra atualizar uma credencial/config de producao, edite o secret `ENV_PRODUCTION` no Gitea e rode
   o deploy de novo (push em `master` ou `workflow_dispatch`) — nao precisa mais SSH na VM pra
   editar arquivo a mao. Como o secret fica guardado no Gitea (fora da VM), tambem resolve o risco
   de perder a unica copia das credenciais se o disco da VM falhar.

### Rollback manual

O deploy guarda a versao anterior em `$PROD_DEPLOY_PATH.previous` antes de sincronizar o codigo
novo. Se o deploy subir uma versao com problema (o `node --check` so pega erro de sintaxe, nao de
logica), o rollback e:

```bash
rsync -a --delete "$PROD_DEPLOY_PATH.previous"/ "$PROD_DEPLOY_PATH"/
cd "$PROD_DEPLOY_PATH" && pm2 restart ecosystem.config.js --update-env
```

## Observacoes

1. O projeto ainda nao tem suite automatizada robusta.
2. O rollout recomendado e por fases com feature flags.
3. Nao remover schema legado antes de estabilizar o fluxo novo.
4. Consulte `docs/checklist.md` antes de cada deploy para validar pre e pos-subida.