Release v4928.1.4.2 stable

docs/CLIENTFLOW_V4927_2_HOTFIX.md

@@ -0,0 +1,34 @@
+# ClientFlow v4927.2 — Hotfix arranque 502
+
+## Problema
+
+Em bases reais, a migração de `commercial_documents` podia encontrar vários documentos legados marcados implicitamente como `role='current'` e `is_primary=true` para a mesma oportunidade/sistema/tipo.
+
+A versão v4927.1 tentava normalizar antes de criar o índice único, mas em produção continuou a existir duplicação suficiente para o PostgreSQL falhar em:
+
+```sql
+CREATE UNIQUE INDEX IF NOT EXISTS ux_commercial_documents_primary_role
+```
+
+Quando este erro acontece dentro de `init_db()`, a aplicação FastAPI/uvicorn não arranca e o nginx devolve `502 Bad Gateway`.
+
+## Correção
+
+A v4927.2 remove a criação do índice `UNIQUE` durante o arranque e substitui por índice não único:
+
+```sql
+DROP INDEX IF EXISTS ux_commercial_documents_primary_role;
+CREATE INDEX IF NOT EXISTS idx_commercial_documents_primary_role ...;
+```
+
+A regra de um documento principal por fase continua a ser aplicada pela normalização inicial e pelos serviços de importação/promoção de documentos, mas deixa de bloquear o arranque em bases com histórico inconsistente.
+
+## Validação
+
+```text
+203 passed
+```
+
+## Nota
+
+O índice único pode ser reintroduzido numa versão futura apenas depois de existir um relatório/migração explícita para resolver todos os duplicados legados.