hs-data/docs/06-接口文档.md

接口文档

hs-data 后端对外接口参考。契约唯一来源是 docs/02-技术架构 §5;本文是面向调用方的完整说明。 机读:后端运行时 GET /openapi.json 与 Swagger UI /docs;前端 TS 类型见 packages/api-types。

项	内容
阶段	MVP 开发中(未发布)
更新日期	2026-06-25
Base URL(本地)	http://localhost:8000
鉴权	MVP 暂无(内网访问);对外开放前需加鉴权,见 docs/01 §7

1. 健康检查

GET /health

返回 200,不依赖数据库。用于探活。

---

2. 拼团漏斗查询

POST /api/funnels/query
Content-Type: application/json

固定 5 步拼团漏斗:启动 start → 曝光 show → 拼团详情 detail → 下单 order → 成功 paid。数据 T+1,最大可查日为昨日。

2.1 请求

字段	类型	必填	说明
period	string 枚举	是	day(单日)/ last_7d / last_30d。非法值 → 422
snapshot_dt	string YYYY-MM-DD	否	仅 day 有效:指定历史某日;省略=最新(昨日)。上限昨日,今天/未来 → 422。last_7d/last_30d 忽略此字段

{ "period": "day", "snapshot_dt": "2026-06-20" }

2.2 响应 200

字段	类型	说明
period	string	回显请求周期
snapshot_dt	string yyyyMMdd | null	实际取数那行的 dt;单日=该日,近 7/30 天=rolling 的 as-of 日;missing 时为 null
results	array(5)	固定 5 步,见下
data_status	string 枚举	ready / missing

results[] 每项:

字段	类型	说明
step_index	int	从 1 开始
name	string	中文步骤名(启动/曝光/拼团详情/下单/成功)
event_key	string	稳定 key(start/show/detail/order/paid)
uv	int	该步骤独立用户数
conversion_rate	float | null	uv[i]/uv[i-1];第 1 步为 null;uv[i-1]==0 时为 null
dropoff_rate	float | null	1 - conversion_rate;同上为 null

{
  "period": "day",
  "snapshot_dt": "20260620",
  "results": [
    { "step_index": 1, "name": "启动",     "event_key": "start",  "uv": 10000, "conversion_rate": null, "dropoff_rate": null },
    { "step_index": 2, "name": "曝光",     "event_key": "show",   "uv": 8200,  "conversion_rate": 0.82, "dropoff_rate": 0.18 },
    { "step_index": 3, "name": "拼团详情", "event_key": "detail", "uv": 5100,  "conversion_rate": 0.62, "dropoff_rate": 0.38 },
    { "step_index": 4, "name": "下单",     "event_key": "order",  "uv": 2200,  "conversion_rate": 0.43, "dropoff_rate": 0.57 },
    { "step_index": 5, "name": "成功",     "event_key": "paid",   "uv": 1800,  "conversion_rate": 0.82, "dropoff_rate": 0.18 }
  ],
  "data_status": "ready"
}

2.3 数据状态

值	含义
ready	目标行存在且对应列非空,正常返回
missing	目标行不存在或对应列为空。不补零:results 为空、snapshot_dt 为 null

2.4 错误 422

请求不合法时返回 422(FastAPI 标准校验错误体,detail 含原因):

• period 缺失或非枚举值。
• period=day 且 snapshot_dt 为今天或未来(数据 T+1,最大昨日)。

2.5 取数说明(实现)

• day → 读 ads_trd_group_funnel_daily:给 snapshot_dt 取该行,否则取最新 dt。
• last_7d / last_30d → 读 ads_trd_group_funnel_rolling 唯一行的 *_7d / *_30d 列。
• 不读 bitmap、不跨天聚合。表结构见 docs/03 §11。

2.6 示例

# 默认单日(最新=昨日)
curl -X POST http://localhost:8000/api/funnels/query -H 'Content-Type: application/json' -d '{"period":"day"}'
# 历史某日
curl ... -d '{"period":"day","snapshot_dt":"2026-06-18"}'
# 近 7 天
curl ... -d '{"period":"last_7d"}'
# 今天 → 422
curl ... -d '{"period":"day","snapshot_dt":"2026-06-25"}'