@danhachuel/leadmaster 0.1.18 → 0.1.20

package/CHANGELOG.md

@@ -37,6 +37,71 @@ normaliza para a forma canônica (ex.: `0.1.0`).
    falha se `process.stdin.resume();` desaparecer, se `.unref()` aparecer, se o
    ciclo de vida vinculado for removido ou se os handlers globais sumirem.
 
+## [0.1.20] — 2026-11-09
+
+### Adicionado
+
+- **Módulo de Agentes de IA (controle e configuração):**
+  - Backend: `GET /api/agents` (status + prompt de cada agente, e flag
+    `llm_configurado`), `PUT /api/agents/{agent_id}/status` (ativo/inativo) e
+    `PUT /api/agents/{agent_id}/prompt` — persistência no novo arquivo
+    `storage/agents.json` (seed com prompts padrão em pt-BR).
+  - **Regra de bloqueio:** ativar o **Agente de Disparo** sem a chave do LLM
+    configurada retorna **400** com mensagem acionável ("Configure a API Key
+    do LLM em Ferramentas..."); desativar e o Atendimento são sempre
+    permitidos.
+  - Frontend: `frontend/src/pages/Agentes.tsx` reformulado em **dois cards
+    lado a lado** (Disparo / Atendimento): badge de status, **toggle grande**
+    (w-16 h-9 — Fitts), **pulso animado verde-esmeralda** e badge esmeralda
+    quando ativo (von Restorff + Zeigarnik), textarea do **Prompt do Sistema**
+    + botão "Salvar Prompt", toast específico ("Configure a API Key na aba
+    Ferramentas primeiro.") quando o bloqueio 400 ocorre, e **accordion** com
+    as configurações avançadas (modelo LLM/temperatura; modo texto/voz do
+    atendimento) — Lei de Hick.
+- **8 novos testes pytest** (`backend/tests/test_agents_routes.py`): listagem,
+  bloqueio do disparo sem LLM (400), ativação do atendimento, ativação do
+  disparo com LLM, desativação, status inválido/agente desconhecido (400/404),
+  persistência do prompt e erros de prompt.
+
+## [0.1.19] — 2026-11-09
+
+### Adicionado
+
+- **`POST /api/config`** — alias do `PUT /api/config` (frontend continua usando
+  PUT; clientes externos podem usar POST, como na especificação da tela de
+  Ferramentas).
+- **Prevenção de erros (Nielsen) — trim automático:** todo texto do payload de
+  configuração recebe `strip()` antes de gravar (recursivo, inclui arrays e
+  objetos aninhados) — espaço acidental em API Key ou URL não vira falha
+  misteriosa depois.
+- **Validação de payload (422):** seção que é objeto no padrão (`llm`,
+  `extratores`, `integracoes`, `agentes`, `webhook`, `perfil`) recebendo valor
+  escalar é rejeitada com mensagem acionável, em vez de corromper o
+  `config.json` e a UI.
+- **Ícone de olho no campo de API Key** (`CampoSecreto` em Ferramentas):
+  alterna visibilidade da chave (von Restorff) — conferir/colar sem apagar o
+  campo. Continua com placeholder mascarado e aviso "deixe vazio para manter".
+- **Testes (`backend/tests/test_config.py`)** — 7 novos testes de
+  `GET/POST/PUT /api/config`: estrutura padrão, segredos nunca expostos ( GET
+  devolve vazio + `_configurado` e o corpo cru não contém a chave),
+  persistência + trim, segredo vazio não apaga o atual, PUT funcional,
+  payload inválido → 422 e trim em arrays aninhados.
+  Suíte completa: **51 passed**.
+
+### Auditoria
+
+- **Tela de Ferramentas:** auditada contra a especificação — a página
+  (`frontend/src/pages/Ferramentas.tsx`, rota `/ferramentas` já no menu) já
+  cobria LLM (provedor/base URL/modelo/API Key), Extratores (Maps, igmapper,
+  templates em accordion, CNPJ/Scrapling), Perfil e o botão gradiente "Salvar
+  configurações" com toast. Gaps entregues acima: POST, trim, validação, olho.
+- **Integrações:** a seção cobre **OpenOutreach** (disparo) e **pipecat**
+  (atendimento por voz), que são as integrações do produto. **YouTube/Meta não
+  foram implementados** — o AGENTS.md (§1) é explícito: produção/upload de
+  vídeos **não faz parte** do LeadMaster (o storage já remove chaves desses
+  sistemas em migração). Se o pipeline de vídeos entrar no roadmap um dia, será
+  como novo módulo com decisão de produto registrada.
+
 ## [0.1.18] — 2026-11-09
 
 ### Adicionado

package/backend/main.py

@@ -552,19 +552,109 @@ def buscar_cnpj(dados: CnpjSearchIn):
         raise HTTPException(502, str(e))
 
 
+# ---------------------------------------------------------------------------
+# Agentes de IA (status + prompt do sistema)
+# ---------------------------------------------------------------------------
+
+@app.get("/api/agents")
+def listar_agentes():
+    """Status e prompt de cada agente (disparo / atendimento)."""
+    agentes = storage.get_agents()
+    llm_ok = llm.configurado()
+    return {
+        "llm_configurado": llm_ok,
+        "agentes": {
+            agent_id: {
+                "status": agentes.get(agent_id, {}).get("status", "inativo"),
+                "prompt": agentes.get(agent_id, {}).get("prompt", ""),
+            }
+            for agent_id in storage.AGENTE_IDS
+        },
+    }
+
+
+@app.put("/api/agents/{agent_id}/status")
+def alterar_status_agente(agent_id: str, dados: dict):
+    """Liga/desliga um agente. Ativar o de disparo exige LLM configurada."""
+    if agent_id not in storage.AGENTE_IDS:
+        raise HTTPException(404, f"Agente desconhecido: {agent_id}. Use: disparo ou atendimento.")
+    status = (dados.get("status") or "").strip().lower()
+    if status not in ("ativo", "inativo"):
+        raise HTTPException(400, 'Status inválido. Use: ativo ou inativo.')
+    if status == "ativo" and agent_id == "disparo" and not llm.configurado():
+        raise HTTPException(
+            400,
+            "Configure a API Key do LLM em Ferramentas antes de ativar o Agente de Disparo.",
+        )
+    agente = storage.save_agent(agent_id, {"status": status})
+    return {"ok": True, "agent_id": agent_id, "status": agente["status"]}
+
+
+@app.put("/api/agents/{agent_id}/prompt")
+def salvar_prompt_agente(agent_id: str, dados: dict):
+    """Salva o prompt do sistema do agente em agents.json."""
+    if agent_id not in storage.AGENTE_IDS:
+        raise HTTPException(404, f"Agente desconhecido: {agent_id}. Use: disparo ou atendimento.")
+    prompt = dados.get("prompt")
+    if prompt is None:
+        raise HTTPException(400, "Informe o prompt do sistema.")
+    agente = storage.save_agent(agent_id, {"prompt": str(prompt)})
+    return {"ok": True, "agent_id": agent_id, "prompt": agente["prompt"]}
+
+
 # ---------------------------------------------------------------------------
 # Configuração e integrações
 # ---------------------------------------------------------------------------
 
 @app.get("/api/config")
 def obter_config():
+    """Configuração local (config.json) — segredos NUNCA são expostos (regra do
+    AGENTS.md): campo devolvido vazio + flag `<campo>_configurado`."""
+    return storage.redact_config(storage.get_config())
+
+
+def _validar_patch(patch: dict) -> None:
+    """Rejeita payload que quebraria a estrutura da config.
+
+    Seções que são objetos no padrão (llm, extratores, integracoes...) precisam
+    continuar objetos — um valor escalar no lugar corromperia o arquivo e a UI.
+    Nenhum campo é obrigatório: o app roda com os defaults e valida credenciais
+    apenas no momento da ação (regra do AGENTS.md — sem travas de pré-registo).
+    """
+    for chave, valor in patch.items():
+        padrao = storage.DEFAULT_CONFIG.get(chave)
+        if isinstance(padrao, dict) and not isinstance(valor, dict):
+            raise HTTPException(422, f"O campo '{chave}' deve ser um objeto com os subcampos.")
+
+
+def _aparar_textos(valor):
+    """Nielsen (prevenção de erros): trim automático em textos antes de salvar —
+    espaços acidentais no início/fim (copiar-e-colar de chaves) não quebram a
+    credencial nem disparam falsos "inválido" depois."""
+    if isinstance(valor, str):
+        return valor.strip()
+    if isinstance(valor, dict):
+        return {k: _aparar_textos(v) for k, v in valor.items()}
+    if isinstance(valor, list):
+        return [_aparar_textos(v) for v in valor]
+    return valor
+
+
+def _salvar_config(patch: dict):
+    _validar_patch(patch)
+    storage.update_config(_aparar_textos(patch))
     return storage.redact_config(storage.get_config())
 
 
 @app.put("/api/config")
+@app.post("/api/config")
 def salvar_config(patch: dict):
-    storage.update_config(patch)
-    return storage.redact_config(storage.get_config())
+    """Salva a configuração em config.json (merge profundo, atômico, sob lock).
+
+    POST e PUT são equivalentes (o frontend usa PUT). Segredos vazios mantêm o
+    valor atual; textos recebem trim automático. Devolve a config mascarada.
+    """
+    return _salvar_config(patch)
 
 
 @app.post("/api/config/test/llm")

package/backend/services/storage.py

@@ -20,6 +20,7 @@ LEADS_FILE = "leads.json"
 CAMPAIGNS_FILE = "campaigns.json"
 PIPELINE_FILE = "pipeline.json"
 CONFIG_FILE = "config.json"
+AGENTS_FILE = "agents.json"
 
 
 # ---------------------------------------------------------------------------
@@ -352,6 +353,47 @@ def delete_campaign(campaign_id: str) -> bool:
         return True
 
 
+# ---------------------------------------------------------------------------
+# Agentes de IA (status e prompt do sistema)
+# ---------------------------------------------------------------------------
+
+DEFAULT_AGENTS = {
+    "disparo": {
+        "status": "inativo",
+        "prompt": (
+            "Você é um especialista em prospecção consultiva. Escreva mensagens curtas, "
+            "educadas e personalizadas, sempre citando a empresa do lead. Nunca use "
+            "linguagem agressiva ou spam."
+        ),
+    },
+    "atendimento": {
+        "status": "inativo",
+        "prompt": (
+            "Você é o assistente de atendimento do LeadMaster. Responda de forma clara e "
+            "objetiva em português do Brasil, encaminhe dúvidas comerciais para o "
+            "responsável quando necessário."
+        ),
+    },
+}
+
+AGENTE_IDS = ("disparo", "atendimento")
+
+
+def get_agents() -> dict:
+    return _deep_merge(DEFAULT_AGENTS, _read(AGENTS_FILE, {}))
+
+
+def save_agent(agent_id: str, dados: dict) -> dict:
+    """Atualiza campos de um agente (status/prompt) e persiste em agents.json."""
+    with LOCK:
+        agents = get_agents()
+        if agent_id not in agents:
+            agents[agent_id] = {"status": "inativo", "prompt": ""}
+        agents[agent_id].update({k: v for k, v in dados.items() if k in ("status", "prompt")})
+        _write(AGENTS_FILE, agents)
+        return agents[agent_id]
+
+
 # ---------------------------------------------------------------------------
 # Seeds (primeira execução)
 # ---------------------------------------------------------------------------
@@ -433,6 +475,8 @@ def ensure_seeds() -> None:
             _write(CAMPAIGNS_FILE, _seed_campaigns())
         if not (d / CONFIG_FILE).exists():
             _write(CONFIG_FILE, DEFAULT_CONFIG)
+        if not (d / AGENTS_FILE).exists():
+            _write(AGENTS_FILE, DEFAULT_AGENTS)
 
 
 def limpar_seeds_demo() -> None:

package/backend/tests/test_agents_routes.py

@@ -0,0 +1,82 @@
+"""Testes do controle dos Agentes de IA (backend/main.py).
+
+GET /api/agents, PUT /api/agents/{id}/status (com bloqueio do disparo sem
+LLM configurada) e PUT /api/agents/{id}/prompt. Home isolado em tmp.
+"""
+
+import pytest
+from fastapi.testclient import TestClient
+
+import main
+
+
+@pytest.fixture()
+def client(tmp_path, monkeypatch):
+    monkeypatch.setenv("LEADMASTER_HOME", str(tmp_path))
+    with TestClient(main.app) as c:
+        yield c
+
+
+def test_listar_agentes(client):
+    r = client.get("/api/agents")
+    assert r.status_code == 200
+    corpo = r.json()
+    assert "disparo" in corpo["agentes"] and "atendimento" in corpo["agentes"]
+    assert corpo["agentes"]["disparo"]["status"] == "inativo"
+    assert corpo["llm_configurado"] is False  # seed sem chave de LLM
+
+
+def test_ativar_disparo_sem_llm_bloqueia(client):
+    r = client.put("/api/agents/disparo/status", json={"status": "ativo"})
+    assert r.status_code == 400
+    assert "API Key" in r.json()["detail"]
+    # Continua inativo
+    estado = client.get("/api/agents").json()["agentes"]["disparo"]["status"]
+    assert estado == "inativo"
+
+
+def test_ativar_atendimento_permitido_sem_llm(client):
+    r = client.put("/api/agents/atendimento/status", json={"status": "ativo"})
+    assert r.status_code == 200
+    assert r.json()["status"] == "ativo"
+    # Persistido em agents.json
+    estado = client.get("/api/agents").json()["agentes"]["atendimento"]["status"]
+    assert estado == "ativo"
+
+
+def test_ativar_disparo_com_llm(client):
+    # Configura a chave do LLM e ativa o disparo.
+    client.put("/api/config", json={"llm": {"api_key": "sk-teste-123"}})
+    r = client.put("/api/agents/disparo/status", json={"status": "ativo"})
+    assert r.status_code == 200
+    assert r.json()["status"] == "ativo"
+
+
+def test_desativar_agente(client):
+    client.put("/api/agents/atendimento/status", json={"status": "ativo"})
+    r = client.put("/api/agents/atendimento/status", json={"status": "inativo"})
+    assert r.status_code == 200
+    assert r.json()["status"] == "inativo"
+
+
+def test_status_invalido_e_agente_desconhecido(client):
+    r = client.put("/api/agents/disparo/status", json={"status": "talvez"})
+    assert r.status_code == 400
+    r2 = client.put("/api/agents/inexistente/status", json={"status": "ativo"})
+    assert r2.status_code == 404
+
+
+def test_salvar_prompt_persiste(client):
+    prompt = "Você é um agente de prospecção especialista em SaaS."
+    r = client.put("/api/agents/disparo/prompt", json={"prompt": prompt})
+    assert r.status_code == 200
+    assert r.json()["prompt"] == prompt
+    salvo = client.get("/api/agents").json()["agentes"]["disparo"]["prompt"]
+    assert salvo == prompt
+
+
+def test_salvar_prompt_agente_desconhecido(client):
+    r = client.put("/api/agents/inexistente/prompt", json={"prompt": "x"})
+    assert r.status_code == 404
+    r2 = client.put("/api/agents/disparo/prompt", json={})
+    assert r2.status_code == 400

package/backend/tests/test_config.py

@@ -0,0 +1,90 @@
+"""Testes das rotas de configuração — GET/POST/PUT /api/config.
+
+Valida a estrutura padrão, o sigulo absoluto dos segredos (regra do
+AGENTS.md: GET nunca expõe chaves), a persistência em config.json, o trim
+automático de textos (prevenção de erros — Nielsen) e a rejeição de payloads
+quebrados. LEADMASTER_HOME em diretório temporário.
+"""
+
+from fastapi.testclient import TestClient
+
+import main
+from services import storage
+
+
+def _client(tmp_path, monkeypatch):
+    monkeypatch.setenv("LEADMASTER_HOME", str(tmp_path))
+    return TestClient(main.app)
+
+
+def test_get_retorna_estrutura_padrao(tmp_path, monkeypatch):
+    with _client(tmp_path, monkeypatch) as client:
+        c = client.get("/api/config").json()
+        for secao in ("llm", "extratores", "integracoes", "agentes", "webhook", "perfil"):
+            assert secao in c
+        assert c["llm"]["base_url"]  # default do OpenAI-compat
+        assert c["llm"]["api_key"] == ""  # nunca exposto
+        assert c["extratores"]["google_maps_cli"] == ""
+        assert c["integracoes"]["openoutreach"]["enabled"] is False
+
+
+def test_get_nunca_expõe_segredos(tmp_path, monkeypatch):
+    with _client(tmp_path, monkeypatch) as client:
+        client.post("/api/config", json={"llm": {"api_key": "sk-super-secreta"}})
+        corpo = client.get("/api/config").json()
+        assert corpo["llm"]["api_key"] == ""
+        assert corpo["llm"]["api_key_configurado"] is True
+        # Nem o corpo cru da resposta pode conter a chave.
+        assert "sk-super-secreta" not in client.get("/api/config").text
+
+
+def test_post_persiste_e_aplica_trim(tmp_path, monkeypatch):
+    with _client(tmp_path, monkeypatch) as client:
+        r = client.post(
+            "/api/config",
+            json={"llm": {"base_url": "  https://api.exemplo.com/v1  ", "api_key": "  sk-123  "}},
+        )
+        assert r.status_code == 200
+        gravado = storage.get_config()["llm"]
+        assert gravado["base_url"] == "https://api.exemplo.com/v1"  # trim aplicado
+        assert gravado["api_key"] == "sk-123"
+        # Round-trip pelo GET (mascarado) confirma a persistência.
+        get = client.get("/api/config").json()
+        assert get["llm"]["base_url"] == "https://api.exemplo.com/v1"
+        assert get["llm"]["api_key_configurado"] is True
+
+
+def test_post_segredo_vazio_mantem_atual(tmp_path, monkeypatch):
+    with _client(tmp_path, monkeypatch) as client:
+        client.post("/api/config", json={"llm": {"api_key": "sk-original"}})
+        client.post("/api/config", json={"llm": {"api_key": "", "modelo": "gpt-4o"}})
+        gravado = storage.get_config()["llm"]
+        assert gravado["api_key"] == "sk-original"  # vazio não apaga
+        assert gravado["modelo"] == "gpt-4o"
+
+
+def test_put_continua_funcionando(tmp_path, monkeypatch):
+    with _client(tmp_path, monkeypatch) as client:
+        r = client.put("/api/config", json={"extratores": {"igmapper_cli": "  C:\\ferramentas\\igmapper.exe  "}})
+        assert r.status_code == 200
+        assert storage.get_config()["extratores"]["igmapper_cli"] == "C:\\ferramentas\\igmapper.exe"
+
+
+def test_payload_invalido_422(tmp_path, monkeypatch):
+    with _client(tmp_path, monkeypatch) as client:
+        # Lista no lugar de objeto: rejeitado pelo FastAPI.
+        assert client.post("/api/config", json=["nao", "e", "objeto"]).status_code == 422
+        # Seção que deve ser objeto recebendo escalar: rejeitado pela validação.
+        r = client.post("/api/config", json={"llm": "string-no-lugar-de-objeto"})
+        assert r.status_code == 422
+        assert "objeto" in r.json()["detail"]
+        # A configuração anterior (padrão) permanece íntegra.
+        assert storage.get_config()["llm"]["base_url"] != "string-no-lugar-de-objeto"
+
+
+def test_post_trim_em_arrays_e_aninhados(tmp_path, monkeypatch):
+    with _client(tmp_path, monkeypatch) as client:
+        client.post("/api/config", json={"webhook": {"url": "  https://hook.exemplo.com/x  ", "eventos": ["  lead.criado  "]}})
+        wh = storage.get_config()["webhook"]
+        assert wh["url"] == "https://hook.exemplo.com/x"
+        assert wh["eventos"][0] == "lead.criado"