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

> 所属:Intent 组（前缀 `/api/v1`，外卖比价透传） | 鉴权:无（MVP 阶段不鉴权） | [← 返回 API 索引](../README.md)

透传到 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 入参（首帧）:
```json
{
  "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 出参:
```json
{
  "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 入参（首帧）:
```json
{
  "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 出参（无券首帧秒过）:
```json
{
  "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）