Release v4928.1.4.2 stable

docs/CLIENTFLOW_V4927_1_HOTFIX.md

@@ -0,0 +1,21 @@
+# ClientFlow v4927.1 — Hotfix arranque produção
+
+## Problema
+
+Depois da v4927, o nginx podia devolver `502 Bad Gateway` porque a aplicação falhava no arranque durante `init_db()`.
+
+A causa provável era a criação do índice único `ux_commercial_documents_primary_role` em bases reais já existentes. Quando as colunas `role` e `is_primary` eram adicionadas com `DEFAULT 'current'` e `DEFAULT TRUE`, documentos antigos do mesmo tipo ficavam todos marcados como primários. Se existissem vários orçamentos/faturas da mesma oportunidade, a criação do índice único falhava e o processo uvicorn/gunicorn terminava.
+
+## Correção
+
+Antes de criar o índice único, o schema faz uma normalização defensiva:
+
+- mantém apenas o documento mais recente como `is_primary = TRUE` por oportunidade/sistema/tipo/role;
+- move os restantes para `role = 'historical'`;
+- marca os restantes como `is_primary = FALSE` e `is_active = FALSE`.
+
+## Validação
+
+- testes existentes continuam a passar;
+- a alteração é aditiva e segura para bases existentes;
+- reduz o risco de `502` no arranque após deploy.