26 lines
2.0 KiB
Markdown
26 lines
2.0 KiB
Markdown
# POST /api/v1/intent/recognize — 外卖比价 Phase 1 意图识别（透传 + 首帧 harvest 建行）
|
||
|
||
> 所属:Compare 组（前缀 `/api/v1`,外卖比价） | 鉴权:**软鉴权 OptionalUser**（带 JWT 则绑 `user_id`,不带也放行） | [← 返回 API 索引](../README.md)
|
||
|
||
## 入参
|
||
任意 JSON body,**不做 schema 校验**,原样透传给上游。后端从中读 `device_id`、`trace_id`、`step`、`device_info` 用于日志与落库。
|
||
客户端实际传源平台购物车页的无障碍树采集结果（pricebot 协议里的 `screens`:`cart_page_1` / `cart_page_2`）。
|
||
|
||
## 出参
|
||
pricebot-backend 的响应**原样返回**（JSON object）,并在顶层补 `trace_id`。典型含 `result`（店名）、`calibration`（含 `source_platform_id` / `items` / `price`），客户端在 `step=0` 把它透传进 `/price/step`。
|
||
|
||
## 错误码
|
||
- `400` body 不是合法 JSON
|
||
- `502` pricebot 上游不可达（网络错误）或返回 5xx
|
||
|
||
## 说明
|
||
把请求体原样转发到 `PRICEBOT_BASE_URL` 的 `/api/intent/recognize`（去掉 `/v1`,async httpx）。**一次比价只调一次**。真正的识别逻辑（剪枝 + 索引 + LLM）在 **pricebot-backend（另一个 repo,GoalEngine）**,本接口只是"透传壳"。
|
||
|
||
外卖比价由客户端无障碍引擎在源平台（淘宝闪购 / 美团 / 京东外卖）购物车页点悬浮球触发 → 调本接口拿 `query` + `calibration` → 进入 `/price/step` 循环。
|
||
|
||
**trace_id 签发 + harvest 建行(2026-07 起,`compare.py`)**:客户端首帧可不带 `trace_id`——app-server 用 uuid 签发、注入转发 body、回填响应顶层;**仅签发那帧**按 `trace_id` 建 [comparison_record](../../database/comparison_record.md) 的 `running` 行(幂等,best-effort),done / finalize 帧再补终态。**软鉴权**:带 Bearer 则记录绑 `user_id`,匿名行 `user_id` 暂空、由后续 `/compare/record` 上报补。
|
||
|
||
**相关配置**:
|
||
- `PRICEBOT_BASE_URL`（默认 `http://localhost:8000`）
|
||
- `PRICEBOT_COMPARE_TIMEOUT_SEC`（默认 60s,意图识别是大上下文 LLM,比领券的 30s 长）
|