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

@@ -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.

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) |