Release v4928.1.4.2 stable

docs/CLIENTFLOW_V4928_DECISIONAL_UI.md

@@ -0,0 +1,101 @@
+# ClientFlow v4.9.28 — Reconciliação decisional e UI operacional
+
+Esta versão constrói sobre a baseline estável v4.9.27.2 sem reintroduzir constraints únicas agressivas no arranque.
+
+## Objetivo
+
+Transformar a reconciliação e a oportunidade numa experiência orientada à decisão:
+
+- oportunidade = processo de compra comercial;
+- documento Jasmin/Odoo = evidência/documento oficial ligado ao processo;
+- task = próxima ação humana;
+- reconciliação = decisão explícita sobre cada evidência.
+
+## Alterações principais
+
+### 1. Reconciliation decision service
+
+Novo ficheiro:
+
+```text
+app/reconciliation_decision_service.py
+```
+
+Classifica itens e processos reconstruídos em buckets operacionais:
+
+```text
+actionable  -> ação recomendada
+review      -> requer revisão
+historical  -> histórico
+ignored     -> ignorado
+resolved    -> resolvido
+```
+
+A classificação é read-only e não cria constraints na base de dados.
+
+### 2. Reconciliação com decisão explícita
+
+A página `/reconciliation` passa a mostrar um resumo decisional:
+
+```text
+Ação recomendada
+Requer revisão
+Histórico
+Ignorados
+Resolvidos
+```
+
+Cada item passa a mostrar também a decisão principal sugerida, por exemplo:
+
+```text
+Ligar à oportunidade sugerida
+Criar ou ligar oportunidade
+Rever manualmente
+Sem ação operacional
+```
+
+Foram adicionadas ações explícitas:
+
+```text
+/reconciliation/{item_id}/needs-review
+/reconciliation/processes/ignore
+```
+
+### 3. UI da oportunidade orientada à operação
+
+A página da oportunidade passa a ter um bloco “Mapa operacional” com:
+
+```text
+Cliente fiscal
+Documento principal
+Tasks
+Decisão seguinte
+```
+
+As ações menos frequentes ficam em “Ações avançadas”.
+
+### 4. Documentos Jasmin mais seguros
+
+Quando a oportunidade já tem documento Jasmin atual, a UI deixa de apresentar “Associar e importar” como ação equivalente. Passa a mostrar “Substituir atual”, evitando duplicados acidentais.
+
+O botão “Converter em fatura” só fica ativo se existir orçamento/pró-forma elegível.
+
+### 5. Tasks com contexto reforçado
+
+A task detail passa a repetir no painel de próxima ação os chips de fila, estado e prioridade para reforçar o contexto operacional.
+
+## Segurança de deploy
+
+Esta versão mantém a regra da v4.9.27.2:
+
+```text
+Não criar índice único forte no arranque sobre dados legados.
+```
+
+A consistência de “documento principal” é tratada pela aplicação e pela UI, não por constraint nova que possa bloquear o arranque.
+
+## Validação
+
+```text
+203 passed
+```