Import ClientFlow production v4928.1.5.132.4

RELEASE_NOTES_v4928_1_5_129_RECONCILIATION_COHERENCE.md

@@ -0,0 +1,103 @@
+# ClientFlow v4928.1.5.129 — coerência da Reconciliação e tasks operacionais
+
+## Objetivo
+
+Evitar que vendas Odoo já ligadas continuem na Reconciliação com ações obsoletas, impedir regressões da oportunidade e garantir que ações de expedição aparecem no Centro de Trabalho.
+
+## Alterações
+
+### Reconciliação Odoo
+
+- Antes de criar um candidato, o sincronizador procura uma ligação exata em `operation_links` por ID Odoo ou número da venda.
+- Uma ligação exata e única faz com que o candidato antigo seja resolvido como `linked`, sem alterar oportunidade, fase, valor ou documentos.
+- Mais de uma ligação exata gera `conflict`; nunca é resolvida automaticamente.
+- Correspondências por nome, cliente ou valor continuam a exigir decisão do operador.
+- A interface passa a indicar vendas já ligadas, candidatos obsoletos resolvidos e conflitos.
+
+### Proteção contra regressão
+
+Ao ligar nova evidência a uma oportunidade existente:
+
+- compara a fase sugerida com a fase atual;
+- preserva a fase e a ação atuais quando já estão no mesmo nível ou mais avançadas;
+- não cria `SEND_INVOICE` quando já existe fatura Jasmin ligada;
+- recalcula a próxima ação pelo motor central depois da transação.
+
+### Expedição
+
+- O motor central continua a usar `SHIP_ORDER` como decisão de domínio.
+- A task persistida é normalizada para `CREATE_SHIPMENT`.
+- Fila: `logistica`.
+- Texto do operador: `Enviar encomenda`.
+- A task não é concluída por mensagens Chatwoot e não depende de Packlink.
+
+### Correção dos candidatos atuais
+
+Novo script:
+
+```bash
+python scripts/apply_reconciliation_coherence_fixes.py
+```
+
+O script é dry-run por defeito. Só considera seguro um candidato Odoo que tenha exatamente uma ligação exata a uma oportunidade aberta.
+
+Aplicação direcionada:
+
+```bash
+python scripts/apply_reconciliation_coherence_fixes.py \
+  --sale S00324 \
+  --sale S00325 \
+  --sale S00326 \
+  --apply
+```
+
+O script:
+
+- resolve os candidatos como já ligados;
+- preserva fase, valor, documentos e `operation_links`;
+- materializa a próxima task calculada pelo motor central;
+- não altera BBKW/S00323 porque não existe ligação exata.
+
+### Auditoria
+
+Incluído o auditor read-only v128.1 em:
+
+```bash
+scripts/audit_reconciliation_coherence.py
+```
+
+Depois da correção:
+
+```bash
+python scripts/audit_reconciliation_coherence.py \
+  --days 3 \
+  --limit 500 \
+  --live odoo,jasmin \
+  --max-live 30
+```
+
+## Packlink
+
+A configuração por defeito continua:
+
+```env
+PACKLINK_ENABLED=false
+```
+
+`CREATE_SHIPMENT` representa trabalho logístico do operador e não ativa Packlink. Packlink só poderá ser usado quando a integração for reativada explicitamente.
+
+## Segurança
+
+- dry-run por defeito;
+- correspondência automática apenas por ID/número exato;
+- exatamente uma oportunidade aberta;
+- sem correção automática de diferenças de valor;
+- sem criação automática de oportunidade para BBKW;
+- sem regressão de fase;
+- criação de tasks idempotente.
+
+## Validação
+
+```text
+508 testes aprovados
+```