151 lines
3.4 KiB
Markdown
151 lines
3.4 KiB
Markdown
# 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.
|