ClientFlow MVP Backend

ClientFlow é o novo nome do antigo CCE / Customer Context Engine.

Função:

Receber mensagens de clientes
→ interpretar intenção com Qwen3 30B via OpenRouter
→ aplicar regras ClientFlow
→ devolver estado comercial normalizado

Decisão técnica atual

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

cd clientflow_mvp_backend
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
nano .env

Define:

OPENROUTER_API_KEY=...
OPENROUTER_MODEL=qwen/qwen3-30b-a3b

Correr API

./scripts/run_dev.sh

Health check:

curl http://127.0.0.1:8000/health | jq .

Testar análise:

./scripts/test_sample.sh

Endpoint

POST /analyze

Input:

{
  "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:

{
  "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:

python scripts/apply_migrations.py --dry-run
python scripts/apply_migrations.py

Check health:

python scripts/check_clientflow_health.py

Install Jasmin outbox timer:

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.

Previsão comercial de receitas

A versão v4928.1.5.122 disponibiliza uma previsão ponderada do pipeline em /finance/forecast e na API interna /api/internal/revenue-forecast.

A previsão combina valor comercial, probabilidade da fase e atividade operacional. É uma ferramenta de gestão comercial e não substitui dados contabilísticos ou de tesouraria.