# 接口文档

> 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. 健康检查

```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 日。**仅未命中任何行时为 `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` |

```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` | 目标行不存在,**或**命中行但对应列为 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 示例

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

---

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

```text
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。

```json
{ "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 步,口径一致) |

```json
{
  "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 示例

```bash
# 近 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"}'
```