shaguabijia-app-server/docs/api/meituan/meituan-feed.md

POST /api/v1/meituan/feed — 首页推荐流(多 tab)

所属:美团 CPS 组(前缀 /api/v1/meituan,全部无鉴权) | 鉴权:无 | ← 返回 API 索引

集成实现:见 integrations/meituan(CPS S-Ca 签名、入参换算坑);离线库见 database/meituan_coupon。

入参

字段	类型	必填	默认	说明
longitude	float	✅	—	经度
latitude	float	✅	—	纬度
page	int	❌	1	≥1
page_size	int	❌	20	1–20
tab	string	❌	""	rec 智能推荐 / distance 距离最近 / 空=默认混合 feed(老客户端兼容)

销量最高(sales)tab 不在本接口,走 /top-sales。

出参

响应 200:{ items: CouponCard[], has_next: bool, page: int, status: "ok"|"empty"|"degraded" }。CouponCard 结构见 API 索引。

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。
  • 翻页成本:美团搜索只能靠 searchId 续页,本接口又是无状态的(客户端只传页码)。服务端把沿途 searchId 按「量化坐标(~1km)+平台+关键词」缓存 10 分钟(utils/mt_search_cursor),稳态下每翻一页恒定 1 次上游请求(改前是「取第 N 页 = 发 N 次」);缓存冷/过期才从最近的已知页往后重放。缓存是进程内的,多 worker 不共享 —— 只影响快慢,不影响结果。
• 默认(空 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 仍走库(配置开关不挡纯库查询)。