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 @
2.9 KiB
2.9 KiB
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。- 默认(空 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仍走库(配置开关不挡纯库查询)。