shaguabijia-app-server/docs/api/intent/intent-step.md

比价意图多帧步进（intent/step + intent/precoupon/step）

所属:Intent 组（前缀 /api/v1，外卖比价透传） | 鉴权:无（MVP 阶段不鉴权） | ← 返回 API 索引

透传到 pricebot-backend。请求体原样转发、不做 schema 校验。

---

POST /intent/step — Phase 1 多帧意图识别（淘宝源）

淘宝源走多帧版意图识别（展开+滚动采集→提取）：循环调用直到 done（done 帧顶层带 result + calibration）。其它源走单次 /intent/recognize。

入参

透传 pricebot，客户端按 pricebot 协议组装。关键字段：

字段	类型	说明
device_id	string	设备 ID
trace_id	string	比价 trace 标识
frame	int	帧序号（0 起始）
continue	bool	是否继续（pricebot 回传，客户端 next 调用时带上帧）
image	string	当前帧截图 base64
platform	string	源平台
package	string	目标平台包名
(透传)		其余字段由 pricebot 定义，本端点不做校验

Mock 入参（首帧）:

{
  "device_id": "android_abc123def456",
  "trace_id": "tr_20260703_e5f6g7h8",
  "frame": 0,
  "continue": true,
  "image": "/9j/4AAQSkZJRgABAQEAYABgAAD/...(base64)",
  "platform": "taobao",
  "package": "com.sankuai.meituan"
}

出参

透传 pricebot 原始响应。通常包含 action.command（continue / done）、action.params 等。

Mock 出参:

{
  "trace_id": "tr_20260703_e5f6g7h8",
  "frame": 0,
  "continue": true,
  "action": {
    "command": "continue",
    "params": {
      "next_frame": 1,
      "scroll_distance": 300
    }
  }
}

---

POST /intent/precoupon/step — Phase 0 意图识别前先用券（美团源）

美团源平台「意图识别前先用券」多帧循环：客户端在调 /intent/recognize 之前先循环调本端点到 done（continue=false）。订单页底部有「点击使用X红包」就自动选最大免费券用上，已用券/无券则首帧秒过。与 /intent/step 同属 intent 域，复用同一透传壳。

入参

同 /intent/step，透传 pricebot。

Mock 入参（首帧）:

{
  "device_id": "android_abc123def456",
  "trace_id": "tr_20260703_i9j0k1l2",
  "frame": 0,
  "continue": true,
  "image": "/9j/4AAQSkZJRgABAQEAYABgAAD/...(base64)",
  "platform": "meituan",
  "package": "com.sankuai.meituan"
}

出参

透传 pricebot 原始响应。

Mock 出参（无券首帧秒过）:

{
  "trace_id": "tr_20260703_i9j0k1l2",
  "frame": 0,
  "continue": false,
  "action": {
    "command": "done",
    "params": {
      "coupon_used": false,
      "reason": "no_coupon_available"
    }
  }
}

---

错误码

• 502 pricebot 不可达或返回 5xx
• 400 请求体不是合法 JSON

说明

• 两个端点是同域透传，区别是 pricebot 后端路由不同（/api/intent/step vs /api/intent/precoupon/step）
• 一致性 hash 按 trace_id 路由到同一 pricebot 实例
• MVP 阶段不鉴权（待补 JWT）