# Quickstart: Migração de E-mail (013)

**Público:** Técnicos Ligbox (ops_lead, technician)  
**Pré-requisito:** Conta destino já criada no Carbonio (wizard VM112 ou zmprov)

---

## Regra operacional

> **Nunca alterar MX/DNS até `migration_gate = ready_for_dns`.**  
> Sync inicial e deltas correm **com MX ainda no servidor antigo**.

---

## 1. Instalar ferramentas (uma vez por host worker)

```bash
cd /opt/ligbox-ops-platform
sudo ./scripts/install-migration-tools.sh
```

Conteúdo esperado:
- `/usr/bin/imapsync`
- `/usr/bin/readpst`
- `/opt/migration-tools/imap-upload/imap_upload.py`

---

## 2. Criar job no Desk

1. Login Desk → **Email Migration** → **Novo job**
2. Preencher:
   - Domínio: `cliente.com.br`
   - Tenant: VM112
   - Ticket: #123 (onboarding ou migração dedicado)
   - Servidor origem: label descritivo
3. Adicionar mailboxes:

| E-mail | Tipo origem | Host origem |
|--------|-------------|-------------|
| admin@cliente.com.br | imap | imap.hostantigo.com |
| vendas@cliente.com.br | pst | (upload ficheiro) |

---

## 3. Preflight

```bash
# API
curl -s -X POST "http://10.10.10.122:8080/api/v1/migration/jobs/1/preflight" \
  -H "Authorization: Bearer $TOKEN"
```

Ou botão **Preflight** na UI.

Verificar: credenciais OK, pastas listadas, destino acessível.

---

## 4. Sync inicial (SEM DNS)

**IMAP:**
```bash
curl -s -X POST "http://10.10.10.122:8080/api/v1/migration/jobs/1/sync" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"run_type":"initial"}'
```

**PST (após upload na UI):**
- Worker executa automaticamente: `readpst` → `imap-upload`
- Erros em **Quarentena** — rever antes do gate

Repetir **delta** a cada 6–24h até contagem estabilizar.

---

## 5. Verificação

```bash
curl -s "http://10.10.10.122:8080/api/v1/migration/jobs/1/verify" \
  -H "Authorization: Bearer $TOKEN" | python3 -m json.tool
```

Critérios:
- Ratio mensagens ≥ **99%**
- Inbox e Sent = **100%**
- PST: 0 erros críticos em quarentena

---

## 6. Aprovar gate (ops_lead)

```bash
curl -s -X POST "http://10.10.10.122:8080/api/v1/migration/jobs/1/approve-gate" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"comment":"Cliente validou amostra 10/06"}'
```

Estado passa a `ready_for_dns`.

---

## 7. Cutover DNS (só agora)

1. Baixar TTL MX (se possível, 24h antes)
2. Alterar MX no Cloudflare / pfSense
3. Sync **final** no Desk
4. Validar recepção no Carbonio
5. Fechar ticket + fase `closed`

---

## Comandos manuais (debug)

### imapsync directo

```bash
imapsync \
  --host1 imap.origem.com --user1 user@dominio.com --password1 '***' \
  --host2 mail.destino.com --user2 user@dominio.com --password2 '***' \
  --ssl1 --ssl2 --automap --dry
```

### PST manual

```bash
mkdir -p /tmp/mbox
readpst -o /tmp/mbox -r arquivo.pst
python3 /opt/migration-tools/imap-upload/imap_upload.py \
  --ssl --host mail.destino.com --user user@dominio.com --password '***' \
  --error /tmp/errors.mbox -r /tmp/mbox
```

### TGZ Zimbra→Carbonio

```bash
su - zextras -c "zmmailbox -z -m user@dominio.com getRestURL '/?fmt=tgz'" > user.tgz
# transferir para destino
su - zextras -c "zmmailbox -z -m user@dominio.com postRestURL '/?fmt=tgz&resolve=skip' /path/user.tgz"
```

---

## Troubleshooting

| Sintoma | Acção |
|---------|-------|
| Gate blocked, ratio 95% | Correr delta; verificar pasta com erro no log imapsync |
| PST partial | Abrir quarentena ERR_MBOX; re-upload pasta falhada |
| O365 auth fail | Usar OAuth2 (oauth2_imap), não password |
| Duplicatas | imapsync usa Message-Id; não misturar upload manual + imapsync mesma pasta |
| DNS virado cedo | Sync final + contactar origem forwarding |

---

## Referências

- [spec.md](./spec.md)
- [research.md](./research.md) — ferramentas avaliadas
- imapsync FAQ: https://imapsync.lamiral.info/FAQ.d/FAQ.Folders_Mapping.txt