clientflow_backend/docs/CLIENTFLOW_V4927_1_HOTFIX.md

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.