From 2437864133108a844d02a50d2bbfc0bc95247426 Mon Sep 17 00:00:00 2001 From: Rafael Lopes Date: Wed, 15 Jul 2026 13:31:07 -0300 Subject: [PATCH] DOCS: Manual do usuario + documentacao de onde fica o .env.production e rollback Cria docs/manualusuario.md: guia pratico "se eu fizer X no SN/GLPI, acontece Y", pra quem usa os sistemas no dia a dia sem precisar entender a implementacao. README ganha duas secoes na parte de Producao: onde o .env.production fica e por que (agora materializado a partir do secret ENV_PRODUCTION do Gitea, nao mais um arquivo mantido a mao na VM), e o passo a passo de rollback manual usando o backup .previous que o deploy passa a manter. --- README.md | 33 +++++++++++++- docs/manualusuario.md | 103 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 135 insertions(+), 1 deletion(-) create mode 100644 docs/manualusuario.md diff --git a/README.md b/README.md index 72b08d1..cf607fb 100644 --- a/README.md +++ b/README.md @@ -27,7 +27,8 @@ Executado pelo `main()`: 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. Plano e checklist de rollout: [docs/checklist.md](docs/checklist.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 @@ -99,6 +100,36 @@ 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. diff --git a/docs/manualusuario.md b/docs/manualusuario.md new file mode 100644 index 0000000..4e10137 --- /dev/null +++ b/docs/manualusuario.md @@ -0,0 +1,103 @@ +# Manual do Usuario - Integracao ServiceNow <-> GLPI + +Este documento e um guia pratico pra quem usa o ServiceNow (SN) ou o GLPI no dia a dia e quer saber +"se eu fizer X, o que acontece do outro lado?". Nao e um documento tecnico - pra detalhes de +implementacao, ver `docs/regrasdenegocio.md` e `docs/fluxo.md`. + +## 1. Abertura de chamado + +- Se um chamado novo e aberto no ServiceNow, atribuido ao grupo Sothis, entao um chamado + correspondente e criado automaticamente no GLPI. +- O campo "Ticket Externo" no SN e preenchido com o numero do chamado GLPI logo apos a criacao. + +## 2. Comentarios e tarefas + +- Se voce escreve um comentario no SN, entao ele aparece como um followup no GLPI. +- Se o time tecnico escreve um followup/comentario no GLPI, entao ele aparece como comentario no SN + (visivel pro solicitante). +- Se uma work note e registrada no SN, entao ela vira uma tarefa (task) no GLPI. +- Se uma task e criada no GLPI, entao ela **nao** aparece no SN - tasks do GLPI sao uso interno do + time tecnico, nao chegam ao solicitante. +- Comentarios e tarefas nunca duplicam, mesmo se o sistema processar o mesmo chamado varias vezes + seguidas. +- Hoje a integracao so sincroniza texto - imagens e anexos nao atravessam de um sistema pro outro. + +## 3. Quando o GLPI resolve o chamado + +- Se o time tecnico marca o chamado como "Solucionado" no GLPI, entao o chamado e resolvido + automaticamente no ServiceNow tambem, usando a nota de solucao do GLPI como base. +- Se o chamado no SN estava em "Em Espera" ou "Aguardando Atendimento" nesse momento, entao ele e + movido primeiro pra "Em Atendimento" e so depois resolvido (o SN exige isso pra permitir a + resolucao). + +## 4. Quando o GLPI encerra definitivamente o chamado + +- Se o time tecnico marca o chamado como "Fechado" no GLPI, entao um aviso e publicado + automaticamente no SN: "Chamado encerrado definitivamente. Reabertura deste chamado nao sera + atendida. Caso necessario, abra um novo chamado." +- O status do chamado no SN **nao** e alterado por esse evento - so o comentario e adicionado. +- O chamado sai do monitoramento automatico da integracao - nenhuma acao futura acontece nele. + +## 5. Reabertura de chamado + +- Se o solicitante reabre o chamado no SN e o chamado no GLPI estava "Solucionado", entao o GLPI + tambem volta pra "Em Atendimento" automaticamente. +- Se o chamado no GLPI ja estava "Fechado" (encerramento definitivo), entao a reabertura **nao** e + refletida no GLPI - nesse caso e preciso abrir um chamado novo. + +## 6. Quando o SN resolve ou encerra por conta propria (antes do GLPI) + +Se o solicitante ou alguem no SN resolve/encerra o chamado, mas o GLPI ainda nao tinha chegado em +"Solucionado"/"Fechado", o GLPI **nao** fecha automaticamente. Em vez disso: + +1. Uma nota e adicionada no GLPI avisando que o chamado foi resolvido/encerrado pelo SN (com o nome + de quem fez isso). +2. Um aviso e publicado de volta no SN dizendo que a Sothis nao vai mais atender esse chamado. +3. O chamado e transferido pra fila de TI da CAOA no SN. +4. O chamado sai do monitoramento automatico da integracao. + +## 7. Chamados fora do escopo da Sothis + +- Se o time tecnico usa o tipo de solucao "fora de escopo" ao solucionar no GLPI, entao: + 1. A justificativa e enviada como nota pro SN. + 2. O grupo responsavel no GLPI e removido do chamado. + 3. O chamado e transferido pra fila de TI da CAOA no SN. + 4. O chamado sai do monitoramento automatico - isso nao e um encerramento normal. + +## 8. Mandante - espelhamento de status intermediario (recurso opcional, hoje desligado) + +- Por padrao, mudancas de status "no meio do caminho" (Aguardando Atendimento / Em Atendimento / Em + Espera) em qualquer um dos dois sistemas **nao** sao refletidas automaticamente no outro - cada + time so ve as mudancas que ele mesmo fizer no proprio sistema. +- Existe uma configuracao (`MANDANTE`) que pode ligar esse espelhamento numa direcao so - fazendo um + sistema "mandar" nesses status intermediarios sobre o outro. **Hoje esse recurso esta desligado em + producao.** +- Esse recurso, mesmo quando ligado, nunca muda o comportamento dos itens 3 a 7 acima (resolucao, + fechamento definitivo, fora de escopo, reabertura) - essas regras sao sempre fixas. + +## 9. O que nao acontece automaticamente hoje + +- Imagens e anexos nao sao sincronizados entre os sistemas (nem SN -> GLPI, nem GLPI -> SN), so + texto. +- Um chamado com erro de sincronizacao e reprocessado automaticamente, mas so ate um numero maximo + de tentativas. Depois disso ele fica marcado pra intervencao manual - vale avisar o time tecnico + se um chamado parecer "parado". +- Mudanca de status intermediario (item 8) so e refletida entre os sistemas se o recurso Mandante + estiver ligado - por padrao, nao esta. + +## 10. Resumo rapido + +| Se voce... | O que acontece | +| --- | --- | +| Abre um chamado no SN pro grupo Sothis | Cria automaticamente no GLPI | +| Comenta no SN | Vira followup no GLPI | +| Comenta/responde no GLPI | Vira comentario no SN | +| Cria work note no SN | Vira task no GLPI | +| Cria task no GLPI | Fica so no GLPI, nao vai pro SN | +| Marca "Solucionado" no GLPI | Resolve automaticamente no SN | +| Marca "Fechado" no GLPI | Publica aviso definitivo no SN, sem reabertura | +| Reabre no SN (GLPI estava Solucionado) | GLPI volta pra Em Atendimento | +| Reabre no SN (GLPI estava Fechado) | Nao reflete - precisa abrir chamado novo | +| Resolve/encerra no SN antes do GLPI | GLPI recebe nota, SN recebe aviso de que a Sothis nao atende mais e vai pra fila CAOA | +| Marca solucao "fora de escopo" no GLPI | Chamado sai do fluxo Sothis, vai pra fila CAOA no SN | +| Muda status intermediario em qualquer sistema | Nao reflete no outro, a menos que o Mandante esteja ligado (hoje desligado) |