clientflow_backend/RELEASE_NOTES_v4928_1_5_132_OPERATIONAL_COHERENCE.md

ClientFlow v4928.1.5.132 — Coerência operacional e precedência do Centro de Trabalho

Objetivo

Corrigir as incoerências identificadas pela auditoria forense entre:

• estado físico Odoo;
• fase persistida da oportunidade;
• revisão de processos reconstruídos;
• task pendente;
• ação apresentada no Centro de Trabalho;
• candidatos de reconciliação já ligados.

A atualização não altera valores comerciais, documentos, pagamentos nem associações de clientes fiscais.

Correções de código

Odoo assigned

• assigned passa a significar apenas stock/picking reservado.
• A fase segura é ORDER_PREPARATION enquanto não existir validação física.
• Só uma validação física explícita permite READY_TO_SHIP.
• Só um envio/tracking real permite SHIPMENT_CREATED.
• O sincronizador pode corrigir de forma controlada uma fase demasiado avançada quando não existe validação, tracking nem envio.
• Evidência physical_validation deixa de ser criada a partir de assigned.

Revisão de processos reconstruídos

• Novo estado persistido: required, validated ou waived.
• O título ou clientflow_record_mode deixam de ser suficientes para inventar um bloqueio.
• VALIDATE_PHYSICAL_ORDER passa a ser tratada como ação sensível.
• Uma revisão concluída não volta a abrir apenas porque o título continua histórico.
• Tasks ignoradas ou saltadas não contam como revisão concluída.

Precedência das ações

A primeira ação apresentada passa a respeitar:

1. associação explicitamente bloqueante;
2. revisão reconstruída explicitamente obrigatória;
3. task pendente executável;
4. decisão central seguinte.

A lista e o detalhe das Oportunidades usam a mesma política.

Reconciliação

• candidatos já ligados podem ser resolvidos por script com guards;
• exige exatamente uma ligação externa;
• exige NIF ou nome coerente por defeito;
• identidade desconhecida fica para revisão;
• S00323 não é resolvido automaticamente sem confirmação explícita.

Script de migração

scripts/apply_v132_operational_coherence.py

Características:

• dry-run por defeito;
• filtros independentes para oportunidades e candidatos;
• transação protegida;
• idempotente;
• relatório JSON e Markdown;
• não modifica valores, documentos, pagamentos ou clientes.

Opções principais:

--focus <nome/UUID>
--candidate-ref <S00...>
--skip-opportunities
--skip-candidates
--allow-unknown-identity
--apply

Casos atuais esperados

• NOLTIA: SHIPMENT_CREATED → ORDER_PREPARATION; revisão reconstruída antes da validação física.
• MAFIROL: SHIPMENT_CREATED → ORDER_PREPARATION; revisão reconstruída antes da validação física.
• DUNAS: READY_TO_SHIP → ORDER_PREPARATION; resolver S00318; revisão antes da validação física.
• RICARDO: persistir revisão como validada e manter SEND_INVOICE.
• ENVIENERGY: remover o falso override visual de associação e mostrar a task real.
• S00323: permanece para revisão até confirmação da oportunidade BBKW.

Validação

• py_compile: OK
• self-test do corretor: OK
• self-test do auditor forense: OK
• suite completa: 522 testes aprovados

A atualização não foi executada contra a base de dados de produção durante a preparação do pacote. Deve ser aplicada primeiro em dry-run no servidor.