guke
a563c1ca4b
docs/api目录文档分类和补全 --------- Co-authored-by: guke <guke@autohome.com.cn> Reviewed-on: #111
42 lines
2.9 KiB
Markdown
42 lines
2.9 KiB
Markdown
# POST /api/v1/meituan/feed — 首页推荐流(多 tab)
|
||
|
||
> 所属:美团 CPS 组(前缀 `/api/v1/meituan`,**全部无鉴权**) | 鉴权:无 | [← 返回 API 索引](../README.md)
|
||
>
|
||
> 集成实现:见 [integrations/meituan](../integrations/meituan.md)(CPS S-Ca 签名、入参换算坑);离线库见 [database/meituan_coupon](../database/meituan_coupon.md)。
|
||
|
||
## 入参
|
||
| 字段 | 类型 | 必填 | 默认 | 说明 |
|
||
|---|---|---|---|---|
|
||
| `longitude` | float | ✅ | — | 经度 |
|
||
| `latitude` | float | ✅ | — | 纬度 |
|
||
| `page` | int | ❌ | 1 | ≥1 |
|
||
| `page_size` | int | ❌ | 20 | 1–20 |
|
||
| `tab` | string | ❌ | `""` | `rec` 智能推荐 / `distance` 距离最近 / 空=默认混合 feed(老客户端兼容) |
|
||
|
||
> 销量最高(sales)tab **不在本接口**,走 [`/top-sales`](./meituan-top-sales.md)。
|
||
|
||
## 出参
|
||
响应 `200`:`{ items: CouponCard[], has_next: bool, page: int, status: "ok"|"empty"|"degraded" }`。`CouponCard` 结构见 [API 索引](./README.md#复用数据结构)。
|
||
|
||
### `status` 字段(前端据此显示占位)
|
||
| 值 | 含义 | 前端建议 |
|
||
|---|---|---|
|
||
| `ok` | 有数据 | 正常渲染 |
|
||
| `empty` | 后端正常、查询成功但确实没数据 | 显示「暂无优惠券」 |
|
||
| `degraded` | 上游(美团)或库查询失败,已降级返空 | 显示「服务繁忙,下拉重试」 |
|
||
|
||
> 老客户端不读 `status`(字段缺省即兼容),仍可只按 `items` 是否为空展示。
|
||
|
||
## 各 tab 行为
|
||
- **`rec` 智能推荐**:走【离线库 `meituan_coupon`】筛佣金率 ≥ 3%,`DISTINCT ON(dedup_key)` 去重后按销量降序分页。**纯库查询、不打美团、不依赖 MT 凭证**。库为空(prod 刚部署 / ETL 未跑完)→ `empty`;库异常 → `degraded`。**不显示距离**(库里距离相对城市默认点,对用户无意义)。
|
||
- 为何不实时:实测同城热销榜中位佣金 ~0.8%,筛佣金≥3% 后每页剩 0–1 条,既撞 402 又填不满,故从库出;库空时也**不回退实时**(回退同样填不满)。
|
||
- **`distance` 距离最近**:外卖搜「外卖」+ 到店搜「美食」(均 `sortField=6`),两路并行顺序翻页,实时按你坐标算距离、由近及远。两路**都失败**且无结果 → `degraded`;否则有结果 `ok` / 无结果 `empty`。
|
||
- **默认(空 tab)**:逐轮分页的混合 feed(2 外卖 + 1 到店交叉,写死 3 页:爆款 / 今日必推 / 精选+限时),第 4 页返空。两路榜单都失败 → `degraded`。
|
||
|
||
## 错误码
|
||
无业务级错误码:任何失败场景都返 `200` + 空 `items` + `status=degraded`(不再抛 5xx,避免前端弹报错 toast)。
|
||
|
||
## 兜底说明(1.0 内测)
|
||
- rec / sales 是库查询:**prod 刚部署、ETL 首灌未完成**时库为空 → 返 `empty`。最佳实践是**开内测前先手动跑一次 ETL 灌满库**(见 `scripts/pull_meituan_coupons.py` 与 `deploy/meituan-etl.{service,timer}`)。
|
||
- 未配 `MT_CPS_APP_KEY/SECRET` 时:`distance` / 默认 直接 `degraded`;`rec` 仍走库(配置开关不挡纯库查询)。
|