Release v4928.1.4.2 stable

README.md

@@ -0,0 +1,144 @@
+# ClientFlow MVP Backend
+
+ClientFlow é o novo nome do antigo CCE / Customer Context Engine.
+
+Função:
+
+```text
+Receber mensagens de clientes
+→ interpretar intenção com Qwen3 30B via OpenRouter
+→ aplicar regras ClientFlow
+→ devolver estado comercial normalizado
+```
+
+## Decisão técnica atual
+
+```text
+Modelo base: qwen/qwen3-30b-a3b
+Provider: OpenRouter
+Qwen3 Max: não usar por defeito nesta fase
+Hardware local: não comprar ainda
+```
+
+A validação anterior mostrou que o modelo base com regras ClientFlow é suficiente para o MVP.
+
+## Instalação local
+
+```bash
+cd clientflow_mvp_backend
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+cp .env.example .env
+nano .env
+```
+
+Define:
+
+```env
+OPENROUTER_API_KEY=...
+OPENROUTER_MODEL=qwen/qwen3-30b-a3b
+```
+
+## Correr API
+
+```bash
+./scripts/run_dev.sh
+```
+
+Health check:
+
+```bash
+curl http://127.0.0.1:8000/health | jq .
+```
+
+Testar análise:
+
+```bash
+./scripts/test_sample.sh
+```
+
+## Endpoint
+
+```text
+POST /analyze
+```
+
+Input:
+
+```json
+{
+  "last_customer_message": "",
+  "previous_context": "",
+  "current_state": {
+    "conversation_state": "a_aguardar_cliente",
+    "commercial_state": "proposta_enviada",
+    "relationship_state": "lead_existente",
+    "last_action_by": "empresa"
+  },
+  "source": "email",
+  "conversation_id": "",
+  "contact_id": ""
+}
+```
+
+Output:
+
+```json
+{
+  "app": "ClientFlow",
+  "model": "qwen/qwen3-30b-a3b",
+  "raw_llm_result": {},
+  "normalized_result": {},
+  "usage": {},
+  "needs_review": false
+}
+```
+
+## Próximos passos
+
+1. Testar `/analyze` com os casos reais.
+2. Migrar os testes `caso_001...caso_050` para chamadas HTTP.
+3. Guardar resultados em PostgreSQL.
+4. Criar webhook receiver para Chatwoot.
+5. Adicionar nota privada no Chatwoot com resumo ClientFlow.
+
+
+## ClientFlow v3.2
+
+Versão incremental com HTMX progressivo na página de oportunidade, feedback visual para ações Jasmin/outbox, validação antes de criar orçamento, reprocessamento de outbox pela UI e filtro de produtos ativos sem Artigo Jasmin. Ver `docs/CLIENTFLOW_V32_NOTES.md`.
+
+## ClientFlow v4 operational commands
+
+Apply migrations:
+
+```bash
+python scripts/apply_migrations.py --dry-run
+python scripts/apply_migrations.py
+```
+
+Check health:
+
+```bash
+python scripts/check_clientflow_health.py
+```
+
+Install Jasmin outbox timer:
+
+```bash
+sudo ./scripts/install_systemd_timers.sh /mnt/ssd/home/plx/clientflow_backend
+```
+
+## ClientFlow v4.7 — UI operacional
+
+A navegação da UI admin foi reorganizada para separar operação diária de diagnóstico técnico:
+
+- Chatwoot é a inbox/conversa.
+- Operations é o centro de trabalho do operador.
+- Opportunities mantém o contexto comercial.
+- Admin agrupa Tasks, Communications, Outbox, Events, Runs, Queues e System health.
+
+
+## v4.8.4 — Fiscal Link Consistency Hotfix
+
+Corrige a leitura do cliente fiscal em Operations: a fila passa a usar o cliente ligado à oportunidade antes de qualquer fallback da task. Isto evita cards que dizem "Cliente fiscal por associar" quando a ficha da task já mostra um cliente fiscal válido.