# 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:

```text
--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.