# POP: Processar Anexos do ServiceNow

## Objetivo
Processar automaticamente e-mails recebidos de `ricardo.amorim@wkve.com.br`, baixando os arquivos `.xlsx` anexos e atualizando o banco de dados do sistema SGD (`sgd_wkve_build`).

## Entradas
- **E-mail Trigger:** `@popcontrol.com.br`
- **Remetente:** `ricardo.amorim@wkve.com.br`
- **Anexo:** Arquivo no formato `.xlsx`.

## Ferramentas e Scripts Utilizados
- **Orquestração:** Workflow do n8n (Captura de e-mail e salvamento no `/tmp/`).
- **Execução:** `/var/www/html/robot/execution/process_attachment_sgd.py`

## Passo a Passo da Execução (n8n)
1. **EmailReadImap Node:** Conecta-se à caixa `@popcontrol.com.br` via IMAP e ouve novos e-mails.
2. **Filtro / Condição:** Verifica se o remetente é `ricardo.amorim@wkve.com.br` e possui anexos `.xlsx`.
3. **Write Binary File Node:** Salva o anexo na pasta `/tmp`.
4. **Execute Command Node:** Roda o script Python determinístico passando o arquivo como argumento.
   - *Comando:* `/var/www/html/robot/.venv/bin/python3 /var/www/html/robot/execution/process_attachment_sgd.py "/tmp/<nome-do-arquivo>.xlsx"`

## Saídas
- O banco de dados MySQL do sistema SGD é atualizado (UPSERT na tabela `tarefas`).
- As tabelas `status` e `levantamento` são sincronizadas automaticamente pós-importação (sincronização do SGD).
- Campos `info_adicionais` nulos na tabela `tarefas` são corrigidos a partir do `serv_detalhado`.
- Arquivo `/tmp/<arquivo>.xlsx` deletado ao final.

## Edge Cases (Casos Extremos)
- **Arquivo Corrompido / Formato Inválido:** O script Python retornará erro, mantendo o arquivo na pasta para auditoria. O n8n deverá alertar.
- **Tarefa já existente com os mesmos dados:** O script ignora a atualização (evitando falsos logs).
- **Banco de Dados Inacessível:** O script Python falha com código não-zero, n8n pode emitir notificação de falha.

## Aprendizados (Learnings)
- *2026-05-25:* O script Python de execução não valida quem é o remetente do e-mail. Toda a filtragem de remetente (ex: `FROM "ricardo.amorim@wkve.com.br"`) é feita **exclusivamente no n8n**, usando o parâmetro `customEmailConfig` dentro do nó de EmailReadImap.
- *2026-05-25:* O domínio `@popcontrol.com.br` não suporta IMAP nativamente na configuração atual. Para fins de homologação/testes, o fluxo no n8n foi alterado para ouvir a caixa `@popcontrol.com.br`. Nessas situações de teste, é obrigatório alterar também o remetente (Sender) no nó do n8n para a conta que enviará os testes.
- *2026-05-26:* Em nós do n8n (como Write Binary File), caminhos relativos usando o til (`~`) não são expandidos pelo Node.js, resultando no erro `ENOENT: no such file or directory, realpath '~/.n8n'`. É necessário usar caminhos absolutos como `/tmp/`. Além disso, para permitir que o n8n escreva em pastas locais, os caminhos devem estar liberados na variável de ambiente `N8N_RESTRICT_FILE_ACCESS_TO` no PM2. Whitelist atualizada com `/tmp/`.
- *2026-05-26:* Portada a lógica de sincronização em três etapas (status, levantamento e correção de info_adicionais) diretamente para o script Python `process_attachment_sgd.py`, eliminando a necessidade de rodar a atualização manual pelo painel PHP pós-importação.