@ (#111)
docs/api目录文档分类和补全 --------- Co-authored-by: guke <guke@autohome.com.cn> Reviewed-on: #111
This commit was merged in pull request #111.
This commit is contained in:
@@ -0,0 +1,25 @@
|
||||
# POST /api/v1/intent/recognize — 外卖比价 Phase 1 意图识别（透传到 pricebot）
|
||||
|
||||
> 所属:Compare 组（前缀 `/api/v1`,外卖比价） | 鉴权:**无（MVP 阶段不鉴权）** | [← 返回 API 索引](../README.md)
|
||||
|
||||
## 入参
|
||||
任意 JSON body,**不做 schema 校验**,原样透传给上游。后端仅从中读 `device_id`、`trace_id`、`step` 用于日志。
|
||||
客户端实际传源平台购物车页的无障碍树采集结果（pricebot 协议里的 `screens`:`cart_page_1` / `cart_page_2`）。
|
||||
|
||||
## 出参
|
||||
pricebot-backend 的响应**原样返回**（JSON object）。典型含 `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` 循环。
|
||||
|
||||
⚠️ **MVP 阶段不鉴权**（同 `coupon/step`）:`device_id` 透传给 pricebot 区分设备,后端拿不到 `user_id` → 行为暂绑不到登录用户。待补 JWT,见 [待办与技术债.md](../guides/待办与技术债.md) P1。
|
||||
|
||||
**相关配置**:
|
||||
- `PRICEBOT_BASE_URL`（默认 `http://localhost:8000`）
|
||||
- `PRICEBOT_COMPARE_TIMEOUT_SEC`（默认 60s,意图识别是大上下文 LLM,比领券的 30s 长）
|
||||
@@ -0,0 +1,23 @@
|
||||
# POST /api/v1/price/step — 外卖比价 Phase 2 步进（透传到 pricebot）
|
||||
|
||||
> 所属:Compare 组（前缀 `/api/v1`,外卖比价） | 鉴权:**无（MVP 阶段不鉴权）** | [← 返回 API 索引](../README.md)
|
||||
|
||||
## 入参
|
||||
任意 JSON body,**不做 schema 校验**,原样透传给上游。后端仅从中读 `device_id`、`trace_id`、`step` 用于日志。
|
||||
客户端逐帧上报 `screen_state` + 上一步 `action_result`;`step=0` 还带 `query` + `calibration`（来自 Phase 1）。
|
||||
|
||||
## 出参
|
||||
pricebot-backend 的响应**原样返回**（JSON object）。含 `action`（tap / set_text / launch / wait / done…）、`continue`、`status`;最终 `done` 帧带 `comparison_results`（源 + 各目标平台到手价,按价升序）。
|
||||
|
||||
## 错误码
|
||||
- `400` body 不是合法 JSON
|
||||
- `502` pricebot 上游不可达（网络错误）或返回 5xx
|
||||
|
||||
## 说明
|
||||
把请求体原样转发到 `PRICEBOT_BASE_URL` 的 `/api/price/step`（去掉 `/v1`,async httpx）。**多轮循环**:客户端按返回的 `action` 操作手机、再上报下一帧,直到 `continue=false`。真正的目标驱动比价逻辑（多目标平台串行复现订单、读到手价、聚合排序）在 **pricebot-backend**,本接口只是"透传壳"。
|
||||
|
||||
⚠️ **MVP 阶段不鉴权**（同 `coupon/step`）。
|
||||
|
||||
**相关配置**:
|
||||
- `PRICEBOT_BASE_URL`（默认 `http://localhost:8000`;生产部署应与 pricebot-backend 同内网——比价一单 30~80 步、逐帧多一跳,走公网延迟会累积）
|
||||
- `PRICEBOT_COMPARE_TIMEOUT_SEC`（默认 60s,price/step 每帧都是 LLM）
|
||||
@@ -0,0 +1,113 @@
|
||||
# 比价意图多帧步进（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）
|
||||
Reference in New Issue
Block a user