guke
b23335d5fb
docs: reorganize api docs into categorized subdirectories and fill missing docs - Categorize 77 existing api docs into 16 business-domain subdirectories (auth/ad/wallet/coupon/compare/savings/signin/tasks/invite/user/ device/platform/intent/meituan/other) plus admin/ and internal/ - Split admin/ into 7 sub-resource subdirectories (auth/users/wallet/ withdraws/feedbacks/admins/ad) with 4 single-file docs at root - Create 21 new docs covering 28 previously undocumented endpoints: ad/watch-report, wallet/transfer-auth (3 endpoints), coupon/session+ stats+completed-today+prompt (7), invite/me+invitees+bind+landing-track, user/onboarding (2), platform/flags+ad-config+app-version, intent/step+precoupon/step, analytics/events, order/report, report/submit+records, feedback/config+records, trace/finalize - Add mock request/response JSON examples to all new docs - Create docs/README.md with full category index for LLM navigation - Update docs/api/README.md: fix all links, add new endpoint rows, replace "no doc" markers with actual links - Fix back-navigation links (./README.md -> ../README.md or ../../README.md) in all moved files @
114 lines
3.0 KiB
Markdown
114 lines
3.0 KiB
Markdown
# 比价意图多帧步进（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）
|