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 Mahoraga)

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

Signal Lifecycle — Whitepaper Definitivo

Status: ACTIVE | Ultima revisao: S221 (2026-04-13) — adicionado EC-Test: variante de injecao de sinais de teste (Phase C, signal_source=test, is_test isolation)

Versao: 2.1
Data: 2026-03-31
Status: v2.1: Adicionado 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

Fluxo geral

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

OPEN (linhas 221-280)

1. Gera trade_group_id (UUID)
2. Calcula sl_distance = abs(price - sl), tp_distance = abs(tp - price)
3. Cria Signal com origin="ea", expires_at = now + 1min
4. Cria SignalAck com status="ORIGIN" para conta master
5. Cria TradeLink com is_origin=True para conta master
6. Busca peers do mesmo group_id (exceto master)
7. Para cada peer:
8. Se peer.invert != account.invert → aplica inversao (ver specs/invert-rules.md)
9. Cria Signal + PendingSignal (TTL 60s)
10. Push WS: ea_ws_manager.notify_account(peer.id, "new_signal")

Regra R5: Circuit Breaker

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

MODIFY (linhas 370-400)

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: cria Signal + PendingSignal com ticket = local_ticket do peer
5. Aplica inversao se necessario

CLOSE (linhas 497-520)

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: 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)

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.

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)

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)

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)

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

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.

AF Hedge

AF v2 — Regras Definitivas

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)

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: max_risk >= $2.500 AND max_dd >= 10%

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

Excluidas:
- Alpha Pro: max_risk $1.500 < $2.500 base
- FTP Classic: max_dd 8% < 10%

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?
     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): XAUUSD: $10 | BTCUSD: $50 | Default: $10
Configuravel por pool: rsafe2_price_gate no config JSONB (override via API ou dashboard)

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.

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

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

EA

Status: ACTIVE | Ultima revisao: S194 (2026-04-06)

SSoT para: Modulos EA, compilacao, versionamento, erros MT5, armadilhas
Versao: 2.2 (EA v3.69.0, atualizado S194 — 2026-04-06). Desde 2.1: WebBridge usa Digits() no DoubleToString, MODIFY-VERIFY queue, heartbeat async retry, mensagens legiveis.
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).

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: Copia .mq5 Dropbox→Terminal, compila via MetaEditor CLI, copia .ex5 de volta pro Dropbox.

Terminal MT5: C:\Users\mrodr\AppData\Roaming\MetaQuotes\Terminal\53785E099C927DB68A545C249CDBCE06\MQL5
Junction: MQL5\Include\CopyTrade\ -> Dropbox (editar no Dropbox, MetaEditor le direto)

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.25.0+):
- Backoff: imediato -> 5s -> 15s -> 30s (max)
- Health check 60s: se connected=true mas sem msgs -> reset
- Fallback: 3x WS fail -> HTTP polling (2-5s adaptive). WS retenta cada 120s

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]

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
ExecStart=uvicorn app.main:app --host 127.0.0.1 --port 8000
Restart=always | RestartSec=5
WorkingDirectory=/opt/copytrade-server

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

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.

Cron

0 3 * * *    backup_daily.sh        # Backup diario 3h UTC
*/2 * * * *  healthcheck_v2.sh      # Watchdog: auto-restart se cair
*/5 * * * *  monitor.sh             # Monitor proativo + Telegram alert

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: Login 10/min/IP (50 localhost), API 1000/min/IP, in-memory
• 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

Armadilhas

• http://5.161.104.126:8000 -> porta NAO exposta
• SSH aspas: SEMPRE simples no exterior
• Uvicorn 1 worker: multiplos workers duplicam background tasks
• Log rotation: se disco >80%, checar logs primeiro

Dashboard

Status: ACTIVE | Ultima revisao: S233 (2026-04-14) — drift flush: S11 closePair #160 fix, test accounts toggle, signal timeline modal, pool-paused timer freeze, historical chairs P53-safe [allow-spec]

SSoT para: Frontend SPA, tabs, deploy, armadilhas, XSS, temas
Consolida: memory/dashboard-features.md + .claude/knowledge/copytrade-dashboard.md + memory/dashboard-sidebar-notes.md

Stack

• SPA puro: HTML + vanilla JS + CSS. Sem framework
• Servido por: nginx como static files
• VPS: /opt/copytrade-server/static/ (subpastas: css/, js/)
• URL: https://linniuc.com
• Auth: JWT via localStorage.ct_token (NAO jwt!)
• Login: POST /api/auth/login retorna access_token (NAO token)

Arquivos

Arquitetura JS (S127)

Namespace CT.*

Todo estado compartilhado vive em window.CT = {} (definido em api.js). Variáveis: CT.token, CT.accounts, CT.allSignals, CT.equityChart, CT.chartHours, CT.refreshInterval, CT.notifSound, CT.ws, CT.wsHealthy, CT.syncingAccounts, CT.syncConfirmedAt, CT.afCurrentPool, CT.afPools, etc. Código novo DEVE usar CT.* — nunca criar variáveis globais soltas.

Event Emitter wsEvents

WebSocket handlers registram-se via wsEvents.on('event', fn) em vez de monkey-patching handleWS. Definido em websocket.js. Eventos: heartbeat, signal, ack, reverse, login_failed, settings_synced, alert, account_new, af_pair_update. Módulos que escutam: af_hedge.js (af_pair_update), remote_settings.js (heartbeat), websocket.js (signal, ack, account_new, login_failed, heartbeat).

CSS

Todo CSS vive em styles.css e themes.css. NUNCA injetar CSS via JavaScript (document.createElement('style')). Seções em styles.css: base + Simulator + Delay Analysis + Remote Settings + Modify Modal + ACK Spinner + AF Hedge (battle cards, fighter panels, insight cards) + Journal + Prop Firms.

Tabs (5 grupos, consolidado S107)

1. Visao Geral (Alt+1) — Summary cards por grupo, equity chart overlay, desync alert sonoro, contas. Contas: classificacao obrigatoria (Mesa/Fase/Tamanho/Steps/Dono), botao X excluir permanente (hard delete com confirmacao dupla), auto-nome sem contar deletadas/indefinidas
2. AF Hedge (Alt+2) — Pools, battle cards, force execute, pair history, debug mode, swap close countdown (global + per-card via WS), compact battle timeline. Ferramentas: Validar (in-memory, S170), Reset Historico, Deletar Pool (confirmacao dupla: modal + digitar nome). Simular Round e Stress Test removidos (deprecated 410, S170). Arquivo: af_hedge.js
3. Battle cards (S205): Badges amigaveis (Risco Ajustado, Risco Otimizado, Ultima Chance) com tooltips. Mini-panel centralizado (Entry+SL+TP+Exit) com fundo sutil e borda arredondada. SL mostra badge "+" quando buffer aplicado (sl_buffer_offset via risk_detail, fallback $1 XAUUSD). Footer: mini-tabela de metricas com 4 linhas: Entry Gap (pts + $), Exit Gap (pts + $), Hedge Cost ($ + %), Exit Slip (pts + $) — cada uma com dot colorido (verde/amarelo/vermelho por threshold). Labels: "Risco desta batalha" (header), "Risco Max" (fighter). Nomes usam getAccountDisplay() — busca nome completo + cor do dono de CT.accounts (alinhado com Visao Geral)
4. Trading (Alt+3) — Sub-pills: Sinais | Ordens | Posicoes
5. Sinais: Historico filtrado, delay analysis (cards + tabela expansivel)
6. Ordens: Broadcast, risk calculator V2, price ruler, preview por conta
7. Posicoes: Posicoes abertas, close/modify, risco %, auto-refresh 30s
8. Sistema (Alt+4) — Sub-pills: Saude | Journal | Configuracoes
9. Saude: Health cards, monitor, diagnostics grid, trade trace timeline
10. Journal: Diario de trades, CSV export UTF-8, filtros
11. Configuracoes: Sessions, IP whitelist, users, audit, EA versions, master key
12. Tools (Alt+5) — Sub-pills: Roadmap | Prop Firms | Simulador
13. Roadmap: Kanban drag-and-drop (4 colunas), CRUD cards com tags
14. Prop Firms: Tabela comparativa
15. Simulador: Monte Carlo AF v2

Atalhos: Alt+1..5 (tabs), R (refresh), Esc (fechar modal), ? (ajuda)
Backwards compat: switchTab('signals') redireciona automaticamente para Trading > Sinais

Browser Automation (validacao visual)

Browser MCP (unico — S160):

Login: Usar conta test_runner (NAO admin). Credenciais em .secrets.local e tests/test-helpers.js.
- Campos: #loginUser + #loginPass (submit com \n no campo senha)
- Apos login: #loginPage some e #dashboard aparece

Exemplo @playwright/cli:

playwright-cli open https://linniuc.com --headed   # abre Brave
playwright-cli fill e8 "test_runner"                # usuario (ref do snapshot)
playwright-cli fill e11 "PW_test_runner_2026"       # senha
playwright-cli click e12                            # botao Entrar
playwright-cli screenshot                           # salva PNG em .playwright-cli/
playwright-cli close                                # fecha browser

Navegacao — SEMPRE usar eval (NAO clicar):

// Tabs principais (div.nav-tab, NAO sao buttons)
switchTab('overview')   // Visao Geral
switchTab('tournament')  // Torneio
switchTab('trading')    // Trading
switchTab('system')     // Sistema
switchTab('tools')      // Tools

// Sub-tabs (div.sub-pill)
switchSub('tools', 'roadmap')    // Tools > Roadmap
switchSub('tools', 'propfirms')  // Tools > Prop Firms
switchSub('tools', 'simulator')  // Tools > Simulador
switchSub('trading', 'signals')  // Trading > Sinais
switchSub('trading', 'orders')   // Trading > Ordens
switchSub('trading', 'positions') // Trading > Posicoes

Regras browser:
- Browser eh Brave, nao Chrome. SEMPRE rodar Brave-Debug.bat antes do DevTools MCP
- new_tab com URL no payload (NUNCA vazio + navigate separado)
- list_tabs ANTES de close_tab
- NAO usar tab principal do usuario — sempre nova tab
- Usar test_runner pra login automatizado, NUNCA admin

Padroes de Codigo

// Fetch com auth
const token = localStorage.getItem('ct_token');
const resp = await fetch('/api/endpoint', {
    headers: { 'Authorization': `Bearer ${token}` }
});

// WS
const ws = new WebSocket('wss://linniuc.com/api/ws/dashboard');
ws.onopen = () => ws.send(JSON.stringify({ token: localStorage.getItem('ct_token') }));

// setInterval (LIMPAR antes de criar novo — evita memory leak)
if (window._refreshInterval) clearInterval(window._refreshInterval);
window._refreshInterval = setInterval(refreshData, 5000);

Risk Calculator (Tab Ordens)

3 modos: % Balance, % Equity, USD fixo. Formula: riskMoney / (slDist / tickSize * tickValue)

WebSocket Events

Lista completa (definida em websocket.js via wsEvents):
- heartbeat (balance/equity/positions)
- signal (novo signal)
- ack (confirmacao — MODIFY/CLOSE/OPEN)
- ea_status (online/offline)
- af_pair_update (critico AF — usado por af_hedge.js pra live updates de pares)
- reverse, login_failed, settings_synced, account_new, alert (auxiliares)

Theme System

• Temas via data-theme no <html>: original, apple, cyberpunk, pinkpurple, figma, brutalist
• Modo claro/escuro via data-mode: dark, light
• CSS em themes.css, overrides via [data-theme="xxx"]
• Dark theme padrao: --bg-card: #1a1a2e, --accent: #00d4aa, botoes #7c4dff
• Responsive: 5 breakpoints (1200/900/768/480/375px)

XSS (OBRIGATORIO)

Regra: NUNCA inserir dados da API via innerHTML sem escapeHtml() de api.js.

• Precisam escape: Nomes de conta, brokers, msgs erro, audit logs, qualquer string do servidor
• NAO precisam: Numeros puros, booleanos, strings geradas pelo JS

Status S82: 11 pontos XSS encontrados/corrigidos. Pendentes: positions.js (data-ticket), remote_settings.js (rsModalAccountId)

Deploy Frontend

# 1. Copiar
scp app.js admin.js styles.css [email protected]:/opt/copytrade-server/app/static/
# 2. Cache bust (OBRIGATORIO)
ssh [email protected] "sed -i 's/v=[0-9]*/v=$(date +%Y%m%d%H)/' /opt/copytrade-server/app/static/index.html"
# 3. NAO precisa restart (nginx serve static files)
# 4. Verificar em aba anonima

Debugging Visual

Tela branca: F12 -> Console -> erro JS | Network -> app.js (200 vs 404) | Se erro -> const TDZ ou fetch sem try/catch
Dados nao atualizam: Network -> requests sendo feitas? | setInterval limpo? | WS desconectou?
Layout quebrado: Elements -> CSS | styles.css carregou? | media queries

Armadilhas

Mudancas recentes (S230-S233)

Seletores Importantes

// Login (NAO tem #loginBtn!)
document.querySelector('.login-box .btn-primary')
// Sidebar
document.querySelector('.sidebar')
// Tabelas: #positionsTable, #signalsTable, #accountsTable
// Modais: #editModal
// Sidebar mode: localStorage "layoutSidebar" (NAO "dashboardLayout")
// Theme: #themeSelector > #themePanel

Debugging

SSoT para: Metodologia debug, checklists, ferramentas, race conditions
Consolida: memory/debugging-playbook.md + .claude/knowledge/copytrade-debug.md + .claude/knowledge/debug-sistematico.md
Relacionados: specs/signal-lifecycle.md, specs/invert-rules.md, memory/business-constants.md

Principio

Sem root cause = fix aleatorio. Debugging sistematico: ~95% 1st-time fix. Random fixes: ~40%.
Isolar ANTES de consertar. Entender o que acontece, NAO "mudar e ver se melhora".

Fluxo Universal

1. REPRODUZIR  -> Confirmar que o problema existe agora (nao assumir)
2. LOCALIZAR   -> Qual camada? EA / Servidor / Dashboard / Banco / Rede
3. INSTRUMENTAR -> Coletar dados: logs, queries, screenshots
4. ISOLAR      -> 1 hipotese testavel por vez
5. CORRIGIR    -> Fix cirurgico, minimo necessario
6. VALIDAR     -> Confirmar fix funciona E nao quebrou mais nada
7. DOCUMENTAR  -> Atualizar known-issues.md e changelog.md

Checklist de Contexto (OBRIGATORIO — ANTES de diagnosticar)

1. QUE DIA/HORA? -> FDS? Feriado? Fora de sessao?
   - Forex: seg 00:00 -> sex 22:00 UTC. FECHADO sab/dom
   - Metals (XAUUSD): similar Forex
   - Crypto: 24/7 mas brokers podem ter manutencao
   - Indices: sessoes especificas, nao 24h

2. QUAL BROKER? -> Exness (streaming parcial) vs Capital Point (corta tudo)

3. QUAL SIMBOLO? -> Cada simbolo tem sua sessao

4. CONTROLAR VARIAVEIS -> Se 2 contas diferem: versao EA? Broker? Grupo? PC?
   Correlacao != Causalidade

5. SO DEPOIS -> Se contexto nao explica, AI SIM investigar codigo

Regra de ouro: Contexto simples (mercado fechado, broker offline) eh MAIS provavel que bug.

Regra de Investigacao Completa

1. IMPACTO PRIMEIRO -> open_positions: quem tem posicao aberta?
                    -> trade_links is_closed=false orfaos?
                    -> Posicao SEM par = DESYNC ATIVO
2. DEPOIS SINTOMA   -> debounce, logs, spam
3. NUNCA reportar "zero posicoes" sem conferir TODAS as contas

4 Fases (NAO PULAR)

Fase 1: Root Cause Investigation

• [ ] Ler erro/stack trace COMPLETO
• [ ] Reproduzir o bug (ou entender quando ocorre)
• [ ] git log -5 <arquivo> — commits recentes?
• [ ] Tracar data flow PARA TRAS a partir do sintoma
• [ ] Contexto: mercado aberto? broker? deploy recente?

CopyTrade-specific:
- [ ] Broker market hours? Terminal MT5 conectado? VPS SSH reachavel? DB connection?

Fase 2: Pattern Analysis

• Localizar codigo similar que FUNCIONA
• Listar 3-5 diferencas entre working vs broken
• CopyTrade: Comparar conta que funciona vs conta que falha

Fase 3: Hypothesis Testing

• Formular hipotese TESTAVEL ("Se X, entao Y")
• Mudar UMA variavel por vez
• Predizer resultado ANTES de testar

Fase 4: Implementation

• Test case falhando PRIMEIRO (se aplicavel)
• Fix MINIMO (nao aproveitar pra refatorar)
• Se 3+ tentativas falharam -> PARAR -> repensar abordagem

Red Flags (PARAR)

• Propor solucao antes de completar Fase 1
• 2+ mudancas simultaneas
• "Quick fix" sem root cause
• 3+ fix attempts falhados -> problema ESTRUTURAL
• Workaround em vez de fix

CopyTrade: Fluxo de Copy (EA-to-EA)

1. Conta abre trade -> SnapshotEngine detecta -> POST /api/signals
2. Servidor cria Signal + TradeLink(origin) + PendingSignal
3. Destino poll -> GUIExecution abre -> POST ack (FILLED)
4. Servidor cria TradeLink(slave) -> resolve PendingSignal

Timing: Poll 1-3s, GUI 3-7s, ACK imediato (retry 3x). Total: ~5-10s.

Anti-Loop (4 camadas)

1. trade_links: Ticket ja em trade_links -> descarta
2. pending_signals: PendingSignal ativo -> suprime sinais da conta
3. suppress_markers: MODIFY/CLOSE TTL 10s -> descarta echo
4. Processed Signal Tracker (EA): g_processedSignalIds[] 100 IDs circular

Quality Monitor (9 checks automaticos, S149)

Roda a cada 15min na VPS (scripts/quality/quality_monitor.py). Market-aware (weekday/weekend thresholds). Dedup 1h.

Reconcile (reconcile.py): Detecta phantoms, ghosts, e P&L drift. Roda standalone ou via cron.

Alertas: CRITICAL/HIGH → Telegram imediato. MEDIUM → log only.

Race Conditions Conhecidas

CLOSE antes de OPEN ACK: PendingSignal bloqueia CLOSE enquanto OPEN pendente. Se expirou (>60s) -> orphan checker pega.

MODIFY antes de FILL: EA ignora MODIFY (posicao nao existe). SL/TP reconciliation no heartbeat corrige (debounce 30s).

Duplicate ACK: Servidor usa idempotency — segundo ACK com mesmo signal_id = ignora.

Ferramentas MCP

Trace completo: Identificar trade_group_id (dashboard/DB) -> ct_trace -> procurar gaps (signal sem ACK, ACK FAILED).

Checklists por Camada

EA offline

1. Rodando? tasklist | grep terminal64
2. Heartbeat? SELECT * FROM heartbeats WHERE account_id=X ORDER BY created_at DESC LIMIT 3
3. Log EA: powershell Get-Content ...Logs/YYYYMMDD.log -Encoding Unicode -Tail 50

Signal nao executou

1. Signal existe? 2. Pending criado? 3. EA recebeu? 4. ACK enviado? 5. Trade link? 6. Se FAILED: motivo?

GUI execution falhou

1. Qual operacao? 2. Log "[GUI]" 3. Posicao existe? 4. Lock file? 5. MT5 minimizado? 6. Popup broker?

Trade links inconsistentes

Orfaos: WHERE is_closed=false AND created_at < NOW() - INTERVAL '1h'
Duplicados: GROUP BY trade_group_id HAVING COUNT(*) > 4

Dashboard nao atualiza

1. Servidor rodando? 2. Health OK? 3. WS conectado? (F12 Network) 4. Erro JS? 5. Cache? (Ctrl+Shift+R)

Colunas Corretas (NAO chutar)

• signal_acks: error_msg (NAO error_message, NAO error)
• heartbeats: created_at (NAO last_seen). Ultimo HB: ORDER BY created_at DESC LIMIT 1
• trade_links: is_origin (NAO role)
• Login API: access_token (NAO token)

Data Sources (Dashboard vs API vs DB)

Blast Radius

Arquivos P0 (afeta TUDO): signals.py, ea_ws.py, heartbeat.py, settings.py, main.py.
Mudanca -> backup + teste local + deploy horario seguro + monitorar 5min.

Ferramentas Rapidas

Invert

Invert Rules — Referencia Rapida

Status: ACTIVE | Ultima revisao: S230 (2026-04-14) — revisado, mudancas em signals.py e GUIExecution.mqh desde S194 sao de observabilidade (EventLog S228 C10-C14, Fase F simetria Modify/Close 3.73.6, Telegram alerts ack_failed, drift sync). Nenhuma mudanca toca logica de inversao. Ver specs/ea-observability.md.

Versao: 1.2
Data: 2026-04-14
SSoT para: Logica exata de inversao de sinais no CopyTrade

Conceito

Analogia: Invert e como um espelho. Quando o master abre BUY, o slave invertido abre SELL. O SL e TP tambem trocam de lugar (o que era protecao vira alvo, e vice-versa).

Por que existe: No hedge, um lado PRECISA ser o oposto do outro. Invert automatiza isso.

Regra 1: Quem inverte

No modo online, o EA slave NAO aplica inversao — o sinal ja chega invertido.

Regra 2: Condicao de inversao

EA-to-EA (sinal vindo de outro EA)

INVERTE se: peer.invert != master.invert

Dois EAs com invert=true no mesmo grupo copiam entre si SEM inverter. So inverte quando os flags sao DIFERENTES.

Broadcast (sinal vindo do dashboard)

INVERTE se: account.invert == true

No broadcast nao ha conta de origem, entao a condicao e simplesmente if acct.invert.

Regra 3: O que e invertido (formula)

Pseudo-codigo (identico no servidor e no EA)

funcao inverter(direction, sl, tp):
    direction = "SELL" se era "BUY", "BUY" se era "SELL"
    sl, tp = tp, sl    // swap simples
    sl_distance, tp_distance = tp_distance, sl_distance  // swap

Exemplo concreto

MASTER abre:  BUY XAUUSD,  SL = 2000,  TP = 2100
SLAVE recebe: SELL XAUUSD, SL = 2100,  TP = 2000
                           (era TP)     (era SL)

Codigo real — Servidor (signals.py:78-86)

def _invert_direction(direction: str) -> str:
    return "SELL" if direction == "BUY" else "BUY" if direction == "SELL" else direction

def _invert_sl_tp(sl: float, tp: float, invert: bool):
    if invert:
        return tp, sl   # swap simples
    return sl, tp

Codigo real — EA (GUIExecution.mqh:1527-1531)

void GUIExecution_ApplyInversion(string &direction, string &sl, string &tp)
{
   direction = (direction == "BUY") ? "SELL" : "BUY";
   string tmp = sl; sl = tp; tp = tmp;
}

Regra 4: Inversao por tipo de sinal

CLOSE nao inverte NADA. O servidor usa o local_ticket do TradeLink para saber qual posicao fechar. Direction/SL/TP sao zerados no CLOSE.

Regra 5: Inversao local (EA offline)

Quando InpOnlineMode=false e invert=true:

Regra 6: Protecao contra mudanca

# accounts.py:147-148
if data.invert != account.invert:
    _check_open_positions(db, account_id, "invert")
# Lanca HTTP 409 se conta tem posicoes abertas

NAO e possivel mudar o flag invert de uma conta que tem posicoes abertas. Fechar todas antes.

Regra 7: Onde o flag vive

O servidor e a fonte da verdade. O EA sincroniza o valor no heartbeat.

Gotchas (armadilhas conhecidas)

Auto-Update

Auto-Update EA — Referencia Rapida

Status: ACTIVE | Ultima revisao: S230 (2026-04-14) — revisado, mudancas em ea_ws.py desde S173 sao de observabilidade (Telegram alerts ack_failed, Fase E S228) e NAO afetam o fluxo de auto-update. Logica inalterada. Ver specs/ea-observability.md.

Versao: 1.3
Data: 2026-04-14
SSoT para: Fluxo completo de auto-update do EA (upload → staged rollout → restart)
Relacionado: specs/settings-sync-guardian.md — Settings Sync Guardian (v3.66.0, WS push + verify) complementa o auto-update com sync de configuracoes em tempo real

Conceito

Analogia: E como atualizar um app no celular. O operador faz upload da nova versao, o sistema distribui primeiro pros "beta testers" (contas early), e so depois libera pro resto (contas stable). O EA se auto-atualiza, reinicia o MT5, e volta a operar.

Fluxo Ponta a Ponta

OPERADOR                          SERVIDOR                              EA
─────────                        ─────────                            ────
1. Upload .ex5 via Dashboard  →  2. Salva + SHA256 → ea_versions(pending)
3. Clica "Release"            →  4. stage=testing → desired_version nas early
                                 5. Background monitor (30min)
                                                                     6. Heartbeat HTTP → update_available=true
                                                                     7. Posicoes=0? → Download + Verify + Launch
                                                                     8. Gera PS1, mata MT5, copia .ex5, reinicia
                                                                     9. Proximo HB: versao nova → limpa desired
                                 10. Contas early atualizaram →
                                     stage=stable → desired nas stable
                                                                     11. Contas stable: mesmo fluxo (6-9)

Maquina de Estados (EA)

AU_IDLE ──[update_available=true]──→ posicoes=0? ──sim──→ AU_DOWNLOADING
    ↑                                    |                      |
    |                                   nao               [HTTP GET .ex5]
    |                              AU_WAITING                   |
    |                           (max 30min)              AU_VERIFYING
    |                                    |              [SHA256 + size]
    +────[timeout 30min]─────────────────+                      |
                                                        AU_LAUNCHING
                                                     [gera PS1, ShellExecute]
                                                              |
                                                          AU_DONE
                                                    [Sleep(2s) + ExpertRemove]

Como o EA Detecta Update

Fonte 1: Heartbeat HTTP (principal)

Resposta do POST /api/heartbeat inclui:

{
  "update_available": true,
  "update_version": "3.25.0",
  "update_hash": "1869006665f4eae46...",
  "update_size": 337958,
  "update_url": "/api/ea/download/3.25.0",
  "update_force": false
}

Fonte 2: WebSocket push (secundario)

Mensagem tipo "update" com version + hash + size + url. EA monta fakeHB e chama mesma funcao.

{"type": "update", "version": "3.65.0", "hash": "abc123...", "size": 337958, "url": "/api/ea/download/3.65.0"}

Nota: WS push NAO inclui update_force (sempre assume force=false). Se force necessario, usar heartbeat HTTP.
Armadilha: Com WS ativo, HTTP roda so a cada 120s. Update pode demorar ate 2min pra ser detectado via HTTP.

Fonte 3: Auto-Catchup (automatico)

Se conta NAO tem desired_version definido, heartbeat response automaticamente promove para a versao stable mais recente. Sem acao do operador — "pegar o trem" automaticamente.

Implementado em heartbeat.py:740-763. Util quando contas novas sao criadas apos um release.

Comparacao de Versao

// MAJOR.MINOR.PATCH — componente por componente
AU_CompareVersions("3.25.0", "3.24.1")  → positivo (3.25 > 3.24)
AU_CompareVersions("3.25.0", "3.25.0")  → 0 (iguais = nao atualiza)
AU_CompareVersions("3.24.0", "3.25.0")  → negativo (downgrade bloqueado)

Downgrade so permitido com force=true (rollback via dashboard).

Download e Verificacao

Posicoes Abertas

Lock file so e adquirido quando pronto para baixar. Nao segura o lock durante a espera.

Lock File (anti-race entre EAs)

Script PS1 (7 passos)

O EA gera dinamicamente Common/Files/linniuc_updater.ps1:

1. Kill MT5 — Stop-Process -Id $mt5pid -Force (aguarda ate 20s)
2. Backup — copia LinniuC.ex5 → LinniuC.ex5.bak
3. Renomeia .mq5 — move para .mq5.disabled (evita recompilacao)
4. Copia .ex5 — de linniuc_update.dat → MQL5/Experts/LinniuC.ex5
5. Chart injection (v2):
6. Detecta profile ativo via common.ini (ProfileLast=)
7. Busca .chr apenas no profile ativo
8. Se >1 charts com EA: remove extras
9. Se 0 charts com EA: injeta no primeiro .chr
10. Corrige InpWebAPIKey no .chr
11. Restart MT5 — Start-Process terminal64.exe
12. Cleanup — remove linniuc_update.dat + linniuc_update.lock

Se erro: Bloco catch restaura .ex5.bak, remove lock, reinicia MT5.

Staged Rollout

pending → testing (contas early) → stable (contas stable) → completed
                                           ↘ rolled_back

Monitor de rollout (background, 30min)

• Poll a cada 30s por 30 minutos
• Quando contas early reportam nova versao no heartbeat → promove para stable
• Se 30min sem adocao completa → continua disponivel mas nao promove automaticamente

Servidor — Deteccao de Loop

# heartbeat.py
if desired_clean == current_build:
    # Update concluido! Limpa desired_version
    account.desired_version = None
    account.update_attempts = 0
elif attempts >= 10:
    # Desistir: loop detectado
    account.desired_version = None
    alert_ea_update_failed(...)
else:
    # So conta tentativa se pos_count == 0
    # (Com posicoes = EA em AU_WAITING, nao e falha)
    if pos_count == 0:
        account.update_attempts += 1

Constantes

Endpoints

Tabela DB: ea_versions

Campos em accounts: update_group (early/stable), desired_version (ex: "b3.25.0"), update_attempts (0-10)

Armadilhas Conhecidas

Mudancas Pendentes (decisao do usuario, S73)

Banco de Dados

Conexao

PGPASSWORD=(ver .secrets.local) psql -U copytrade_user -h localhost -d copytrade

Tabelas (24)

accounts

Contas MT5 registradas. Cada EA autentica via api_key.
| Coluna | Tipo | Default | Descricao |
|--------|------|---------|-----------|
| id | serial PK | auto | |
| name | varchar | | Nome amigavel |
| broker | varchar | | Nome da corretora |
| account_num | bigint UNIQUE | | Numero da conta MT5 |
| api_key | varchar | | Chave individual do EA |
| group_id | varchar | | Grupo de copy (ex: Grupo01, TESTE) |
| invert | boolean | | BUY<>SELL, SL<>TP |
| is_active | boolean | | EA ativo? |
| is_deleted | boolean | false | Soft delete |
| deleted_at | timestamp | | |
| created_at | timestamp | | |
| pool | varchar | '' | Pool de torneio |
| max_risk_pct | float | 2.0 | Risco maximo % |
| poll_interval | int | 3 | Segundos entre polls |
| sl_buffer | float | 0.0 | Buffer SL legado |
| tp_buffer | float | 0.0 | Buffer TP legado |
| sl_buffer_metals | float | 0.0 | Buffer SL metais |
| tp_buffer_metals | float | 0.0 | Buffer TP metais |
| sl_buffer_forex | float | 0.0 | Buffer SL forex |
| tp_buffer_forex | float | 0.0 | Buffer TP forex |
| sl_buffer_default | float | 0.0 | Buffer SL default |
| tp_buffer_default | float | 0.0 | Buffer TP default |
| buffer_mode | varchar | 'PIPS' | PIPS ou PRICE |
| settings_dirty | boolean | false | Pendente sync no EA |
| mt5_server | varchar | '' | Servidor MT5 reportado |
| account_type | varchar | 'undefined' | undefined/prop/normal/bonus (v2.71: default changed) |
| account_phase | varchar | '' | F1/F2/Funded/'' |
| bonus_pct | float | 0.0 | % bonus |
| prop_firm | varchar | '' | Nome da prop firm (FTMO, etc) |
| prop_size | varchar | '' | 10k/25k/50k/100k/200k |
| prop_steps | varchar | '' | 1-step/2-step/3-step |
| update_group | varchar | 'stable' | early/stable (auto-update) |
| desired_version | varchar | | Versao desejada pra auto-update |
| update_attempts | int | 0 | Tentativas de update (max 5) |

signals

Sinais de trade (OPEN/MODIFY/CLOSE). Criados pelo EA ou broadcast do dashboard.
| Coluna | Tipo | Descricao |
|--------|------|-----------|
| id | serial PK | |
| group_id | varchar | Grupo destino |
| action | varchar | OPEN/MODIFY/CLOSE |
| ticket | bigint | Ticket MT5 de referencia |
| symbol | varchar | BTCUSD, EURUSD etc |
| direction | varchar | BUY/SELL |
| volume | float | Lotes |
| price | float | Preco de abertura |
| sl | float | Stop Loss |
| tp | float | Take Profit |
| source_account | int FK | Conta que originou |
| created_at | timestamp | |
| expires_at | timestamp | TTL |
| origin | varchar | 'ea' ou 'dashboard' |
| trade_group_id | varchar | UUID agrupador de trades relacionados |
| sl_distance | float | Distancia SL em preco |
| tp_distance | float | Distancia TP em preco |
| signal_channel | varchar(10) | Canal de envio (ws/poll) |
| detection_method | varchar(10) | Metodo de deteccao |
| close_reason | varchar(20) | Motivo do close |
| queued_duration_ms | int | Tempo na fila (ms) |
| server_received_at | timestamp | Quando servidor recebeu |
| server_processing_ms | int | Tempo de processamento servidor (ms) |
| signal_source | varchar(16) | S219: 'manual' (default) ou 'test' |
| trace_id | char(32) | S224: W3C-inspired trace identifier (nullable pre-migration) |

signal_acks

Confirmacao de execucao de sinais pelos EAs.
| Coluna | Tipo | Descricao |
|--------|------|-----------|
| id | serial PK | |
| signal_id | int FK | Sinal confirmado |
| account_id | int FK | Conta que executou |
| status | varchar | ORIGIN/FILLED/FAILED/SKIPPED |
| local_ticket | bigint | Ticket local criado |
| error_msg | text | Mensagem de erro se FAILED |
| executed_at | timestamp | |
| open_price | float | Preco real de abertura |
| applied_sl | float | SL aplicado |
| applied_tp | float | TP aplicado |
| actual_volume | float | Volume real executado |
| receive_channel | varchar(20) | Canal de recebimento (ws/poll) |
| gui_duration_ms | int | Tempo de execucao GUI (ms) |
| total_delay_ms | int | Delay total sinal->execucao (ms) |
| trace_id | char(32) | S224: carrega mesmo trace_id do signal pai (nullable pre-migration) |

signal_events (S224 — ea-observability spec)

Event sourcing do ciclo de vida de cada signal (append-only, PARTITIONED BY RANGE(ts_server) daily, 90d retention).
Timeline 1-click: SELECT * FROM signal_events WHERE signal_id=X ORDER BY seq_num.
| Coluna | Tipo | Descricao |
|--------|------|-----------|
| id | bigserial PK composto | Parte do PK (id + ts_server exigido pela particao) |
| signal_id | int FK signals | Signal dono do evento |
| trace_id | char(32) | W3C-inspired 128-bit hex, nullable pra backward-compat |
| account_id | int | Conta (nao FK pra permitir conta deletada) |
| event_type | varchar(32) | signal_created, ea_received, gui_s1_ok..s11_ok, ack_sent, ack_failed |
| seq_num | smallint | Per-signal 1,2,3... ordem dentro do signal |
| ts_ea | timestamptz | Timestamp origem no EA (nullable) |
| ts_server | timestamptz PK composto | Quando chegou no servidor (chave de particao) |
| payload | jsonb | Contexto rico (error, duration, SL/TP aplicado, etc) |

Indexes (propagados automaticamente pras particoes):
- (signal_id, seq_num) — timeline query principal
- trace_id partial WHERE IS NOT NULL — correlacao cross-signal
- (event_type, ts_server) — stats por tipo no periodo

UNIQUE constraint (idempotencia R7): (signal_id, event_type, seq_num, ts_server) — permite retry ON CONFLICT DO NOTHING.

Particionamento: 7 particoes pre-criadas (CURRENT_DATE..+6d) + signal_events_default safety net. Cron scripts/cron/purge_signal_events.sh cria ahead + DROP >90d + VACUUM.

trade_links

Vinculo entre trades copiados. Permite propagar CLOSE/MODIFY.
| Coluna | Tipo | Descricao |
|--------|------|-----------|
| id | serial PK | |
| trade_group_id | varchar | UUID do grupo |
| signal_id | int FK | Sinal que criou |
| account_id | int FK | Conta dona |
| local_ticket | bigint | Ticket MT5 |
| is_origin | boolean | true = quem originou |
| is_closed | boolean | false | Trade fechado? |
| created_at | timestamp | |
| closed_at | timestamp | |
| close_price | float | Preco de fechamento |
| profit | float | P&L |

pending_signals

Fila de sinais aguardando execucao. TTL 5 minutos (300s).
| Coluna | Tipo | Descricao |
|--------|------|-----------|
| id | serial PK | |
| account_id | int FK | Conta destino |
| symbol | varchar | |
| direction | varchar | BUY/SELL |
| volume | float | |
| signal_id | int FK | |
| trade_group_id | varchar | |
| expires_at | timestamp | TTL 5 min (300s) |
| resolved | boolean | false |
| created_at | timestamp | |

suppress_markers

Anti-echo para MODIFY/CLOSE. TTL 10 segundos.
| Coluna | Tipo | Descricao |
|--------|------|-----------|
| id | serial PK | |
| trade_group_id | varchar | |
| action | varchar | MODIFY/CLOSE |
| expires_at | timestamp | TTL 10s |
| created_at | timestamp | |

open_positions

Snapshot de posicoes abertas, atualizado via heartbeat.
| Coluna | Tipo | Descricao |
|--------|------|-----------|
| id | serial PK | |
| account_id | int FK | |
| ticket | bigint | |
| symbol | varchar | |
| direction | varchar | |
| volume | float | |
| open_price | float | |
| current_price | float | |
| sl | float | |
| tp | float | |
| profit | float | |
| pips | float | |
| swap | float | |
| magic | bigint | |
| open_time | varchar | |
| updated_at | timestamp | |
| tick_value | float | Valor do tick |
| tick_size | float | Tamanho do tick |
| spread | float | Spread em valor de preco |
| commission | float | Comissao total dos deals |
| profit_at_sl | float | P&L projetado se bater SL (OrderCalcProfit) |
| profit_at_tp | float | P&L projetado se bater TP (OrderCalcProfit) |

heartbeats

Heartbeats dos EAs (balance, equity, posicoes). Tabela grande (~20MB).
| Coluna | Tipo | Descricao |
|--------|------|-----------|
| id | serial PK | |
| account_id | int FK | |
| balance | float | |
| equity | float | |
| margin | float | |
| free_margin | float | |
| positions | int | Quantidade |
| server_time | varchar | Hora do servidor MT5 |
| ea_version | varchar | Build do EA |
| created_at | timestamp | |
| applied_settings | jsonb | Settings aplicados pelo EA |

ea_remote_logs

Logs persistidos dos EAs. TTL 7 dias.
| Coluna | Tipo | Descricao |
|--------|------|-----------|
| id | serial PK | |
| account_id | int FK | |
| level | varchar | 'INFO' |
| message | text | |
| created_at | timestamp | now() |

ea_versions

Versoes do EA para auto-update.
| Coluna | Tipo | Descricao |
|--------|------|-----------|
| id | serial PK | |
| version | varchar | Ex: 3.3.4 |
| file_path | varchar | Caminho do .ex5 |
| file_hash | varchar | SHA256 |
| file_size | int | |
| changelog | text | |
| is_stable | boolean | |
| is_active | boolean | |
| rollout_stage | varchar | pending/early/stable |
| download_count | int | |
| uploaded_at | timestamp | |
| stable_at | timestamp | |
| force_update | boolean | false | Forcar update mesmo com posicoes abertas |

equity_snapshots

Snapshots periodicos de equity por conta.
| Coluna | Tipo | Descricao |
|--------|------|-----------|
| id | serial PK | |
| account_id | int FK | |
| balance | float | |
| equity | float | |
| margin | float | |
| free_margin | float | |
| positions | int | |
| snapshot_at | timestamp | now() |

symbol_info

Info de simbolos reportada pelos EAs (tick_value, tick_size, etc).
| Coluna | Tipo | Descricao |
|--------|------|-----------|
| id | serial PK | |
| account_id | int FK | |
| symbol | varchar | |
| tick_value | float | |
| tick_size | float | |
| contract_size | float | |
| digits | int | |
| point | float | |
| volume_min | float | 0.01 |
| volume_max | float | 100.0 |
| volume_step | float | 0.01 |
| spread | float | Spread atual |
| bid | float | Preco bid |
| ask | float | Preco ask |
| swap_long | float | Swap compra |
| swap_short | float | Swap venda |
| updated_at | timestamp | now() |

todos

Lista de pendencias do projeto (fonte unica de verdade). Kanban do site e todos.md sao "janelas" pra esta tabela.
| Coluna | Tipo | Default | Descricao |
|--------|------|---------|-----------|
| id | serial PK | auto | |
| title | varchar(200) | | Titulo da tarefa |
| description | text | '' | Descricao detalhada |
| priority | varchar(10) | 'media' | alta/media/baixa |
| status | varchar(10) | 'backlog' | backlog/next/doing/done |
| tags | text[] | '{}' | Tags (ex: bug, feature, infra) |
| created_at | timestamp | now() | |
| updated_at | timestamp | now() | |
| completed_at | timestamp | null | Preenchido quando status=done |

prop_firms (v2.71, expandida S161)

Prop firms com regras completas. SSoT para AF engine e classificacao de contas.
| Coluna | Tipo | Default | Descricao |
|--------|------|---------|-----------|
| id | serial PK | auto | |
| name | varchar(100) UNIQUE | | Nome (FTMO Swing, FundedNext, etc) |
| default_steps | varchar(20) | '2-step' | 1-step/2-step/3-step |
| phases | JSON | [] | Fases disponiveis (F1, F2, Funded) |
| sizes | JSON | [] | Tamanhos disponiveis (10k, 25k, etc) |
| is_builtin | boolean | false | Se veio pre-cadastrada (seed) |
| created_at | timestamp | now() | |
| program | varchar(100) | '' | Nome do programa (ex: High Stakes Challenge) |
| price | int | 0 | Preco USD (referencia 100k) |
| leverage | varchar(20) | '' | Alavancagem (ex: 1:100) |
| max_dd | float | 10.0 | Max DD % (estatico, base saldo inicial) |
| daily_dd | float | 5.0 | Daily DD % |
| daily_dd_type | varchar(10) | 'equity' | 'equity' ou 'balance' |
| target_f1 | float | 8.0 | Meta F1 % |
| target_f2 | float | 5.0 | Meta F2 % |
| min_days_f1 | int | 0 | Dias minimos trading F1 |
| min_days_f2 | int | 0 | Dias minimos trading F2 |
| min_profit_days | int | 0 | Dias lucrativos obrigatorios |
| max_risk | int | 5000 | Risco operacional por trade USD (100k ref) |
| daily_dd_op | int | 4500 | DD operacional diario USD (100k ref) |
| news_eval | varchar(100) | '' | Restricoes noticias avaliacao |
| news_funded | varchar(100) | '' | Restricoes noticias funded |
| limitation | varchar(200) | '--' | Limitacoes especiais |
| has_200k | boolean | false | Tem conta 200k? |
| is_active | boolean | true | Ativa no sistema? |
| is_af_eligible | boolean | true | Elegivel pro AF engine? (auto: risk>=2500 AND dd>=10) |
| updated_at | timestamp | null | Ultima atualizacao |

account_resets (v2.71)

Historico de resets de classificacao de conta.
| Coluna | Tipo | Default | Descricao |
|--------|------|---------|-----------|
| id | serial PK | auto | |
| account_id | int FK | | Conta resetada |
| reset_at | timestamp | now() | Quando |
| pool_id | int | null | Pool de onde saiu |
| pool_name | varchar(100) | '' | Nome da pool (snapshot) |
| previous_type | varchar(20) | '' | Tipo anterior |
| previous_firm | varchar(100) | '' | Prop firm anterior |
| previous_phase | varchar(20) | '' | Fase anterior |

Tabelas auxiliares

users — Usuarios do dashboard (username, password_hash, display_name, is_active)
user_sessions — Sessoes ativas (username, ip, user_agent, login_at, last_activity, request_count)
login_attempts — Tentativas de login (username_tried, password_tried, ip, success, fail_reason)
page_visits — Visitas a paginas (ip, path, user_agent, username, visited_at)
audit_log — Log de acoes (user, action, detail, created_at)
pairings — Pareamentos de torneio (pool, round_num, account_a/b, balance_a/b, diff_pct, status, bracket_id, match_label, trade_group_id, winner_account_id, profit_a, profit_b, started_at, match_duration_s)
tournament_brackets — Brackets de torneio (name, pool, status, config JSONB, account_ids INT[], bracket_structure JSONB, current_round, matches_today, last_match_date, champion_account_id, created_at, completed_at)
ip_whitelist — IPs permitidos (ip_address, description, is_active)

match_metrics (S100)

Metricas detalhadas de cada batalha de torneio — spread, swap, slippage, drawdown.
| Coluna | Tipo | Descricao |
|--------|------|-----------|
| id | serial PK | |
| pairing_id | int FK pairings | Pareamento relacionado |
| bracket_id | int | Bracket do torneio |
| match_label | varchar(50) | Label do match |
| symbol | varchar(20) | Simbolo (XAUUSD etc) |
| direction | varchar(10) | BUY/SELL |
| broker_a/b | varchar(100) | Corretoras |
| volume | float | Volume em lotes |
| open_price_a/b | float | Preco abertura conta A/B |
| close_price_a/b | float | Preco fechamento conta A/B |
| intended_sl/tp | float | SL/TP planejados |
| actual_sl_a/tp_a | float | SL/TP reais aplicados |
| profit_a/b | float | P&L por conta |
| swap_a/b | float | Swap por conta |
| net_pnl | float | P&L liquido combinado |
| spread_at_open/close | float | Spread no momento de abertura/fechamento |
| slippage_open_a/b | float | Slippage na abertura |
| slippage_close_a/b | float | Slippage no fechamento |
| started_at/ended_at | timestamp | Inicio/fim do match |
| duration_s | int | Duracao em segundos |
| close_trigger | varchar(20) | O que causou o close (sl/tp/timeout) |
| max_dd_a/b | float | Drawdown maximo |
| max_floating_loss_a/b | float | Perda flutuante maxima |
| balance_a/b_before/after | float | Balance antes/depois |
| risk_pct | float | Risco % |
| risk_money | float | Risco $ |
| latency_open/close_a/b | float | Latencia sinal→execucao (s) |
| commission_a/b | float | Comissao por conta |
| spread_broker_a/b | float | Spread do broker |
| winner_account_id | int | Conta vencedora |
| winner_reason | varchar(50) | Motivo da vitoria |
| created_at | timestamp | |

Tabelas AF v2 (S78)

af_pools — Pools AF v2 (name, mode varchar(20) default 'live' LEGACY, validated bool default false, symbol, status, spread_pct, trade_interval_sec, trade_timeout_sec, group_id, config JSONB, created_at, updated_at). S170: mode é legacy (código não lê mais). validated controla se pool pode operar.
af_pool_accounts — Contas no pool com prop atribuida (pool_id FK, account_id FK nullable UNIQUE (uq_account_one_pool — 1 conta = 1 pool), prop_name, prop_config JSONB, phase, virtual_balance, profitable_days, trading_days, status active/dead/funded/paused/passed, chair_number, transition_at, daily_pnl, daily_pnl_peak, direction_history JSONB default '[]' — ultimas 10 direcoes executadas pro anti-OSB, created_at, updated_at). S207: prop_config agora inclui snapshot: owner, account_name, account_type, original_group_id. Cadeiras passed/dead com account_id=NULL usam prop_config pra display historico (nome, cor, badge). virtual_balance serve como saldo congelado.
af_rounds — Rodadas de trading (pool_id FK, round_number, status pending/executing/completed/failed, pairs_count, started_at, completed_at, summary JSONB, created_at)
af_pairs — Pares/batalhas dentro de rodada (round_id FK, pool_id FK, account_a_id FK, account_b_id FK CHECK(a != b — chk_pair_diff_accounts), risk_usd, risk_detail JSONB, symbol, direction_a, volume, sl_price, tp_price, scheduled_at, status, winner_pool_account_id FK, profit_a, profit_b, spread_cost, created_at, completed_at)
af_trades — Trades individuais (pair_id FK, pool_account_id FK, account_id FK, signal_id FK, direction, volume, sl/tp/open/close price, profit, status, local_ticket bigint)
af_audit_log — Log imutavel INSERT-only (pool_id FK, action, entity_type, entity_id, detail text)
af_dead_letters — Dead Letter Queue: sinais AF que falharam (pool_id FK, pair_id, account_id, prop_name, failure_type varchar(50), reason text, attempts int, context JSONB). Tipos: timeout, margin, rsafe, invert, e7_exhausted, gui_fail
symbol_presets — Presets de configuracao por simbolo (id PK, symbol varchar(20) UNIQUE, config JSONB, spread_pct float, created_at, updated_at). Campos preset: sl_min/max, dz_min/max, rsafe2_price_gate, modify_margin_min/max, push_buffer_usd. Defaults hardcoded em server/af/presets.py (XAUUSD, BTCUSD, _default).

trade_events (S128)

Diario de bordo: cada evento na vida de uma posicao. Append-only, cleanup 90 dias.
| Coluna | Tipo | Descricao |
|--------|------|-----------|
| id | bigserial PK | |
| created_at | timestamptz | Quando o evento foi registrado |
| event_type | varchar(30) | OPEN, MODIFY, CLOSE, PROPAGATE, ACK |
| account_id | int FK accounts | Conta envolvida |
| ticket | bigint | Ticket MT5 |
| trade_group_id | varchar(64) | Trade group (ex: TG_xxx, AF_P123) |
| signal_id | int | Signal que gerou o evento |
| origin | varchar(40) | ea, server_cleanup, server_auto_close, ws_detect, heartbeat_gone, admin_reconcile, af_orphan_cleanup |
| close_reason | varchar(30) | Motivo do close (se aplicavel) |
| price | float | Preco da operacao |
| profit | float | P&L capturado |
| volume | float | Volume em lots |
| context | jsonb | Dados extras (symbol, direction, reason, etc) |
Indices: trade_group_id, (account_id, created_at), (event_type, created_at), created_at
Endpoints: GET /api/af/trade-events/pair/{pair_id}, GET /api/af/trade-events/account/{account_id}, GET /api/af/trade-events/{trade_group_id}