# MT4_GATEWAY_INVENTORY.yml - Inventario del MT4 Gateway Service
# OrbiQuant IA Trading Platform
# Fecha creación: 2025-12-12
# Última actualización: 2025-12-12

metadata:
  version: "1.0.0"
  created: "2025-12-12"
  last_updated: "2025-12-12"
  author: "Architecture-Analyst"
  module: "MT4 Gateway Service"
  epic: "OQI-009"  # Nueva épica para trading execution
  description: "Servicio gateway para múltiples terminales MT4 con agentes independientes"
  status: "Implementación Inicial"

# ============================================
# RESUMEN EJECUTIVO
# ============================================
resumen:
  proposito: "Unificar acceso a múltiples terminales MT4, cada uno con su agente de trading"
  tipo_servicio: "Python/FastAPI"
  puerto_default: 8090
  total_archivos: 8
  total_endpoints: 15
  agentes_configurados: 3
  estado_implementacion: "Estructura Base"

# ============================================
# ESTRUCTURA DE ARCHIVOS
# ============================================
archivos:
  - id: "FILE-MT4GW-001"
    path: "apps/mt4-gateway/src/main.py"
    tipo: "FastAPI Application"
    descripcion: "Aplicación principal del gateway"
    lineas: ~400
    dependencias:
      - "providers/mt4_bridge_client.py"
      - "config/agents.yml"
    endpoints_definidos: 15
    estado: "Implementado"

  - id: "FILE-MT4GW-002"
    path: "apps/mt4-gateway/src/providers/mt4_bridge_client.py"
    tipo: "Client Library"
    descripcion: "Cliente para comunicación con EA Bridge en MT4"
    lineas: ~350
    clases:
      - name: "MT4BridgeClient"
        metodos: 15
        async: true
      - name: "MT4Tick"
        tipo: "dataclass"
      - name: "MT4Position"
        tipo: "dataclass"
      - name: "MT4AccountInfo"
        tipo: "dataclass"
      - name: "TradeResult"
        tipo: "dataclass"
    estado: "Implementado"

  - id: "FILE-MT4GW-003"
    path: "apps/mt4-gateway/config/agents.yml"
    tipo: "Configuration"
    descripcion: "Configuración de agentes de trading"
    agentes_definidos:
      - agent_1: "Atlas (Conservative)"
      - agent_2: "Orion (Moderate)"
      - agent_3: "Nova (Aggressive)"
    estado: "Implementado"

  - id: "FILE-MT4GW-004"
    path: "apps/mt4-gateway/.env.example"
    tipo: "Environment Template"
    descripcion: "Variables de entorno del servicio"
    variables: 15
    estado: "Implementado"

  - id: "FILE-MT4GW-005"
    path: "apps/mt4-gateway/requirements.txt"
    tipo: "Dependencies"
    descripcion: "Dependencias Python del servicio"
    dependencias_principales:
      - "fastapi>=0.104.0"
      - "uvicorn>=0.24.0"
      - "aiohttp>=3.9.0"
      - "pyyaml>=6.0"
      - "loguru>=0.7.0"
    estado: "Implementado"

  - id: "FILE-MT4GW-006"
    path: "apps/mt4-gateway/src/__init__.py"
    tipo: "Module Init"
    estado: "Implementado"

  - id: "FILE-MT4GW-007"
    path: "apps/mt4-gateway/src/providers/__init__.py"
    tipo: "Module Init"
    estado: "Implementado"

  - id: "FILE-MT4GW-008"
    path: "apps/mt4-gateway/src/services/__init__.py"
    tipo: "Module Init"
    estado: "Implementado"

# ============================================
# API ENDPOINTS
# ============================================
endpoints:
  health:
    - id: "EP-MT4GW-001"
      path: "/health"
      method: "GET"
      descripcion: "Health check del servicio"
      response: "{status, agents_configured, agents_active}"
      autenticacion: false

    - id: "EP-MT4GW-002"
      path: "/api/status"
      method: "GET"
      descripcion: "Estado detallado del servicio"
      response: "{service, version, agents[]}"
      autenticacion: false

  agents:
    - id: "EP-MT4GW-003"
      path: "/api/agents"
      method: "GET"
      descripcion: "Lista todos los agentes configurados"
      response: "{agent_id: {name, enabled, strategy, pairs, active}}"

    - id: "EP-MT4GW-004"
      path: "/api/agents/summary"
      method: "GET"
      descripcion: "Resumen consolidado de todos los agentes"
      response: "GlobalSummary"
      modelo_respuesta: "GlobalSummary"

    - id: "EP-MT4GW-005"
      path: "/api/agents/{agent_id}"
      method: "GET"
      descripcion: "Información detallada de un agente"
      parametros:
        - name: "agent_id"
          tipo: "path"
          required: true

    - id: "EP-MT4GW-006"
      path: "/api/agents/{agent_id}/account"
      method: "GET"
      descripcion: "Información de cuenta MT4 del agente"
      response: "{balance, equity, margin, free_margin, profit, currency, leverage}"

    - id: "EP-MT4GW-007"
      path: "/api/agents/{agent_id}/positions"
      method: "GET"
      descripcion: "Posiciones abiertas del agente"
      response: "{count, positions[]}"

    - id: "EP-MT4GW-008"
      path: "/api/agents/{agent_id}/tick/{symbol}"
      method: "GET"
      descripcion: "Precio actual de un símbolo"
      response: "{bid, ask, spread, timestamp}"

  trading:
    - id: "EP-MT4GW-009"
      path: "/api/agents/{agent_id}/trade"
      method: "POST"
      descripcion: "Ejecuta un trade para un agente"
      body: "TradeRequest"
      response: "{success, ticket, message, error_code}"
      validaciones:
        - "Lot size vs max allowed"
        - "Symbol in allowed pairs"

    - id: "EP-MT4GW-010"
      path: "/api/agents/{agent_id}/close"
      method: "POST"
      descripcion: "Cierra una posición"
      body: "CloseRequest"

    - id: "EP-MT4GW-011"
      path: "/api/agents/{agent_id}/modify"
      method: "POST"
      descripcion: "Modifica SL/TP de una posición"
      body: "ModifyRequest"

    - id: "EP-MT4GW-012"
      path: "/api/agents/{agent_id}/close-all"
      method: "POST"
      descripcion: "Cierra todas las posiciones de un agente"
      parametros:
        - name: "symbol"
          tipo: "query"
          required: false

  emergency:
    - id: "EP-MT4GW-013"
      path: "/api/emergency/stop-all"
      method: "POST"
      descripcion: "EMERGENCY - Cierra todas las posiciones de todos los agentes"
      warning: "Usar solo en emergencias"

# ============================================
# MODELOS DE DATOS (Pydantic)
# ============================================
modelos:
  request:
    - id: "MOD-MT4GW-001"
      name: "TradeRequest"
      campos:
        - name: "symbol"
          tipo: "str"
          required: true
        - name: "action"
          tipo: "str"
          values: ["buy", "sell"]
          required: true
        - name: "lots"
          tipo: "float"
          required: true
        - name: "sl"
          tipo: "float"
          required: false
        - name: "tp"
          tipo: "float"
          required: false
        - name: "comment"
          tipo: "str"
          default: "OrbiQuant"

    - id: "MOD-MT4GW-002"
      name: "CloseRequest"
      campos:
        - name: "ticket"
          tipo: "int"
          required: true
        - name: "lots"
          tipo: "float"
          required: false

    - id: "MOD-MT4GW-003"
      name: "ModifyRequest"
      campos:
        - name: "ticket"
          tipo: "int"
          required: true
        - name: "sl"
          tipo: "float"
          required: false
        - name: "tp"
          tipo: "float"
          required: false

  response:
    - id: "MOD-MT4GW-004"
      name: "AgentSummary"
      campos:
        - "agent_id: str"
        - "name: str"
        - "status: str"
        - "balance: float"
        - "equity: float"
        - "profit: float"
        - "open_positions: int"
        - "strategy: str"

    - id: "MOD-MT4GW-005"
      name: "GlobalSummary"
      campos:
        - "total_balance: float"
        - "total_equity: float"
        - "total_profit: float"
        - "total_positions: int"
        - "agents_online: int"
        - "agents_offline: int"
        - "agents: List[AgentSummary]"

# ============================================
# AGENTES DE TRADING
# ============================================
agentes:
  - id: "AGENT-001"
    codigo: "agent_1"
    nombre: "Atlas"
    descripcion: "Conservative AMD strategy focused on gold"
    enabled: true
    mt4_port: 8081
    strategy: "amd"
    pairs: ["XAUUSD"]
    risk_config:
      initial_balance: 200
      max_risk_per_trade: 0.01
      max_daily_loss: 0.05
      max_positions: 1
      lot_size: 0.01

  - id: "AGENT-002"
    codigo: "agent_2"
    nombre: "Orion"
    descripcion: "Moderate ICT strategy for forex majors"
    enabled: false
    mt4_port: 8082
    strategy: "ict"
    pairs: ["EURUSD", "GBPUSD"]
    risk_config:
      initial_balance: 500
      max_risk_per_trade: 0.015
      max_daily_loss: 0.05
      max_positions: 2
      lot_size: 0.02

  - id: "AGENT-003"
    codigo: "agent_3"
    nombre: "Nova"
    descripcion: "Aggressive multi-pair strategy"
    enabled: false
    mt4_port: 8083
    strategy: "mixed"
    pairs: ["XAUUSD", "EURUSD", "GBPUSD", "USDJPY"]
    risk_config:
      initial_balance: 1000
      max_risk_per_trade: 0.02
      max_daily_loss: 0.05
      max_positions: 3
      lot_size: 0.05

# ============================================
# DEPENDENCIAS
# ============================================
dependencias:
  internas:
    - modulo: "ML Engine"
      tipo: "Consumer"
      descripcion: "Consume señales del ML Engine"
      endpoint: "http://localhost:8000/api/v1/signals"
      protocolo: "HTTP REST"
      estado: "Pendiente integración"

    - modulo: "Data Service"
      tipo: "Reference"
      descripcion: "Referencia para datos de mercado"
      archivo: "apps/data-service/"
      estado: "Activo"

    - modulo: "Backend Express"
      tipo: "Integration"
      descripcion: "Integración para admin dashboard"
      endpoint: "/api/trading/*"
      estado: "Pendiente"

  externas:
    - servicio: "MT4 Terminal + EA Bridge"
      tipo: "Critical"
      descripcion: "Terminal MT4 con EA Bridge corriendo"
      puertos: [8081, 8082, 8083]
      protocolo: "HTTP REST"
      requerido: true

    - servicio: "EBC Financial Group"
      tipo: "Broker"
      descripcion: "Broker MT4 para ejecución"
      servidor: "EBCFinancialGroupKY-Demo02"
      tipo_cuenta: "Demo"

    - servicio: "Polygon.io / Massive.com"
      tipo: "Data Provider"
      descripcion: "Datos de mercado históricos"
      via: "Data Service"

# ============================================
# CONFIGURACIÓN DE PUERTOS
# ============================================
puertos:
  - servicio: "MT4 Gateway"
    puerto: 8090
    protocolo: "HTTP"

  - servicio: "MT4 Terminal Agent 1 (Atlas)"
    puerto: 8081
    protocolo: "HTTP (EA Bridge)"

  - servicio: "MT4 Terminal Agent 2 (Orion)"
    puerto: 8082
    protocolo: "HTTP (EA Bridge)"

  - servicio: "MT4 Terminal Agent 3 (Nova)"
    puerto: 8083
    protocolo: "HTTP (EA Bridge)"

# ============================================
# TRAZABILIDAD
# ============================================
trazabilidad:
  documentacion:
    - tipo: "Arquitectura"
      path: "docs/01-arquitectura/ARQUITECTURA-MULTI-AGENTE-MT4.md"
      estado: "Creado"

    - tipo: "Setup Guide"
      path: "docs/90-transversal/setup/SETUP-MT4-TRADING.md"
      estado: "Creado"

    - tipo: "ADR"
      path: "docs/97-adr/ADR-002-MVP-OPERATIVO-TRADING.md"
      estado: "Creado"

    - tipo: "Integración"
      path: "docs/90-transversal/integraciones/INT-MT4-001-gateway-service.md"
      estado: "Pendiente"

  epicas_relacionadas:
    - codigo: "OQI-003"
      nombre: "Trading y Charts"
      relacion: "Consumer"

    - codigo: "OQI-006"
      nombre: "Señales ML"
      relacion: "Provider"

    - codigo: "OQI-007"
      nombre: "LLM Strategy Agent"
      relacion: "Integration"

    - codigo: "OQI-008"
      nombre: "Portfolio Manager"
      relacion: "Integration"

# ============================================
# MÉTRICAS Y MONITOREO
# ============================================
metricas:
  servicio:
    - nombre: "gateway_health"
      tipo: "gauge"
      descripcion: "Estado del gateway (0/1)"

    - nombre: "agents_online"
      tipo: "gauge"
      descripcion: "Número de agentes conectados"

    - nombre: "total_positions"
      tipo: "gauge"
      descripcion: "Total de posiciones abiertas"

    - nombre: "trade_requests_total"
      tipo: "counter"
      descripcion: "Total de solicitudes de trade"

    - nombre: "trade_latency_seconds"
      tipo: "histogram"
      descripcion: "Latencia de ejecución de trades"

  sla:
    - nombre: "Disponibilidad"
      target: "99.5%"
    - nombre: "Latencia P99"
      target: "<500ms"
    - nombre: "Error Rate"
      target: "<1%"

# ============================================
# PENDIENTES DE IMPLEMENTACIÓN
# ============================================
pendientes:
  - id: "TODO-MT4GW-001"
    descripcion: "Integrar con ML Engine para recibir señales"
    prioridad: "Alta"
    dependencia: "ML Engine WebSocket ready"

  - id: "TODO-MT4GW-002"
    descripcion: "Implementar risk manager service"
    prioridad: "Alta"
    archivos_nuevos:
      - "src/services/risk_manager.py"

  - id: "TODO-MT4GW-003"
    descripcion: "Agregar autenticación JWT"
    prioridad: "Media"

  - id: "TODO-MT4GW-004"
    descripcion: "Implementar WebSocket para updates en tiempo real"
    prioridad: "Media"

  - id: "TODO-MT4GW-005"
    descripcion: "Agregar logging estructurado a PostgreSQL"
    prioridad: "Baja"

# ============================================
# REFERENCIAS
# ============================================
referencias:
  - tipo: "Documentación Externa"
    nombre: "MT4 REST API EA"
    url: "https://github.com/nickyshlee/MT4-REST-API"

  - tipo: "Documentación Externa"
    nombre: "DWX ZeroMQ Connector"
    url: "https://github.com/darwinex/dwx-zeromq-connector"

  - tipo: "Documentación Interna"
    nombre: "Data Service Integration"
    path: "docs/90-transversal/integraciones/INT-DATA-001-data-service.md"