compute_metric

计算供应链 KPI 的实际值。

HTTP 调 Sprint 2 POST /api/graphs/{graph_id}/metrics/{metric_id}/execute， 按 LLM 友好结构包装返回（value / threshold_status / primary_sql 等）。

设计来源: design-sprint3.md v3 §2 (C11)

输入 Schema

用途

算指标值。绕过 RAG 检索直接走 SQL：编译 formula_ast → 跑 PostgreSQL/DuckDB → 返数值 + 阈值评估。错填 metric_id 会自动给同义建议。

调用示例

Claude Desktop 中说："用 graphforge 算一下准交率最近 30 天"

JSON-RPC payload：

{
  "method": "tools/call",
  "params": {
    "name": "compute_metric",
    "arguments": {
      "input": "准交率 最近 30 天"
    }
  }
}

或显式参数（自研 client）：

{
  "metric_id": "on_time_delivery_rate",
  "graph_id": "kg_xxxxxx",
  "time_range": { "from": "2024-11-01", "to": "2024-11-30" },
  "dimensions": ["region"]
}

返回示例

{
  "metric_id": "on_time_delivery_rate",
  "status": "ok",
  "value": 94.3,
  "unit": "%",
  "threshold_status": "amber",
  "rows": [
    { "region": "华东", "value": 96.1 },
    { "region": "华南", "value": 92.5 },
    { "region": "华北", "value": 94.2 }
  ],
  "executed_at": "2024-12-15T10:30:00Z",
  "duration_ms": 145
}

何时用

• 用户问的是具体数字（"X 是多少 / X 涨跌了多少"）
• 比 query_knowledge 快（不走 LLM 综合）+ 准（直接 SQL）
• 复杂归因走 analyze_root_cause，里面会自动调 compute_metric

错误场景

注意

value 按 metric 的 scale 单位输出（pct_ratio scale=100 → 94.3 不是 0.943）。

threshold_status ∈ {green, amber, red, unknown}，需 metric 定义了 thresholds。