clientflow_backend/docs/CLIENTFLOW_V47_ADMIN_UI_REFACTOR.md

ClientFlow v4.7 — Refactor UI e Centro de Trabalho do Operador

Objetivo

A v4.7 reorganiza a UI administrativa sem alterar regras de negócio, schema da base de dados ou fluxo Chatwoot/auto-complete. A versão parte da v4.6.8 e foca-se em manutenção, clareza para o operador e redução do ficheiro app/admin_dashboard.py.

Modelo operacional

• Chatwoot = conversa e inbox.
• Centro de trabalho / Operations = trabalho diário do operador.
• Oportunidades = contexto comercial e próxima ação.
• Admin = diagnóstico técnico, outbox, eventos, runs e comunicações internas.

Alterações principais

Navegação

O menu principal fica focado no operador:

• Dashboard
• Centro de trabalho
• Oportunidades
• Clientes
• Produtos
• Encomendas
• Financeiro
• Integrações

As áreas técnicas passam para o grupo Admin:

• Tasks
• Comunicações
• Outbox
• Eventos
• Runs
• Filas
• System health
• Configuração

As rotas antigas continuam disponíveis por URL direto.

Estrutura de código

Foram extraídos módulos para app/admin_ui/:

• styles.py — CSS da UI admin.
• navigation.py — modelo e renderização da navegação.
• layout.py — shell HTML comum.
• components.py — componentes reutilizáveis, incluindo KPI cards.

app/admin_dashboard.py mantém as rotas públicas, mas perde CSS/layout/nav embutidos e fica significativamente menor.

Oportunidades

Os cards de oportunidade com tarefas pendentes passam a expor a intenção operacional:

• Concluir tarefa pendente quando existe trabalho humano aberto.
• Ver oportunidade quando não há tarefas pendentes.

Isto aproxima a board do conceito de centro de trabalho.

Sem migração

A v4.7 não requer migração de base de dados.

Validação

PYTHONPATH=. python -m compileall app scripts tests
PYTHONPATH=. pytest -q

Rollback

Como não há migração de DB, o rollback é reposição do diretório anterior e restart do serviço.

sudo systemctl restart clientflow-api

Atualização v4.7.2 — Rotas por domínio

A v4.7.2 move o registo das rotas administrativas para módulos por domínio em app/admin_ui/pages/, mantendo os URLs existentes e sem alterar regras de negócio.

Módulos principais:

• dashboard.py — página inicial.
• operations.py — centro de trabalho.
• opportunities.py — oportunidades, documentos comerciais e ações comerciais.
• tasks.py — listagem, detalhe e ações de tasks.
• customers.py, products.py, orders.py, finance.py, integrations.py.
• communications.py, outbox.py, events.py, runs.py, queues.py, system.py para áreas técnicas/admin.

Esta alteração não requer migração de base de dados.