# TRACEABILITY.yml - OQI-004 Cuentas de Inversión
# Mapeo de requerimientos a implementación

version: "1.0.0"
epic: OQI-004
name: "Cuentas de Inversión Gestionadas"
updated: "2025-12-05"
status: pending

# Resumen de trazabilidad
summary:
  total_requirements: 6
  total_specs: 7
  total_user_stories: 14
  total_files_to_implement: 45
  test_coverage: "TBD"
  story_points: 57

# Mapeo de Requerimientos Funcionales
requirements:
  RF-INV-001:
    name: "Catálogo de Productos"
    status: pending
    specs:
      - ET-INV-001
      - ET-INV-002
      - ET-INV-005
    user_stories:
      - US-INV-001
      - US-INV-010
    implementation:
      backend:
        - path: apps/backend/src/modules/investment/services/product.service.ts
          description: "Servicio de productos de inversión"
          methods:
            - getProducts
            - getProductById
            - getProductByCode
            - compareProducts
            - getProductPerformance
        - path: apps/backend/src/modules/investment/controllers/investment.controller.ts
          methods:
            - listProducts
            - getProduct
            - compareProducts
        - path: apps/backend/src/modules/investment/investment.routes.ts
          routes:
            - "GET /investment/products"
            - "GET /investment/products/:id"
            - "GET /investment/products/compare"
      frontend:
        - path: apps/frontend/src/modules/investment/pages/Products.tsx
          description: "Catálogo de productos"
        - path: apps/frontend/src/modules/investment/components/ProductCard.tsx
          description: "Tarjeta de producto (Atlas/Orion/Nova)"
        - path: apps/frontend/src/modules/investment/components/ProductComparison.tsx
          description: "Comparador de productos"
        - path: apps/frontend/src/modules/investment/components/RiskIndicator.tsx
          description: "Indicador de riesgo"
      database:
        - path: apps/database/schemas/04_investment_schema.sql
          tables:
            - investment_products
            - product_performance
          enums:
            - product_type_enum
            - risk_level_enum
    tests:
      - path: apps/backend/tests/investment/product.service.test.ts
        status: pending

  RF-INV-002:
    name: "Gestión de Cuentas"
    status: pending
    specs:
      - ET-INV-001
      - ET-INV-002
    user_stories:
      - US-INV-002
      - US-INV-004
      - US-INV-009
    implementation:
      backend:
        - path: apps/backend/src/modules/investment/services/account.service.ts
          description: "Servicio de cuentas de inversión"
          methods:
            - createAccount
            - getAccounts
            - getAccountById
            - updateAccount
            - closeAccount
            - getAccountBalance
            - getAccountPerformance
        - path: apps/backend/src/modules/investment/controllers/investment.controller.ts
          methods:
            - createAccount
            - getMyAccounts
            - getAccount
            - closeAccount
        - path: apps/backend/src/modules/investment/investment.routes.ts
          routes:
            - "GET /investment/accounts"
            - "POST /investment/accounts"
            - "GET /investment/accounts/:id"
            - "PUT /investment/accounts/:id"
            - "DELETE /investment/accounts/:id"
      frontend:
        - path: apps/frontend/src/modules/investment/pages/Investment.tsx
          description: "Página principal de inversiones"
        - path: apps/frontend/src/modules/investment/pages/AccountDetail.tsx
          description: "Detalle de cuenta"
        - path: apps/frontend/src/modules/investment/pages/OpenAccount.tsx
          description: "Abrir nueva cuenta"
        - path: apps/frontend/src/modules/investment/components/AccountSummary.tsx
          description: "Resumen de cuenta"
        - path: apps/frontend/src/modules/investment/components/AccountList.tsx
          description: "Lista de cuentas"
      database:
        - path: apps/database/schemas/04_investment_schema.sql
          tables:
            - investment_accounts
            - account_balances
          enums:
            - account_status_enum
    tests:
      - path: apps/backend/tests/investment/account.service.test.ts
        status: pending

  RF-INV-003:
    name: "Depósitos"
    status: pending
    specs:
      - ET-INV-002
      - ET-INV-003
    user_stories:
      - US-INV-003
    implementation:
      backend:
        - path: apps/backend/src/modules/investment/services/deposit.service.ts
          description: "Servicio de depósitos"
          methods:
            - initiateDeposit
            - confirmDeposit
            - getDeposits
            - calculateDepositFee
            - validateDeposit
        - path: apps/backend/src/modules/investment/controllers/investment.controller.ts
          methods:
            - createDeposit
            - getDeposits
            - confirmDeposit
        - path: apps/backend/src/modules/investment/investment.routes.ts
          routes:
            - "POST /investment/accounts/:id/deposit"
            - "GET /investment/accounts/:id/deposits"
            - "POST /investment/deposits/:id/confirm"
      frontend:
        - path: apps/frontend/src/modules/investment/components/DepositModal.tsx
          description: "Modal de depósito"
        - path: apps/frontend/src/modules/investment/components/DepositHistory.tsx
          description: "Historial de depósitos"
        - path: apps/frontend/src/modules/investment/components/PaymentMethodSelector.tsx
          description: "Selector de método de pago"
      database:
        - path: apps/database/schemas/04_investment_schema.sql
          tables:
            - deposits
          enums:
            - deposit_status_enum
            - payment_method_enum
    external:
      - service: Stripe
        usage: "Procesamiento de pagos"
    tests:
      - path: apps/backend/tests/investment/deposit.service.test.ts
        status: pending

  RF-INV-004:
    name: "Retiros"
    status: pending
    specs:
      - ET-INV-002
      - ET-INV-003
    user_stories:
      - US-INV-006
    implementation:
      backend:
        - path: apps/backend/src/modules/investment/services/withdrawal.service.ts
          description: "Servicio de retiros"
          methods:
            - initiateWithdrawal
            - approveWithdrawal
            - rejectWithdrawal
            - getWithdrawals
            - calculateWithdrawalFee
            - validateWithdrawal
        - path: apps/backend/src/modules/investment/controllers/investment.controller.ts
          methods:
            - createWithdrawal
            - getWithdrawals
            - cancelWithdrawal
        - path: apps/backend/src/modules/investment/investment.routes.ts
          routes:
            - "POST /investment/accounts/:id/withdraw"
            - "GET /investment/accounts/:id/withdrawals"
            - "DELETE /investment/withdrawals/:id"
      frontend:
        - path: apps/frontend/src/modules/investment/components/WithdrawModal.tsx
          description: "Modal de retiro"
        - path: apps/frontend/src/modules/investment/components/WithdrawalHistory.tsx
          description: "Historial de retiros"
        - path: apps/frontend/src/modules/investment/components/BankAccountSelector.tsx
          description: "Selector de cuenta bancaria"
      database:
        - path: apps/database/schemas/04_investment_schema.sql
          tables:
            - withdrawals
            - bank_accounts
          enums:
            - withdrawal_status_enum
    tests:
      - path: apps/backend/tests/investment/withdrawal.service.test.ts
        status: pending

  RF-INV-005:
    name: "Agentes de Trading"
    status: pending
    specs:
      - ET-INV-004
    user_stories:
      - US-INV-014
    implementation:
      backend:
        - path: apps/backend/src/modules/investment/services/agent.service.ts
          description: "Servicio de agentes/bots"
          methods:
            - getAgents
            - getAgentById
            - getAgentPerformance
            - assignAgentToAccount
            - getAgentTrades
        - path: apps/backend/src/modules/investment/controllers/investment.controller.ts
          methods:
            - listAgents
            - getAgentPerformance
            - assignAgent
        - path: apps/backend/src/modules/investment/investment.routes.ts
          routes:
            - "GET /investment/agents"
            - "GET /investment/agents/:id"
            - "GET /investment/agents/:id/performance"
            - "POST /investment/accounts/:id/agent"
      frontend:
        - path: apps/frontend/src/modules/investment/components/BotSelector.tsx
          description: "Selector de bot/agente"
        - path: apps/frontend/src/modules/investment/components/AgentCard.tsx
          description: "Tarjeta de agente"
        - path: apps/frontend/src/modules/investment/components/AgentPerformance.tsx
          description: "Rendimiento del agente"
      database:
        - path: apps/database/schemas/04_investment_schema.sql
          tables:
            - trading_agents
            - agent_performance
            - agent_trades
          enums:
            - agent_status_enum
            - agent_strategy_enum
    tests:
      - path: apps/backend/tests/investment/agent.service.test.ts
        status: pending

  RF-INV-006:
    name: "Reportes y Rendimiento"
    status: pending
    specs:
      - ET-INV-005
      - ET-INV-006
    user_stories:
      - US-INV-005
      - US-INV-007
      - US-INV-008
      - US-INV-011
      - US-INV-012
    implementation:
      backend:
        - path: apps/backend/src/modules/investment/services/report.service.ts
          description: "Servicio de reportes"
          methods:
            - getPerformanceReport
            - getTransactionHistory
            - getDistributionHistory
            - exportReport
            - generatePDF
            - sendNotification
        - path: apps/backend/src/modules/investment/controllers/investment.controller.ts
          methods:
            - getPerformance
            - getTransactions
            - exportReport
        - path: apps/backend/src/modules/investment/investment.routes.ts
          routes:
            - "GET /investment/accounts/:id/performance"
            - "GET /investment/accounts/:id/transactions"
            - "GET /investment/accounts/:id/distributions"
            - "GET /investment/accounts/:id/export"
      frontend:
        - path: apps/frontend/src/modules/investment/components/PerformanceChart.tsx
          description: "Gráfico de rendimiento"
        - path: apps/frontend/src/modules/investment/components/TransactionHistory.tsx
          description: "Historial de transacciones"
        - path: apps/frontend/src/modules/investment/components/DistributionHistory.tsx
          description: "Historial de distribuciones"
        - path: apps/frontend/src/modules/investment/components/ReportExporter.tsx
          description: "Exportador de reportes"
      database:
        - path: apps/database/schemas/04_investment_schema.sql
          tables:
            - transactions
            - distributions
            - performance_snapshots
          enums:
            - transaction_type_enum
    tests:
      - path: apps/backend/tests/investment/report.service.test.ts
        status: pending

# Mapeo de archivos de configuración
config_files:
  backend:
    - path: apps/backend/src/modules/investment/investment.module.ts
      description: "Módulo de inversión"
    - path: apps/backend/src/modules/investment/validators/investment.validators.ts
      description: "Validadores Zod"
    - path: apps/backend/src/modules/investment/types/investment.types.ts
      description: "Tipos TypeScript"
    - path: apps/backend/src/modules/investment/cron/investment.cron.ts
      description: "Jobs programados"
  frontend:
    - path: apps/frontend/src/modules/investment/stores/investment.store.ts
      description: "Store de inversión Zustand"
    - path: apps/frontend/src/modules/investment/hooks/useInvestment.ts
      description: "Hook principal de inversión"
    - path: apps/frontend/src/modules/investment/services/investment.api.ts
      description: "Cliente API de inversión"

# Dependencias externas
external_dependencies:
  npm_backend:
    - name: stripe
      version: "^14.0.0"
      usage: "Procesamiento de pagos"
    - name: pdfkit
      version: "^0.14.0"
      usage: "Generación de reportes PDF"
    - name: node-cron
      version: "^3.0.0"
      usage: "Jobs programados"
    - name: nodemailer
      version: "^6.9.7"
      usage: "Notificaciones por email"
  npm_frontend:
    - name: recharts
      version: "^2.10.0"
      usage: "Gráficos de rendimiento"
    - name: "@tanstack/react-query"
      version: "^5.0.0"
      usage: "Data fetching"

# APIs de terceros
third_party_apis:
  - name: Stripe
    docs: https://stripe.com/docs/api
    usage:
      - Payment Intents
      - Customers
      - Payment Methods
      - Payouts
  - name: TradingAgent ML
    docs: internal
    usage:
      - Predicciones ML
      - Señales de trading
      - Ejecución automatizada

# Endpoints API
api_endpoints:
  base_path: /api/v1/investment
  endpoints:
    # Productos
    - method: GET
      path: /products
      requirement: RF-INV-001
      auth: false
    - method: GET
      path: /products/:id
      requirement: RF-INV-001
      auth: false
    - method: GET
      path: /products/compare
      requirement: RF-INV-001
      auth: false
    # Cuentas
    - method: GET
      path: /accounts
      requirement: RF-INV-002
      auth: true
    - method: POST
      path: /accounts
      requirement: RF-INV-002
      auth: true
    - method: GET
      path: /accounts/:id
      requirement: RF-INV-002
      auth: true
    - method: DELETE
      path: /accounts/:id
      requirement: RF-INV-002
      auth: true
    # Depósitos
    - method: POST
      path: /accounts/:id/deposit
      requirement: RF-INV-003
      auth: true
    - method: GET
      path: /accounts/:id/deposits
      requirement: RF-INV-003
      auth: true
    # Retiros
    - method: POST
      path: /accounts/:id/withdraw
      requirement: RF-INV-004
      auth: true
    - method: GET
      path: /accounts/:id/withdrawals
      requirement: RF-INV-004
      auth: true
    # Agentes
    - method: GET
      path: /agents
      requirement: RF-INV-005
      auth: true
    - method: GET
      path: /agents/:id/performance
      requirement: RF-INV-005
      auth: true
    - method: POST
      path: /accounts/:id/agent
      requirement: RF-INV-005
      auth: true
    # Reportes
    - method: GET
      path: /accounts/:id/performance
      requirement: RF-INV-006
      auth: true
    - method: GET
      path: /accounts/:id/transactions
      requirement: RF-INV-006
      auth: true
    - method: GET
      path: /accounts/:id/export
      requirement: RF-INV-006
      auth: true

# Dependencias de épicas
dependencies:
  blocks:
    - epic: OQI-008
      reason: "Portfolio Manager usa cuentas de inversión"
  blocked_by:
    - epic: OQI-001
      reason: "Requiere autenticación de usuarios"
    - epic: OQI-005
      reason: "Requiere sistema de pagos para depósitos"
    - epic: OQI-006
      reason: "Agentes usan señales ML"

# Productos de inversión
products:
  - code: ATLAS
    name: "Atlas Growth"
    risk: moderate
    min_investment: 5000
    target_return: "12-18% anual"
    strategy: "ML momentum + value"
  - code: ORION
    name: "Orion Aggressive"
    risk: high
    min_investment: 10000
    target_return: "20-35% anual"
    strategy: "ML high-frequency + options"
  - code: NOVA
    name: "Nova Conservative"
    risk: low
    min_investment: 1000
    target_return: "6-10% anual"
    strategy: "ML index + dividend"

# Notas y decisiones
notes:
  - "Montos mínimos de inversión por producto"
  - "Distribuciones trimestrales automáticas"
  - "Retiros procesados en 3-5 días hábiles"
  - "KYC básico requerido para inversiones > $10,000"
  - "Performance fee: 20% sobre ganancias > benchmark"
  - "Management fee: 1% anual sobre AUM"