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

接口文档

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

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

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 日。仅未命中任何行时为 null(命中行但列为 NULL 的 missing 仍回该行 dt)
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	目标行不存在,或命中行但对应列为 NULL。不补零:results 为空;snapshot_dt 仅在未命中行时为 null(命中行但列空时仍回该行 dt)

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"}'

---

3. 拼团漏斗趋势(按日折线)

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

同一批 5 个事件的按日时间序列(事件 UV + 相邻转换率),供漏斗页「趋势」Tab。数据源 ads_trd_group_funnel_daily(天然时序)。

3.1 请求

字段	类型	必填	说明
start_dt	string YYYY-MM-DD	否	起始(含)。省略=end_dt 往前 29 天
end_dt	string YYYY-MM-DD	否	结束(含)。省略=最新可用日。上限昨日,今天/未来 → 422

都省略 → 最新可用日往前 30 天。start_dt > end_dt → 422。

{ "start_dt": "2026-05-23", "end_dt": "2026-06-21" }

3.2 响应 200

字段	类型	说明
start_dt	string yyyyMMdd | null	返回序列首日(裁前导 0 后);missing 时 null
end_dt	string yyyyMMdd | null	返回序列末日;missing 时 null
data_status	string 枚举	ready / missing
points	array	按 dt 升序;每项 { dt, results },results 同 §2.2(5 步,口径一致)

{
  "start_dt": "20260523",
  "end_dt": "20260621",
  "data_status": "ready",
  "points": [
    { "dt": "20260523", "results": [ /* 5 步 FunnelStepResult,同 §2.2 */ ] }
  ]
}

• 前导全 0 天(上线前爬坡)裁掉;范围内缺口日(ETL 漏跑)直接缺该 dt 点 → 前端断线、不补零。
• 整段无产出 → data_status=missing、points=[]、首尾为 null。

3.3 错误 422

• end_dt 为今天或未来(T+1)。
• start_dt > end_dt。

3.4 示例

# 近 30 天(默认)
curl -X POST http://localhost:8000/api/funnels/trend -H 'Content-Type: application/json' -d '{}'
# 自定义范围
curl ... -d '{"start_dt":"2026-05-23","end_dt":"2026-06-21"}'