|
@@ -0,0 +1,108 @@
|
|
|
|
|
+# 接口文档
|
|
|
|
|
+
|
|
|
|
|
+> 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. 健康检查
|
|
|
|
|
+
|
|
|
|
|
+```text
|
|
|
|
|
+GET /health
|
|
|
|
|
+```
|
|
|
|
|
+返回 `200`,不依赖数据库。用于探活。
|
|
|
|
|
+
|
|
|
|
|
+---
|
|
|
|
|
+
|
|
|
|
|
+## 2. 拼团漏斗查询
|
|
|
|
|
+
|
|
|
|
|
+```text
|
|
|
|
|
+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` 忽略此字段 |
|
|
|
|
|
+
|
|
|
|
|
+```json
|
|
|
|
|
+{ "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` |
|
|
|
|
|
+
|
|
|
|
|
+```json
|
|
|
|
|
+{
|
|
|
|
|
+ "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 示例
|
|
|
|
|
+
|
|
|
|
|
+```bash
|
|
|
|
|
+# 默认单日(最新=昨日)
|
|
|
|
|
+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"}'
|
|
|
|
|
+```
|
