Release v4928.1.4.2 stable

docs/CLIENTFLOW_V47_ADMIN_UI_REFACTOR.md

@@ -0,0 +1,95 @@
+# 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
+
+```bash
+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.
+
+```bash
+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.