# 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.

## 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.