evotraders/docs/runtime-api-changes.md

Runtime Service API 说明

概述

本文档描述当前 runtime_service API 的关键端点、增强响应字段和启动/健康检查相关行为。 它应被视为 runtime API 的补充说明，而不是迁移过程中的一次性变更记录。

适用范围

• 运行时控制面：backend.apps.runtime_service
• 运行时 API 前缀：/api/runtime/*
• 当前推荐配套阅读：
  • README.md
  • README_zh.md
  • docs/current-architecture.md

关于 schedule_mode 的当前约定

当前对外约定统一使用 daily / interval。

• interval 是当前公开的盘中轮询名称
• intraday 仅作为向后兼容输入别名保留
• runtime API 的响应和写回配置应优先输出 interval

新增端点

1. GET /api/runtime/mode

返回当前运行模式（实盘或回测）及相关配置。

响应模型: RuntimeModeResponse

{
  "mode": "live",
  "is_backtest": false,
  "run_id": "20250401_120000",
  "schedule_mode": "daily",
  "is_running": true
}

字段说明:

• mode: 运行模式，"live"（实盘）或 "backtest"（回测），运行时停止时为 "stopped"
• is_backtest: 是否为回测模式
• run_id: 当前运行的任务 ID
• schedule_mode: 调度模式字段。当前公开值为 daily 或 interval； 历史输入别名 intraday 会在服务端归一化为 interval。
• is_running: Gateway 是否正在运行

---

2. GET /api/runtime/gateway/health

全面的 Gateway 健康检查，包括进程状态、端口连通性和配置状态。

响应模型: GatewayHealthResponse

{
  "status": "healthy",
  "checks": {
    "process": {
      "status": "healthy",
      "details": {
        "pid": 12345,
        "status": "running",
        "returncode": null
      }
    },
    "port": {
      "status": "healthy",
      "details": {
        "port": 8765,
        "accessible": true
      }
    },
    "configuration": {
      "status": "healthy",
      "details": {
        "has_runtime_manager": true
      }
    }
  },
  "timestamp": "2025-04-01T12:00:00.000000"
}

状态说明:

• status: 整体健康状态，"healthy"（健康）、"degraded"（降级）或 "unhealthy"（不健康）
• checks.process.status: 进程状态
• checks.port.status: 端口连通性
• checks.configuration.status: 配置状态

---

3. GET /health/gateway

服务级别的 Gateway 健康检查端点。

响应示例:

{
  "status": "healthy",
  "checks": {
    "process": {
      "status": "healthy",
      "details": {
        "pid": 12345,
        "status": "running",
        "returncode": null
      }
    },
    "port": {
      "status": "healthy",
      "details": {
        "port": 8765,
        "accessible": true
      }
    },
    "configuration": {
      "status": "healthy",
      "details": {
        "has_runtime_manager": true
      }
    }
  },
  "timestamp": "2025-04-01T12:00:00.000000"
}

---

关键端点说明

GET /api/runtime/gateway/status

新增字段:

• process_status: 进程状态（"running"、"exited"、"not_running"）
• pid: 进程 ID

响应示例:

{
  "is_running": true,
  "port": 8765,
  "run_id": "20250401_120000",
  "process_status": "running",
  "pid": 12345
}

---

GET /health

改进的响应结构:

{
  "status": "healthy",
  "service": "runtime-service",
  "gateway": {
    "running": true,
    "port": 8765,
    "pid": 12345,
    "process_status": "running",
    "returncode": null
  }
}

字段说明:

• status: 服务整体状态（考虑 Gateway 进程状态）
• gateway.running: Gateway 是否运行中
• gateway.pid: Gateway 进程 ID
• gateway.process_status: 进程详细状态
• gateway.returncode: 进程退出码（如已退出）

---

GET /api/status

新增字段:

• runtime.gateway_pid: Gateway 进程 ID
• runtime.gateway_process_status: 进程状态

响应示例:

{
  "status": "operational",
  "service": "runtime-service",
  "runtime": {
    "gateway_running": true,
    "gateway_port": 8765,
    "gateway_pid": 12345,
    "gateway_process_status": "running",
    "has_runtime_manager": true
  }
}

---

POST /api/runtime/start

改进的错误信息:

启动失败时返回详细的错误信息，包括：

• 进程退出码
• 最近的日志输出（最多 4000 字符）
• 配置问题检测

错误响应示例:

{
  "detail": "Gateway process exited unexpectedly\nExit code: 1\nRecent log output:\n[ERROR] FINNHUB_API_KEY not set...\nConfiguration issues detected: FINNHUB_API_KEY environment variable is required for live mode"
}

---

POST /api/runtime/stop

改进的错误信息:

• 当 Gateway 进程已退出时，返回包含退出码和 PID 的详细信息
• 停止失败时返回具体原因

错误响应示例（进程已退出）:

{
  "detail": "No runtime is currently running. Previous Gateway process exited with code 1. PID: 12345"
}

成功响应:

{
  "status": "stopped",
  "message": "Runtime stopped successfully (PID: 12345)"
}

---

配置验证

启动时验证

Gateway 启动前会自动验证以下配置：

1. 模式验证

   • mode 必须是 "live" 或 "backtest"

2. 环境变量

   • 实盘模式需要 FINNHUB_API_KEY
   • 需要 MODEL_NAME 和 OPENAI_API_KEY

3. 股票池

   • tickers 不能为空且必须是列表

4. 数值验证

   • initial_cash 必须大于 0
   • margin_requirement 必须在 0-1 之间

5. 回测日期

   • start_date 和 end_date 格式必须为 YYYY-MM-DD
   • start_date 必须早于 end_date

6. 调度模式

   • 当前公开校验值为 "daily" / "interval"
   • 历史输入 "intraday" 会被兼容性归一化为 "interval"

验证失败响应:

{
  "detail": "Gateway configuration validation failed: FINNHUB_API_KEY environment variable is required for live mode; initial_cash must be greater than 0"
}

---

数据模型

GatewayStatusResponse

class GatewayStatusResponse(BaseModel):
    is_running: bool
    port: int
    run_id: Optional[str] = None
    process_status: Optional[str] = None  # 新增
    pid: Optional[int] = None             # 新增

GatewayHealthResponse

class GatewayHealthResponse(BaseModel):
    status: str
    checks: Dict[str, Any]
    timestamp: str

RuntimeModeResponse

class RuntimeModeResponse(BaseModel):
    mode: str
    is_backtest: bool
    run_id: Optional[str] = None
    schedule_mode: Optional[str] = None
    is_running: bool

---

架构改进

新增辅助函数

1. _validate_gateway_config(bootstrap)

   • 验证 Gateway 启动配置
   • 返回验证错误列表

2. _get_gateway_process_details()

   • 获取 Gateway 进程详细信息
   • 包括 PID、状态、退出码

3. _check_gateway_health()

   • 执行全面的健康检查
   • 检查进程、端口、配置

---

向后兼容性

所有改进都保持向后兼容：

• 现有端点继续工作
• 新增字段为可选
• 错误响应格式保持不变（仅在 detail 中提供更详细信息）