Import ClientFlow production v4928.1.5.132.4

RELEASE_NOTES_STABILIZATION_20260708.md

@@ -0,0 +1,68 @@
+# ClientFlow Backend — versão de estabilização 2026-07-08
+
+## Objetivo
+Consolidar a última versão do backend antes de novas funcionalidades, corrigindo falhas P0/P1 encontradas na review: suíte de testes não-verde, bug em `list_tasks()`, divergências no workflow de oportunidades, linking ambíguo, `.env.example` ausente e problemas de coleção do pytest.
+
+## Correções principais
+
+### Testes e packaging
+- Adicionado `pytest.ini` com `testpaths = tests`, `pythonpath = .` e `--import-mode=importlib`.
+- Removido o teste duplicado de raiz `test_v4928_1_5_72_opportunity_consistency_static.py` para evitar `import file mismatch`.
+- Adicionado `.env.example` com flags obrigatórias e opcionais documentadas.
+- Consolidado teste estático contraditório de `workflow_guard`: a implementação mantém compatibilidade com schema sem coluna `completed_at` e continua a aceitar `completed_at` quando a evidência vem em payload/dict.
+- Consolidado teste de materialização `PREPARE_ORDER` com a regra de arquitetura que remove esse código da triagem LLM em `action_catalog.py`.
+
+### `task_service.py`
+- Corrigido bug P0 em `list_tasks()`: `customer_column` agora é calculado antes do SQL através de `opportunity_customer_column()` e tem fallback seguro para `local_customer_id`.
+- Removida duplicação acidental de coluna em `get_task_detail()`.
+
+### Workflow de oportunidades
+- `WAIT_PRODUCTION` volta a mostrar a label operacional “Aguardar produção”, mantendo alias/compatibilidade UI para “Aguardar WH/OUT”.
+- Fluxo `after_delivery` com envio já criado e pagamento por confirmar passa a sugerir `FOLLOW_UP_PAYMENT`, em vez de voltar para `PREPARE_ORDER`.
+- Mantida prioridade de fecho/entrega sobre estados de produção quando WH/OUT/picking já está concluído.
+- Evidência de fatura enviada continua a considerar payload do documento e tasks `SEND_INVOICE` concluídas.
+
+### UI/admin
+- A página de oportunidades filtra tasks de pagamento/follow-up obsoletas quando o pagamento já está confirmado.
+- O resumo operacional passa a usar `display_next_action_code` para evitar fallback para `last_action_code` antigo.
+- Adicionada mensagem explícita quando o Jasmin existe mas não tem novos campos fiscais para importar.
+- `admin_dashboard.py` ficou abaixo do limite legado de 1800 linhas sem alterar rotas principais.
+
+### Segurança funcional / linking
+- Ambiguidade de oportunidades por contacto Chatwoot passa a usar razão explícita `multiple_recent_open_opportunities_for_chatwoot_contact`.
+- `action_catalog.py` mantém `PREPARE_ORDER` fora do catálogo de triagem LLM; o código interno é tratado dinamicamente para compatibilidade operacional.
+
+### Outros ajustes
+- Corrigidos warnings de `compileall` por escapes inválidos em SQL LIKE/ESCAPE.
+- Adicionado marcador de identificação ao script `probe_jasmin_print_layout_catalog.py`.
+
+## Validação local
+
+Com variáveis de teste:
+
+```bash
+OPENROUTER_API_KEY=test \
+DATABASE_URL=postgresql+psycopg://u:p@localhost:5432/db \
+CLIENTFLOW_ADMIN_TOKEN=test \
+PYTHONPATH=. \
+pytest -q
+```
+
+Resultado:
+
+```text
+463 passed in 1.12s
+```
+
+Compilação:
+
+```bash
+python -m compileall -q app scripts tests
+```
+
+Resultado: sem erros e sem warnings reportados.
+
+## Limitações
+- Não foram executadas integrações reais com Postgres, Jasmin, Odoo, Packlink, Chatwoot ou OpenAI/OpenRouter.
+- A validação foi feita por testes locais/estáticos/unitários e compilação Python.
+- Antes de produção, correr migrações e smoke tests contra uma base staging.