Release v4928.1.4.2 stable

docs/CLIENTFLOW_V40_NOTES.md

@@ -0,0 +1,72 @@
+# ClientFlow v4.0 — estabilização operacional + refactor modular incremental
+
+Esta versão junta a estabilização prevista para v3.5 com o arranque do refactor v4.
+
+## Incluído
+
+### Operação segura
+
+- Migrações SQL versionadas em `migrations/`.
+- Script `scripts/apply_migrations.py`.
+- Script `scripts/check_clientflow_health.py`.
+- Script `scripts/install_systemd_timers.sh`.
+- Índices adicionais para outbox, clientes, documentos, envios e produtos.
+- Colunas de segurança na outbox: `locked_at`, `lock_owner`, `ignored_at`.
+- API interna read-only:
+  - `/api/internal/health`
+  - `/api/internal/outbox/summary`
+  - `/api/internal/documents/summary`
+
+### Refactor modular incremental
+
+- Novo pacote `app/admin_ui/`.
+- `app/main.py` passa a importar o router admin através de `app.admin_ui.router`.
+- O router ainda usa `app.admin_dashboard` internamente para manter compatibilidade.
+- Helpers HTML comuns em `app/admin_ui/components.py`.
+- Estrutura de destino criada para modularizar:
+  - `app/customers/`
+  - `app/opportunities/`
+  - `app/commercial/`
+  - `app/logistics/`
+  - `app/integrations/`
+  - `app/outbox/`
+
+## Deploy recomendado
+
+```bash
+cd /mnt/ssd/home/plx/clientflow_backend
+source .venv/bin/activate
+python scripts/apply_migrations.py --dry-run
+python scripts/apply_migrations.py
+python -m py_compile app/*.py scripts/*.py
+python scripts/check_clientflow_health.py
+sudo systemctl restart clientflow-api
+```
+
+## Timers systemd
+
+Jasmin:
+
+```bash
+sudo ./scripts/install_systemd_timers.sh /mnt/ssd/home/plx/clientflow_backend
+```
+
+Packlink, só quando o fluxo de envios estiver validado:
+
+```bash
+ENABLE_PACKLINK_TIMER=true sudo -E ./scripts/install_systemd_timers.sh /mnt/ssd/home/plx/clientflow_backend
+```
+
+## Próximo passo após v4.0
+
+Migrar gradualmente rotas de `app/admin_dashboard.py` para:
+
+```text
+app/admin_ui/pages/customers.py
+app/admin_ui/pages/opportunities.py
+app/admin_ui/pages/products.py
+app/admin_ui/pages/outbox.py
+app/admin_ui/pages/integrations.py
+```
+
+Sem mudar URLs públicas.