Corrige e-mail, adiciona CC persistido e migra painel para React

.env.example

@@ -172,3 +172,19 @@ SF_CANC_MRR_FIELD=Valor_Liquido_Mensal__c
 SF_CANC_REASON_FIELD=Motivo_Cancelamento__c
 SF_CANC_PRODUCT_FIELD=ProdutoPrincipal__c
 SF_CANC_OWNER_FIELD=GC_Nome__c
+
+# ---- Fonte de Contratos (módulo de CONSULTA — busca somente leitura) ----
+# Objetos usados pela tela de "Busca" do painel (contratos, itens de contrato
+# e clientes). NÃO participa do pipeline diário de métricas — é lido sob
+# demanda (busca ao vivo no Salesforce) e cacheado no Turso (busca híbrida).
+SF_CONTRACT_OBJECT=Contrato_oPT__c
+SF_CONTRACT_ITEM_OBJECT=Item_do_Contrato__c
+# Nome de API do campo de LOOKUP do Contrato -> Account (ex.: "Conta__c").
+# Deixe em branco se não souber: a busca de contratos por cliente fica
+# desativada até você preencher (consulte Setup -> Gerenciador de Objetos ->
+# Contrato_oPT__c -> Campos, e copie o "Nome de API" do campo de lookup).
+SF_CONTRACT_ACCOUNT_FIELD=
+# Nome de API do campo de LOOKUP do Item de Contrato -> Contrato (ex.:
+# "Contrato__c"). Deixe em branco se não souber: a tela de detalhe do
+# contrato não lista os itens vinculados até você preencher.
+SF_CONTRACT_ITEM_PARENT_FIELD=

api.py

@@ -123,6 +123,8 @@ relatório). Opera <strong>somente leitura</strong> no Salesforce.</p>
 <li><code>POST /run</code> — executa o pipeline (corpo JSON)</li>
 <li><code>GET /run?date=YYYY-MM-DD</code> — executa pelo navegador (mais fácil)</li>
 <li><code>GET /metrics/{data}</code> — lê as métricas já salvas (rápido, sem reexecutar)</li>
+<li><code>GET /consulta/busca?termo=...</code> — busca de contas/oportunidades/contratos/itens</li>
+<li><code>GET /consulta/objeto/{tipo}/{id}</code> — detalhe completo de um registro</li>
 <li><a href="/docs">/docs</a> — documentação interativa (Swagger)</li>
 </ul>
 <p>Se <code>APP_API_TOKEN</code> estiver definido, envie o cabeçalho
@@ -433,6 +435,90 @@ def metrics_do_dia(
         )
 
 
+# ----------------------------------------------------------------------
+# Consulta (busca híbrida) — Contas, Oportunidades, Contratos, Itens.
+# ----------------------------------------------------------------------
+@app.get("/consulta/tipos")
+def consulta_tipos(
+    x_api_key: str | None = Header(default=None, alias="X-API-Key"),
+) -> dict[str, Any]:
+    """Lista os tipos de busca disponíveis e o estado da configuração."""
+    _exigir_token(x_api_key)
+    from src.query.search_service import status_tipos
+
+    return status_tipos(get_settings())
+
+
+@app.get("/consulta/busca")
+def consulta_busca(
+    termo: str,
+    tipos: str | None = None,
+    limite: int = 20,
+    x_api_key: str | None = Header(default=None, alias="X-API-Key"),
+) -> dict[str, Any]:
+    """Busca híbrida (cache no Turso + fallback ao vivo no Salesforce).
+
+    Args:
+        termo: Texto buscado (mínimo 2 caracteres).
+        tipos: Lista separada por vírgula (ex.: ``conta,contrato``). Vazio = todos.
+        limite: Máximo de resultados por tipo (padrão 20).
+    """
+    _exigir_token(x_api_key)
+    from src.database.turso_client import get_turso_client
+    from src.query.search_service import TIPOS_VALIDOS, buscar
+    from src.salesforce.client import get_salesforce_client
+
+    lista_tipos = [t.strip() for t in tipos.split(",") if t.strip()] if tipos else None
+    if lista_tipos:
+        invalidos = [t for t in lista_tipos if t not in TIPOS_VALIDOS]
+        if invalidos:
+            raise HTTPException(
+                status_code=400,
+                detail=f"Tipo(s) inválido(s): {invalidos}. Use: {list(TIPOS_VALIDOS)}.",
+            )
+
+    settings = get_settings()
+    try:
+        sf_client = get_salesforce_client(settings)
+        sf_client.connect()
+        resultados = buscar(settings, get_turso_client(), sf_client, termo, lista_tipos, limite)
+        return {"termo": termo, "resultados": resultados}
+    except Exception as exc:
+        raise HTTPException(
+            status_code=502, detail=f"Falha na busca: {type(exc).__name__}: {exc}"
+        )
+
+
+@app.get("/consulta/objeto/{tipo}/{record_id}")
+def consulta_detalhe(
+    tipo: str,
+    record_id: str,
+    x_api_key: str | None = Header(default=None, alias="X-API-Key"),
+) -> dict[str, Any]:
+    """Detalhe completo de um registro (Conta, Oportunidade, Contrato ou Item)."""
+    _exigir_token(x_api_key)
+    from src.database.turso_client import get_turso_client
+    from src.query.search_service import TIPOS_VALIDOS, detalhar
+    from src.salesforce.client import get_salesforce_client
+
+    if tipo not in TIPOS_VALIDOS:
+        raise HTTPException(
+            status_code=400, detail=f"Tipo inválido: {tipo!r}. Use: {list(TIPOS_VALIDOS)}."
+        )
+
+    settings = get_settings()
+    try:
+        sf_client = get_salesforce_client(settings)
+        sf_client.connect()
+        return detalhar(settings, get_turso_client(), sf_client, tipo, record_id)
+    except ValueError as exc:
+        raise HTTPException(status_code=404, detail=str(exc))
+    except Exception as exc:
+        raise HTTPException(
+            status_code=502, detail=f"Falha ao obter detalhe: {type(exc).__name__}: {exc}"
+        )
+
+
 # ----------------------------------------------------------------------
 # Painel React (estático) — serve frontend-react/dist em "/", se compilado.
 # ----------------------------------------------------------------------

frontend-react/src/App.jsx

@@ -9,6 +9,7 @@ import Leads from "./views/Leads.jsx";
 import Tasks from "./views/Tasks.jsx";
 import Satisfaction from "./views/Satisfaction.jsx";
 import Cancellations from "./views/Cancellations.jsx";
+import Search from "./views/Search.jsx";
 import Alerts from "./views/Alerts.jsx";
 import Trends from "./views/Trends.jsx";
 import Report from "./views/Report.jsx";
@@ -133,6 +134,7 @@ export default function App() {
   function renderConteudo() {
     if (view === "config") return <Config notificar={notificar} onConfigSalva={() => { checarSaude(); carregarDias(); }} />;
     if (view === "tendencias") return <Trends />;
+    if (view === "busca") return <Search notificar={notificar} />;
 
     if (erroDia && !dia) {
       return (

frontend-react/src/api.js

@@ -67,3 +67,16 @@ export const adicionarEmailCc = (email) =>
   requisicao("/config/email-cc", { method: "POST", body: JSON.stringify({ email }) });
 export const removerEmailCc = (email) =>
   requisicao("/config/email-cc/" + encodeURIComponent(email), { method: "DELETE" });
+
+// Consulta (busca/detalhe híbrida: cache Turso + Salesforce ao vivo).
+// Somente leitura — espelha os tipos configurados em src/query/search_service.py.
+export const consultaTipos = () => requisicao("/consulta/tipos");
+
+export const consultaBuscar = (termo, tipos, limite = 20) => {
+  const params = new URLSearchParams({ termo, limite: String(limite) });
+  if (tipos && tipos.length) params.set("tipos", tipos.join(","));
+  return requisicao("/consulta/busca?" + params.toString());
+};
+
+export const consultaDetalhar = (tipo, recordId) =>
+  requisicao("/consulta/objeto/" + encodeURIComponent(tipo) + "/" + encodeURIComponent(recordId));

frontend-react/src/components/Sidebar.jsx

@@ -5,6 +5,7 @@ const ITENS = [
   { v: "tarefas", i: "✅", t: "Tarefas" },
   { v: "satisfacao", i: "😊", t: "Satisfação" },
   { v: "cancelamentos", i: "❌", t: "Cancelamentos" },
+  { v: "busca", i: "🔎", t: "Consulta" },
   { v: "alertas", i: "🚨", t: "Alertas" },
   { v: "tendencias", i: "📈", t: "Tendências" },
   { v: "relatorio", i: "📄", t: "Relatório" },
@@ -15,10 +16,11 @@ export default function Sidebar({ view, onNavigate, aberta }) {
   return (
     <aside className={"sidebar" + (aberta ? " open" : "")}>
       <div className="sb-brand">
-        <div className="logo">📊</div>
+        {/* TODO: substituir pelo arquivo real da logo Penso (aguardando upload como anexo). */}
+        <div className="logo penso-logo">P</div>
         <div>
           <h1>Analytical-Force</h1>
-          <div className="s">Diagnóstico comercial</div>
+          <div className="s">Penso · Diagnóstico comercial</div>
         </div>
       </div>
       <nav>

frontend-react/src/style.css

@@ -1,34 +1,37 @@
 :root{
-  --c1:#6366f1;--c2:#8b5cf6;--c3:#ec4899;
-  --bg:#f5f6fb;--surface:#ffffff;--surface2:#f7f8fd;--line:#eceef5;
-  --txt:#1e2440;--muted:#6b7280;--faint:#9aa3b2;
-  --ok:#16a34a;--high:#ef4444;--med:#f59e0b;--low:#eab308;
-  --blue:#2563eb;--green:#16a34a;--red:#e11d48;--amber:#d97706;--violet:#7c3aed;--teal:#0d9488;
-  --radius:18px;--shadow:0 10px 28px rgba(40,40,90,.08);--shadow-lg:0 26px 60px rgba(40,40,90,.22);--sb:248px;
+  /* Paleta Penso (02 - Cores.pdf): Blue #0018FF, Blue Tech #0004DD, Black Intense #060606. */
+  --c1:#0018FF;--c2:#0004DD;--c3:#FFC453;
+  --bg:#f5f6fb;--surface:#ffffff;--surface2:#F7F8FA;--line:#E6EAEE;
+  --txt:#171717;--muted:#6b7280;--faint:#9aa3b2;
+  --ok:#16C79A;--high:#F05454;--med:#FFC453;--low:#eab308;
+  --blue:#0018FF;--green:#16C79A;--red:#F05454;--amber:#FFC453;--violet:#0004DD;--teal:#16C79A;
+  --penso-blue:#0018FF;--penso-bluetech:#0004DD;--penso-black:#171717;--penso-blackx:#060606;
+  --radius:18px;--shadow:0 10px 28px rgba(6,6,6,.08);--shadow-lg:0 26px 60px rgba(6,6,6,.22);--sb:248px;
 }
-[data-theme="dark"]{--bg:#0e1020;--surface:#171a2e;--surface2:#1c2138;--line:#272c47;--txt:#e8eaf5;--muted:#9aa3c0;--faint:#6c7595;
+[data-theme="dark"]{--bg:#0b0b0f;--surface:#141520;--surface2:#191b28;--line:#272c47;--txt:#e8eaf5;--muted:#9aa3c0;--faint:#6c7595;
   --shadow:0 10px 28px rgba(0,0,0,.45);--shadow-lg:0 26px 60px rgba(0,0,0,.6)}
 *{box-sizing:border-box}
 body{margin:0;font-family:'Segoe UI',system-ui,-apple-system,Arial,sans-serif;color:var(--txt);
-  background:radial-gradient(1200px 500px at 100% -10%,rgba(139,92,246,.10),transparent),
-             radial-gradient(900px 400px at -10% 0%,rgba(236,72,153,.08),transparent),var(--bg);
+  background:radial-gradient(1200px 500px at 100% -10%,rgba(0,24,255,.08),transparent),
+             radial-gradient(900px 400px at -10% 0%,rgba(255,196,83,.07),transparent),var(--bg);
   min-height:100vh}
 a{color:var(--c1)}
 .app{display:flex;min-height:100vh}
-.sidebar{width:var(--sb);background:linear-gradient(170deg,#6366f1 0%,#7c3aed 52%,#c026d3 120%);color:#fff;position:fixed;inset:0 auto 0 0;
+.sidebar{width:var(--sb);background:linear-gradient(170deg,#060606 0%,#0004DD 55%,#0018FF 120%);color:#fff;position:fixed;inset:0 auto 0 0;
   display:flex;flex-direction:column;padding:16px 12px;z-index:40;transition:transform .25s}
 .sb-brand{display:flex;align-items:center;gap:11px;padding:6px 10px 16px;margin-bottom:6px;border-bottom:1px solid rgba(255,255,255,.18)}
 .sb-brand .logo{width:40px;height:40px;border-radius:13px;background:rgba(255,255,255,.22);display:grid;place-items:center;font-size:20px}
-.sb-brand h1{font-size:15px;margin:0;font-weight:800;letter-spacing:.2px} .sb-brand .s{font-size:11px;color:#ece6ff}
+.sb-brand .penso-logo{background:#fff;color:#0018FF;font-weight:900;font-size:20px;font-family:Arial,sans-serif}
+.sb-brand h1{font-size:15px;margin:0;font-weight:800;letter-spacing:.2px} .sb-brand .s{font-size:11px;color:#CEE2FF}
 nav{display:flex;flex-direction:column;gap:3px;overflow:auto;margin-top:6px}
-nav a{display:flex;align-items:center;gap:12px;color:#f0ecff;text-decoration:none;padding:10px 12px;border-radius:12px;
+nav a{display:flex;align-items:center;gap:12px;color:#EAF0FF;text-decoration:none;padding:10px 12px;border-radius:12px;
   font-size:13.5px;font-weight:600;cursor:pointer;transition:.18s}
 nav a .i{width:22px;text-align:center;font-size:16px}
 nav a:hover{background:rgba(255,255,255,.14);color:#fff;transform:translateX(2px)}
-nav a.active{background:#fff;color:#6d28d9;box-shadow:0 6px 16px rgba(0,0,0,.18)}
+nav a.active{background:#fff;color:#0018FF;box-shadow:0 6px 16px rgba(0,0,0,.18)}
 .sb-foot{margin-top:auto;padding-top:14px;display:flex;align-items:center;gap:10px;border-top:1px solid rgba(255,255,255,.18)}
 .sb-foot img{width:38px;height:38px;border-radius:50%;border:2px solid rgba(255,255,255,.65)}
-.sb-foot .n{font-size:12.5px;font-weight:700} .sb-foot .r{font-size:11px;color:#ece6ff}
+.sb-foot .n{font-size:12.5px;font-weight:700} .sb-foot .r{font-size:11px;color:#CEE2FF}
 .mainwrap{margin-left:var(--sb);flex:1;min-width:0;display:flex;flex-direction:column}
 .topbar{position:sticky;top:0;z-index:30;background:rgba(255,255,255,.82);backdrop-filter:blur(10px);
   border-bottom:1px solid var(--line);padding:12px 22px;display:flex;align-items:center;gap:12px;flex-wrap:wrap}
@@ -62,7 +65,7 @@ main{padding:22px;flex:1}
 .meta{display:flex;gap:8px;flex-wrap:wrap}
 .chip{background:var(--surface2);border:1px solid var(--line);color:var(--txt);border-radius:999px;padding:6px 12px;font-size:12.5px;font-weight:600}
 .chip.good{background:#dcfce7;color:#15803d;border-color:#bbf7d0} .chip.bad{background:#ffe4e6;color:#be123c;border-color:#fecdd3}
-.hero{border-radius:14px;padding:16px 18px;background:linear-gradient(120deg,rgba(99,102,241,.10),rgba(236,72,153,.08));border:1px solid rgba(124,58,237,.18);border-left:4px solid var(--c2);margin-bottom:16px}
+.hero{border-radius:14px;padding:16px 18px;background:linear-gradient(120deg,rgba(0,24,255,.08),rgba(255,196,83,.08));border:1px solid rgba(0,4,221,.18);border-left:4px solid var(--c2);margin-bottom:16px}
 .hero .h{font-size:12px;font-weight:800;color:var(--c2);text-transform:uppercase;letter-spacing:.05em;margin-bottom:6px}
 .hero p{margin:0 0 10px;font-size:14px;line-height:1.6} .hero p:last-child{margin-bottom:0}
 .hero strong{color:var(--txt)}
@@ -141,3 +144,4 @@ input:focus{outline:none;border-color:var(--c1);box-shadow:0 0 0 3px rgba(99,102
 .ccrow button{background:none;border:0;color:var(--red);cursor:pointer;font-size:13px;font-weight:700}
 .ccadd{display:flex;gap:8px;margin-top:14px}
 @media(max-width:860px){.sidebar{transform:translateX(-100%)} .sidebar.open{transform:none} .mainwrap{margin-left:0} .hamb{display:block} .split{grid-template-columns:1fr}}
+

frontend-react/src/views/Search.jsx

@@ -0,0 +1,252 @@
+import { useEffect, useMemo, useState } from "react";
+import SecaoHeader from "../components/SecaoHeader.jsx";
+import { consultaTipos, consultaBuscar, consultaDetalhar } from "../api.js";
+
+// Tela de Consulta: busca e detalhe somente-leitura sobre Salesforce, com
+// cache Turso como camada rápida (modo híbrido). Nenhum cálculo é feito
+// aqui — apenas exibição do que o backend Python já retornou.
+
+const ROTULOS_TIPO = {
+  conta: { icone: "🏢", cor: "#0018FF" },
+  oportunidade: { icone: "💼", cor: "#16C79A" },
+  contrato: { icone: "📄", cor: "#0004DD" },
+  item: { icone: "🧾", cor: "#FFC453" },
+};
+
+export default function Search({ notificar }) {
+  const [tiposInfo, setTiposInfo] = useState(null);
+  const [tiposAtivos, setTiposAtivos] = useState([]);
+  const [termo, setTermo] = useState("");
+  const [buscando, setBuscando] = useState(false);
+  const [resultados, setResultados] = useState(null);
+  const [erroBusca, setErroBusca] = useState(null);
+
+  const [selecionado, setSelecionado] = useState(null); // { tipo, id, name }
+  const [detalhe, setDetalhe] = useState(null);
+  const [carregandoDetalhe, setCarregandoDetalhe] = useState(false);
+  const [erroDetalhe, setErroDetalhe] = useState(null);
+
+  useEffect(() => {
+    consultaTipos()
+      .then((d) => {
+        setTiposInfo(d);
+        setTiposAtivos((d.tipos || []).map((t) => t.tipo));
+      })
+      .catch(() => setTiposInfo(null));
+  }, []);
+
+  const tiposDisponiveis = useMemo(() => tiposInfo?.tipos || [], [tiposInfo]);
+
+  function alternarTipo(tipo) {
+    setTiposAtivos((atuais) =>
+      atuais.includes(tipo) ? atuais.filter((t) => t !== tipo) : [...atuais, tipo]
+    );
+  }
+
+  async function executarBusca(e) {
+    e?.preventDefault();
+    const t = termo.trim();
+    if (t.length < 2) {
+      setErroBusca("Digite ao menos 2 caracteres.");
+      return;
+    }
+    setBuscando(true);
+    setErroBusca(null);
+    setResultados(null);
+    try {
+      const d = await consultaBuscar(t, tiposAtivos, 20);
+      setResultados(d.resultados || {});
+    } catch (err) {
+      setErroBusca(err.message);
+      notificar?.("Falha na busca: " + err.message, "bad");
+    } finally {
+      setBuscando(false);
+    }
+  }
+
+  async function abrirDetalhe(tipo, item) {
+    setSelecionado({ tipo, id: item.id, name: item.name });
+    setDetalhe(null);
+    setErroDetalhe(null);
+    setCarregandoDetalhe(true);
+    try {
+      const d = await consultaDetalhar(tipo, item.id);
+      setDetalhe(d);
+    } catch (err) {
+      setErroDetalhe(err.message);
+    } finally {
+      setCarregandoDetalhe(false);
+    }
+  }
+
+  const totalResultados = resultados
+    ? Object.values(resultados).reduce((acc, arr) => acc + arr.length, 0)
+    : 0;
+
+  return (
+    <>
+      <div className="card">
+        <SecaoHeader
+          icone="🔎"
+          titulo="Consulta — Contratos, Clientes e Oportunidades"
+          cor="linear-gradient(120deg,#0004DD,#0018FF)"
+          extra={
+            <span className="chip">
+              Fonte: cache Turso + Salesforce (somente leitura)
+            </span>
+          }
+        />
+
+        <form onSubmit={executarBusca}>
+          <label className="lbl">Buscar por nome</label>
+          <div style={{ display: "flex", gap: 9 }}>
+            <input
+              type="text"
+              placeholder="Ex.: Contrato 4521, Empresa XPTO, Oportunidade Renovação…"
+              value={termo}
+              onChange={(e) => setTermo(e.target.value)}
+              autoFocus
+            />
+            <button className="btn btn-primary btn-sm" type="submit" disabled={buscando}>
+              {buscando ? "Buscando…" : "Buscar"}
+            </button>
+          </div>
+        </form>
+
+        <div className="filters" style={{ marginTop: 14 }}>
+          {tiposDisponiveis.map((t) => (
+            <span
+              key={t.tipo}
+              className={"fchip" + (tiposAtivos.includes(t.tipo) ? " active" : "")}
+              onClick={() => alternarTipo(t.tipo)}
+              title={t.objeto}
+            >
+              {ROTULOS_TIPO[t.tipo]?.icone || "•"} {t.rotulo}
+            </span>
+          ))}
+        </div>
+
+        {tiposInfo && !tiposInfo.itens_do_contrato_configurados && (
+          <div className="empty" style={{ textAlign: "left", padding: "10px 0 0", fontSize: 12.5 }}>
+            ⚙️ Vínculo Contrato → Itens não configurado (defina{" "}
+            <code>SF_CONTRACT_ITEM_PARENT_FIELD</code> no .env). O contrato ainda pode ser
+            consultado, mas sem a lista de itens relacionados.
+          </div>
+        )}
+
+        {erroBusca && <div className="err" style={{ marginTop: 14 }}>{erroBusca}</div>}
+      </div>
+
+      <div className="split">
+        <div className="card">
+          <SecaoHeader
+            icone="📋"
+            titulo={resultados ? `Resultados (${totalResultados})` : "Resultados"}
+            cor="#0018FF"
+          />
+          {buscando && <div className="empty">Buscando��</div>}
+          {!buscando && !resultados && (
+            <div className="empty">Digite um termo e clique em Buscar.</div>
+          )}
+          {!buscando && resultados && totalResultados === 0 && (
+            <div className="empty">Nenhum resultado para "{termo}".</div>
+          )}
+          {!buscando &&
+            resultados &&
+            Object.entries(resultados).map(([tipo, itens]) => (
+              <div key={tipo} style={{ marginBottom: 16 }}>
+                <div
+                  style={{
+                    fontSize: 12,
+                    fontWeight: 800,
+                    textTransform: "uppercase",
+                    letterSpacing: ".05em",
+                    color: "var(--muted)",
+                    marginBottom: 8,
+                  }}
+                >
+                  {ROTULOS_TIPO[tipo]?.icone} {tiposInfo?.tipos?.find((t) => t.tipo === tipo)?.rotulo || tipo}
+                </div>
+                <div className="dgrid">
+                  {itens.map((item) => (
+                    <div
+                      key={item.id}
+                      className="dcard"
+                      style={{
+                        cursor: "pointer",
+                        border:
+                          selecionado?.id === item.id ? "2px solid #0018FF" : "1px solid var(--line)",
+                      }}
+                      onClick={() => abrirDetalhe(tipo, item)}
+                    >
+                      <div className="dh" style={{ background: ROTULOS_TIPO[tipo]?.cor || "#0018FF" }}>
+                        <span>{item.name}</span>
+                      </div>
+                      {item.subtitle && (
+                        <div style={{ padding: "10px 14px", fontSize: 12.5, color: "var(--muted)" }}>
+                          {item.subtitle}
+                        </div>
+                      )}
+                    </div>
+                  ))}
+                </div>
+              </div>
+            ))}
+        </div>
+
+        <div className="card">
+          <SecaoHeader icone="🗂️" titulo="Detalhe" cor="#171717" />
+          {!selecionado && <div className="empty">Selecione um resultado para ver os detalhes.</div>}
+          {selecionado && carregandoDetalhe && <div className="empty">Carregando detalhe…</div>}
+          {selecionado && erroDetalhe && <div className="err">{erroDetalhe}</div>}
+          {selecionado && detalhe && (
+            <>
+              <div className="chip" style={{ marginBottom: 12 }}>
+                Origem: {detalhe.origem}
+              </div>
+              <table className="owners">
+                <tbody>
+                  {(detalhe.campos || []).map((c) => (
+                    <tr key={c.campo}>
+                      <th style={{ whiteSpace: "nowrap" }}>{c.campo}</th>
+                      <td>{String(c.valor)}</td>
+                    </tr>
+                  ))}
+                </tbody>
+              </table>
+
+              {detalhe.itens_do_contrato != null && (
+                <div style={{ marginTop: 18 }}>
+                  <SecaoHeader icone="🧾" titulo={`Itens do contrato (${detalhe.itens_do_contrato.length})`} cor="#FFC453" />
+                  {detalhe.itens_do_contrato.length === 0 ? (
+                    <div className="empty">Nenhum item vinculado.</div>
+                  ) : (
+                    <div className="dgrid">
+                      {detalhe.itens_do_contrato.map((it, idx) => (
+                        <div className="dcard" key={it.Id || idx}>
+                          <div className="dh" style={{ background: "#FFC453", color: "#171717" }}>
+                            {it.Name || it.Id}
+                          </div>
+                          <ul>
+                            {Object.entries(it)
+                              .filter(([k, v]) => k !== "attributes" && v != null && k !== "Name")
+                              .slice(0, 6)
+                              .map(([k, v]) => (
+                                <li key={k}>
+                                  <b>{k}:</b> {String(v)}
+                                </li>
+                              ))}
+                          </ul>
+                        </div>
+                      ))}
+                    </div>
+                  )}
+                </div>
+              )}
+            </>
+          )}
+        </div>
+      </div>
+    </>
+  );
+}

frontend-react/vite.config.js.timestamp-1783562543181-33acbd5d299df.mjs

@@ -0,0 +1,15 @@
+// vite.config.js
+import { defineConfig } from "file:///sessions/zen-zealous-feynman/mnt/Analytical-Force/analytical_force/frontend-react/node_modules/vite/dist/node/index.js";
+import react from "file:///sessions/zen-zealous-feynman/mnt/Analytical-Force/analytical_force/frontend-react/node_modules/@vitejs/plugin-react/dist/index.js";
+var vite_config_default = defineConfig({
+  plugins: [react()],
+  base: "./",
+  build: {
+    outDir: "dist",
+    emptyOutDir: true
+  }
+});
+export {
+  vite_config_default as default
+};
+//# sourceMappingURL=data:application/json;base64,ewogICJ2ZXJzaW9uIjogMywKICAic291cmNlcyI6IFsidml0ZS5jb25maWcuanMiXSwKICAic291cmNlc0NvbnRlbnQiOiBbImNvbnN0IF9fdml0ZV9pbmplY3RlZF9vcmlnaW5hbF9kaXJuYW1lID0gXCIvc2Vzc2lvbnMvemVuLXplYWxvdXMtZmV5bm1hbi9tbnQvQW5hbHl0aWNhbC1Gb3JjZS9hbmFseXRpY2FsX2ZvcmNlL2Zyb250ZW5kLXJlYWN0XCI7Y29uc3QgX192aXRlX2luamVjdGVkX29yaWdpbmFsX2ZpbGVuYW1lID0gXCIvc2Vzc2lvbnMvemVuLXplYWxvdXMtZmV5bm1hbi9tbnQvQW5hbHl0aWNhbC1Gb3JjZS9hbmFseXRpY2FsX2ZvcmNlL2Zyb250ZW5kLXJlYWN0L3ZpdGUuY29uZmlnLmpzXCI7Y29uc3QgX192aXRlX2luamVjdGVkX29yaWdpbmFsX2ltcG9ydF9tZXRhX3VybCA9IFwiZmlsZTovLy9zZXNzaW9ucy96ZW4temVhbG91cy1mZXlubWFuL21udC9BbmFseXRpY2FsLUZvcmNlL2FuYWx5dGljYWxfZm9yY2UvZnJvbnRlbmQtcmVhY3Qvdml0ZS5jb25maWcuanNcIjtpbXBvcnQgeyBkZWZpbmVDb25maWcgfSBmcm9tIFwidml0ZVwiO1xuaW1wb3J0IHJlYWN0IGZyb20gXCJAdml0ZWpzL3BsdWdpbi1yZWFjdFwiO1xuXG4vLyBQYWluZWwgUmVhY3QgZG8gQW5hbHl0aWNhbC1Gb3JjZS5cbi8vIFwiYmFzZTogJy4vJ1wiIGdlcmEgY2FtaW5ob3MgcmVsYXRpdm9zIG5vIGJ1aWxkIFx1MjAxNCBpbXBvcnRhbnRlIHBvcnF1ZSBvXG4vLyBiYWNrZW5kIChGYXN0QVBJKSBzZXJ2ZSBvIGRpc3QvIGNvbW8gYXJxdWl2b3MgZXN0XHUwMEUxdGljb3MgYSBwYXJ0aXIgZGFcbi8vIHJhaXogZG8gY29udGFpbmVyIG5vIEh1Z2dpbmcgRmFjZSBTcGFjZXMgKHZlciBzcmMvZGVsaXZlcnkvc3RhdGljX2FwcC5weSkuXG5leHBvcnQgZGVmYXVsdCBkZWZpbmVDb25maWcoe1xuICBwbHVnaW5zOiBbcmVhY3QoKV0sXG4gIGJhc2U6IFwiLi9cIixcbiAgYnVpbGQ6IHtcbiAgICBvdXREaXI6IFwiZGlzdFwiLFxuICAgIGVtcHR5T3V0RGlyOiB0cnVlLFxuICB9LFxufSk7XG4iXSwKICAibWFwcGluZ3MiOiAiO0FBQXdhLFNBQVMsb0JBQW9CO0FBQ3JjLE9BQU8sV0FBVztBQU1sQixJQUFPLHNCQUFRLGFBQWE7QUFBQSxFQUMxQixTQUFTLENBQUMsTUFBTSxDQUFDO0FBQUEsRUFDakIsTUFBTTtBQUFBLEVBQ04sT0FBTztBQUFBLElBQ0wsUUFBUTtBQUFBLElBQ1IsYUFBYTtBQUFBLEVBQ2Y7QUFDRixDQUFDOyIsCiAgIm5hbWVzIjogW10KfQo=

frontend-react/vite.config.js.timestamp-1783562598611-6eea937b4fc98.mjs

@@ -0,0 +1,15 @@
+// vite.config.js
+import { defineConfig } from "file:///sessions/zen-zealous-feynman/mnt/Analytical-Force/analytical_force/frontend-react/node_modules/vite/dist/node/index.js";
+import react from "file:///sessions/zen-zealous-feynman/mnt/Analytical-Force/analytical_force/frontend-react/node_modules/@vitejs/plugin-react/dist/index.js";
+var vite_config_default = defineConfig({
+  plugins: [react()],
+  base: "./",
+  build: {
+    outDir: "dist",
+    emptyOutDir: true
+  }
+});
+export {
+  vite_config_default as default
+};
+//# sourceMappingURL=data:application/json;base64,ewogICJ2ZXJzaW9uIjogMywKICAic291cmNlcyI6IFsidml0ZS5jb25maWcuanMiXSwKICAic291cmNlc0NvbnRlbnQiOiBbImNvbnN0IF9fdml0ZV9pbmplY3RlZF9vcmlnaW5hbF9kaXJuYW1lID0gXCIvc2Vzc2lvbnMvemVuLXplYWxvdXMtZmV5bm1hbi9tbnQvQW5hbHl0aWNhbC1Gb3JjZS9hbmFseXRpY2FsX2ZvcmNlL2Zyb250ZW5kLXJlYWN0XCI7Y29uc3QgX192aXRlX2luamVjdGVkX29yaWdpbmFsX2ZpbGVuYW1lID0gXCIvc2Vzc2lvbnMvemVuLXplYWxvdXMtZmV5bm1hbi9tbnQvQW5hbHl0aWNhbC1Gb3JjZS9hbmFseXRpY2FsX2ZvcmNlL2Zyb250ZW5kLXJlYWN0L3ZpdGUuY29uZmlnLmpzXCI7Y29uc3QgX192aXRlX2luamVjdGVkX29yaWdpbmFsX2ltcG9ydF9tZXRhX3VybCA9IFwiZmlsZTovLy9zZXNzaW9ucy96ZW4temVhbG91cy1mZXlubWFuL21udC9BbmFseXRpY2FsLUZvcmNlL2FuYWx5dGljYWxfZm9yY2UvZnJvbnRlbmQtcmVhY3Qvdml0ZS5jb25maWcuanNcIjtpbXBvcnQgeyBkZWZpbmVDb25maWcgfSBmcm9tIFwidml0ZVwiO1xuaW1wb3J0IHJlYWN0IGZyb20gXCJAdml0ZWpzL3BsdWdpbi1yZWFjdFwiO1xuXG4vLyBQYWluZWwgUmVhY3QgZG8gQW5hbHl0aWNhbC1Gb3JjZS5cbi8vIFwiYmFzZTogJy4vJ1wiIGdlcmEgY2FtaW5ob3MgcmVsYXRpdm9zIG5vIGJ1aWxkIFx1MjAxNCBpbXBvcnRhbnRlIHBvcnF1ZSBvXG4vLyBiYWNrZW5kIChGYXN0QVBJKSBzZXJ2ZSBvIGRpc3QvIGNvbW8gYXJxdWl2b3MgZXN0XHUwMEUxdGljb3MgYSBwYXJ0aXIgZGFcbi8vIHJhaXogZG8gY29udGFpbmVyIG5vIEh1Z2dpbmcgRmFjZSBTcGFjZXMgKHZlciBzcmMvZGVsaXZlcnkvc3RhdGljX2FwcC5weSkuXG5leHBvcnQgZGVmYXVsdCBkZWZpbmVDb25maWcoe1xuICBwbHVnaW5zOiBbcmVhY3QoKV0sXG4gIGJhc2U6IFwiLi9cIixcbiAgYnVpbGQ6IHtcbiAgICBvdXREaXI6IFwiZGlzdFwiLFxuICAgIGVtcHR5T3V0RGlyOiB0cnVlLFxuICB9LFxufSk7XG4iXSwKICAibWFwcGluZ3MiOiAiO0FBQXdhLFNBQVMsb0JBQW9CO0FBQ3JjLE9BQU8sV0FBVztBQU1sQixJQUFPLHNCQUFRLGFBQWE7QUFBQSxFQUMxQixTQUFTLENBQUMsTUFBTSxDQUFDO0FBQUEsRUFDakIsTUFBTTtBQUFBLEVBQ04sT0FBTztBQUFBLElBQ0wsUUFBUTtBQUFBLElBQ1IsYUFBYTtBQUFBLEVBQ2Y7QUFDRixDQUFDOyIsCiAgIm5hbWVzIjogW10KfQo=

src/agent/analytical_force_agent.py

@@ -31,18 +31,21 @@ from ..database.migrations import run_migrations
 from ..database.repositories import (
     AgentRunRepository,
     AlertsRepository,
+    ConfigRepository,
     MetricsRepository,
     ObjectMappingRepository,
     ReportRepository,
+    SearchCacheRepository,
     SnapshotRepository,
 )
 from ..database.turso_client import get_turso_client
 from ..delivery.file_writer import salvar_relatorio_md
 from ..models.model_router import ModelRouter
 from ..models.template_client import gerar_plano_acao
-from ..salesforce.client import SalesforceAuthError, get_salesforce_client
+from ..salesforce.client import SalesforceAuthError, SalesforceClient, get_salesforce_client
 from ..salesforce.extractors import SalesforceExtractor
 from ..salesforce.field_mapping import get_field_mapping
+from ..salesforce.search_sync import sincronizar_cache_busca
 from ..utils.date_utils import agora_tz, para_soql_date
 from ..utils.logger import get_logger
 from .report_generator import gerar_relatorio
@@ -148,7 +151,7 @@ class AnalyticalForceAgent:
             resultado.run_id = run_id
 
             # --- Extração do Salesforce ---
-            extrator = self._montar_extrator(snapshot_repo)
+            extrator, sf_client = self._montar_extrator(snapshot_repo)
             dados = self._extrair(extrator, dia_ref)
 
             # --- Histórico para comparação ---
@@ -207,6 +210,23 @@ class AnalyticalForceAgent:
             caminho = salvar_relatorio_md(markdown, dia_ref)
             resultado.caminho_relatorio = str(caminho)
 
+            # --- Cache de busca (módulo de Consulta) — best-effort ---
+            # Sincroniza Account/Opportunity/Contrato/Item de Contrato de forma
+            # incremental. Nunca deve impedir o sucesso do pipeline principal.
+            try:
+                sync_resultado = sincronizar_cache_busca(
+                    sf_client,
+                    self._settings,
+                    ConfigRepository(turso),
+                    SearchCacheRepository(turso),
+                )
+                logger.info("Cache de busca sincronizado: %s", sync_resultado)
+            except Exception as exc:
+                logger.warning(
+                    "Falha ao sincronizar cache de busca (não bloqueia o pipeline): %s",
+                    type(exc).__name__,
+                )
+
             run_repo.finalizar_execucao(run_id, "success")
             resultado.status = "success"
             logger.info("Execução concluída com sucesso (provider=%s).", provider)
@@ -228,21 +248,29 @@ class AnalyticalForceAgent:
     # ------------------------------------------------------------------
     # Etapas internas
     # ------------------------------------------------------------------
-    def _montar_extrator(self, snapshot_repo: SnapshotRepository) -> SalesforceExtractor:
+    def _montar_extrator(
+        self, snapshot_repo: SnapshotRepository
+    ) -> tuple[SalesforceExtractor, SalesforceClient]:
         """Autentica no Salesforce e devolve o extrator configurado.
 
         Usa o cliente com as configurações do agente. Por padrão, a
         autenticação ocorre via OAuth Refresh Token (somente leitura).
+
+        Returns:
+            Tupla ``(extrator, cliente_sf)`` — o cliente autenticado também é
+            devolvido para ser reaproveitado pela sincronização do cache de
+            busca (evita autenticar duas vezes na mesma execução).
         """
         sf_client = get_salesforce_client(self._settings)
         sf_client.connect()  # valida credenciais cedo (levanta erro controlado)
-        return SalesforceExtractor(
+        extrator = SalesforceExtractor(
             client=sf_client,
             field_mapping=get_field_mapping(),
             timezone=self._tz,
             snapshot_repo=snapshot_repo,
             ignore_lead_names=self._settings.lead_ignore_names,
         )
+        return extrator, sf_client
 
     def _extrair(self, extrator: SalesforceExtractor, dia: date) -> dict[str, pd.DataFrame]:
         """Extrai todos os DataFrames necessários do Salesforce."""
@@ -423,11 +451,23 @@ class AnalyticalForceAgent:
 
         opp_fech = dados.get("opp_fechadas")
         if opp_fech is not None and not opp_fech.empty and "IsWon" in opp_fech.columns:
-            ganhas = opp_fech[opp_fech["IsWon"].fillna(False).astype(bool)]
+            ganha_bool = opp_fech["IsWon"].fillna(False).astype(bool)
+            ganhas = opp_fech[ganha_bool]
             destaques["oportunidades_ganhas"] = [
                 _reg(r.get("Id"), r.get("Name"), self._info_moeda(r.get("Amount")))
                 for _, r in ganhas.head(limite).iterrows()
             ]
+            # Espelha exatamente a lógica das ganhas, para o lado perdido —
+            # alimenta o e-mail/painel com nomes e links (não só o agregado).
+            perdidas = opp_fech[~ganha_bool]
+            destaques["oportunidades_perdidas"] = [
+                _reg(
+                    r.get("Id"),
+                    r.get("Name"),
+                    self._info_moeda(r.get("Amount")),
+                )
+                for _, r in perdidas.head(limite).iterrows()
+            ]
 
         travadas = (metricas.get("opportunities", {}) or {}).get(
             "stalled_opportunity_details"

src/config/settings.py

@@ -324,6 +324,11 @@ class Settings:
     # Permitem ativar esses módulos sem fixar nomes no código (regra 16/17).
     satisfaction_source: dict[str, Any] = field(default_factory=dict)
     cancellation_source: dict[str, Any] = field(default_factory=dict)
+    # Fonte configurável de Contratos (objeto de contrato + item de contrato).
+    # Usada pelo módulo de CONSULTA (busca somente leitura) — não pelo pipeline
+    # diário de métricas. Os campos de vínculo (conta/contrato) são opcionais:
+    # sem eles, a consulta funciona em modo degradado (sem relacionamento).
+    contract_source: dict[str, Any] = field(default_factory=dict)
 
     # ------------------------------------------------------------------
     # Validações
@@ -549,6 +554,32 @@ def _carregar_fonte_cancelamento() -> dict[str, Any]:
     }
 
 
+def _carregar_fonte_contrato() -> dict[str, Any]:
+    """Monta a configuração da fonte de Contratos (objeto + vínculos).
+
+    Diferente de satisfação/cancelamento, esta fonte não filtra por data —
+    ela alimenta o módulo de CONSULTA (busca somente leitura de contratos,
+    itens de contrato e clientes). Os campos de vínculo (``account_field`` e
+    ``item_parent_field``) são o NOME DE API do campo de lookup na org; como
+    o projeto não pode inventar nomes de campo (regra 3), eles ficam vazios
+    por padrão — a consulta funciona em modo degradado (sem relacionamento
+    de conta/itens) até que sejam configurados via ``.env`` ou pelo painel.
+
+    Padrões de objeto alinhados à org Penso (``Contrato_oPT__c`` e
+    ``Item_do_Contrato__c``); ajuste via env se sua org usar outros nomes.
+    """
+    return {
+        "object": _get_str("SF_CONTRACT_OBJECT", "Contrato_oPT__c"),
+        "item_object": _get_str("SF_CONTRACT_ITEM_OBJECT", "Item_do_Contrato__c"),
+        # Lookup do Contrato -> Account (nome de API do campo, ex.: "Conta__c").
+        # Vazio = busca de contratos por cliente fica desativada.
+        "account_field": _get_str("SF_CONTRACT_ACCOUNT_FIELD", ""),
+        # Lookup do Item de Contrato -> Contrato (nome de API do campo).
+        # Vazio = a tela de contrato não lista os itens vinculados.
+        "item_parent_field": _get_str("SF_CONTRACT_ITEM_PARENT_FIELD", ""),
+    }
+
+
 @lru_cache(maxsize=1)
 def get_settings() -> Settings:
     """Constrói (uma única vez) e retorna as configurações do agente.
@@ -659,4 +690,5 @@ def get_settings() -> Settings:
         ],
         satisfaction_source=_carregar_fonte_satisfacao(),
         cancellation_source=_carregar_fonte_cancelamento(),
+        contract_source=_carregar_fonte_contrato(),
     )

src/database/migrations.py

@@ -108,6 +108,23 @@ _DDL: list[str] = [
         updated_at TEXT
     );
     """,
+    # 9.8 — Cache de busca (mirror somente leitura para o módulo de Consulta).
+    # Guarda um "espelho" de Account/Opportunity/Contrato/Item de Contrato,
+    # sincronizado incrementalmente pelo pipeline diário. É a camada RÁPIDA
+    # da busca híbrida; quando não encontra ou o dado precisa estar fresco,
+    # a consulta cai para o Salesforce ao vivo (ver src/query/search_service.py).
+    """
+    CREATE TABLE IF NOT EXISTS search_cache (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        object_name TEXT NOT NULL,
+        record_id TEXT NOT NULL,
+        display_name TEXT,
+        subtitle TEXT,
+        payload_json TEXT NOT NULL,
+        synced_at TEXT NOT NULL,
+        UNIQUE(object_name, record_id)
+    );
+    """,
 ]
 
 # Índices para acelerar buscas históricas (comparação dia anterior / 7 dias).
@@ -122,6 +139,8 @@ _INDICES: list[str] = [
     "ON salesforce_snapshots (snapshot_date, object_name);",
     "CREATE INDEX IF NOT EXISTS idx_agent_runs_date "
     "ON agent_runs (run_date, status);",
+    "CREATE INDEX IF NOT EXISTS idx_search_cache_lookup "
+    "ON search_cache (object_name, display_name);",
 ]
 
 

src/database/repositories.py

@@ -546,3 +546,118 @@ class ObjectMappingRepository:
             ),
         )
         logger.info("Mapeamento salvo para domínio %s (objeto=%s).", domain, salesforce_object)
+
+
+# ----------------------------------------------------------------------
+# search_cache
+# ----------------------------------------------------------------------
+class SearchCacheRepository:
+    """Operações sobre a tabela ``search_cache``.
+
+    É a camada RÁPIDA do módulo de Consulta (busca híbrida): um espelho
+    somente leitura de Account/Opportunity/Contrato/Item de Contrato,
+    sincronizado incrementalmente (ver ``src/salesforce/search_sync.py``).
+    Quando a busca não encontra nada aqui (ou o dado precisa estar fresco),
+    o serviço de consulta cai para o Salesforce ao vivo.
+    """
+
+    def __init__(self, client: TursoClient) -> None:
+        self._client = client
+
+    def upsert_registros(
+        self,
+        object_name: str,
+        registros: list[dict[str, Any]],
+        campo_nome: str = "Name",
+        campo_subtitulo: str | None = None,
+    ) -> int:
+        """Insere ou atualiza um lote de registros no cache de busca.
+
+        Args:
+            object_name: Nome da API do objeto (ex.: ``"Account"``).
+            registros: Lista de registros (dicionários vindos do Salesforce,
+                já sem o atributo ``attributes``).
+            campo_nome: Campo usado como nome de exibição (padrão ``Name``).
+            campo_subtitulo: Campo opcional usado como subtítulo (ex.: um
+                valor monetário ou o nome da conta relacionada).
+
+        Returns:
+            Quantidade de registros gravados.
+        """
+        if not registros:
+            return 0
+        agora = _agora_iso()
+        linhas = [
+            (
+                object_name,
+                str(reg.get("Id", "")),
+                str(reg.get(campo_nome) or reg.get("Id") or ""),
+                str(reg.get(campo_subtitulo)) if campo_subtitulo and reg.get(campo_subtitulo) is not None else None,
+                json.dumps(reg, ensure_ascii=False, default=str),
+                agora,
+            )
+            for reg in registros
+            if reg.get("Id")
+        ]
+        if not linhas:
+            return 0
+        self._client.execute_many(
+            """
+            INSERT INTO search_cache
+                (object_name, record_id, display_name, subtitle, payload_json, synced_at)
+            VALUES (?, ?, ?, ?, ?, ?)
+            ON CONFLICT(object_name, record_id) DO UPDATE SET
+                display_name = excluded.display_name,
+                subtitle = excluded.subtitle,
+                payload_json = excluded.payload_json,
+                synced_at = excluded.synced_at
+            """,
+            linhas,
+        )
+        logger.info("Cache de busca atualizado: %d registro(s) de %s.", len(linhas), object_name)
+        return len(linhas)
+
+    def buscar(self, object_name: str, termo: str, limite: int = 20) -> list[dict[str, Any]]:
+        """Busca no cache por trecho do nome de exibição (case-insensitive).
+
+        Returns:
+            Lista de dicionários ``{id, name, subtitle}`` (sem o payload
+            completo — use :meth:`buscar_por_id` para o detalhe).
+        """
+        termo_like = f"%{termo.strip()}%"
+        linhas = self._client.fetch_all(
+            """
+            SELECT record_id, display_name, subtitle
+              FROM search_cache
+             WHERE object_name = ? AND display_name LIKE ? COLLATE NOCASE
+             ORDER BY display_name
+             LIMIT ?
+            """,
+            (object_name, termo_like, int(limite)),
+        )
+        return [
+            {"id": l["record_id"], "name": l["display_name"], "subtitle": l.get("subtitle")}
+            for l in linhas
+        ]
+
+    def buscar_por_id(self, object_name: str, record_id: str) -> dict[str, Any] | None:
+        """Retorna o payload completo cacheado de um registro (ou None)."""
+        linha = self._client.fetch_one(
+            "SELECT payload_json, synced_at FROM search_cache WHERE object_name = ? AND record_id = ?",
+            (object_name, record_id),
+        )
+        if not linha:
+            return None
+        try:
+            payload = json.loads(linha["payload_json"])
+        except (json.JSONDecodeError, TypeError):
+            return None
+        return {"payload": payload, "synced_at": linha.get("synced_at")}
+
+    def contar(self, object_name: str) -> int:
+        """Quantidade de registros cacheados de um objeto."""
+        linha = self._client.fetch_one(
+            "SELECT COUNT(*) AS total FROM search_cache WHERE object_name = ?",
+            (object_name,),
+        )
+        return int(linha["total"]) if linha else 0

src/delivery/email_sender.py

@@ -22,8 +22,31 @@ from ..utils.logger import get_logger
 
 logger = get_logger("delivery.email")
 
+# ----------------------------------------------------------------------
+# Identidade visual (Penso) — paleta oficial da marca.
+# ----------------------------------------------------------------------
+# Cores "vivas" (uso em fundos/selos) e variantes escurecidas para texto
+# sobre fundo branco (mantém contraste de leitura sem perder a identidade).
+_PENSO_BLUE = "#0018FF"
+_BLUE_TECH = "#0004DD"
+_PENSO_BLACK = "#171717"
+_BLACK_INTENSE = "#060606"
+_SUCESSO = "#16C79A"
+_SUCESSO_TXT = "#0d8a6d"
+_ERRO = "#F05454"
+_ERRO_TXT = "#c62f2f"
+_ALERTA = "#FFC453"
+_ALERTA_TXT = "#a15c00"
+_DIVISORIA = "#E6EAEE"
+_HOVER = "#F7F8FA"
+
+# Logo do Salesforce (fonte de dados) — mesma URL pública já usada no painel React.
+_LOGO_SALESFORCE_URL = "https://upload.wikimedia.org/wikipedia/commons/f/f9/Salesforce.com_logo.svg"
+
 # Cores por severidade (usadas em selos/badges no e-mail HTML).
-_COR_SEVERIDADE = {"high": "#c0392b", "medium": "#e67e22", "low": "#f1c40f"}
+_COR_SEVERIDADE = {"high": _ERRO, "medium": _ALERTA, "low": "#94a3b8"}
+# Texto do selo: escuro sobre o Alerta (amarelo) para manter contraste; branco nos demais.
+_TEXTO_SEVERIDADE = {"high": "#ffffff", "medium": _PENSO_BLACK, "low": "#ffffff"}
 _ROTULO_SEVERIDADE = {"high": "ALTA", "medium": "MÉDIA", "low": "BAIXA"}
 
 
@@ -128,7 +151,7 @@ def _md_para_html(texto: str) -> str:
 # ----------------------------------------------------------------------
 # Blocos do e-mail HTML
 # ----------------------------------------------------------------------
-def _linha_kpi(rotulo: str, valor: str, destaque: str = "#1f4fb2") -> str:
+def _linha_kpi(rotulo: str, valor: str, destaque: str = _PENSO_BLUE) -> str:
     """Célula de KPI (rótulo + valor) para a grade de números-chave."""
     return (
         '<td style="padding:10px 14px;border:1px solid #e6e8eb;'
@@ -155,16 +178,16 @@ def _grade_kpis(metrics: dict[str, Any]) -> str:
             "Pipeline aberto",
             _moeda(opp.get("open_pipeline_product_value") or opp.get("open_pipeline_amount")),
         ),
-        _linha_kpi("Oportunidades ganhas", _num(opp.get("won_opportunities")), "#15803d"),
-        _linha_kpi("Oportunidades perdidas", _num(opp.get("lost_opportunities")), "#b91c1c"),
-        _linha_kpi("Oportunidades paradas", _num(opp.get("stalled_opportunities")), "#b45309"),
-        _linha_kpi("Tarefas vencidas", _num(tasks.get("tasks_overdue")), "#b45309"),
+        _linha_kpi("Oportunidades ganhas", _num(opp.get("won_opportunities")), _SUCESSO_TXT),
+        _linha_kpi("Oportunidades perdidas", _num(opp.get("lost_opportunities")), _ERRO_TXT),
+        _linha_kpi("Oportunidades paradas", _num(opp.get("stalled_opportunities")), _ALERTA_TXT),
+        _linha_kpi("Tarefas vencidas", _num(tasks.get("tasks_overdue")), _ALERTA_TXT),
     ]
     if sat.get("configured") and sat.get("responses"):
         celulas.append(_linha_kpi("Satisfação (nota média)", _num(sat.get("avg_score"))))
     if canc.get("configured") and canc.get("cancellations_count"):
         celulas.append(
-            _linha_kpi("Cancelamentos", _num(canc.get("cancellations_count")), "#b91c1c")
+            _linha_kpi("Cancelamentos", _num(canc.get("cancellations_count")), _ERRO_TXT)
         )
 
     # Distribui as células em linhas de 3 colunas.
@@ -199,6 +222,7 @@ def _bloco_alertas(alerts: list[dict[str, Any]]) -> str:
     for a in selecionados:
         sev = a.get("severity", "low")
         cor = _COR_SEVERIDADE.get(sev, "#94a3b8")
+        cor_texto_selo = _TEXTO_SEVERIDADE.get(sev, "#ffffff")
         rotulo = _ROTULO_SEVERIDADE.get(sev, "INFO")
         acao = a.get("recommended_action")
         acao_html = (
@@ -208,9 +232,9 @@ def _bloco_alertas(alerts: list[dict[str, Any]]) -> str:
             else ""
         )
         cartoes.append(
-            f'<div style="border-left:4px solid {cor};background:#f8fafc;'
+            f'<div style="border-left:4px solid {cor};background:{_HOVER};'
             f'padding:10px 14px;margin-bottom:10px;border-radius:0 8px 8px 0;">'
-            f'<span style="display:inline-block;background:{cor};color:#fff;'
+            f'<span style="display:inline-block;background:{cor};color:{cor_texto_selo};'
             f'font-size:10px;font-weight:700;padding:2px 8px;border-radius:10px;'
             f'letter-spacing:.04em;">{rotulo}</span> '
             f'<span style="font-weight:700;color:#0f172a;font-size:14px;">'
@@ -256,36 +280,59 @@ def _montar_html(
     corpo_ia = _md_para_html(resumo_ia) if resumo_ia.strip() else ""
     if corpo_ia:
         bloco_ia = (
-            "<div style='background:#eef4ff;border:1px solid #dbe5fb;border-left:4px solid #1f4fb2;"
+            f"<div style='background:{_HOVER};border:1px solid {_DIVISORIA};border-left:4px solid {_PENSO_BLUE};"
             "border-radius:10px;padding:14px 16px;margin:0 0 18px;'>"
-            "<div style='font-size:12px;color:#1f4fb2;font-weight:700;text-transform:uppercase;"
+            f"<div style='font-size:12px;color:{_PENSO_BLUE};font-weight:700;text-transform:uppercase;"
             "letter-spacing:.04em;margin-bottom:8px;'>🧠 Análise do dia</div>"
             f"{corpo_ia}"
             "</div>"
         )
+    # Cabeçalho: identidade visual da Penso (marca-texto) + Analytical-Force.
+    # TODO: quando o arquivo do logo real da Penso estiver disponível, trocar
+    # este bloco por um <img> com o PNG/SVG oficial (base64 ou hospedado).
+    # Por ora, usa apenas cores da marca (Penso Blue/Black) — sem inventar formas.
+    cabecalho = f"""\
+      <td style="background:linear-gradient(120deg,{_BLACK_INTENSE},{_BLUE_TECH} 55%,{_PENSO_BLUE});padding:26px 28px;">
+        <table role="presentation" cellspacing="0" cellpadding="0"><tr>
+          <td style="width:34px;height:34px;background:#ffffff;border-radius:9px;text-align:center;
+                     vertical-align:middle;font-weight:800;font-size:16px;color:{_PENSO_BLUE};">P</td>
+          <td style="padding-left:10px;color:#ffffff;font-size:13px;font-weight:700;letter-spacing:.03em;">PENSO</td>
+        </tr></table>
+        <div style="color:#ffffff;font-size:22px;font-weight:800;letter-spacing:.2px;margin-top:12px;">📊 Analytical-Force</div>
+        <div style="color:#dbe4ff;font-size:13px;margin-top:4px;">Relatório diário de performance comercial</div>
+        <span style="display:inline-block;margin-top:12px;background:rgba(255,255,255,.18);color:#ffffff;
+              font-size:12px;font-weight:600;padding:5px 12px;border-radius:999px;">📅 {_escape(report_date)}</span>
+      </td>"""
+    rodape = f"""\
+      <td style="background:{_HOVER};padding:16px 28px;border-top:1px solid {_DIVISORIA};">
+        <table role="presentation" cellspacing="0" cellpadding="0"><tr>
+          <td style="font-size:11px;color:#94a3b8;text-transform:uppercase;letter-spacing:.05em;padding-right:8px;">Fonte de dados</td>
+          <td><img src="{_LOGO_SALESFORCE_URL}" alt="Salesforce" style="height:14px;vertical-align:middle;" /></td>
+        </tr></table>
+        <div style="font-size:12px;color:#94a3b8;margin-top:10px;">
+          Relatório gerado automaticamente pelo agente <strong>Analytical-Force</strong> (Penso).
+          Os números são calculados em Python a partir do Salesforce; a interpretação
+          é gerada por modelo local. O relatório completo está anexado/registrado no sistema.
+        </div>
+      </td>"""
     return f"""\
 <div style="background:#f1f5f9;padding:24px 0;font-family:Arial,Helvetica,sans-serif;">
   <table role="presentation" width="640" align="center" cellspacing="0" cellpadding="0"
          style="max-width:640px;margin:0 auto;background:#ffffff;border-radius:12px;
-                overflow:hidden;border:1px solid #e2e8f0;">
+                overflow:hidden;border:1px solid {_DIVISORIA};">
     <tr>
-      <td style="background:linear-gradient(120deg,#0b3d91,#1f4fb2 58%,#3b82f6);padding:26px 28px;">
-        <div style="color:#ffffff;font-size:22px;font-weight:800;letter-spacing:.2px;">📊 Analytical-Force</div>
-        <div style="color:#dbe4ff;font-size:13px;margin-top:4px;">Relatório diário de performance comercial</div>
-        <span style="display:inline-block;margin-top:12px;background:rgba(255,255,255,.18);color:#ffffff;
-              font-size:12px;font-weight:600;padding:5px 12px;border-radius:999px;">📅 {_escape(report_date)}</span>
-      </td>
+{cabecalho}
     </tr>
     <tr>
       <td style="padding:24px 28px;">
-        <h3 style="font-size:14px;color:#0f172a;margin:0 0 10px;padding-left:10px;border-left:3px solid #1f4fb2;">Resumo executivo</h3>
+        <h3 style="font-size:14px;color:#0f172a;margin:0 0 10px;padding-left:10px;border-left:3px solid {_PENSO_BLUE};">Resumo executivo</h3>
         <p style="font-size:14px;color:#475569;margin:0 0 14px;line-height:1.55;">{resumo}</p>
         {bloco_ia}
 
-        <h3 style="font-size:14px;color:#0f172a;margin:22px 0 10px;padding-left:10px;border-left:3px solid #1f4fb2;">Números-chave</h3>
+        <h3 style="font-size:14px;color:#0f172a;margin:22px 0 10px;padding-left:10px;border-left:3px solid {_PENSO_BLUE};">Números-chave</h3>
         {_grade_kpis(metrics)}
 
-        <h3 style="font-size:14px;color:#0f172a;margin:22px 0 10px;padding-left:10px;border-left:3px solid #dc2626;">Principais alertas</h3>
+        <h3 style="font-size:14px;color:#0f172a;margin:22px 0 10px;padding-left:10px;border-left:3px solid {_ERRO};">Principais alertas</h3>
         {_bloco_alertas(alerts)}
 
         {_bloco_prioridades(alerts)}
@@ -294,13 +341,7 @@ def _montar_html(
       </td>
     </tr>
     <tr>
-      <td style="background:#f8fafc;padding:16px 28px;border-top:1px solid #e2e8f0;">
-        <div style="font-size:12px;color:#94a3b8;">
-          Relatório gerado automaticamente pelo agente <strong>Analytical-Force</strong>.
-          Os números são calculados em Python a partir do Salesforce; a interpretação
-          é gerada por modelo local. O relatório completo está anexado/registrado no sistema.
-        </div>
-      </td>
+{rodape}
     </tr>
   </table>
 </div>"""
@@ -369,6 +410,7 @@ _ROTULO_DESTAQUE = {
     "leads_sem_tarefa": "⏳ Leads sem 1ª tarefa",
     "oportunidades_travadas": "🚧 Oportunidades travadas",
     "oportunidades_ganhas": "🏆 Oportunidades ganhas",
+    "oportunidades_perdidas": "📉 Oportunidades perdidas",
     "cancelamentos": "❌ Cancelamentos",
     "satisfacoes_piores": "😟 Piores satisfações",
 }

src/query/__init__.py

@@ -0,0 +1,10 @@
+"""Camada de Consulta (busca somente leitura) do Analytical-Force.
+
+Diferente de ``analytics`` (que calcula métricas do pipeline diário), este
+pacote orquestra a busca/detalhe sob demanda de Contas, Oportunidades,
+Contratos e Itens de Contrato para o painel — usada pela tela de "Busca".
+"""
+
+from .search_service import TIPOS_VALIDOS, buscar, detalhar, status_tipos
+
+__all__ = ["TIPOS_VALIDOS", "buscar", "detalhar", "status_tipos"]

src/query/search_service.py

@@ -0,0 +1,212 @@
+"""Serviço de Consulta (busca híbrida) — camada de orquestração.
+
+Não calcula métricas nem gera relatório: apenas orquestra a busca de
+Account, Opportunity, Contrato e Item de Contrato para o painel, seguindo a
+estratégia HÍBRIDA definida para o projeto:
+
+1. Busca primeiro no cache do Turso (``search_cache``) — rápido.
+2. Se não encontrar nada, cai para consulta ao vivo no Salesforce (somente
+   leitura) e, quando encontra algo, grava o resultado no cache para
+   acelerar a próxima busca pelo mesmo termo.
+
+Esta é a ÚNICA camada que conhece o mapeamento "tipo lógico -> objeto do
+Salesforce". A API HTTP (``api.py``) nunca deve aceitar um nome de objeto
+arbitrário vindo do cliente — apenas um dos tipos em :data:`TIPOS_VALIDOS`,
+o que evita qualquer risco de injeção de SOQL pela camada web.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ..config.settings import Settings
+from ..database.repositories import SearchCacheRepository
+from ..database.turso_client import TursoClient
+from ..salesforce import search as sf_search
+from ..salesforce.client import SalesforceAuthError, SalesforceClient
+from ..utils.logger import get_logger
+
+logger = get_logger("query.search_service")
+
+# Tipos lógicos aceitos pela API — único ponto que traduz para o objeto real
+# do Salesforce. Nunca exponha nomes de objeto direto na API HTTP.
+TIPOS_VALIDOS: tuple[str, ...] = ("conta", "oportunidade", "contrato", "item")
+
+_ROTULOS = {
+    "conta": "Clientes (Account)",
+    "oportunidade": "Oportunidades",
+    "contrato": "Contratos",
+    "item": "Itens de contrato",
+}
+
+_TAMANHO_MINIMO_TERMO = 2
+
+
+def _mapa_objetos(settings: Settings) -> dict[str, str]:
+    """Mapa tipo lógico -> nome de API do objeto Salesforce."""
+    contrato = settings.contract_source or {}
+    return {
+        "conta": "Account",
+        "oportunidade": "Opportunity",
+        "contrato": contrato.get("object") or "Contrato_oPT__c",
+        "item": contrato.get("item_object") or "Item_do_Contrato__c",
+    }
+
+
+def status_tipos(settings: Settings) -> dict[str, Any]:
+    """Retorna os tipos de busca disponíveis e o estado da configuração.
+
+    Usado pela tela de Busca para exibir avisos (ex.: "vínculo com conta
+    não configurado") sem travar a funcionalidade principal.
+    """
+    contrato = settings.contract_source or {}
+    mapa = _mapa_objetos(settings)
+    return {
+        "tipos": [
+            {"tipo": tipo, "objeto": objeto, "rotulo": _ROTULOS.get(tipo, tipo)}
+            for tipo, objeto in mapa.items()
+        ],
+        "conta_do_contrato_configurada": bool(contrato.get("account_field")),
+        "itens_do_contrato_configurados": bool(contrato.get("item_parent_field")),
+    }
+
+
+def buscar(
+    settings: Settings,
+    turso: TursoClient,
+    sf_client: SalesforceClient,
+    termo: str,
+    tipos: list[str] | None = None,
+    limite: int = 20,
+) -> dict[str, list[dict[str, Any]]]:
+    """Busca híbrida: cache do Turso primeiro, Salesforce ao vivo como fallback.
+
+    Args:
+        termo: Texto buscado (mínimo 2 caracteres — evita varreduras amplas).
+        tipos: Subconjunto de :data:`TIPOS_VALIDOS` (``None`` = todos).
+        limite: Máximo de resultados por tipo.
+
+    Returns:
+        Dicionário ``{tipo: [{id, name, subtitle}, ...]}`` — tipos sem
+        resultado não aparecem na resposta.
+    """
+    termo = (termo or "").strip()
+    if len(termo) < _TAMANHO_MINIMO_TERMO:
+        return {}
+
+    mapa = _mapa_objetos(settings)
+    tipos_busca = [t for t in (tipos or TIPOS_VALIDOS) if t in mapa]
+    cache = SearchCacheRepository(turso)
+    resultado: dict[str, list[dict[str, Any]]] = {}
+
+    for tipo in tipos_busca:
+        objeto = mapa[tipo]
+        achados: list[dict[str, Any]] = []
+        try:
+            achados = cache.buscar(objeto, termo, limite)
+        except Exception as exc:  # cache não deve derrubar a busca
+            logger.warning("Falha ao consultar cache de %s: %s", objeto, type(exc).__name__)
+
+        if not achados:
+            # Fallback: Salesforce ao vivo (somente leitura).
+            try:
+                registros = sf_search.buscar_por_nome(sf_client, objeto, termo, limite)
+                achados = [
+                    {"id": r.get("Id"), "name": r.get("Name") or r.get("Id"), "subtitle": None}
+                    for r in registros
+                ]
+                if registros:
+                    # Alimenta o cache com o achado ao vivo (acelera a próxima busca).
+                    try:
+                        cache.upsert_registros(objeto, registros)
+                    except Exception as exc:
+                        logger.warning(
+                            "Falha ao alimentar cache de %s: %s", objeto, type(exc).__name__
+                        )
+            except SalesforceAuthError as exc:
+                logger.warning("Busca ao vivo falhou em %s: %s", objeto, exc)
+
+        if achados:
+            resultado[tipo] = achados
+
+    return resultado
+
+
+def detalhar(
+    settings: Settings,
+    turso: TursoClient,
+    sf_client: SalesforceClient,
+    tipo: str,
+    record_id: str,
+) -> dict[str, Any]:
+    """Detalhe completo de um registro (ao vivo; cache como último recurso).
+
+    Prioriza a consulta ao vivo para o DETALHE (mais sensível a estar
+    desatualizado do que a lista de busca); só usa o cache se o Salesforce
+    falhar (ex.: instabilidade momentânea da API).
+
+    Args:
+        tipo: Um dos :data:`TIPOS_VALIDOS`.
+        record_id: Id do registro no Salesforce.
+
+    Returns:
+        Dicionário com ``tipo``, ``objeto``, ``origem`` (salesforce/cache),
+        ``campos`` (lista ``{campo, valor}``) e, para contratos,
+        ``itens_do_contrato`` quando o vínculo estiver configurado.
+
+    Raises:
+        ValueError: Tipo inválido ou registro não encontrado em nenhuma fonte.
+    """
+    mapa = _mapa_objetos(settings)
+    if tipo not in mapa:
+        raise ValueError(f"Tipo de consulta inválido: {tipo!r}")
+    objeto = mapa[tipo]
+    cache = SearchCacheRepository(turso)
+
+    payload: dict[str, Any] | None = None
+    origem = "salesforce"
+    try:
+        payload = sf_search.detalhar_registro(sf_client, objeto, record_id)
+        if payload:
+            try:
+                cache.upsert_registros(objeto, [payload])
+            except Exception as exc:
+                logger.warning("Falha ao atualizar cache de %s: %s", objeto, type(exc).__name__)
+    except SalesforceAuthError as exc:
+        logger.warning("Detalhe ao vivo falhou em %s/%s: %s", objeto, record_id, exc)
+
+    if not payload:
+        cacheado = cache.buscar_por_id(objeto, record_id)
+        if cacheado:
+            payload = cacheado["payload"]
+            origem = f"cache (sincronizado em {cacheado.get('synced_at')})"
+
+    if not payload:
+        raise ValueError(f"Registro não encontrado: {objeto}/{record_id}")
+
+    resultado: dict[str, Any] = {
+        "tipo": tipo,
+        "objeto": objeto,
+        "origem": origem,
+        "campos": [
+            {"campo": campo, "valor": valor}
+            for campo, valor in payload.items()
+            if campo != "attributes" and valor is not None
+        ],
+    }
+
+    # Contrato -> lista os itens vinculados, se o campo de vínculo estiver configurado.
+    if tipo == "contrato":
+        contrato_cfg = settings.contract_source or {}
+        campo_pai = contrato_cfg.get("item_parent_field")
+        if campo_pai:
+            try:
+                itens = sf_search.listar_relacionados(sf_client, mapa["item"], campo_pai, record_id)
+                resultado["itens_do_contrato"] = itens
+            except SalesforceAuthError as exc:
+                logger.warning("Falha ao listar itens do contrato: %s", exc)
+                resultado["itens_do_contrato"] = []
+        else:
+            resultado["itens_do_contrato"] = None  # vínculo não configurado
+
+    return resultado

src/salesforce/search.py

@@ -0,0 +1,130 @@
+"""Consulta ao vivo (SOQL) para o módulo de Busca — somente leitura.
+
+Não participa do pipeline diário de métricas: é usado sob demanda pelo
+serviço de consulta (``src/query/search_service.py``) quando o cache do
+Turso não tem o registro procurado, ou quando o dado precisa estar fresco.
+
+Regra 3 do projeto (nunca inventar campos): a busca usa apenas ``Id``/``Name``
+(sempre presentes em qualquer objeto do Salesforce, padrão ou customizado) e
+o detalhe usa ``FIELDS(ALL)`` — os campos exibidos vêm do schema real da
+organização (descoberto em tempo de execução), nunca fixados no código.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from .client import SalesforceAuthError, SalesforceClient
+from ..utils.logger import get_logger
+
+logger = get_logger("salesforce.search")
+
+# Formato de Id do Salesforce (15 ou 18 caracteres alfanuméricos).
+_ID_VALIDO = re.compile(r"^[a-zA-Z0-9]{15,18}$")
+
+# Nome de objeto/campo de API do Salesforce: letras, números, "_" e "__c"/"__r".
+_NOME_API_VALIDO = re.compile(r"^[a-zA-Z][a-zA-Z0-9_]*$")
+
+_LIMITE_MAXIMO_BUSCA = 50
+_LIMITE_MAXIMO_DETALHE = 200  # teto exigido pelo SOQL ao usar FIELDS(ALL)/FIELDS(CUSTOM)
+
+
+def _escapar_termo(termo: str) -> str:
+    """Escapa aspas simples/barras para uso seguro em cláusula LIKE do SOQL."""
+    return (termo or "").replace("\\", "\\\\").replace("'", "\\'")
+
+
+def _validar_nome_api(nome: str, rotulo: str) -> str:
+    """Garante que ``nome`` é um identificador de API válido (objeto/campo).
+
+    Barreira contra injeção de SOQL nos poucos lugares em que o nome do
+    objeto/campo é interpolado diretamente na consulta (esses nomes vêm de
+    configuração interna — nunca de entrada livre do usuário).
+    """
+    if not nome or not _NOME_API_VALIDO.match(nome):
+        raise SalesforceAuthError(f"{rotulo} inválido para consulta: {nome!r}")
+    return nome
+
+
+def _validar_id(record_id: str) -> str:
+    """Garante que ``record_id`` tem o formato de um Id do Salesforce."""
+    valor = (record_id or "").strip()
+    if not _ID_VALIDO.match(valor):
+        raise SalesforceAuthError("Id inválido para consulta.")
+    return valor
+
+
+def buscar_por_nome(
+    client: SalesforceClient, objeto: str, termo: str, limite: int = 20
+) -> list[dict[str, Any]]:
+    """Busca registros de um objeto por trecho do campo ``Name`` (ao vivo).
+
+    Args:
+        client: Cliente Salesforce autenticado (somente leitura).
+        objeto: Nome de API do objeto (ex.: ``"Account"``, ``"Opportunity"``).
+        termo: Trecho buscado (aplica-se ``LIKE '%termo%'``).
+        limite: Máximo de registros retornados (até 50).
+
+    Returns:
+        Lista de registros (``Id`` e ``Name``). Vazia em caso de falha —
+        busca é uma funcionalidade auxiliar e não deve derrubar a tela.
+    """
+    _validar_nome_api(objeto, "Objeto")
+    termo_esc = _escapar_termo(termo)
+    limite = max(1, min(int(limite), _LIMITE_MAXIMO_BUSCA))
+    soql = f"SELECT Id, Name FROM {objeto} WHERE Name LIKE '%{termo_esc}%' LIMIT {limite}"
+    try:
+        return client.query(soql)
+    except SalesforceAuthError as exc:
+        logger.warning("Busca ao vivo falhou em %s: %s", objeto, exc)
+        return []
+
+
+def detalhar_registro(
+    client: SalesforceClient, objeto: str, record_id: str
+) -> dict[str, Any] | None:
+    """Retorna TODOS os campos populados de um registro (ao vivo).
+
+    Usa ``FIELDS(ALL)`` (SOQL, disponível a partir da API v58.0) — os campos
+    exibidos vêm do schema real da organização, nunca fixados no código.
+
+    Args:
+        client: Cliente Salesforce autenticado (somente leitura).
+        objeto: Nome de API do objeto.
+        record_id: Id do registro (validado antes de entrar na consulta).
+
+    Returns:
+        Dicionário de campos do registro, ou ``None`` se não encontrado.
+    """
+    _validar_nome_api(objeto, "Objeto")
+    rid = _validar_id(record_id)
+    soql = f"SELECT FIELDS(ALL) FROM {objeto} WHERE Id = '{rid}' LIMIT 1"
+    registros = client.query(soql)
+    return registros[0] if registros else None
+
+
+def listar_relacionados(
+    client: SalesforceClient,
+    objeto_filho: str,
+    campo_pai: str,
+    id_pai: str,
+    limite: int = 200,
+) -> list[dict[str, Any]]:
+    """Lista registros filhos vinculados a um pai por um campo de lookup.
+
+    Usado, por exemplo, para listar os Itens de um Contrato quando o campo
+    de vínculo (``SF_CONTRACT_ITEM_PARENT_FIELD``) estiver configurado.
+
+    Args:
+        objeto_filho: Nome de API do objeto filho (ex.: ``"Item_do_Contrato__c"``).
+        campo_pai: Nome de API do campo de lookup que aponta para o pai.
+        id_pai: Id do registro pai.
+        limite: Máximo de registros retornados (até 200, teto do FIELDS(ALL)).
+    """
+    _validar_nome_api(objeto_filho, "Objeto filho")
+    _validar_nome_api(campo_pai, "Campo de vínculo")
+    rid = _validar_id(id_pai)
+    limite = max(1, min(int(limite), _LIMITE_MAXIMO_DETALHE))
+    soql = f"SELECT FIELDS(ALL) FROM {objeto_filho} WHERE {campo_pai} = '{rid}' LIMIT {limite}"
+    return client.query(soql)

src/salesforce/search_sync.py

@@ -0,0 +1,117 @@
+"""Sincronização incremental do cache de busca (módulo de Consulta).
+
+Roda como etapa BEST-EFFORT do pipeline diário (chamada por
+``AnalyticalForceAgent.executar``): uma falha aqui nunca deve derrubar a
+execução principal. Usa ``LastModifiedDate`` para buscar apenas o que mudou
+desde a última sincronização (guardada em ``agent_config`` via
+``ConfigRepository``), paginando por ``OFFSET`` respeitando o limite de 200
+registros por página exigido pelo ``FIELDS(ALL)``.
+
+É a camada de escrita da busca HÍBRIDA escolhida para o projeto: o cache
+(Turso) responde rápido; quando não encontra, ``src/query/search_service.py``
+cai para consulta ao vivo no Salesforce.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ..config.settings import Settings
+from ..database.repositories import ConfigRepository, SearchCacheRepository
+from ..salesforce.client import SalesforceAuthError, SalesforceClient
+from ..utils.date_utils import agora_tz
+from ..utils.logger import get_logger
+
+logger = get_logger("salesforce.search_sync")
+
+_LOTE = 200  # teto de registros por página exigido pelo FIELDS(ALL)
+_MAX_REGISTROS_POR_OBJETO = 2000  # teto de segurança por execução/objeto
+_CHAVE_ULTIMA_SYNC = "search_sync_last_{objeto}"
+_DESDE_PADRAO = "2000-01-01T00:00:00Z"  # primeira sincronização: busca tudo (até o teto)
+
+
+def _consultar_alterados(
+    client: SalesforceClient, objeto: str, desde_iso: str
+) -> list[dict[str, Any]]:
+    """Busca (com paginação) os registros de ``objeto`` alterados desde ``desde_iso``."""
+    registros: list[dict[str, Any]] = []
+    offset = 0
+    while offset < _MAX_REGISTROS_POR_OBJETO:
+        soql = (
+            f"SELECT FIELDS(ALL) FROM {objeto} "
+            f"WHERE LastModifiedDate >= {desde_iso} "
+            f"ORDER BY LastModifiedDate ASC LIMIT {_LOTE} OFFSET {offset}"
+        )
+        try:
+            pagina = client.query(soql)
+        except SalesforceAuthError as exc:
+            # Objeto pode não existir na org (ex.: contrato customizado não
+            # aplicável) — registra e segue sem quebrar os demais objetos.
+            logger.warning("Sincronização de %s interrompida: %s", objeto, exc)
+            break
+        if not pagina:
+            break
+        registros.extend(pagina)
+        if len(pagina) < _LOTE:
+            break
+        offset += _LOTE
+    else:
+        logger.warning(
+            "Sincronização de %s atingiu o teto de segurança (%d); pode haver "
+            "registros pendentes para o próximo ciclo.",
+            objeto,
+            _MAX_REGISTROS_POR_OBJETO,
+        )
+    return registros
+
+
+def sincronizar_cache_busca(
+    client: SalesforceClient,
+    settings: Settings,
+    config_repo: ConfigRepository,
+    cache_repo: SearchCacheRepository,
+) -> dict[str, int]:
+    """Sincroniza incrementalmente Account/Opportunity/Contrato/Item no Turso.
+
+    Cada objeto é isolado: uma falha em um (ex.: objeto de contrato não
+    existe nesta org) não afeta a sincronização dos demais.
+
+    Args:
+        client: Cliente Salesforce já autenticado (reaproveitado da extração
+            principal — evita autenticar duas vezes na mesma execução).
+        settings: Configurações do agente (usa ``settings.contract_source``).
+        config_repo: Repositório de configuração (guarda o "desde quando"
+            de cada objeto).
+        cache_repo: Repositório do cache de busca (destino da gravação).
+
+    Returns:
+        Dicionário ``{objeto: quantidade_sincronizada}``.
+    """
+    contrato_cfg = settings.contract_source or {}
+    objetos: list[tuple[str, str, str | None]] = [
+        ("Account", "Name", None),
+        ("Opportunity", "Name", "StageName"),
+        (contrato_cfg.get("object") or "Contrato_oPT__c", "Name", None),
+        (contrato_cfg.get("item_object") or "Item_do_Contrato__c", "Name", None),
+    ]
+    agora_iso = agora_tz(settings.report_timezone).strftime("%Y-%m-%dT%H:%M:%SZ")
+    resultado: dict[str, int] = {}
+
+    for objeto, campo_nome, campo_subtitulo in objetos:
+        chave = _CHAVE_ULTIMA_SYNC.format(objeto=objeto)
+        try:
+            desde = config_repo.buscar_config(chave) or _DESDE_PADRAO
+            registros = _consultar_alterados(client, objeto, desde)
+            gravados = cache_repo.upsert_registros(objeto, registros, campo_nome, campo_subtitulo)
+            config_repo.salvar_config(
+                chave,
+                agora_iso,
+                descricao=f"Última sincronização do cache de busca de {objeto}.",
+            )
+            resultado[objeto] = gravados
+            logger.info("Cache de busca sincronizado: %s (%d registro(s)).", objeto, gravados)
+        except Exception as exc:  # objeto isolado — não derruba os demais
+            logger.warning("Falha ao sincronizar cache de %s: %s", objeto, type(exc).__name__)
+            resultado[objeto] = 0
+
+    return resultado