Analista — analistaNode e Desfecho por TIER

Para future Claude

Esta nota é um aprofundamento da seção "② analistaNode" e "③ Desfecho por TIER efetivo" do canvas Excalidraw (Mercado Livre Jornada) e da seção 5 do Mapa Geral. O analistaNode recebe o evento PRICE_CHANGE já emitido (ver Diagrama 5a) e decide o TIER efetivo antes de agir.

O diagrama

analistaNode — reúne dados, chama LLM, decide o TIER efetivo

1. PRICE_CHANGE chega com { itemId, diffPct, newPrice, competitor } (eventType ≠ PRICE_CHANGE → noop).
2. Reúne dados: getItem + getPriceToWin + loadItemCost. O custo vem do espelho MeliItem.cost no banco (o Mercado Livre não fornece custo). Falha de fetch → errorPatch (noop).
3. Chama a LLM com price_to_win, status, boosts, winner, current_price, cost, marginFloor (≈1,15× o custo) → retorna { recommendation, newPrice, reason, marginFloorRespected }.
4. resolveEffectiveTier: cost === null? marginFloorRespected === false? Se sim, força TIER_3. Se não, chama classifyTier('price_change', |diffPct|).
5. classifyTier classifica por magnitude: < 5% → TIER_1 (auto) · 5%–10% → TIER_2 (notifica) · > 10% → TIER_3 (aprovação).

Desfecho por TIER efetivo (outcome implementado)

TIER_1 — AUTO (executeAndAudit): updatePrice(itemId, newPrice), não notifica (mudança pequena), audit PRICE_CHANGE_AUTO. Output: { applied: true }.

TIER_2 — NOTIFY (executeAndAudit): updatePrice(itemId, newPrice) — já executa —, notifica o humano (notified: true), audit PRICE_CHANGE_NOTIFY. Output: { applied: true, notified: true }.

TIER_3 — APROVAÇÃO (handleTier3): dispara quando cost é null, a margem furou, ou |diffPct| > 10%. Não executa — createPendingApproval cria um pedido pendente, registrado em pendingApprovals[]. Output: { applied: false, approvalId }. O humano decide; a IA não toca no preço.

Regra-mãe (resolveEffectiveTier): custo desconhecido (MeliItem.cost null) ou margem furada sempre força TIER_3, independente do tamanho da mudança. A trava de margem protege contra vender abaixo do custo — só TIER_2 executa-e-notifica; TIER_3 espera aprovação antes de agir.

Tratamento de falha: em TIER_1/TIER_2, se updatePrice falhar → audit PRICE_CHANGE_FAILED + output { applied: false }. Falha de fetch, LLM ou parse antes da decisão → errorPatch (noop), nem chega a classificar o tier.