Mapa do Sistema

Status: ACTIVE | Ultima revisao: S152 (2026-03-30)

Arquitetura

DASHBOARD (browser) → HTTP/WS → SERVIDOR (VPS FastAPI) → HTTP polling 1-3s → EAs MT5 (MQL5)

Fluxo de Uma Implementacao

 IDEIA / BUG REPORT
      │
      ▼
 CLAUDE INVESTIGA
      │ ←── [100%] Guardian injeta patterns relevantes (59 ativos)
      │ ←── [100%] Spec-loader carrega docs por topico
      │ ←── [100%] Agent-router sugere subagent (VPS/EA/Dashboard)
      │
      ▼
 CLAUDE EDITA CODIGO
      │ ←── [100%] protect-specs.sh BLOQUEIA whitepapers sem aprovacao
      │ ←── [100%] frontend-lint.py BLOQUEIA globals soltos, CSS injection
      │ ←── [100%] af-stress-protocol.sh AVISA stress test se AF mudou
      │
      ▼
 CLAUDE COMMITA
      │ ←── [100%] validate-commit.sh BLOQUEIA:
      │       • Secrets no staged
      │       • Spec protegido sem [allow-spec]
      │       • .mqh mudou sem EA_BUILD++
      │       • Drift codigo ↔ spec (via spec-code-map.json)
      │       • 3+ arquivos codigo sem memory
      │
      │ ←── [100%] post-commit:
      │       • git push vps master (background)
      │       • sync-docs-vps.sh → specs mudados vao pro /guide
      │
      │ ←── [100%] post-commit-learn.sh sugere /learn se commit tipo fix:
      │
      ▼
 CLAUDE FAZ DEPLOY
      │ ←── [100%] pre-deploy-quality.sh BLOQUEIA se property tests falharem
      │ ←── [100%] protect-ea-deploy.sh BLOQUEIA cp/mv .ex5 direto
      │ ←── [100%] post-deploy-verify.sh checa saude apos deploy
      │
      ▼
 SESSAO TERMINA
      │ ←── [100%] auto-capture.py BLOQUEIA se licoes nao capturadas
      │ ←── [100%] verify-memory.sh verifica memoria salva
      │
      ▼
 PROXIMA SESSAO
      │ ←── [100%] Guardian com novo pattern aprendido
      └── CICLO SE REPETE (auto-melhoria continua)

Hierarquia de Garantias

Regra de ouro: Se algo precisa ser 100%, precisa de HOOK. Regra so no CLAUDE.md nao basta.

Hooks por Categoria

Bloqueantes (BLOCK — impedem a acao)

Alertas (WARN — avisam mas permitem)

Silenciosos (monitoram sem interferir)

Background (24/7 na VPS)

Ferramentas de Browser

Skills (invocadas manualmente ou por keyword)

Auto-Melhoria (ciclo Patterns)

Bug encontrado → /learn captura pattern → Guardian injeta na proxima sessao
     │                                              │
     │                                              ▼
     │                                    Claude evita repetir
     │                                              │
     └──── 3x repetido? → Promover pro CLAUDE.md ──┘

• 59 patterns ativos no Guardian
• 112 licoes no KnowledgeHub universal
• Feedback automatico: cada sessao alimenta scores dos patterns
• Lifecycle: patterns 50+ sessoes sem hit → candidatos a aposentar

Sistema de Qualidade

Status: ACTIVE | Ultima revisao: S194 (2026-04-06) — property tests atualizados (test_risk_engine.py), skills /rapid + /triage adicionadas (S192)

SSoT para: Scripts de qualidade, testes automaticos, monitoramento em producao
Relacionados: specs/debugging.md, specs/sweetspot-pilares.md

O que eh

Sistema de 3 camadas que previne e detecta problemas automaticamente:
1. Monitoramento — roda 24/7 na VPS, avisa no Telegram
2. Testes preventivos — roda antes de deployar, encontra bugs antes de irem pra producao
3. Testes de resiliencia — simula falhas pra ver se o servidor aguenta

Onde fica cada arquivo

scripts/quality/
  quality_monitor.py   <- Roda na VPS a cada 15min (cron)
  watchdog.py          <- Vigia se o monitor parou (cron cada 30min)
  invariant_check.py   <- Versao standalone dos invariantes (backup)
  reconcile.py         <- Versao standalone da reconciliacao (backup)
  fault_injection.py   <- Simula falhas (rodar manualmente)
  .state/              <- Arquivos de estado (heartbeat, dedup)

tests/property/
  test_pure_functions.py  <- 30 testes: volume, P&L, NaN, market hours
  test_risk_engine.py     <- 22 testes: risk, daily DD, OSB, dist/cush

.claude/hooks/
  pre-deploy-quality.sh   <- Hook: roda testes antes de SCP pro VPS

Camada 1: Quality Monitor (VPS, automatico)

O que faz

A cada 15 minutos, roda 9 queries SQL no banco verificando regras que nunca devem ser quebradas. Se alguma quebrar, manda Telegram.

Cron

*/15 * * * *  quality_monitor.py  (9 checks)
*/30 * * * *  watchdog.py         (vigia o monitor)

Os 9 checks

*Check 4 (stale_heartbeat) roda sempre mas com tolerancia adaptativa:
- Dia util (mercado aberto): alerta apos 15 minutos sem heartbeat
- FDS/fora de horario: alerta apos 30 minutos (cobre restarts de PC)

Alertas Telegram

• CRITICAL e HIGH: Telegram imediato (com dedup — mesma violacao 1x por hora)
• MEDIUM: Apenas no log (nao spamma Telegram)
• Cada alerta inclui o que fazer (ex: "Verificar se EA esta rodando no MT5")

Watchdog

O watchdog verifica se o quality_monitor esta rodando. Se o heartbeat file tiver mais de 30 minutos, avisa no Telegram: "Quality Monitor parou!"

Como adicionar um novo check

Editar quality_monitor.py, adicionar entrada no dict CHECKS:

"nome_do_check": {
    "description": "O que verifica em linguagem simples",
    "severity": "CRITICAL|HIGH|MEDIUM",
    "market_only": True|False,
    "action": "O que fazer quando violacao encontrada",
    "query": "SELECT ... FROM ... WHERE <condicao_de_violacao>"
}

Camada 2: Property Tests (local, antes do deploy)

O que faz

Extrai funcoes do servidor (sem precisar de banco de dados) e joga milhares de inputs aleatorios tentando quebrar. Se quebrar, mostra exatamente qual input causou o problema.

Como rodar

pytest tests/property/ -v       # Rodar todos (52 testes, ~30s)
pytest tests/property/ -q       # Resumido

Os testes

Nota S194: test_risk_engine.py refatorado — importa funcoes reais de app.af.engine (SSoT) em vez de manter copias locais (FakeProp/FakePA removidos, -154 linhas).

Hook pre-deploy (automatico)

Quando eu faco SCP de arquivo .py pro VPS, o hook pre-deploy-quality.sh roda automaticamente:
- Se testes passam → deploy prossegue
- Se testes falham → deploy BLOQUEADO com mensagem de erro

Camada 3: Fault Injection (manual, sob demanda)

O que faz

Manda requests "errados" de proposito pro servidor e verifica que ele nao crasha (retorna 500).

Como rodar

python scripts/quality/fault_injection.py --all        # Todos os 8 cenarios
python scripts/quality/fault_injection.py --scenario X  # Um cenario especifico
python scripts/quality/fault_injection.py --dry-run     # Mostra o que faria

Os 8 cenarios

Quando rodar

• Depois de mudar endpoints da API (signals, heartbeat, ack)
• Antes de deploy grande
• Quando desconfiar que algo pode crashar com input inesperado

Bugs encontrados ate agora

Metricas de eficacia

Copy Trade

Status: ACTIVE | Ultima revisao: S315.1 (2026-05-02) — Onda 5 cleanup: Etapa 4 aponta canonical (create_signal_canonical + dispatch_pending_to_eas). Detalhes em specs/signal-dispatch-canonical.md.

Versao: 2.3
Data: 2026-05-02
Status: v2.3 (S315.1 Onda 5): Etapa 4 atualizada — Signal+PendingSignal+TradeLink+SignalAck criados via create_signal_canonical() (SSoT em server/signal_dispatch.py). WS push pos-commit via dispatch_pending_to_eas() (substitui _push_signals_to_eas legacy, removido). Origin agora canonico via enum OriginType (lista exaustiva — ver specs/signal-dispatch-canonical.md). Fallback signal.origin or "ea" removido em ACK logging (signals legacy ficam origin=NULL, dashboard renderiza "(legacy)"). v2.2: Adicionado secao Trace ID. v2.1: EA remote logs pipeline, mapa de funcoes EA/servidor, ACK validation V1-V4, reconciliation pos-trade, grupo-only routing (S1015).
SSoT para: Ciclo completo de vida de um sinal — da deteccao ate o trade_link

Visao Geral

┌─────────────────────────────────────────────────────────────────────────────┐
│                          CICLO DE VIDA DE UM SINAL                         │
│                                                                            │
│  EA Master                Servidor                    EA Slave             │
│  ─────────               ─────────                   ─────────            │
│  1. Detecta trade ──WS/HTTP──> 2. Valida + armazena                       │
│     (OTT ou SE)                   Signal + PendingSignal                   │
│                                   + TradeLink (origin)                     │
│                                3. Distribui ──WS push──> 4. Recebe sinal  │
│                                   (aplica invert)   HTTP poll (safety net) │
│                                                      5. Executa via GUI   │
│                          6. Recebe ACK <──HTTP POST── 6. Envia ACK        │
│                             SignalAck + TradeLink                          │
│                             PendingSignal.resolved                         │
└─────────────────────────────────────────────────────────────────────────────┘

Etapa 1 — Deteccao de Trade (EA Master)

O EA tem 2 mecanismos paralelos que detectam trades. Ambos alimentam a mesma fila.

Mecanismo A: OnTradeTransaction (OTT) — instantaneo

Fase 1 (sempre executa, mesmo com g_busy=true):
- Armazena SE_DealHint via SE_StoreDealHint() com: positionId, symbol, entry (IN/OUT), closeReason (SL/TP/STOP_OUT/MANUAL), dealVolume, dealPrice
- TTL do hint: 10 segundos | Buffer: 10 hints max (SE_MAX_DEAL_HINTS)

Fase 2 (so se g_busy=false):
- Chama SnapshotEngine_ProcessCycle() + SnapshotEngine_FlushQueueWeb() imediatamente

Mecanismo B: SnapshotEngine (SE) — polling via timer

Logica de comparacao (SE_CompareSnapshots, linha 252):

Como decide OTT vs SE: No momento do enqueue, verifica SE_HasDealHint(ticket):
- Hint existe → detection_method = "OTT"
- Hint nao existe → detection_method = "SE"

Regra R1: Primeira execucao = baseline

Na primeira chamada, o SE apenas armazena o snapshot atual como g_se_prevSnap. Nenhum sinal e gerado. Isso evita que todas as posicoes existentes sejam reportadas como "novas" ao iniciar o EA.

Etapa 2 — Fila de Sinais (SE Queue)

Arquivo: SnapshotEngine.mqh

Regra R2: CLOSE tem prioridade maxima

CLOSE vai para o INICIO da fila (linha 364-377). OPEN e MODIFY vao para o final.

Regra R3: Deduplicacao

MODIFY ja existente na fila para o mesmo ticket: atualiza sl, tp, volume no lugar (nao duplica).

Regra R4: Fila cheia = descarte

Se fila tem 200 itens, novos sinais sao descartados com log [ALERTA] Fila CHEIA.

Etapa 3 — Envio do Sinal (EA → Servidor)

Arquivo: SnapshotEngine.mqh, funcao SnapshotEngine_FlushQueueWeb() (linha 424)

Cooldowns por tipo (independentes entre si)

Retry por item

Canal primario: WebSocket

Funcao: SE_SendSignalViaWS() (linha 389)

{
  "type": "signal",
  "action": "OPEN",
  "ticket": 123456,
  "symbol": "XAUUSD",
  "direction": "BUY",
  "volume": 0.10,
  "price": 2650.00,
  "sl": 2640.00,
  "tp": 2660.00,
  "close_reason": "",
  "signal_channel": "ws",
  "detection_method": "OTT",
  "queued_duration_ms": 15
}

Se WS_IsConnected() retorna false OU SE_SendSignalViaWS() falha → fallback imediato para HTTP.

Canal fallback: HTTP POST

Funcao: WebBridge_PostSignal() (WebBridge.mqh:686)
Endpoint: POST /api/signals
Headers: X-API-Key, X-Account-Num, Content-Type: application/json

Etapa 4 — Processamento no Servidor

Arquivo: /opt/copytrade-server/app/routes/signals.py
Endpoint: POST /api/signals

SSoT canonica (S314.6+, parcial — Onda 4 lifecycle pendente): Signal+PendingSignal+TradeLink+SignalAck sao criados via create_signal_canonical() em server/signal_dispatch.py (B7+B11 fix — single source) em rotas dashboard (broadcast_*) + AF engine 100% (af/signals.py + routes/af.py — S315.0). Master OPEN do endpoint EA POST /api/signals (batch insert ~linha 762) ainda usa sa_insert(Signal).values(signal_rows) batch insert manual (NAO o helper create_signal_canonical()) — sera migrado em Onda 4 lifecycle. Atualizacao S361 (doc-fresh): origin e signal_source JA usam enums canonicos (OriginType.EA.value / SignalSource.EA.value, linhas ~747/755), NAO mais strings cruas "ea"/"manual" — o drift R9 de string hardcoded foi resolvido; resta apenas o batch insert nao passar pelo helper unico. WS push pos-commit via dispatch_pending_to_eas(db, trade_group_id) 100% canonical em todos os paths. Detalhes completos + escopo Onda 4: specs/signal-dispatch-canonical.md.

Fluxo geral

1. Valida API key (X-API-Key → verify_api_key)
2. Identifica conta master pelo api_key
3. Processa conforme action

OPEN

1. Gera trade_group_id (UUID)
2. Calcula sl_distance = abs(price - sl), tp_distance = abs(tp - price)
3. Master: create_signal_canonical(origin=OriginType.EA, signal_source=SignalSource.EA, create_pending_signal=False, create_trade_link=True, is_origin_link=True, create_origin_ack=True) — cria Signal + TradeLink(is_origin=True) + SignalAck("ORIGIN") atomico
4. Busca peers do mesmo group_id (exceto master)
5. Para cada peer:
6. Se peer.invert != account.invert → caller aplica _invert_direction/_invert_sl_tp ANTES (R8: caller invert, canonical e agnostica)
7. create_signal_canonical(create_pending_signal=True, expires_in_seconds=PENDING_SIGNAL_TTL_SECONDS) — cria Signal + PendingSignal (TTL 60s)
8. Pos-commit: await dispatch_pending_to_eas(db, trade_group_id) faz WS push uniforme via _build_ws_payload (R11)

Regra R5: Circuit Breaker

Se conta slave tem >= CIRCUIT_BREAKER_MAX_POSITIONS (10) posicoes abertas, o OPEN e bloqueado para aquela conta.

MODIFY

1. Busca TradeLink ativo pelo ticket do master
2. Busca peers via trade_group_id
3. Verifica suppress_marker — se existe para trade_group_id + MODIFY, ignora (anti-echo)
4. Para cada peer: create_signal_canonical(action="MODIFY", ticket=local_ticket_do_peer, ...) — cria Signal + PendingSignal
5. Caller aplica inversao SL/TP ANTES (R8) se peer.invert != account.invert
6. Pos-commit: await dispatch_pending_to_eas(db, trade_group_id)

CLOSE

1. Busca TradeLink ativo pelo ticket
2. Late DEAL_PROFIT: Se TradeLink ja foi fechado pelo heartbeat (orphan closer), atualiza profit + close_price do link existente e retorna "profit_updated" (sem re-fechar)
3. Fecha TradeLink da conta master (is_closed=True, closed_at=now)
4. P&L Priority Chain:
5. deal_price do EA (preco exato de fill do deal) — prioridade maxima
6. deal_profit do EA (DEAL_PROFIT + COMMISSION + SWAP consolidado)
7. Fallback: OpenPosition cache (ultimo bid do heartbeat)
8. Fallback: position cache (posicao pre-close)
9. Fallback: zero
10. Busca peers via trade_group_id
11. Verifica suppress_marker — se existe para trade_group_id + CLOSE, ignora
12. Para cada peer aberto: create_signal_canonical(action="CLOSE", ticket=local_ticket_do_peer, ...) — cria Signal + PendingSignal
13. Cria SuppressMarker com TTL 10s para o trade_group_id (anti-echo servidor)
14. Trade Event Log: log_trade_event(event_type="CLOSE", close_reason, profit, close_price)
15. Pos-commit: await dispatch_pending_to_eas(db, trade_group_id)

Etapa 5 — PendingSignal (fila de distribuicao)

Tabela: pending_signals

Regra R6: TTL de 5 minutos

PendingSignal expira em 60s (1 min). Sinais OPEN nao executados sao auto-fechados pela background task (a cada 15s). Sinais MODIFY/CLOSE expirados sao marcados resolved=True pelo cleanup periodico (loop a cada 15min em main.py).

Regra R7: Cleanup manual disponivel

Endpoint POST /api/admin/cleanup/pending-signals para forcar limpeza.

Etapa 6 — Distribuicao (Servidor → EA Slave)

Via WebSocket push (instantaneo)

O servidor chama ea_ws_manager.notify_account(account_id, "new_signal") que envia o sinal completo via WS.

Via HTTP polling (safety net)

Endpoint: GET /api/signals/pending
Funcao EA: WebBridge_PollSignals() (WebBridge.mqh:760)

Regra R8: Dupla garantia WS + HTTP

O EA SEMPRE faz poll HTTP, mesmo com WS ativo. O WS acelera a entrega, o HTTP garante que nada se perde.

Retomada apos reconexao WS (v3.77+, S253 Onda 2)

Resume semantics — EA informa "ate onde ja processou":

• EA mantem g_ws_lastSignalId (long) persistido em MQL5/Files/ws_last_signal_id.txt
• Atualizado em LNC_MarkSignalProcessed (monotonic: so cresce)
• Enviado no auth payload: {"type":"auth", "api_key":"...", "account_num":"...", "last_signal_id":N}
• Servidor (_flush_pending_signals em ea_ws.py) filtra WHERE signal_id > last_signal_id

Por que: antes, ao reconectar, servidor re-enviava TODOS os pendings unresolved. Se EA ja processou via HTTP poll no intervalo (comum — HTTP 1-3s vencia WS reconnect 22s backoff na S252), o buffer circular g_processedSignalIds[100] protegia mas gerava log noise + trafego redundante.

Fail-open (backward compat):
- EA velho sem campo: last_signal_id=0 -> envia tudo (comportamento pre-S253 preservado)
- Arquivo corrompido: StringToInteger retorna 0 -> mesmo fallback
- Escrita em disco falha: global atualizado mas nao persistido -> proximo restart re-flusha (buffer 100 IDs protege)

Monotonic: WS_SetLastSignalId so aceita sigId > g_ws_lastSignalId. Evita regressao se LNC_MarkSignalProcessed receber IDs fora de ordem.

Paridade HTTP/WS em detect_missing_positions (v3.77+, S253 Onda 2)

_detect_missing_positions (detecta posicoes orfas comparando HB vs TradeLink) agora roda em AMBOS os paths:
- WS heartbeat (_handle_ws_heartbeat): desde S224+
- HTTP heartbeat (POST /api/heartbeat): desde S253 Onda 2 (antes: delay de 15min via orphan task)

Anti-race: Advisory lock Postgres (pg_try_advisory_lock(account_id)) impede concorrencia. Se WS path ja esta rodando, HTTP path skipa (nao-blocking). Evita double-close de posicao.

Etapa 7 — Execucao do Sinal (EA Slave)

Arquivo: Experts/LinniuC.mq5 + Include/CopyTrade/GUIExecution.mqh

Pre-execucao

OPEN (GUIExecution_Open, GUIExecution.mqh:765)

1. GUI_AcquireGUILock() — lock exclusivo em arquivo (TTL 30s para stale locks)
2. GUI_EnsureVisible() — restaura MT5 se minimizado
3. GUI_CloseAllMT5Dialogs() — fecha dialogos residuais
4. GUI_OpenF9() — WM_COMMAND 32848 abre dialogo "Nova Ordem"
5. GUI_WaitForDialog() — timeout InpTimeoutMs (5000ms)
6. GUI_SelectSymbol() — seleciona simbolo no combo (ID 10331)
7. GUI_WaitForSubDialog() — aguarda controles carregarem
8. Preenche volume (10333), SL (10334), TP (10336)
9. Clica BUY (10408) ou SELL (10409)
10. Loop de confirmacao: aguarda dialogo fechar OU detecta popup do broker
11. GUI_TryConfirmBrokerPopup() — confirma popups (leverage, risk) ou detecta erros (failed, insufficient)

Pos-execucao:
- GUIExecution_DetectNewTicket() — compara lista de posicoes antes/depois
- Fallback: SE_FindRecentOpenDeal() usa DealHint do OTT
- SE_SuppressTicket(newTicket, 5) — suprime re-deteccao por 5s (Pattern #34, S84)

MODIFY (GUIExecution_Modify, GUIExecution.mqh:844)

1. GUI_AcquireGUILock()
2. GUI_OpenPositionDialogSafe(ticket) — localiza na ListView (10328), duplo-clique
3. GUI_VerifyDialogTicket() — verifica titulo contem ticket esperado
4. Seleciona "Modificar" no ComboBox de tipo (10338)
5. Aguarda botao Modificar (10351) aparecer
6. Preenche SL e TP, clica Modificar
7. SE_SuppressTicket(localTicket, 10) — suprime por 10 segundos

CLOSE (GUIExecution_Close, GUIExecution.mqh:948)

1. GUI_AcquireGUILock()
2. GUI_EnsureVisible()
3. Ate 3 tentativas com GUI_ForceCloseResidualDialogs() entre elas
4. GUI_OpenPositionDialogSafe(ticket) — ListView → duplo-clique
5. Clica botao Close (10410)
6. Loop aguarda fechamento
7. SE_SuppressTicket(localTicket, 10) — suprime por 10 segundos

Etapa 8 — ACK (EA Slave → Servidor)

Arquivo: WebBridge.mqh:808
Endpoint: POST /api/signals/{signalId}/ack

Payload

{
  "status": "FILLED|FAILED|SKIPPED",
  "local_ticket": 789012,
  "error_msg": "",
  "open_price": 2650.12,
  "applied_sl": 2640.00,
  "applied_tp": 2660.00,
  "actual_volume": 0.10,
  "receive_channel": "ws_push|http_poll",
  "gui_duration_ms": 1450
}

Status possiveis

Retry do ACK

O que o servidor faz com o ACK

1. Cria/atualiza SignalAck com todos os campos
2. Se FILLED: cria TradeLink com is_origin=False, local_ticket do slave
3. Marca PendingSignal.resolved=True
4. Push WS para dashboard
5. MODIFY ACK (v2.0): Captura applied_sl vs target_sl, applied_tp vs target_tp — mostra divergencia entre o que foi pedido e o que o broker aplicou
6. Trade Event Log: log_trade_event(event_type="ACK", status, action="OPEN"|"MODIFY", context)

Delay Audit Fields (v2.0)

Exec Slippage Fields (v2.4 — S336+)

Capturados pelo EA via SymbolInfoTick() 1 linha antes de GUIExecution_Open/Close/Modify. Servidor calcula slippages no handler ACK. Backwards-compat: ACKs pre-S336 (EA build < 3.85.3) tem campos NULL.

Lados da cotacao (R2):
- OPEN BUY -> ASK (compra ao ASK)
- OPEN SELL -> BID (vende ao BID)
- CLOSE BUY -> BID (vende pra fechar)
- CLOSE SELL-> ASK (compra pra fechar)
- MODIFY -> guarda bid+ask pra audit (saber se preco passou pelo SL/TP em transito), exec_slip = NULL

Tag close_reason="ROLLOVER" (Layer 1 EA anti-swap): Rollover_TryClose chama Rollover_TagTicket antes do GUI close; SnapshotEngine override close_reason -> "ROLLOVER" em vez de "MANUAL" (default DEAL_REASON_CLIENT). Distingue de Layer 2 servidor (close_reason="ROLLOVER_FALLBACK" via close_pair_positions).

Spec completa: specs/exec-slippage-telemetria.md.

Etapa 9 — TradeLink (vinculo master-slave)

Tabela: trade_links

Regra R9: trade_group_id e o elo

Todo MODIFY e CLOSE usa o trade_group_id para encontrar quais slaves precisam ser notificados. Sem TradeLink = sinal nao propaga.

Caminhos Alternativos e Edge Cases

EC1: Falha de WebSocket

EC2: Orphan Checker (posicoes orfas) — 2 mecanismos

Mecanismo A — Background task (ativo):

Mecanismo B — Heartbeat passivo (v2.0):

Mecanismo B detecta closes mais rapido que A (dentro de 1 heartbeat vs 15min).

EC3: Anti-Echo (2 niveis)

Problema: EA slave executa um trade → SnapshotEngine detecta como "novo" → reenvia ao servidor → loop infinito.

Nivel 1 — EA (SE_SuppressTicket):

Buffer: g_se_suppressTickets[] (max 20). Antes de enfileirar MODIFY ou CLOSE, verifica SE_IsTicketSuppressed().

Nota: SE_MAX_RETRIES define 5 em SnapshotEngine.mqh:43, mas FlushQueueWeb usa hardcoded >= 10. O valor efetivo e 10 retries.

Nivel 2 — Servidor (suppress_markers):

Nota (v2.0): Implementacao atual usa 10s para TODAS as origens (EA e dashboard). A diferenciacao 10s/15s documentada na v1.0 nao foi implementada.

Quando master envia MODIFY/CLOSE, servidor verifica se existe marker ativo → ignora (evita loop).

EC4: Partial Close

• Detectado pelo SE como mudanca de volume: abs(curr.volume - prev.volume) > 0.0001
• Enfileirado como MODIFY com close_reason = "PARTIAL_CLOSE"
• Servidor distribui como MODIFY normal (atualiza volume nos peers)

EC5: Posicao ja fechada no CLOSE

• EA slave recebe CLOSE mas PositionSelectByTicket() retorna false
• Envia ACK FILLED direto (posicao ja nao existe — nada a fazer)

EC6: Signal do Dashboard (broadcast)

• Endpoint separado do EA-to-EA
• Broadcast-open: cria sinal para TODAS as contas ativas do grupo
• Broadcast-modify: busca TradeLink e distribui para peers
• Inversao: usa if acct.invert (sem comparar com outra conta, diferente do EA-to-EA)

Estado Afogado + Visibilidade de Saturacao (S386, v2.4)

NAO altera as regras R1-R10 acima. Adiciona 3o estado de conta entre alive e offline + 2 guardas no dispatch (dedup #330 + back-pressure SKIP). Invariante S2-zero-sum de hedge preservado por construcao.

Nota: as referencias a "invariante S2-zero-sum" abaixo apontam pra regra interna do modulo saturation.py — NAO confundir com a R2 deste documento ("CLOSE tem prioridade maxima").

Problema: o EA executa ordens via cliques de GUI Win32 (GUIExecution.mqh), seriais, no MESMO OnTimer que envia batimento. Quando a tela ocupa o laco, o batimento estica e o servidor fica cego — sem saber distinguir "EA morreu" de "EA esta ocupado executando". Pior: o servidor reemitia CLOSEs do mesmo ticket em loop (classe do #330) achando que o EA nao recebeu.

Solucao: 3o estado saturated + dedup in-flight + back-pressure SKIP. Modulo central: server/saturation.py (3 funcoes puras + store in-memory).

Estados de conta

Backstop: mesmo sem beacon (EA velho/travou), inferencia por ritmo marca saturated se gap > 15s com pendente.

Regra R11: Beacon ea_busy (EA → Servidor, dispara-e-esquece)

EA dispara frame WS {"type":"ea_busy","op":<OPEN|MODIFY|CLOSE>,"ticket":<n>,"expected_ms":<n>} IMEDIATAMENTE APOS pegar o lock de GUI (GUI_AcquireGUILock em GUIExecution.mqh), antes do trabalho lento de tela (GUI_EnsureVisible, GUI_ExecuteOpenInternal). Se o lock falhar, o beacon NAO eh enviado. Dispara-e-esquece — sem retry, sem ACK queue, timeout <=200ms. Handler servidor: routes/ea_ws.py::_handle_ws_ea_busy -> saturation.set_busy(account_id, op, ticket). Beacon explica silencio longo (gap > 60s mas conta esta saturated, nao offline).

Regra R12: Dedup in-flight (mata classe do #330 na origem)

Antes de criar PendingSignal pra (conta, ticket, action=CLOSE), signal_dispatch.create_signal_canonical checa se ja ha pendente NAO-resolvido (sem ACK, dentro do TTL) pro mesmo (conta, ticket) -> pula + emite evento DISPATCH_DEDUP + retorna skipped_duplicate=True, skip_reason="dedup_inflight_close". Excecao: ACK FAILED do EA resolve o pendente legado MAS cria retry-PS novo (+70s) — dedup AINDA suprime re-CLOSE server-originated enquanto retry-PS estiver em-voo (correto, anti-#330: nao empilhar enquanto o retry do EA esta pendente). Liberacao real: FILLED, 3 retries exauridos, OU TTL expirou. Escopo: SO CLOSE (idempotente). MODIFY fica com a supressao anti-echo do SuppressMarker (descrita acima nas regras de processamento server-side) + dedup da fila do EA.

Regra R13: Back-pressure por SKIP (hedge gating)

Gating primario em af/signals.py::check_all_online_in_pool (sync+async): conta saturated NAO entra em round novo, mesmo com HB fresco. Reason: "saturated (afogada — GUI gargalo, fora de round novo)". Filtra antes do generate_signals_for_pair/scheduler.

Defesa em profundidade em signal_dispatch.create_signal_canonical: antes do PendingSignal create, consulta should_hold_dispatch(state, action, is_completing_hedge_leg, is_existing_position_op). Se True -> skip + evento DISPATCH_HELD + retorna skipped_duplicate=True, skip_reason="held_saturated".

Invariante S2-zero-sum (CRITICO, regra do modulo saturation.py): should_hold_dispatch retorna False (passa direto) se:
- is_completing_hedge_leg=True (perna que completa par ja aberto — naked leg = quebra zero-sum)
- action in (CLOSE, MODIFY) ou is_existing_position_op=True (mexe posicao broker existente)

Sobra apenas OPEN novo independente em conta saturated como alvo do skip.

Abort do par (HR-iter2-01, race protection): em generate_signals_for_pair (af/signals.py), apos master canonical: se master_result.skip_reason == "held_saturated" (race entre check_all_online e dispatch) -> db.rollback() + raise ValueError. Caller main.py af_scheduler tem except ValueError que loga warning + nao marca pair.status='failed' (proxima rodada reavalia). Slave nunca abre sozinho.

Trade-off honesto: Hold = SKIP, nao ADIA. Signal record fica pra audit, mas sem PendingSignal e sem retry server-side. Quando conta sai de saturated, proximo signal natural (proxima rodada AF / novo broadcast) reentra. Retry temporizado dedicado fica como TODO S386-FU2 (sweetspot inicial confia no fluxo upstream — gating primario cobre 99%).

Visibilidade

• Dashboard: selo "AFOGADO" amarelo distinto de offline em 4 superficies (overview compact + Cadastros full + modal detalhe + tooltip Telegram), com sync inicial + WS-update em TODAS.
• REST: GET /api/accounts retorna account_state na carga inicial (evita janela ~10s F5 sem badge).
• Telegram: alert_ea_saturated edge-trigger + market-hours + dedup (50s) descreve as 4 salvaguardas (distingue, nao reemite CLOSE, fora de round novo, PULA OPEN novo).
• Eventos: DISPATCH_DEDUP, DISPATCH_HELD em trade_events/signal_events. ea_saturated no canal de alertas.

Arquivos-chave

• server/saturation.py — 3 funcoes puras (classify_state, should_dedup_dispatch, should_hold_dispatch) + store in-memory + helpers ingest_pulse/set_busy/clear_busy/get_state/reset_state.
• server/heartbeat_helpers.py — ingestao do pulso enriquecido + broadcast account_state no WS.
• server/signal_dispatch.py — wire dedup + hold + skip_reason no canonical.
• server/af/signals.py — check_all_online_in_pool (sync+async) filtro saturated + 8 callsites com flags is_completing_hedge_leg / is_existing_position_op + abort do generate_signals_for_pair se master held.
• server/routes/ea_ws.py — handler frame ea_busy.
• server/routes/accounts.py — REST initial state + reset_state em hard delete.
• Include/CopyTrade/WinHttpWS.mqh — WS_SendHeartbeat enriquecido (queue_depth, busy_*, oldest_age_ms) + WS_SendBusyBeacon dispara-e-esquece.
• static/js/{overview,positions,websocket}.js — selo AFOGADO + sync WS.

Specs relacionados

• specs/saturacao-visibilidade-gui-S386.md — spec autocontida (Tier L, sweetspot 3 pilares + Fase 4 hedge gating).
• .planning/PLAN-S386-saturacao-visibilidade-gui.md — plano atomico (5 fases).

Sinais AF (AutoFund Hedge) — Canal Isolado (v2.0)

O sistema AF gera sinais que usam a mesma infraestrutura (Signal, PendingSignal, TradeLink) mas com isolacao total do copy-trade normal.

Signal Channel

AF Signal Types

Isolacao (anti-broadcast)

Mecanismo A — AF Pending Linkage: Quando conta re-detecta sua propria execucao AF (via SE/OTT), servidor reconhece signal_channel='af' no PendingSignal, vincula TradeLink sem criar broadcast novo, auto-ACK como FILLED.

Mecanismo B — Pool Active Suppression: Se conta esta em pool AF ativo/pausado, OPEN cria signal + auto-ACK com status='ORIGIN', define signal_channel='af', retorna 'af_pool_suppressed'. Peers NAO recebem.

P19 (CRITICO): Sem esta isolacao, sinais AF propagariam para TODAS as contas do grupo. Bug causou 63 posicoes e -$46k.

AF signals bypass

• SEM circuit breaker check (AF tem proprios limites de risco)
• SEM invert aplicado (AF usa mapeamento master/slave direto)
• SEM sl_distance/tp_distance (SL/TP sao absolutos, nao delta)

Reconciliation Post-Offline (S300)

Mecanismo retroativo que recupera profit/close_price quando o EA volta de
janela offline durante a qual o broker fechou posicoes (SL hit, manual close,
margin call). Causa raiz coberta: profit_source=none em _detect_missing_positions
ao detectar ticket sumido (3 fallbacks retornavam None → profit gravado=0 →
AfPair classificada erroneamente como pnl_suspect).

Caminho retroativo via HistorySelect (3 trigger points no EA)

Include/CopyTrade/ReconcileEngine.mqh — modulo:
- RE_FetchOpenTradeLinks: GET /api/ea/open-tradelinks retorna lista de tickets que o servidor ainda considera abertos.
- RE_ScanHistory: HistorySelect(from_time, now) + filtra DEAL_ENTRY_OUT cujo DEAL_POSITION_ID ∈ open_tickets.
- RE_EnqueueRetroactive: POST /api/signals com is_retroactive=true + profit consolidado (R4: DEAL_PROFIT + DEAL_SWAP + DEAL_COMMISSION) + deal_price.
- Mutex g_reconcile_running (R10) impede multi-trigger concorrente.
- Checkpoint local MQL5/Files/reconcile_checkpoint_<account>.txt (R11) reduz custo de scan na N-esima execucao. Primeiro run varre ate 7d atras.

Idempotency Contract (R6)

signals.is_retroactive BOOLEAN NOT NULL DEFAULT FALSE + index parcial:

CREATE UNIQUE INDEX ix_signals_retroactive_unique
  ON signals (source_account, ticket, action)
  WHERE is_retroactive = TRUE;

Garante: 1 retroactive por (conta, ticket, action). Multi-trigger seguro — segunda chamada bate no IntegrityError ou no SELECT prefix-check, retorna skipped_idempotent. Signals normais (is_retroactive=false) NAO sao afetados pelo index.

Override broker-canonical com tolerancia $0.01

_process_retroactive_close em routes/signals.py:
1. Idempotency check (R6): SELECT existing → skip silent.
2. Sanity check (R28): validate_retroactive_profit(profit, balance) → |profit| > 2*balance rejeita 422 + Telegram alert.
3. Tolerance check (R5): |old_profit - new_profit| < $0.01 → skip silent (sem audit churn).
4. Override absoluto: link.profit = data.profit; link.close_price = data.deal_price. Broker eh fonte canonica.
5. Audit: log_trade_event(origin='reconcile_retroactive') com before/after profit + delta.
6. Re-validate: atualiza AfTrade.profit do lado; se ambos lados tem profit, chama process_trade_result(pair_id, profit_a, profit_b).

Sanity gate (R28 — defesa adversarial)

validate_retroactive_profit(profit, balance) em af/engine.py:
- balance <= 0 → reject balance_invalid
- |profit| > 2 * balance → reject absurd_value
- caso contrario → ok

Tests cobrem 11 cenarios (5 ex + 3 inv + 3 property-based via Hypothesis em test_reconcile_retroactive.py).

Watchdog 5min + market hours (R8 + R9)

Coroutine async em main.py:_watchdog_offline_with_trade():
- Tick 60s. Lista accounts com TradeLink open.
- Compara max(Heartbeat.created_at) com NOW(). age > 300s E acc ∈ TradeLink open → alert candidato.
- Edge-trigger via dict _watchdog_alerted — alerta dispara 1x na transicao online→offline. Reset com heartbeat fresco.
- R9 market hours: is_market_open(symbol) cruzado antes de alertar (suprime weekend/rollover).
- Telegram via send_watchdog_offline_with_trade com debounce 60s.

Limitacao conhecida

Reconcile cobre apenas CLOSE retroativo. Se EA estava offline durante OPEN, pair vira failed/timeout e nao eh recuperavel via reconcile. Exemplo: Pair 81 (Round 21) — af_trades.status='timeout' sem ACK de OPEN, fix via SQL manual em S299 (CA-8).

Spec autocontida (referencia)

specs/reconciliacao-pos-offline.md — 14 casos de borda, 11 regras, 27 riscos, prior art externo (MQL5 Article #11248, HistorySelect docs). Status: APROVADO (S299) → IMPLEMENTADO (S300).

SL/TP Reconciliation via Heartbeat (v2.0)

Mecanismo server-side que detecta e corrige divergencias de SL/TP entre peers.

Trade Event Log — Diario de Bordo (v2.0)

Todo evento significativo eh registrado na tabela TradeEvent para auditoria completa.

Funcao: log_trade_event(db, event_type, ...)

Pontos de captura

Trace ID — Rastreabilidade Ponta-a-Ponta (S224+)

Analogia: O trace_id e como o numero de rastreio de uma encomenda. Cada sinal recebe um codigo unico no momento em que nasce, e esse codigo acompanha TODOS os passos — da deteccao no EA master ate o ACK do EA slave e a timeline no dashboard. Se algo deu errado, basta buscar o trace_id pra ver exatamente onde parou.

Geracao

Propagacao por Etapa

Event Types Rastreados (19+)

O EventLog (EventLog.mqh) emite eventos em cada passo da execucao GUI:

Cada event type tem variante _ok e _fail (ex: gui_s5_ok, gui_s5_fail).

Backward Compatibility

Consultas no Dashboard

Specs Relacionados

• specs/ea-observability.md — Event sourcing hibrido, buffer persistente, idempotencia (12/12 CAs)
• specs/telemetria-sweetspot.md — Gap detection, anomaly detector, Telegram alerts (9/11 CAs)

Arquivos-Chave

Pipeline de Logs Remotos do EA (S1015)

O EA envia logs pro servidor via heartbeat. Pipeline completo:

EA (MQL5)                              Servidor (Python)
─────────                              ─────────────────
LNC_LogRemote(msg)
  → g_logBuffer[100] (circular)
  → LNC_BuildLogJSON()
  → heartbeat body: "last_logs": [...]
                                       POST /api/heartbeat
                                         → heartbeat.py:385-418
                                         → dedup (5min window por account)
                                         → INSERT ea_remote_logs
                                         → level auto-detect:
                                           "ERROR"/"FAIL"/"FALHOU" → ERROR
                                           "WARN"/"SKIP"           → WARN
                                           else                    → INFO

                                       GET /api/heartbeat/diagnostics
                                         → recent_logs (20 ultimas)
                                         → recent_errors (10 ultimas, level=ERROR)

                                       Cleanup: TTL 7 dias (main.py startup)

Eventos Logados pelo EA (28 tipos)

gui_trace Formato

TAB:0|C1d:rows=1|SEL:0|F9:ok|DLG:found|SYM:set|DIR:set|VOL:set|SLTP:set|PLACE:ok

Cada passo da execucao GUI separado por |. O ultimo passo indica onde parou se falhou.

Queries Uteis

-- Ultimos 30 logs de uma conta
SELECT message, level, created_at FROM ea_remote_logs
WHERE account_id = X ORDER BY created_at DESC LIMIT 30;

-- Erros das ultimas 24h
SELECT account_id, message, created_at FROM ea_remote_logs
WHERE level = 'ERROR' AND created_at > NOW() - INTERVAL '24 hours'
ORDER BY created_at DESC;

-- GUI traces (buscar passos que falharam)
SELECT message FROM ea_remote_logs
WHERE account_id = X AND message LIKE '%gui_trace%'
ORDER BY created_at DESC LIMIT 10;

Mapa de Funcoes EA - Servidor (S1015)

EA: Experts/LinniuC.mq5

EA: Include/CopyTrade/WebBridge.mqh

EA: Include/CopyTrade/GUIExecution.mqh

Servidor: Endpoints Principais

ACK Validation V1-V4 (S1015)

Checks automaticos no handler de ACK (HTTP + WS):

Implementado em validate_ack_data() (signals.py), chamado por ambos handlers (HTTP e WS).

Reconciliation Pos-Trade

Apos ambos ACKs de um par AF (_af_ack_count >= 2):
- reconcile_af_pair() verifica: 2 trades, tickets diferentes, direcoes opostas, volumes iguais, open_price > 0
- Se falha: alerta Telegram + bloqueia MODIFY scheduling

EC-Test: Variante de Injecao de Sinais de Teste (Phase C — S219)

Endpoint: POST /api/test/inject (so disponivel quando TEST_INJECTION_ENABLED=true)
signal_source: "test" (vs "ea" no fluxo normal)

O lifecycle normal comeca na Etapa 1 (deteccao de trade no EA master). A injecao de teste entra direto na Etapa 4 (processamento no servidor), pulando as etapas 1-3:

Diferencas vs fluxo normal

Regra R10 — Isolamento de teste

R10: Sinal signal_source='test' NUNCA distribui para conta is_test=false.
- O handler valida que account.is_test=True antes de criar qualquer PendingSignal.
- Nao ha broadcast de group_id — so a conta alvo recebe.
- Invariant CA-7/R1: COUNT(*) FROM pending_signals JOIN signals JOIN accounts WHERE signal_source='test' AND is_test=false = 0 SEMPRE.
- Conta 52 (Teste Sandbox) esta em blocked_account_ids do pairing AF — nunca entra em round real.

Etapas equivalentes pos-Etapa 4

A partir da distribuicao (Etapa 5), o fluxo e identico ao normal:
- PendingSignal criado → EA da conta 52 polls/recebe WS → executa via GUI automation → ACK volta com ticket real
- signal_source='test' preservado em todos os registros (Signal, SignalAck, TradeLink)
- Dashboard filtra sinais test por default (include_test=false em /api/signals/history e /api/accounts)

Ativacao

O endpoint so existe quando TEST_INJECTION_ENABLED=true (env). Em producao fica false — qualquer chamada retorna 404.
Isolamento via porta: o runner de testes sobe uvicorn :8001 --lifespan off separado do prod :8000.

Carteiros

Status: ACTIVE | Ultima revisao: S342 (2026-05-12) — trio carteiro fechado

3 carteiros canonicos cobrem o ciclo de vida completo de cada sinal de trade.
Cada um eh um helper unico ("1 cabeca, varias bocas") — wrappers HTTP e WS
finos delegam toda a logica pro mesmo helper, eliminando drift por construcao.

Visao geral — quem faz o que

Fluxo end-to-end

[Dashboard/Master EA]
      |
      | (1) cria sinal
      v
+---------+        sinal       +-----+
|   IDA   |  ---- via WS  ---> |  EA |
+---------+      ou HTTP       +-----+
      ^                          |
      |                          | (2) executou (ou falhou)
      | broadcast WS             v
      |                       +---------+
      +---------------------- |  VOLTA  |
                              +---------+

   [PLANTAO roda em paralelo, sempre — 10s ou 30s]
   +-----------+   HB telemetria   +-----+
   |  PLANTAO  | <---------------- |  EA |
   +-----------+   (vivo? saudo?)  +-----+

Carteiro Canonical (IDA) — create_signal_canonical

Arquivo: server/signal_dispatch.py:create_signal_canonical
Quem chama: 20 callsites em routes/signals.py, af/signals.py, routes/heartbeat.py:_reconcile_sl_tp, etc. (python scripts/show_canonical_api.py --callsites)
Origem: S317 Onda 4a (2026-05-02) — substituiu Signal() raw nas rotas e AF engine.

O que faz

1. Cria 1 row em signals (a "encomenda")
2. Cria 1 row em pending_signals (a "lista de espera ate alguem entregar")
3. Cria 1 row em trade_links se origem eh origin
4. Opcionalmente cria signal_ack com status=SUCCESS (server-initiated routes)
5. Logga evento em trade_events para auditoria
6. Push WS imediato pro EA via dispatch_pending_to_eas

Tabelas tocadas

Regras criticas

• R9: Idempotencia por (account_id, trade_group_id, action) — race UNIQUE constraint detecta duplicata e retorna skipped_duplicate=True
• R10: Push WS roda APOS db.commit() (commit_then_publish pattern, evita idle in transaction)
• R12: flag_modified() em qualquer mutacao JSONB (pattern P12)
• Invert/Hedge: OriginType.SERVER_RECONCILE, MASTER_ENTRY, AF_PAIR_ENTRY respeitam invert da conta destino

Carteiro Conferente (VOLTA) — apply_ack_canonical

Arquivo: server/ack_helpers.py:apply_ack_canonical
Quem chama:
- server/routes/signals.py:ack_signal (HTTP POST /api/ack)
- server/routes/ea_ws.py:_handle_ws_ack (WS msg_type=ack)

Origem: S341 (2026-05-12) — refactor extraiu 600 linhas duplicadas entre HTTP e WS handlers.

O que faz

1. UPSERT atomico em signal_acks (race-safe via IntegrityError retry com _apply_fields interno)
2. compute_exec_slippage ANTES do commit (1 commit so — D1 canonical)
3. Detecta FALSE_ACK via validate_ack_data (V1-V4) e marca status=FAILED se aplicavel
4. Cria/atualiza trade_links quando status=FILLED (preenche local_ticket)
5. Marca pending_signals.resolved=True pra acabar o ciclo
6. Logga trade_events (ACK + MODIFY-BUFFER mismatch + CLOSE P&L cascade)
7. Dispara AF MODIFY post-fill (reconcile_af_pair + check_and_schedule_modify) quando 2 ACKs FILLED chegam no mesmo trade_group_id AF
8. Telegram alerts: MODIFY-BUFFER MISMATCH, AF MODIFY BLOCKED, CLOSE RETRY EXHAUSTED
9. CLOSE FAILED auto-retry (max 3 tentativas) — SE-2 cure do refactor
10. Broadcast commit_then_publish("ack", ...) no final pro dashboard

Tabelas tocadas

Drift HTTP vs WS (catalog 12 divergencias)

Auditoria completa em specs/scratch/ack-drift-S341.md. 2 bugs latentes corrigidos:
- SE-1: HTTP nao usava commit_then_publish (B5/P224 nao propagado)
- SE-2: WS nao tinha CLOSE FAILED auto-retry (90% dos ACKs vem por WS)

Regras criticas

• R1: Helper recebe db aberto, NAO chama db.close() (lifecycle do FastAPI Depends)
• R5: IntegrityError retry via funcao interna _apply_fields (race-safe upsert)
• R6: flag_modified() em qualquer mutacao JSONB (pattern P12)
• Trace ID: propagado pro SignalAck.trace_id em INSERT e UPDATE (race recovery cobre branch UPDATE manualmente)

Carteiro Plantonista (PLANTAO) — apply_heartbeat_canonical

Arquivo: server/heartbeat_helpers.py:apply_heartbeat_canonical
Quem chama:
- server/routes/heartbeat.py:receive_heartbeat (HTTP POST /api/heartbeat)
- server/routes/ea_ws.py:_handle_ws_heartbeat (WS msg_type=heartbeat)

Origem: S342 (2026-05-12) — refactor extraiu 1130 linhas duplicadas entre HTTP e WS handlers.

O que faz (18 sub-tarefas por HB)

1. _sanitize_nan recursive (NaN/Inf em qualquer profundidade)
2. Backfill broker se conta foi auto-registrada por WS auth (SE-2)
3. Zombie check 1x no inicio (timer_tick congelado por 2 HBs)
4. Update broker_name, mt5_server (com guard 2+ chars apos strip)
5. terminal_build change alert via Telegram (SE-3 cure)
6. Update account.last_heartbeat_at SEMPRE (mesmo no throttle WS — S314.3 Bug 3 fix)
7. Insert Heartbeat row (force_save=True; throttle 30s no WS)
8. Equity snapshot (cooldown 5min)
9. Diagnostics cache in-memory
10. Chart price cache (BID/ASK fresh do MT5)
11. SymbolInfo cache + DB upsert (tick_value, tick_size, contract_size, etc.)
12. UPSERT open_positions (delete gone + capture P&L pra TradeLink antes do delete — CR-03)
13. Settings sync verify (SE-4 cure: ambos canais via commit_then_publish)
14. EA back-online alert (se estava em _offline_accounts)
15. Desync check (group_peers mostra outras contas do grupo)
16. SL/TP reconcile (_reconcile_sl_tp — MODIFY pra peer divergente)
17. Detect missing positions (_detect_missing_positions com advisory lock)
18. Broadcast HB unificado (SE-5/SE-6: super-set inclui ea_version + sl/tp/open_price)

Tabelas tocadas

Drift HTTP vs WS (catalog 18 divergencias)

Auditoria completa em specs/scratch/hb-drift-S342.md. 6 bugs latentes corrigidos:
- SE-1: WS NaN/Inf so cobria 5+8 campos
- SE-2: WS auto-reg criava broker=""
- SE-3: WS nao detectava terminal_build change
- SE-4: HTTP settings_verify_fail nao usava commit_then_publish (B5/P224)
- SE-5: broadcast HTTP nao incluia ea_version
- SE-6: broadcast HTTP open_positions sem sl/tp/open_price

Regras criticas

• R1: Helper recebe db aberto, NAO chama db.close() (lifecycle FastAPI/SessionLocal)
• R3: force_save: bool — HTTP sempre True; WS = should_save_db decide
• R5: _sanitize_nan recursive cobre dict/list/tuple/set/frozenset (SE-1 cure)
• R9: Zombie check ANTES do throttle decision (detecao mais responsiva)
• R11: settings_verify sempre via commit_then_publish (SE-4 cure)
• R12: terminal_build alert dispara em AMBOS canais (SE-3 cure)
• R14: Pool DB nao satura sob carga (72 HBs/min × 12 contas)

Frequencia em prod

• WS: 10s/conta × 12 contas = 72 HBs/min sustentado
• HTTP fallback: 30s/conta (polling natural)
• Throttle WS limita gravacao em heartbeats table pra 30s/conta — sem perder telemetria (broadcast + last_heartbeat_at continuam em cada HB)

Fluxo de dados na rede (payloads IN/OUT)

Cada carteiro recebe um payload JSON e responde/broadcasta outro. Aqui o que efetivamente trafega entre EA, servidor e dashboard — diferente das tabelas DB acima que mostram o que persiste.

Carteiro Canonical (IDA) — payloads

Entrada: chamada Python interna (nao tem JSON IN — eh callee de 20 callsites).

Saida 1 — push WS pro EA (WS_PAYLOAD_FIELDS, 16 campos exatos — schema estrito, contrato com EA):

Saida 2 — broadcast "new_signal" pro dashboard (dashboard ouve via WS, atualiza aba Sinais).

Carteiro Conferente (VOLTA) — payloads

Entrada AckIn (EA -> servidor, schema Pydantic em server/schemas.py:120):

Saida 1 — response HTTP (apenas via path HTTP, WS path retorna None): {ok: bool, ack_id: int|null, status: str, errors: list[str]}.

Saida 2 — broadcast "ack" pro dashboard (via commit_then_publish):

Carteiro Plantonista (PLANTAO) — payloads

Entrada HeartbeatIn (EA -> servidor, schema Pydantic em server/schemas.py:46):

Cada item de open_positions: {ticket, symbol, direction, volume, profit, sl, tp, open_price, current_price, pips, swap, magic, open_time, spread, commission, tick_value, tick_size, profit_at_sl, profit_at_tp} (19 campos).

Saida 1 — response HTTP HeartbeatOut (HTTP-only, enriquecido com auto-update):

Saida 2 — push WS update_push (WS-only, EA recebe via send_text):

{ "type": "update", "version": "3.85.6", "hash": "...", "size": 102400, "url": "/api/ea/download/3.85.6" }

Saida 3 — broadcast "heartbeat" pro dashboard (super-set unificado, SE-5/SE-6 cures):

Saida 4 — alerta drawdown (so se dd_pct > max_risk_pct * 2): broadcast {type: drawdown, account_id, account_name, account_num, drawdown_pct, threshold, balance, equity}.

Observabilidade

Prometheus REMOVIDO em S367. O endpoint /metrics e os counters
copytrade_* existiam mas NADA os consumia (sem Prometheus/Grafana rodando na
VPS). A observabilidade dos carteiros hoje eh via aba de saude customizada
(/api/health, /api/debug/health-full), logs e alertas Telegram. Se um dia
precisar de tendencia historica/grafico, considerar Netdata (1 binario,
zero-config) em vez de reerguer Prometheus+Grafana.

Como validar visualmente

1. Aba Sinais — cada linha mostra OPEN/MODIFY/CLOSE (IDA cria, VOLTA confirma)
2. Aba Contas — equity, last_heartbeat (PLANTAO atualiza)
3. Posicoes abertas — open_positions (PLANTAO mantem snapshot)
4. Notificacao Telegram — alerts disparados pelos 3 carteiros (mt5_build_change, modify_buffer_mismatch, af_modify_blocked, close_retry_exhausted)
5. /api/debug/health-full (auth JWT) — health consolidado de cada conta com ack_stats_1h, recent_logs, diagnostics

Historico

• S317 Onda 4a (2026-05-02): create_signal_canonical criado, migrou 4 callsites primarios
• S319 (2026-05-02): Skill canonical-carteiro + script show_canonical_api.py (cheatsheet auto-fresh)
• S321 Onda 4e (2026-05-03): 100% callsites migrados pro IDA canonical
• S341 (2026-05-12): VOLTA apply_ack_canonical extraido (5 iters review)
• S342 (2026-05-12): PLANTAO apply_heartbeat_canonical extraido (10 iters validate+review — pattern P228 capturado: zero MED/LOW e bar absoluta, nao apenas zero CRITICAL/HIGH)

Slippage Telemetria

Status: ACTIVE | Adicionado S336+ (2026-05-10, deploy 02:20 UTC) — explica em linguagem leiga + tabela tecnica o que cada um dos 4 campos novos em signal_acks significa.

A ideia em 1 paragrafo

Imagina que voce pediu uma pizza por delivery por R$50, mas quando chegou cobraram R$52. A diferenca (R$2) é o slippage — o quanto voce foi "pisado" entre o pedido e o recibo. No copy trade, cada operacao real tem 3 momentos de preco:

1. Vitrine (o preco que aparecia na hora do clique — bid_at_request / ask_at_request)
2. Recibo (o preco que o broker realmente entregou — deal_price)
3. Ordem escrita (o preco que o servidor anotou na ordem original do master — signal.price)

A telemetria S336+ mede duas distancias:

• Exec Slip = vitrine vs recibo (culpa do GUI lento + broker requote)
• Pipeline Slip = ordem escrita vs recibo (culpa da rota inteira, servidor->VPS->EA->broker)

Ambos sao modulo (sempre positivo) e em pontos (a unidade nativa do simbolo: 1 ponto BTCUSD = 0.01, 1 ponto XAUUSD = 0.01).

Fechamento automatico por stop/alvo (SL/TP) — a regua do NIVEL (S388)

Quando a posicao fecha sozinha porque bateu o stop loss ou o take profit, nao houve clique — foi o broker que disparou. Logo nao existe "foto da vitrine" (bid/ask no clique) pra comparar. Antes, esse fechamento ficava sem medicao ("—" no painel) — e esse era o caminho MAIS comum (a maioria das batalhas morre batendo TP/SL).

A correcao S388: pra esse caso a regua certa nao e a cotacao, e o NIVEL pedido. O EA passou a guardar o nivel do stop/alvo que disparou (lendo do historico do broker) junto do preco real do fechamento, e o servidor calcula:

• Exec Slip (auto-close) = |preco real do fechamento − nivel do stop/alvo| = o quanto o broker honrou MAL o stop que voce pediu.

Exemplo real (sandbox, fechamento por SL): voce pediu stop em 73640, o broker fechou exatamente em 73640 → Exec Slip = 0.0 (honrou perfeito). Se tivesse fechado em 73638, seria 0.02 pra baixo (broker escorregou 2 pontos contra voce).

Isso vale pros 3 caminhos de fechamento: ao vivo (deteccao instantanea), por varredura, e ate offline — se o EA estava fora do ar quando o stop bateu, ao voltar ele le do historico e atualiza a medicao. So fechamento MANUAL (sem stop disparado) fica "—" honesto: nao ha "nivel pedido" pra comparar.

Resumo das 3 reguas: abertura/fechamento-por-comando usam a cotacao (foto no clique); fechamento-por-stop usa o nivel; quem nao tem nem clique nem stop (manual) fica "—".

Tabela — o que e preenchido em cada tipo de operacao

Os NULLs em MODIFY nao sao bugs — sao consequencias fisicas: MT5 MODIFY so altera SL/TP sem criar deal novo, entao nao ha deal_price pra comparar. A foto bid/ask e capturada mesmo assim pra auditar "o preco passou pelo SL em transito?".

Janela de validade da foto (R5)

A foto bid/ask vale por 60 segundos (stale_threshold_ms = 60000). Se o tempo entre captura e fill no broker passar disso, o servidor descarta o calculo de exec_slip e seta NULL — mas mantem bid/ask pra audit trail. Assim sempre se sabe "qual era a vitrine quando clicaram".

Tag close_reason="ROLLOVER" (Layer 1 anti-swap)

Quando o EA fecha uma posicao perto da meia-noite pra fugir do juro overnight (swap), o Rollover_TryClose tagueia o ticket num buffer em memoria (g_rolloverTagged). O SnapshotEngine consulta esse buffer ao montar o CLOSE signal e:

• (a) override close_reason → "ROLLOVER" em vez de "MANUAL" (default DEAL_REASON_CLIENT)
• (b) injeta bid_at_request/ask_at_request no payload

Distingue de Layer 2 servidor (close_reason="ROLLOVER_FALLBACK" via close_pair_positions — fallback se EA falhar). Spec completa: rollover-dupla-camada.md.

Invariantes (provadas via property-based test T4, 1000 runs)

• INV1: bid_at_request ≤ ask_at_request sempre que ambos NOT NULL
• INV2: exec_slip_pts ≥ 0 sempre (modulo)
• INV3: pipeline_slip_pts ≥ exec_slip_pts em 99% dos casos (transporte adiciona ruido, raro subtrair)
• INV4: bid_at_request IS NULL ⇔ ask_at_request IS NULL (par sempre junto)

Exemplo real — primeira deteccao live (signal 13123, sandbox)

Calculo: BUY pega ASK como referencia. \|81465.82 − 81465.61\| = 0.21 pts. Significa que o GUI levou ~0.21 ponto a mais que a vitrine mostrava no momento do click.

Onde ver no dashboard

No painel /af (modulo af_hedge.js), cada card de signal completo mostra:

• Linha "Exec Slip" em pts, com cor (verde <1pt, amarelo 1-5pt, vermelho >5pt)
• Linha "Pipeline Slip" logo abaixo (mesma escala)
• Badge "ROLLOVER" no header quando close_reason="ROLLOVER" ou "ROLLOVER_FALLBACK"

Se ambos slips forem NULL, as linhas sao omitidas (nao aparecem como "—" pra evitar poluicao).

Referencias tecnicas

• Spec original (Tier L): specs/exec-slippage-telemetria.md
• Plan executado: specs/plans/exec-slippage-telemetria-PLAN.md
• Helper servidor: server/signal_dispatch.py::compute_exec_slippage
• EA buffer rollover: Include/CopyTrade/WebBridge.mqh::SRolloverTag
• Whitepaper signal lifecycle: signal-lifecycle.md linhas 401-413
• Code reviews: specs/reviews/S336-exec-slippage-REVIEW.md

AF Hedge

Status: ACTIVE | Ultima revisao: S233 (2026-04-14) — addendum S231 invert audit (ver specs/invert-log.md)

Versao: 3.2
Data: 2026-03-29

Addendum S231 (invert audit): o step "Slave signal via invert pipeline" em server/af/signals.py::generate_signals_for_pair agora usa _invert_for_peer() (helper centralizado) que alem de aplicar invert grava audit row em signal_inversions via savepoint fire-and-forget. Zero mudanca de regra — so observabilidade. Detalhes: specs/invert-log.md. [drift-flush S233]
Status: CONFIRMADO — Regras core (S67), R-SAFE v1 (S95), Plano Diario + R-SAFE v2 (S96), Invert Dinamico + Pipeline (S99), Push Zone + MODIFY Post-Fill + Anti-Rollover + Post-Round Validation + Price Freshness + DLQ (S150).
Enforced em: server/af/ (6 modulos) + scripts/hedge/rules.py + scripts/hedge/test_rules.py

1. Regras de Pool (como organizamos as contas)

Roteamento dentro da pool (S392 — nota): a ordem e' entregue pelo NUMERO da conta de cada lado do par (AfPair.account_a_id/account_b_id -> create_signal_canonical(target_account_id=...)), NAO pelo nome do grupo (group_id). O group_id e' so RoTULO de isolamento da dupla; a copia legada que rotearia por nome fica SUPRIMIDA pra conta em pool AF. invert segue sendo a oposicao do hedge (motor forca o invert do parceiro). Provado em producao (7 batalhas -> exatamente os 2 do par). Detalhe + codigo (arquivo:funcao): specs/af-roteamento-conta-vs-grupo.md.

2. Regras de Risco (quanto apostar por partida)

3. Regras de Look-ahead (detalhe)

4. Regras de Vida/Morte (lifecycle)

5. Regras de Prop (variam por prop firm)

6. CLEAN_PROPS (pool AF v2)

Filtro: steps == '2-step'

S389-cont5 (2026-05-30): removido o termo max_risk_pct >= 2.5% do filtro de
elegibilidade — era a ULTIMA curadoria legada (mesma classe do max_dd >= 10
removido no S382: herdada da era do "10% fixo", NAO-validada). Risco minimo NAO
eh requisito de pool. Os requisitos REAIS sao: mesmo TAMANHO (prop_size, nivel da
conta), mesma FASE (R8, agrupada no pareamento) e mesmos STEPS (2-step, unico
requisito de prop firm — mantido). Mesa apertada (ex: Alpha 1.5%) opera SEGURA: o
motor cap no teto dela via a FK prop_firm_id -> prop_firms.max_risk_pct (S389
_ROUND_PROP_CACHE). ANTES do S389 ela furava (operava a 2.5% da pool), por isso a
curadoria fazia sentido defensivo; com o S389 virou restricao indevida. Decisao do
usuario. is_af_eligible = (steps == '2-step') — ver _compute_af_eligible.

S382b (2026-05-27): is_af_eligible virou TRAVA DURA de entrada (antes era so
filtro de catalogo, com fallback que deixava mesa nao-elegivel entrar). Agora mesa com
is_af_eligible=false NAO entra em pool nenhuma — bloqueada em
_create_chairs_from_accounts (pula com motivo) e assign_account (400), via helper
_resolve_eligible_prop. Contas JA sentadas nao sao afetadas (trava so vale pra ENTRADA
de conta nova). Decisao do usuario S382.

S382 (2026-05-27): o portao max_dd >= 10% foi REMOVIDO do filtro de
elegibilidade. Era curadoria preventiva NAO-validada (herdada da era do "10% fixo"),
nao uma trava de seguranca real — cada mesa usa seu PROPRIO piso de morte
(_max_dd_val = prop_size*(1-max_dd/100), lido por-mesa). Mesa de 8% validada no
simulador E2E: morre no piso correto (92k em 100k) e o lado perdedor sobrevive ate o
par fechar. Ver specs/prop-firm-dd-form-redesign-S382.md. max_risk migrado de USD
($2.500) pra max_risk_pct (2.5%) em S358/S362.

12 cadeiras = CLEAN_PROPS x 2 (2 contas por prop)

Excluidas:
- ~~Alpha Pro: max_risk $1.500 < $2.500 base~~ — S389-cont5: NAO mais excluida (portao max_risk>=2.5% removido; opera capada em 1.5% via S389 _ROUND_PROP_CACHE, validado no sim: par Alpha cap em $1.500 vs $2.500 das demais)
- ~~FTP Classic: max_dd 8% < 10%~~ — S382: NAO mais excluida (portao max_dd removido; 8% e' valido, validado no sim)
- (hoje so mesas NAO-2-step ficam de fora — unico requisito estrutural)

6b. Invert Dinamico por Rodada (S99)

Pares podem ser same-person (5ers-Linniu vs FTMO-Linniu). Pipeline copy-trade usa invert pra hedge. Se ambos tem mesmo invert → mesma direcao → nao eh hedge.

Regra: AF engine garante master.invert != slave.invert antes de criar signal. Se iguais, flipa o slave.

Pre-condicao flip: 0 open positions na conta (Rule 6 invert-rules.md). Se tem posicao → skip par.

Pares same-person validos. Unica restricao: R7 (nunca same-prop).

Por que pipeline copy-trade: Trade_links automaticos, CLOSE propagacao, anti-echo, 70+ sessoes testado.

6c. Push Zone (precisao no fechamento)

Quando uma conta esta muito perto de passar ou morrer, o risco normal + look-ahead podem ser contraproducentes (reduzir risco = mais trades = mais spread = mais chances de nao fechar). A push zone permite risco levemente acima do max_risk pra fechar em 1 trade.

Exemplo: Conta F1 com distance=$2.550 (dentro de push_limit=$2.600). Risco normal seria limitado a $2.500 (max_risk). Na push zone: risk = ceil($2.550 / 0.98) = $2.602. Fecha em 1 trade ao inves de 2 (economia de 1 dia + 1 spread).

6d. MODIFY Post-Fill (ajuste de precisao)

Apos AMBOS os lados de um par serem FILLED (executados), o servidor pode agendar um MODIFY (ajuste de SL/TP) para otimizar o fechamento — especialmente quando o par esta na push zone.

Framework de seguranca F1-F6

Fluxo:

Ambos FILLED → Detecta push zone → Delay 30-120s → Calcula novo SL/TP
  → F1 (duplicata?) → F2/F3 (mais fraco) → F4 (sanidade) → F5 (limite)
  → F6 (ja proximo?) → Cria sinais MODIFY → EA aplica via GUI

7. Regras de Execucao (EA/servidor, nao simulador)

E5: Plano Diario — Fluxo Completo

22:00 UTC (rollover):
  1. Servidor coleta estado atualizado de todas as contas (balance, fase, distancia, colchao)
  2. Gera plano:
     a. Quais contas estao ativas (nao em transicao, nao mortas)
     b. Pareamento (fase, distancia, never same-prop)
     c. Risco por par (smart risk, LA, death trade, R-SAFE4)
     d. Horarios de execucao (R-SAFE6: espacamento entre siblings)
     e. Ordem aleatoria entre siblings da mesma prop
  3. Envia resumo compacto via Telegram
  4. Aguarda aprovacao do usuario

APROVACAO:
  [Aprovar]     -> execucao automatica nos horarios planejados
  [Skip dia]    -> nenhum trade executa
  [Replanejar]  -> recalcula plano com janela restante
                   (bloqueado se ha trades abertos da rodada)

Sem timeout — plano fica pendente ate resposta.
Se demorou: [Replanejar] gera novo plano a partir do horario atual.

E5: Formato Telegram

PLANO 20/Mar — 6 pares, 12 contas

P1: 5ers-A vs FTMO-B | F1 | $2,500 | ~22:40
P2: City-C vs Bright-D | F2 | $1,920 | ~01:15
P3: 5ers-E vs FNext-F | F1 | $2,500 | ~05:45
P4: FTMO-G vs FPips-H | F1 | $2,500 | ~08:00
P5: 5ers-I vs City-J | F1 | $1,200 | ~10:30
P6: Bright-K vs FNext-L | F2 | $2,500 | ~11:45

Same-prop: 5ers(3): 7h+5h | FTMO(2): 9.3h

[Aprovar] [Skip dia] [Replanejar]

E6: Pre-check de Vida

ANTES de enviar signal ao par:
  Conta A: heartbeat < 90s? SIM
  Conta B: heartbeat < 90s? SIM
  -> Ambas online: prosseguir

  Conta B: heartbeat > 90s? -> OFFLINE
  -> Notificar Telegram: "Conta B offline, esperando..."
  -> Esperar ate ficar online (sem timeout fixo, janela de abertura limita)
  -> Se nao voltar antes do proximo par: skip este par

E7: Retry com Price Gate (falha de execucao)

Signal enviado pra A e B (trade_group_id compartilhado)
  A executa, ACK recebido (entry_price salvo)
  B falha (GUI timeout, ACK fail)

Retry via TradingView WS (streaming, tempo real):
  A cada tick: B online (HB < 90s) E |tv_price - entry_A| <= $2?
    SIM -> re-envia signal pra B com MESMO trade_group_id
    NAO -> continua esperando

  Timer random(60, 90)s expira sem B abrir:
    -> Fecha A via auto-close (origin="server_auto_close")
    -> Notifica Telegram

Cenarios:
  A ok B ok              -> hedge OK
  A ok B falha preco OK  -> retry abre B, hedge OK
  A ok B falha preco >$2 -> timeout, fecha A
  A falha B falha        -> nada abriu, notifica, skip

Price gate $2 (XAUUSD): Conservador. Cobre ~15-30s de movimento em NY. Garante hedge simetrico.
Futuro (BTCUSD, USDJPY): Threshold em % do preco em vez de USD fixo.

8. Regras de Simulacao

10. Regras Anti-Deteccao Same-Prop (R-SAFE)

Principio: VARIACAO MAXIMA — Entre quaisquer contas same-prop (pessoas diferentes, pares diferentes), nenhuma dimensao observavel pode ter correlacao estatistica. O foco: nunca parecer copy trade.

Aplica-se quando: 2+ contas da mesma prop (pessoas diferentes) estao ativas no mesmo dia — INDEPENDENTE DA FASE. F1 vs F2 da mesma prop TAMBEM precisa divergir. A prop nao sabe o que eh "F1" ou "F2" — ela ve TODAS as contas.

Setup: PCs locais separados por pessoa (IP diferente, KYC diferente). Servidor coordena, EA so executa (E8).

Implementacao: Range Valido. Calcular o conjunto de valores validos ANTES de sortear — garantido encontrar se existir, zero tentativa-e-erro.

R-SAFE5: Nivel Absoluto (nao distancia)

Problema da versao anterior (S95): Checar distancia SL/TP (>= $3) nao garante closes em precos diferentes. Entry diferente + distancia diferente podem se cancelar:

Conta A: entry $3,050, SL dist $28 -> SL em $3,022
Conta B: entry $3,063, SL dist $41 -> SL em $3,022  <- MESMO nivel!

Distancia diferiu $13 (OK), mas nivel absoluto IDENTICO (PROBLEMA).

Solucao (S96): Checar o nivel absoluto do SL/TP (onde a ordem realmente fecha):

SL_level_A = entry_A - SL_dist_A  (se BUY)
SL_level_B = entry_B - SL_dist_B  (se BUY)
|SL_level_A - SL_level_B| >= $10  <- o que a prop realmente ve

TP_level_A = entry_A + TP_dist_A  (se BUY)
TP_level_B = entry_B + TP_dist_B  (se BUY)
|TP_level_A - TP_level_B| >= $10

Se nao cabe (range valido de SL/TP nao satisfaz >= $10 de nivel absoluto): skip a conta.
O sibling que ja executou continua normal — apenas o que nao conseguiu divergir fica ocioso.

R-SAFE6: Horario Variavel (Plano Diario)

Integrado com o plano diario (E5). Nao eh por sessao (robotico). Nao eh proporcional exato (robotico).

Regras:
- Janela: 22:30 UTC (30min apos Sydney open) ate 12:00 UTC (NY forex open)
- Espacamento entre siblings: minimo random(1h, 2h) por par de siblings, nao fixo
- Gaps irregulares: as vezes 1.5h, as vezes 8h. Sem padrao
- Ordem aleatoria cada dia (quem opera primeiro eh sorteado)
- Todos os siblings sao SEMPRE agendados. Skip so acontece se preco nao coopera no polling

Exemplo com 3 siblings (janela 13.5h):

Dia 1: 22:40, 01:15, 09:50  (gaps: 2.5h, 8.5h)  ordem: C, A, B
Dia 2: 23:55, 06:20, 07:45  (gaps: 6.4h, 1.4h)  ordem: B, C, A
Dia 3: 00:10, 04:30, 11:50  (gaps: 4.3h, 7.3h)  ordem: A, B, C

R-SAFE2: Polling de Preco

Quando chega o horario de um sibling e o preco nao moveu >= gate do sibling anterior:

Timer encerra (ex: 05:45)
  -> Polling a cada 5 min (rsafe2_retry_min, configurable)
  -> A cada check: |preco_atual - entry_sibling| >= rsafe2_price_gate_pct * price / 100?
     SIM -> executa (com jitter R-SAFE6)
     NAO -> re-agenda +5min, incrementa retry counter

  Fim da janela (12:00 no timezone do pool, via trading_tz_offset)
  OU max retries (60, configurable):
  -> Skip terminal (status = skipped_rsafe)

Gates por simbolo (presets.py, S255 em %): XAUUSD: 0.35% | BTCUSD: 0.08% | _default: 0.30%
Configuravel por pool: rsafe2_price_gate_pct no config JSONB (override via API ou dashboard). S255: migrado USD -> % pra auto-escalar cross-symbol.

Ordem de execucao aleatoria

A ordem entre same-prop siblings eh ALEATORIA. Nao eh sempre "Pessoa A primeiro, Pessoa B depois".
Cada dia, o servidor sorteia quem opera primeiro. Isso impede o padrao "Account X sempre precede Account Y".
Com 3 pessoas: ordem A-B-C, B-C-A, C-A-B, etc. Tudo aleatorio.

Fluxo Range Valido (servidor)

PARA CADA conta same-prop que vai operar apos siblings (ordem aleatoria):

  1. Esperar horario planejado (R-SAFE6, definido no plano diario)
  2. Checar preco vs TODOS os siblings ja executados via TradingView WS
     (R-SAFE2: |preco_atual - preco_sibling_N| >= $10 pra cada N?)
     - NAO: esperar ticks ate mover. Delay random(30s, 180s) apos gate.
     - Fim da janela sem mover: skip
  3. Calcular risco normalmente (smart risk, LA, death trade, etc.)
  4. R-SAFE4: checar risco vs TODOS os siblings
     - Se |risco - risco_sibling_N| < $100 pra algum N:
       risco *= random(0.80, 0.90)
  5. Calcular range valido de SL/TP:
     - Range base: $25-50
     - Pra cada sibling: calcular nivel absoluto e excluir SL/TP que ficaria
       a menos de $10 do nivel absoluto de qualquer sibling
     - Range valido = base - todas exclusoes
     - Se range vazio: skip a conta
  6. Sortear SL/TP do range valido
  7. Calcular lote = risco / (SL/TP_distance * valor_ponto)
  8. Checar lote vs TODOS os siblings:
     - Se |lote - lote_sibling_N| < 0.05 pra algum N:
       re-sortear SL/TP do range valido (novo valor muda lote)
       Se persistir: aceitar (risco/preco ja divergiram)
  9. Pre-check heartbeat (E6): ambas contas do par online?
  10. Executar ordem. Se falha: retry com price gate $2 (E7)

Close divergence (garantido por R-SAFE5)

R-SAFE2 (entry >= $10 diferente) + R-SAFE5 (SL/TP nivel absoluto >= $10 diferente) = closes em precos diferentes = closes em momentos diferentes. Garantido, nao por consequencia.

Escalabilidade (N pessoas por prop)

Funciona com N pessoas. Cada adicional = +1 slot de tempo, +1 check pairwise.
3 pessoas: todos checks sao pairwise (A vs B, A vs C, B vs C).

Direcao dos siblings

Coincidencia de direcao (ambos BUY no mesmo dia) NAO eh problema. Cada sibling esta num par diferente — direcao determinada pelo par (anti-OSB). Traders independentes podem comprar no mesmo dia naturalmente.

Futuro (~3 meses): Anti-bot individual

Padroes que nao sao de correlacao same-prop, mas de "parecer humano". Baixa prioridade — implementar quando R-SAFE1-6 estiver rodando em producao. TODOs #105-107.

• R:R variavel: Sair do 1:1 fixo, variar entre 1:0.8 e 1:1.3
• Delay SL/TP: Nao definir ambos no mesmo instante (SL imediato, TP com 5-30s delay)
• Modificacao ocasional: Trailing stop ou move-to-breakeven aleatorio em ~10% dos trades
• Threshold % (multi-ativo): R-SAFE2/E7 price gate em % do preco (BTCUSD, USDJPY)

Impacto na simulacao

No Monte Carlo (50/50, sem preco real), R-SAFE eh modelado como:
- Skip rate: ~10% dos trades second-pair (R-SAFE1+R-SAFE2 combinados)
- Risk reduction: Quando risco proximo do sibling (< $100), multiplicador 0.80-0.90
- Impacto medido (500 seeds): -8% funded, -6% ROI vs baseline. Aceito como custo de seguranca.
- Horario, SL/TP absoluto e lote sao detalhes de execucao sem impacto no 50/50

10b. Validacao Pos-Rodada (L3-L5)

Apos cada rodada completar, o servidor roda 3 camadas de validacao automatica (run_post_round_validation()):

• Se violacao encontrada: alerta Telegram imediato
• Log de auditoria: action post_round_validation no audit log
• Roda APOS todos os pares da rodada terem resultado (FILLED, FAILED, ou skipped)

Dead Letter Queue (DLQ)

Sinais que falharam sao registrados na tabela AfDeadLetter para auditoria:

Volume — Formula de Calculo

volume = risk_usd / ((sl_distance + sl_buffer) / tick_size * tick_value)

• sl_buffer = $1 — garante que TP trigger antes do SL no par (safety margin)
• Resultado arredondado pro lote mais proximo valido do simbolo

Symbol Presets (configuracao por ativo)

Cada simbolo pode ter defaults diferentes via presets.py. Valores customizados por simbolo sao mergeados com config do banco: defaults ← preset ← database.

S255 USD -> %: 4 thresholds price-facing migrados pra % do preco (auto-escala cross-symbol). dz_min/dz_max permanecem USD (equity-facing). Ver usd-to-pct-migration.md.

Arquitetura de Modulos (servidor)

O codigo AF esta modularizado em 6 arquivos no diretorio server/af/:

9. Ordem do Dia (processamento na simulacao)

INICIO DO DIA:
  1. Adicionar novas F1 (slots reciclados ontem)
  2. Checar passes (balance >= target + profit days ok) → promover F1→F2 ou FUNDED
  3. Checar mortes (balance < piso DD) → marcar pra reciclar amanha
  4. Parear contas restantes (por fase, distancia, same-prop)
  5. Calcular risco (smart risk + look-ahead)
  6. Executar trades (50/50)
  7. Atualizar balances (float)
FIM DO DIA

11. Operacoes Live (consolidado de af-live-operations.md)

Lifecycle (tudo MANUAL pelo usuario)

Transicoes NAO sao automaticas. Toda mudanca de conta/fase depende de acao humana.

Quando os checks rodam (S163)

Fluxo automatico: Rodada completa → nova rodada gera automaticamente → checks rodam no inicio → contas mortas/passadas sao excluidas antes de parear.

Gap: Se pool esta inativo (sem rodadas), mortes entre rodadas NAO sao detectadas ate proxima rodada.

Anti-One-Side-Betting (anti-OSB)

Props flaggam contas que operam sempre na mesma direcao. Sistema sorteia direcao aleatoria com peso crescente:
- 1 seguido = ok | 2 seguidos = alerta | 3+ = critico (forca inversao)
- Se ambas contas do par tem peso alto: prioriza a mais critica

Chair Owners (multi-pessoa)

• chair_owners no JSONB do pool (chave = # cadeira, valor = nome)
• owner_colors no JSONB do pool (chave = nome, valor = cor hex)
• Dashboard mostra nome + cor nos cards. Escalavel sem limite

Telegram — Eventos AF

Market Hours Guard (S288 — spec: market-hours-guard.md)

Regra (I1): Sistema NUNCA envia OPEN signal pra symbol em mercado fechado.

4 camadas de defesa:

Por que pair.symbol (nao pool.symbol): AfPair.symbol eh snapshot imutavel no momento de criar par. Pool symbol pode mudar (PUT /api/af/pool/X) mas pares ja criados com symbol antigo precisam ser checados pelo SEU symbol.

Estados terminais novos (TERMINAL_PAIR_STATES):
- failed_market_closed — pair scheduled em symbol fechado >cutoff
- failed_swap_window — pair scheduled em rollover ativo

Categoria separada no daily report (R7): failed_market_closed NAO conta como falha de execucao (sistema funcionou — mercado estava fechado). Renderiza segregado pra nao inflar taxa de erro.

Telegram dedup: f"market_closed:{pool_id}:{symbol}:{YYYYMMDD}" — 1 alerta/pool/symbol/dia.

Bug exposto (S287): Apos PUT /api/af/pool/20 trocando symbol XAU->BTC, par 81 (scheduled XAU) disparou OPEN em sexta 23:25 UTC (XAU fechado). Causa: guard checava pool.symbol (BTC, aberto). Fix: pair.symbol.

Demo vs Real

O sistema NAO diferencia — logica identica. Demo (Exness): morte = resetar gratis. Real (prop firms): morte = comprar novo teste.

Fluxo de reset (S207, teste only): reset-classification → acha cadeira passed/dead → restaura group_id → seta account_id=NULL → cadeira vira registro historico (prop_config tem snapshot: nome, dono, tipo). Conta fica livre pra re-classificar (#2 se mesmo combo prop/fase/dono). Re-adicionar na pool cria cadeira nova. Dashboard mostra cards historicos com saldo congelado (virtual_balance) e label "Saldo final (historico)". Timer da pool usa paused_at como referencia quando pausada (congela countdowns).

Resumo Visual

PAREAMENTO (por fase, separado):
  F1 pool ──┬── F1 vs F1 (prop diferente, adjacente por distancia)
            └── F1 ociosa (se sem par valido)
  F2 pool ──┬── F2 vs F2 (prop diferente, adjacente por distancia)
            └── F2 ociosa (se sem par valido)

RISCO (hierarquia, primeiro que limita ganha):
  1. Teto da fase (F1: $2.500 | F2: $2.000 ou $2.500 conforme prop)
  2. Smart risk: min(teto, ceil(dist / (1-spread)))
  3. Look-ahead: evitar zona morta $0-$500 (so se >= max risk)
     - Distancia < max_risk = reta final (ignora LA distancia)
     - Colchao < max_risk = death trade (ignora LA colchao, risk = colchao)
  4. Risco do PAR = min(risco_A, risco_B)

CICLO DE VIDA:
  Comprar prop → F1 → [passa] → F2 → [passa] → FUNDED ($8k)
                  ↓                     ↓
               [morre]              [morre]
                  ↓                     ↓
              Nova F1               Nova F1

Historico de Regras

Campos (Regras)

Referência rápida pra consultar sempre. Explica cada valor que aparece na
tabela de regras das mesas (prop firms) e nos ajustes da pool — em linguagem
leiga. Última revisão: S362 (2026-05-21).

A confusão mais comum: são 3 limites DIFERENTES

Muita gente mistura "risco" com "drawdown". São três coisas separadas:

Como eles conversam no motor: o risco por trade é o tamanho normal de cada
aposta. O Daily DD é um teto do dia — se você já perdeu muito hoje, ele
aperta o risco do próximo trade pra não estourar o dia (risco = min(risco_do_trade, quanto_ainda_posso_perder_hoje)). O Max DD é o piso de morte: cruzou, a
conta acabou.

Hoje rodamos ~1 round/dia em demo, então o Daily DD quase nunca "morde" (1
trade de $2.500 < $4.500/dia). Quando operarmos vários trades/dia no real, ele
passa a limitar de verdade.

Regras da PROP FIRM (fixas por programa — tabela prop_firms)

São as regras da mesa. Cada programa (ex: "FTMO Swing") tem as suas. Viram dólar
multiplicando o % pelo tamanho da conta.

Settings da POOL (você ajusta — af_pools.config)

São os ajustes operacionais da pool, não da mesa.

Legado: equity_floor_value (piso em USD) foi trocado por equity_floor_pct
(%) no S362. O servidor ainda lê o USD como fallback pra pools não-migrados.

Como o % vira dólar

A tela de preview das regras (e o motor) pegam o % × tamanho da conta:

• Alvo F1: target_f1 % × tamanho → 8% × $100k = $108.000
• Piso de morte: (1 − max_dd%) × tamanho → (1 − 10%) × $100k = $90.000
• Risco/trade: max_risk_f1_pct % × tamanho (limitado pelo max_risk_pct da mesa)
• Equity floor: (1 − equity_floor_pct%) × tamanho → (1 − 8%) × $100k = $92.000

Por isso o S362 conectou o tamanho real da conta ao motor: antes ele assumia
$100k fixo (funcionava por coincidência, porque tudo é $100k). Agora escala
sozinho — uma conta de $50k calcula alvo $54k e piso $45k.

O que é futuro / inerte hoje

• Daily DD inteiro (daily_dd, daily_dd_op_pct, daily_dd_type): só "morde"
  quando operarmos vários trades/dia. Ideia futura: uma trava (toggle) por pool
  pra ligar/desligar as regras temporais — assim dá pra rodar muitos rounds/dia em
  debug sem disparar limite diário.
• Dias mínimos (min_days_f1/f2, min_profit_days): só preenchem a tabela,
  sem lógica ativa ainda.
• Legados USD (max_risk, daily_dd_op): em remoção. daily_dd_op já está
  morto (motor usa só daily_dd_op_pct). max_risk USD ainda tem 1 uso vivo na
  compensação de spread (R5b) — será migrado pro %-based numa limpeza dedicada.

Lendo o Config Settings da pool (telas novas — S383)

O botão Config Settings de cada pool abre um painel pra ajustar os buffers
(margens de segurança) e conferir como as contas estão. O que cada parte mostra:

Buffer por par (margem de segurança)

O buffer é uma folga que você dá no preço de saída (stop/alvo) pra não ser
tirado por um detalhe do mercado. Ao digitar o buffer de cada tipo (Metais /
Forex / Cripto), o painel mostra, pra cada par real:

• a distância que essa margem representa no preço;
• o spread médio daquele par (a diferença entre o preço de compra e o de
  venda, medida das próprias contas);
• a folga = quantas vezes a margem cobre o spread. Verde = cobre com
  sobra (2x ou mais); amarelo = cobre justo (1x a 2x); vermelho = a
  margem é MENOR que o spread (perigo, pode ser tirado fácil); n.d. = não dá
  pra comparar (sem spread medido ainda).

Mapa de spread médio

Tabela com o spread típico de cada par, juntado das contas. É uma média que
vai acumulando (o spread "normal", não o de um instante isolado). Dá pra ver
por par, por mesa (empresa) ou por conta.

Filtro demo / real

Um interruptor "Só contas demo (simulando mesa)". Hoje todas as 12 contas
são demo (treino). Quando entrarem contas reais de prop firm, desmarque pra
ver só elas. Essa marca é definida num checkbox na hora de classificar a
conta — conta nova entra como real por padrão. No painel inicial, cada
conta demo ganha uma etiqueta azul "demo" no card, pra diferenciar de bate-
pronto.

"Empresa — Desafio"

Onde antes aparecia só o nome do desafio (ex: "Standard 2 Steps"), agora aparece
a empresa junto (ex: "FundedNext — Standard 2 Steps"), pra não confundir qual
mesa é qual.

"Buffers confirmados pelo EA?" — a conferência

O robô (EA) que roda em cada conta recebe os buffers e confirma de volta o
que aplicou. Esse painel compara o que você salvou com o que o robô
confirmou:

• "12/12 contas confirmaram" (verde) = tudo certo, o robô aplicou exatamente
  o que você pôs.
• divergência (amarelo) = mostra "você pôs 50, o robô está com 99". Costuma
  sumir sozinho em segundos, assim que o robô pega o valor novo.
• offline (vermelho) = a conta não está reportando (robô fora do ar ou sem
  internet).
• Botão Recarregar pra checar de novo depois de salvar.

Donos Prop Firms

Por que isto existe: o hedge cruzado assume que cada prop firm é uma empresa independente — dono diferente, time de risco diferente, e elas não comparam contas entre si. Se duas "marcas diferentes" forem do mesmo grupo-mãe, o hedge entre elas vira uma independência ilusória (a empresa percebe que as duas contas são a mesma jogada e pode eliminar as duas). O setor consolida rápido — compras e fusões mês a mês — então esta lista envelhece e precisa de revisão periódica.

Última auditoria: 27 de Maio de 2026 · Próxima revisão recomendada: ~Agosto/2026 (ou assim que sair notícia de nova aquisição).

Veredicto atual

As 11 marcas cadastradas são, hoje, 11 grupos donos distintos — nenhum par da pool compartilha dono, então a premissa do hedge se sustenta. A única mudança recente: a Funded Trading Plus foi comprada pela Instant Funding (grupo Acello, Reino Unido) em 26/05/2026. Como a Instant Funding não está na nossa lista, não cria conflito interno hoje — mas a Funded Trading Plus deixou de ser independente.

Quem é dono de quem

Marca	Grupo / dono real	País (sede)	Independente?
FTMO	FTMO s.r.o. (holding OMHC)	Chéquia	Sim
The 5%ers	Five Percent Online Ltd	Reino Unido	Sim
FundedNext	NEXT Ventures	Emirados	Sim
BrightFunded	BrightFunded B.V. / Bright Global FZCO	Holanda (opera de Dubai)	Sim
City Traders Imperium	CTI FZCO	Emirados	Sim
Funding Pips	ANKH PROP FZCO	Emirados	Sim
Alpha Capital (Alpha Pro 10%)	Alpha Capital Group Ltd (Kohler / AMGP)	Reino Unido	Sim
Funded Trading Plus	Acello Ltd / Instant Funding	Reino Unido	Trocou de dono 26/05
For Traders	FT Trading Ltd + BLN Tech Club DMCC	Emirados (registro em St. Lucia)	Sim
Maven	MAVEN LLC	Saint Lucia (operação em Dubai)	Sim
Fintokei	Purple Group / Purple Trading	Chéquia	Sim

Marcas-irmãs (não adicionar à pool sem checar)

Estas marcas não estão na nossa lista hoje, mas pertencem ao MESMO grupo de uma marca que já está. Se qualquer uma entrar na pool, não pode parear (hedge) com a marca-mãe — seria a mesma empresa disfarçada. A regra R7 do sistema hoje compara o nome da marca, não o grupo-mãe, então este radar é manual até a regra olhar o grupo.

Mapa de localização — onde ficam nossas 11

Inspirado no mapa "Locations of Prop Firms" do PropFirmMatch. Repare na concentração: a maioria fica em Emirados e Reino Unido. Atenção importante — ficar no mesmo país NÃO significa mesmo dono; é só onde a empresa se registrou (muitas escolhem Emirados ou paraísos fiscais por imposto e regulação mais leve).

País	Marcas	Quantas
Emirados	FundedNext · City Traders Imperium · Funding Pips · For Traders	4
Reino Unido	The 5%ers · Alpha Capital · Funded Trading Plus	3
Chéquia	FTMO · Fintokei	2
Holanda	BrightFunded (opera de Dubai)	1
Saint Lucia	Maven (operação em Dubai)	1

O que o "mapa" ensina pro hedge: várias firmas independentes dividem o mesmo endereço (Emirados, principalmente). Isso é normal e não compromete o hedge — o que importa é o dono, não o CEP. O risco de verdade aparece quando duas marcas têm o mesmo grupo-mãe (como Funded Trading Plus e Instant Funding agora) ou usam o mesmo provedor de liquidez nos bastidores — aí a execução pode ficar correlacionada mesmo com donos diferentes.

Fontes (prova) — auditoria 27/05/2026

• Aquisição Funded Trading Plus → Instant Funding: PR Newswire · Finance Magnates
• Donos da Instant Funding / Acello: TradeInformer · Tracxn — Acello Ltd
• The 5%ers = Five Percent Online Ltd (reg. UK 12553363): About · Crunchbase
• FTMO × OANDA: press release OANDA
• FundedNext / NEXT Ventures: About
• BrightFunded: About
• City Traders Imperium = CTI FZCO: About
• Funding Pips = ANKH PROP FZCO: Crunchbase
• Alpha Capital: About
• For Traders = FT Trading Ltd + BLN Tech DMCC: About
• Maven = MAVEN LLC: TradingFinder
• Fintokei = Purple Group: About

EA Architecture

Status: ACTIVE | Ultima revisao: S326 (2026-05-04) — bump EA v3.82.0 -> v3.84.2 (atual). Drift coberto desde S294: S300 RECONCILE retroativo pos-offline (ReconcileEngine.mqh + 3 hooks LinniuC.mq5), S301 fix log spam ReconcileEngine (gate 60s OnTimer), S313 remove MODIFY precheck por tolerancia (formula 5point10^(digits-1) sempre dava 0.5 USD constante), S315.2 popup_text Unicode escape \uXXXX (preserva PT-BR no JSON), S319 cleanup WebBridge_PostReverse codigo morto. S326 Sessao A+B (NOVO): telemetria T4 EXATA via campo ea_received_at_ms no ACK payload. Buffer circular g_signalReceivedAtMs[64] em WebBridge.mqh + helper RecordSignalReceived chamado dentro de LNC_BeginSignalObs (cobre WS via ExecuteSingleSignal:728 + HTTP via PollAndExecuteSignals:1221). Helper _S326_NowEpochMs() usa TimeGMT()*1000 com fallback TimeCurrent() se TimeGMT()=0. Sandbox account_id=3 validado live em 4 signals (WS+HTTP+OPEN/MODIFY/CLOSE). Modulos e responsabilidades inalterados. Tabela WebBridge.mqh "v3.69.0" e nota historica preservada. [allow-spec]

SSoT para: Modulos EA, compilacao, versionamento, erros MT5, armadilhas
Versao: 2.4 (EA v3.84.2, atualizado S326 — 2026-05-04). Desde 2.3: S300 ReconcileEngine retroativo, S301 fix log spam gate 60s, S313 remove MODIFY precheck constante, S315.2 popup_text Unicode escape, S319 cleanup PostReverse, S326 telemetria T4 ea_received_at_ms (Sessao A backend+UI + Sessao B EA exato).
Consolida: memory/ea-modules.md + .claude/knowledge/copytrade-ea.md
Relacionados: specs/invert-rules.md (inversao), specs/auto-update-flow.md (auto-update), specs/settings-sync-guardian.md (sync settings), memory/business-constants.md (constantes)

LinniuC.mq5 (Orquestrador, ~1245 linhas)

Inputs

• Conexao (fixos): InpServerURL, InpWebAPIKey
• Configuraveis (servidor sobrescreve): InpGroupID, InpInvertSignal, 6 buffers SL/TP (Metals/Forex/Default), InpBufferMode (PIPS/PRICE), InpPollInterval, InpCooldownSec, InpSymbolOverrides
• GUI/Execucao: InpPollingMs (200), InpTimeoutMs (5000), InpVisualMode, InpSignalMaxAge (60)
• Safety: InpEquityFloor (0=desabilitado). Se equity < floor, g_floorBreached=true → EA para TUDO (one-way, sem recovery)

OnInit (13 passos)

1. Verificar DLLs | 2. FindMT5Window | 3. OpenProcess ListView
2. Init lock file gui_lock_<HWND>.txt | 5. SettingsManager_Init
3. WebBridge_Init | 7. SymbolResolver_Init | 8. SnapshotEngine_Init
4. Init local signal files (offline) | 10. Panel_Init
5. EventSetMillisecondTimer(200) | 12. Print banner | 13. g_initOK=true

OnTimer — 2 ciclos

• Rapido (200ms): Snapshot -> FlushQueue -> PollAndExecuteSignals
• Lento (30s, online): SettingsManager_Sync -> Heartbeat -> AutoUpdate_Check
• Panel_Update todo ciclo | g_busy guard anti-reentry

PollAndExecuteSignals

Poll -> parse JSON -> para cada signal: resolve symbol -> apply buffers -> GUI execute -> detect local ticket -> ACK (FILLED/FAILED)

Ticket Detection (v3.29.3+)

• Primario: OnTradeTransaction — evento instantaneo do MT5. Chama SE_FindRecentOpenDeal que detecta o ticket no momento da transacao
• Fallback: DetectNewTicket — polling (antes era primario). Usado se OnTradeTransaction nao capturar
• Resultado: Deteccao mais rapida (~instantanea vs ate 100ms de polling). Sleep OPEN reduzido de 200ms para 50ms

Modulos (.mqh)

SnapshotEngine — Comportamentos Criticos

Restart: Posicoes existentes viram snapshot inicial. NAO gera falsos OPEN ao reiniciar.

Anti-Echo (Pattern #34):
- SE_SuppressTicket(ticket, TTL): impede re-deteccao de ticket recem-operado
- OPEN: 5s TTL (chamado em LinniuC.mq5 apos GUI execute com sucesso)
- MODIFY/CLOSE: 10s TTL (chamado dentro do SnapshotEngine)

SettingsManager — Invert:
- ONLINE: Invert eh informacional. Servidor ja entrega sinais invertidos
- OFFLINE/LOCAL: EA faz inversao localmente via ApplyInversion
- SyncFromServer: So sobrescreve campo se servidor envia valor nao-nulo

OTT Fast Close (v3.39.0+)

Quando um deal fecha (SL/TP/STOP_OUT/MANUAL), o EA detecta no callback OnTradeTransaction e envia CLOSE direto via WebSocket — sem esperar o polling do SnapshotEngine (3s).

Heartbeat Server-Side Tracking (S314.3, Bug 3 fix Opcao C)

EA manda HB cada 10s (WS) ou 30s (HTTP fallback). Servidor tem 2 lugares pra rastrear:

Helper canonico (server/account_filters.py:is_account_alive):

from app.account_filters import is_account_alive
if not is_account_alive(account, threshold_sec=30):
    return jsonify({"error": "EA offline"}), 503

NULL-safe: retorna False se last_heartbeat_at IS NULL (conta nova/pre-migration).

Adopcao lazy — 6 callsites legacy (ea_update.py:529, monitoring.py:64, daily_report.py,
settings.py, heartbeat.py:1184, accounts.py:565) continuam usando
heartbeats.created_at. Cada PR que tocar arquivo migra pro helper. (S320: tournament.py removido.)

Spec completo: heartbeat-last-seen.md.

Pulso leve vs Censo pesado (S386 Fase 2)

A partir de S386, o batimento (WS_SendHeartbeat em Include/CopyTrade/WinHttpWS.mqh) virou pulso leve — enriquecido com campos novos pra observabilidade da saturacao SEM tocar caminhos pesados:

Invariante R1 (S386): WS_SendHeartbeat NUNCA chama HistorySelect* nem GUI_*. Censo pesado (WB_BuildPositionsJSON) fica no ciclo separado de ~30s, inalterado.

Beacon ea_busy (S386 Fase 2)

GUIExecution.mqh em OPEN/MODIFY/CLOSE dispara WS_SendBusyBeacon(op, ticket, expected_ms) IMEDIATAMENTE APOS pegar o lock de GUI (GUI_AcquireGUILock), antes do trabalho lento de tela. Se o lock falhar, o beacon NAO eh enviado. Frame WS {"type":"ea_busy",...}, dispara-e-esquece (timeout <=200ms, sem retry, sem ACK queue). Globais g_gui_busyOp + g_gui_busyTicket + g_gui_busySince setados sincronos pro pulso reportar status atual. Limpeza ocorre via GUI_ClearBusy() (em GUIExecution.mqh:204, chamado pelo GUI_ReleaseGUILock em :694) ao final de cada op. O servidor reflete o estado via pulso quando g_gui_busyOp="". Em paralelo, o ACK transporta gui_duration_ms (montado em Include/CopyTrade/WebBridge.mqh:1249) pra calcular latencia.

Spec completo: saturacao-visibilidade-gui-S386.md + signal-lifecycle.md secao "Estado Afogado".

MODIFY Readback Validation (v3.48.0+)

Apos GUIExecution_Modify retornar sucesso, o EA le de volta os valores do broker e so envia FILLED se realmente aplicou:

• Tolerancia: max(5.0 * point * 10^(digits-1), 0.01) — acomoda precisao do simbolo
• Se broker rejeitou (ex: SL=0 quando deveria ter valor): envia FAILED com diagnostico completo (g_gui_modifyDiag)
• Race condition: Se posicao fechou durante MODIFY, detecta e reporta

GUI Input Strategy (v3.49.0+)

O EA usa 3 estrategias em cascata pra preencher campos do dialog F9:

Sync Barrier (WaitForEditValue):
1. SendMessageW(WM_NULL) — flush da fila de mensagens do OS (barreira de sincronizacao)
2. Check imediato — funciona 95%+ das vezes (sem polling)
3. Fallback poll 500ms — captura edge cases (MT5 reformatando valor)

Descoberta (S124): WM_SETTEXT sozinho causa "Invalid Volume" — MT5 precisa de WM_CHAR real pra validar.

Volume/SL/TP Safety Guards (v3.32.0+)

Remote Logging — LNC_LogRemote (v3.34.0+)

Buffer circular das ultimas 15 linhas de log significativas. Enviado no heartbeat campo last_logs.

Exemplos:

"OPEN OK #123456 XAUUSD BUY vol=0.10 250ms [S1-S10]"
"MODIFY READBACK FAIL #123456 SL=2049.5(tgt=2048.5)"
"OTT Deal ENTRY_OUT SL posId=123456 P&L=150.50 reason=SL"
"EQUITY FLOOR BREACHED: 89850.00"

Usado pra diagnostico remoto sem acesso ao terminal MT5.

GUI-TRACE Steps (v3.34.0+)

Cada passo da execucao GUI eh logado com timing:

Trace acumulado em g_gui_traceLog (pipe-separated), enviado nos remote logs.

Buffer SL/TP (EA-side)

Servidor envia SL/TP raw (precos absolutos). EA aplica buffer localmente:

Logica: Buffer adicionado ao SL (margem extra contra slippage). TP geralmente sem buffer.

Equity Floor Circuit Breaker (v3.65.0)

Rollover Dual-Layer — Camada 1 EA (v3.72.0)

Anti-pattern nota: sorteio eh POR POSICAO (nao por par/pool) — evita 5 fechamentos correlatos que prop firm identifica como carimbo de robo.

Compilacao

Compilar: bash compile.sh [LinniuC|RandomTrader|RiskCalculator]

Deploy completo: Usar bash deploy_ea.sh (NUNCA copiar .ex5 manualmente). O script: compila, copia .ex5 Terminal→Dropbox, sincroniza pra VPS.

compile.sh: Detecta worktree via git rev-parse (S301), define DBX apropriado, sincroniza .mqh do $DBX/Include/CopyTrade/ -> $MQL5/Include/CopyTrade/ antes de compilar, chama MetaEditor CLI, copia .ex5 de volta pro $DBX.

Terminal MT5: C:\Users\mrodr\AppData\Roaming\MetaQuotes\Terminal\53785E099C927DB68A545C249CDBCE06\MQL5
Include/CopyTrade: Pasta REAL (S301+) — antes era junction apontando pro Dropbox/main, mas isso vazava arquivos da worktree pro main local quando alguem editava .mqh fora do main. Agora cada bash compile.sh sincroniza explicitamente do $DBX (worktree-aware) pro Terminal.

Dois deploys, dois universos

O sistema tem dois fluxos de deploy distintos com riscos diferentes:

Por que a assimetria eh deliberada:
- Compilar EA exige MetaEditor (Windows GUI), nao roda em CI
- Pool baixa .ex5 em coordenacao — erro propaga pra todas as N contas de uma vez
- Quality gate proposital: passo manual forca validacao no sandbox antes de propagar
- Server restart eh trivial (segundos), reverter eh facil; EA deploy mexe com ordens reais em 12 mesas prop

Implicacao operacional: depois de git commit no main, o servidor ja foi atualizado em background. Mas o EA so atualiza quando voce explicitamente roda bash deploy_ea.sh (com guard que verifica commit limpo + avisa se rodando de worktree).

Workflow Worktree (S301+)

Quando trabalhar numa worktree paralela (criada via Claude Desktop ou bash scripts/paralelo.sh create <nome>):

Risco se pular passo 6: pool roda binario da worktree, mas codigo fonte fica SO na branch. Proximo bash deploy_ea.sh rodado do main compila codigo DIFERENTE/ANTIGO -> regressao silenciosa na pool.

Mitigacao S301++ (commit 125da3f): deploy_ea.sh agora tem guard:
- Aborta se ha mudancas tracked nao-commitadas (forca commit antes de deploy)
- Avisa (nao bloqueia) se rodar de worktree, lembrando do merge pos-validacao
- Override emergencia: DEPLOY_DIRTY_OK=1 bash deploy_ea.sh

Versionamento

Regra: SEMPRE incrementar EA_BUILD ao modificar EA ou qualquer .mqh. Formato: MAJOR.MINOR.PATCH.
CUIDADO: "3.9" > "3.10" em string compare! Sempre usar 2+ digitos: "3.09"
Verificar versao: Log inicializacao | Heartbeat ea_version | Dashboard aba Contas | API GET /accounts

Mixed versions no mesmo grupo: Heartbeat intervals diferentes (WS vs polling), bugs corrigidos em versoes diferentes, ghost WS connections. Recomendacao: Manter TODAS as contas do mesmo grupo na MESMA versao.

Auto-Update v3 Safety

CRITICO: Auto-update NUNCA deve rodar durante trade ativo — EA verifica g_se_hasOpenPositions.

• v3 (atual): PowerShell puro — mata MT5, copia .ex5 novo, MT5 relanca e recarrega EA. Sem ExpertRemove() (v2 usava, podia travar)
• Profile-aware: Le common.ini campo ProfileLast (UTF-16LE) pra detectar qual profile esta ativo. Injeta EA em 1 chart do profile ativo, remove dos extras
• Max tentativas: update_attempts <= 5, depois para
• Reset: UPDATE accounts SET update_attempts=0 WHERE id=X
• Prefixo "b" (ex: "b3.25.0") = versao beta. Normalizar com lstrip('b') no servidor
• Lock file serializa: 1 EA por terminal atualiza por vez

WS Reconnect (v3.77.0+, S253):
- Backoff exponencial: 3s → 6s → 12s → 24s → 48s → 60s (cap 1min). Antes v3.76-: 10-300s (cap 5min) — WS raramente vencia HTTP em reconnect
- Jitter por conta: account_num % 15 (0-14s). Antes v3.76-: % 7 (0-6s). Spread maior anti-storm com 13 EAs simultaneos
- Flush parcial: _flush_pending_signals usa continue em erro (S253) — antes break deixava pendings 4o/5o orfaos ate proximo reconnect
- Health check 60s: se connected=true mas sem msgs -> reset
- Fallback: 3x WS fail -> HTTP polling (2-5s adaptive). WS retenta cada 120s
- Constantes em WinHttpWS.mqh: WS_RECONNECT_BASE_SEC=3, WS_RECONNECT_MAX_SEC=60, WS_RECONNECT_JITTER_MAX_SEC=15

Retomada apos reconexao (server-side, ea_ws.py):
- _flush_pending_signals (linha 600): ao EA reconectar + autenticar, servidor busca PendingSignal da conta com resolved=False e expires_at nao vencido -> re-envia todos via WS. Log [WS-FLUSH] Sent N pending signals to account X. TTL = PENDING_SIGNAL_TTL_SECONDS=60s (sinal velho = pending_expired)
- _detect_missing_positions (linha 647): compara posicoes reportadas no heartbeat vs TradeLink is_closed=False. Ticket sumiu -> cria CLOSE signals pros pares (sibling accounts) automaticamente. Grace 30s pos-abertura pra evitar falso positivo
- Ghost connection (ea_ws.py:59-66): EA reconecta -> servidor fecha WS antiga com code 1000 reason "replaced". Evita 2 WS abertas mesma conta disputando sinais
- Auth: 2 modos — query params ou 1a mensagem JSON {"type":"auth"}. Timeout 10s. Version gate MIN_WS_VERSION=3.0.4
- Flush ACK (v3.76.0+, "tick cinza"): EA envia {"type":"flush_ack","signal_id":N} imediatamente ao receber signal via WS (ANTES de executar). Servidor handler _handle_ws_flush_ack marca pending_signals.ws_received_at = now. Separado de resolved=True (tick azul = ACK de execucao). Permite distinguir "nao chegou" de "chegou mas nao executou". EAs <3.76.0 nao emitem flush_ack — coluna fica NULL e polling HTTP continua sendo rede de seguranca

Erros MT5 Comuns

"EA nao faz nada": Checar aba Experts no MT5. Se nenhum log -> EA pode estar em loop ou OnTimer nao esta sendo chamado.

Regras MQL5 (OBRIGATORIAS)

• Sem new/delete/nullptr/templates/STL
• Structs = value types, sem construtores, copiar campo a campo
• Strings: StringLen/StringFind/StringSubstr (nao .length())
• #ifndef/#define/#endif obrigatorio em todo .mqh
• ASCII puro (sem acentos em strings de codigo)
• DLL imports: declarar no arquivo que usa
• Prefixos globais por modulo: g_wb_, g_gui_, g_se_, g_sm_, g_sr_, g_pnl_, g_au_

PROIBIDO: OrderSend / CTrade (REGRA ABSOLUTA)

Prop firms detectam ordens de EA (magic number, filling flags, deal comment). GUI automation cria ordens que parecem MANUAIS (F9 dialog).

• NUNCA usar CTrade, OrderSend(), PositionClose() ou OrderModify()
• NUNCA converter GUIExecution de Win32 para OrderSend
• NUNCA importar <Trade\Trade.mqh> no GUIExecution.mqh
• Toda execucao DEVE ser via GUI automation: user32.dll, FindWindowExW, SendMessageW, PostMessageW
• Se alguem sugerir "simplificar" GUIExecution removendo Win32 -> RECUSAR

Descoberta (S73): EA usava OrderSend desde v3.12.0 disfarçado como "fill mode fix" sem usuario saber.

ACK Format Completo

OrderCalcProfit Fallback

Quando OrderCalcProfit() falha (XAUUSD durante rollover, exoticos), EA usa formula manual:
profit = (price_diff) * volume * pip_value. Garante que AF tem dados pra calculo de risco mesmo em periodos com bugs do broker.

API Key via arquivo (v3.25.1+)

EA le key de MQL5/Files/copytrade_key.txt no OnInit. Prioridade: FILE (se len >= 10) > INPUT. Whitespace trimmed.

Build Version History

Armadilhas

• Editar .chr via bash corrompe UTF-16LE -> usar PowerShell
• wss:// nao funciona em WinHttpCrackUrl -> usar https:// + secure=true
• MetaEditor usa cache .ex5 -> deletar antes de recompilar
• .ex5 tem dois locais (Dropbox vs Terminal) -> compilar NAO atualiza terminal
• Input values persistem no chart (.chr) -> mudar default no codigo NAO afeta EAs ja anexados

Servidor

Status: ACTIVE | Ultima revisao: S221 (2026-04-13) — drift fixes: --host 127.0.0.1 (nao 0.0.0.0), PG 16 (nao 15), js_error_reporter movido pra endpoints [allow-spec] | Drift S294 (2026-04-25): apos S288-S289 main.py absorveu 3 features novas (Market Hours Guard Camadas 1/4 — ver specs/af-market-hours-guard.md, Correlation ID end-to-end HTTP middleware, Exception Alerter Telegram com dedup). telegram_alerts.py absorveu Telegram dry-run + AfAuditLog (sim-e2e-real F2). Stack/nginx/systemd/PG/cron/rollback inalterados. Cron VPS atual (S293 D''): backup_daily 03h, healthcheck_v2 /2, monitor /5, error-monitor /30 (sem LLM, S293), build-context, quality_monitor, audit-export. daily-audit + weekly-research REMOVIDOS S293. Drift S354 (2026-05-19):* post-receive agora sincroniza scripts/ (causa-raiz drift Abr-25 — crons server-path rodavam código congelado); 7 crons versionados ganharam liveness marker (trap EXIT → /var/log/copytrade-cron-*-last-success.txt) que torna E23 executável. Cron VPS atual = 13 jobs (ver seção Cron). [allow-spec]

SSoT para: Stack VPS, deploy, nginx, systemd, backup, rollback, Telegram, PostgreSQL
Consolida: memory/server-infra.md + .claude/knowledge/copytrade-ops.md + .claude/knowledge/copytrade-server.md + .claude/knowledge/copytrade-rollback.md

Stack

Internet -> Cloudflare (CDN/WAF) -> nginx (SSL linniuc.com) -> uvicorn 127.0.0.1:8000 (1 worker) -> FastAPI
                                                                                            |
                                                                                       PostgreSQL 16

Acesso

• SSH: ssh [email protected]
• App: /opt/copytrade-server/app/
• API interna (via SSH): curl localhost:8000/api/...
• API externa: https://linniuc.com/api/ (porta 8000 NAO exposta)

Systemd Service

[Service]
User=copytrade
WorkingDirectory=/opt/copytrade-server
ExecStart=/opt/copytrade-server/venv/bin/gunicorn app.main:app \
  --bind 127.0.0.1:8000 --workers 1 \
  --worker-class uvicorn.workers.UvicornWorker \
  --timeout 120 --graceful-timeout 30 --keep-alive 5 \
  --access-logfile - --error-logfile - --log-level info
Restart=always | RestartSec=5

1 worker (single-process). Restart limit: 5 em 10s, depois "failed".

Drift fix S373 (2026-05-23): ExecStart real usa gunicorn (gerenciador de processos que supervisiona o worker — reinicia no crash, mata se travar >120s) com worker uvicorn (UvicornWorker), nao uvicorn direto como dizia antes. 1 worker, bind so em localhost. Verificado via systemctl cat copytrade. [allow-spec]

systemctl restart copytrade        # restart
systemctl reset-failed copytrade   # limpar failed
journalctl -u copytrade -f         # logs real-time
journalctl -u copytrade --since '5m ago' --no-pager  # ultimos 5min

Nginx

Config: /etc/nginx/sites-enabled/copytrade. HTTP->HTTPS redirect. www->non-www redirect.
SSL: /etc/ssl/linniuc.com.pem + .key. Certbot auto-renew.
WS: proxy_http_version 1.1, upgrade headers, timeout 600s.

nginx -t && systemctl reload nginx  # testar + reload sem downtime
certbot certificates                # validade SSL

Background Tasks (main.py lifespan)

Endpoints auxiliares (nao background task):
- POST /api/js-error (main.py:835-854) — erros JS do dashboard vao pro Telegram (max 50/uptime via contador _JS_ERROR_MAX, dedup). Nao eh background task; eh endpoint HTTP normal chamado pelo window.onerror do dashboard.

Anti-spam Telegram (S389): o agrupador de rajada (burst aggregator em telegram_alerts.py) agora age SO em erros/riscos — alertas de status (EA online/offline/atualizado/rollout/restart/login ok/reconcile ok) sempre chegam individuais. Erros comprimidos sao resgataveis via comando /erros no bot. SSoT: specs/telegram-antispam-so-erros.md.

Cron

0 3 * * *    backup_daily.sh           # Backup diario 3h UTC (VPS-only)
*/2 * * * *  healthcheck_v2.sh         # Watchdog: auto-restart se cair (VPS-only)
*/5 * * * *  monitor.sh                # Monitor proativo + Telegram (VPS-only)
0 * * * *    build-context.sh          # Contexto pre-compilado do bot
*/30 * * * * error-monitor.sh          # Erros journalctl -> Telegram (sem LLM)
*/15 * * * * quality_monitor.py        # Quality monitor unificado
*/30 * * * * watchdog.py               # Watchdog quality
30 3 * * *   cron/purge_signal_events.sh   # Retention signal_events 90d
0 * * * *    cron/health_audit.sh          # Traffic por endpoint -> alerta
0 4 * * *    cleanup_login_attempts.sh     # Purga login_attempts >30d
45 3 * * *   cron/audit-export.sh          # Export audit .csv.gz (6 anos)
0 12 * * *   vps/drift-detect.sh           # Detecta edicao direta VPS
0 10 * * 0   spec-freshness-alert.sh       # Freshness specs (VPS-only)

Deploy de scripts/ (S354): post-receive sincroniza scripts/ →
/opt/copytrade-server/scripts/ (rsync SEM --delete — preserva VPS-only
como spec-freshness-alert.sh). Antes (até Abr-25) só server/static/docs
eram rsync'd → crons server-path rodavam código congelado. Crons chamados de
/opt/copytrade-code/scripts/ (build-context, error-monitor, drift-detect)
sempre foram frescos (checkout direto do hook).

Liveness markers E23 (#257): os 7 crons versionados gravam epoch UTC em
/var/log/copytrade-cron-<name>-last-success.txt via trap EXIT (só em exit
0). GET /api/health/cron-status lê isso → estação E23 da bateria EA Tester
sai de WARN permanente (available=false) para executável.

Alerta proativo de cron stale (#321, S378+): antes, a estação E23 só pegava
um cron caído manualmente (rodar a bateria) — drift-detect ficou DOWN 6 dias
sem ninguém ver. Agora uma task de fundo no próprio servidor (schedule_cron_stale_check
em server/routes/health_checks.py, disparada no lifespan do main.py) checa
o cron-status a cada CRON_STALE_CHECK_INTERVAL_SEC (6h) e manda Telegram por
cron stale, com dedup por nome via send_telegram_alert(category="cron_stale", dedup_key=<nome>, cooldown=24h) (≤1 alerta/cron/dia). Decisão de design: mora
no servidor (sempre-vivo), NÃO num cron — um cron vigiando crons teria o MESMO
ponto único de falha que isto quer eliminar ("quem vigia o vigia"); se o servidor
cair, tudo já alerta. Função pura testável stale_crons_for_alert(status) (filtra
stale=True; available=false → [], degradação graciosa). Sobrevive a restart
(cooldown in-memory). Limitação conhecida: um cron que nunca gravou marcador é
invisível (sem marcador = fora do mapa); pega o caso real "rodou antes, parou agora"
(marcador envelhece > 24h).

Deploy Checklist (OBRIGATORIO)

Pre-deploy:
1. Syntax check: python -c "import ast; ast.parse(open('file.py').read())"
2. scp arquivo [email protected]:/opt/copytrade-server/app/
3. Import test: ssh root@... 'cd /opt/copytrade-server && python -c "from app.modulo import funcao"'

Deploy:
4. Upload TODOS os arquivos ANTES de restart (deploy atomico)
5. ssh root@... 'systemctl restart copytrade'

Post-deploy:
6. systemctl is-active copytrade -> "active"
7. journalctl -u copytrade --since '30s ago' -> sem erros
8. curl -s https://linniuc.com/api/health -> {"status":"ok"}
9. EAs reconectaram? (ct_status)

REGRA: Restart causa ~2-3s downtime com 4-6 HTTP 502 nos heartbeats. ESPERADO.

Horarios a EVITAR: 23:50-00:05 (daily report), Sun 22:00 UTC (abertura mercado), durante trade ativo.

Rollback

Deploy/mudanca + sistema quebrou?
  |
  +-- Servidor 502? -> §1 Rollback servidor
  +-- DB corrompido? -> §2 Restore DB
  +-- EA crasha?     -> §3 Rollback EA (ver specs/ea-architecture.md)
  +-- Config errada? -> §4 Revert config
  +-- Tela branca?   -> §5 Rollback frontend (ver specs/dashboard.md)

§1 Servidor: cp arquivo.py.bak arquivo.py && systemctl restart copytrade. Sem .bak: git show HEAD~1:scripts/server/ARQUIVO.py.

§2 DB: systemctl stop copytrade && psql < BACKUP.sql && systemctl start copytrade. Parcial: pg_restore -t TABELA.

§4 Config: ct_update_account(account_id=ID, field="group_id", value="GRUPO") ou DB direto.

Checklist pos-rollback: Servidor ativo? Logs sem erros? EAs reconectaram? Posicoes intactas? Dashboard funcional?

PostgreSQL

Pool: SQLAlchemy 5 connections, max overflow 10, recycle 30min.
pg_stat_statements: Habilitado (PG 16). MCP Postgres Pro disponivel.

psql -U copytrade_user -d copytrade -c "VACUUM ANALYZE;"

Tabelas que crescem: heartbeats (cleanup 6h >24h), signal_acks (monitorar), trade_links (ok se <100k).
Migrations: Sem Alembic. ALTER TABLE manual. SEMPRE backup antes. Deploy codigo DEPOIS do ALTER.

Telegram

2 sistemas (mesmo bot @linniuc_vps_bot):
- telegram_alerts.py — Alertas automaticos (thread sync, non-blocking). Debounce por chave+cooldown
- telegram_bot.py — Bot interativo (asyncio polling). Comandos /s, /p, /help

Anti-spam: _should_send(key, cooldown). Chave ACK: ack_failed_{account_name}_{action} (5min).
Cooldown reseta no restart do servidor.
Severidade: _send(text, level="INFO") — prefix emoji por nivel: CRITICAL 🚨, ERROR ❌, WARNING ⚠️, INFO (sem prefix), DEBUG 🔍.

Middlewares

• TrackingMiddleware: PageVisits, UserSessions (JWT), skip heartbeat/ws/health
• RateLimitMiddleware (S381 — contrato cooperativo): conta por identidade VALIDADA (JWT HMAC verificado no middleware sem DB / api-key no cache) e nao por IP cru — resolve o problema do IP consolidado pela Cloudflare. DOIS limites empilhados: balde-por-identidade (usuario logado 1500/min, EA por api-key 300/min) + TETO-POR-IP que SEMPRE aplica (2500/min, defesa em profundidade contra cracha forjado). Anonimo conta so por IP estrito (300/min). /api/sim/* e /api/test/* piso interno 1500/min. Login 30/min/IP (50 localhost). Toda resposta /api/* traz RateLimit-Limit/Remaining/Reset; o 429 traz Retry-After (>=1s) — cliente se auto-regula (dashboard apiFetch re-tenta leitura honrando Retry-After+jitter, nunca escrita; bateria idem). Relogio monotonic (imune a NTP). Estouro sustentado de uma chave (>=20/300s) -> alerta Telegram debounced. in-memory janela-deslizante (CF-Connecting-IP ou TCP source — anti-spoof). Spec: specs/api-rate-limit-sweetspot.md. TODO #322: token bucket futuro gated em metrica.
• IP Whitelist: Bloqueia dashboard de IPs nao listados. Fail-secure se DB/exception (retorna 503, linha 705-708 main.py — confirmado S221). EA/login/static/WS sempre permitidos

MCP Server (Local)

Claude Code (Win11) --stdio--> copytrade_mcp.py (FastMCP 3.1, Python 3.14) --HTTPS--> linniuc.com/api/*

Auth JWT auto-renovacao. Cache TTL 15s/30s. 15 tools read-only.

Scripts Operacionais

Account Onboarding

Adicionar: DB insert ou Dashboard Admin > Contas > Adicionar. Instalar EA, configurar key.
Remover: Fechar posicoes -> SET is_active=false -> remover EA do chart. NAO deletar do DB.

Referencia Rapida