# 技术架构

> hs-data 平台的技术栈、目录结构、接口契约、计算与非功能性需求。

| 项 | 内容 |
|----|------|
| 文档版本 | v1.0 |
| 文档状态 | 待评审 |
| 更新日期 | 2026-06-21 |

## 修订记录

| 版本 | 日期 | 修订内容 |
|------|------|----------|
| v1.0 | 2026-06-21 | 初版 |

---

## 1. 技术栈

MVP 使用前后端分离架构:

- 前端:React 19 + Vite + TypeScript + **Tailwind CSS v4 + shadcn/ui**(Radix-based)+ ECharts(漏斗图)+ TanStack Query。
- 后端:FastAPI(Python 3.11+)+ Pydantic v2 + SQLAlchemy(async)。
- 存储:PostgreSQL 16(MVP 漏斗读 `ads_trd_group_funnel` 预聚合宽表,见 `docs/03` §11)。

本项目不使用 Next.js。原因是内部数据后台不需要 SEO/SSR;前端用 React/Vite 更轻,UI 走 shadcn/ui 拷贝式组件 + Tailwind 工具类。

> **2026-06-24 修订**:前端 UI 库由 Ant Design 5 改为 **shadcn/ui + Tailwind v4**(参见 CHANGELOG)。ECharts 漏斗图保留。
> 原 Ant Design 方案因观感不达预期被替换。bitmap 相关存储格式(原 `bytea` + roaring bitmap)随漏斗方案转向预聚合宽表已退出 MVP,挪到后续"泛用漏斗"阶段(见 `docs/03` v2 头注)。
>
> **视觉/交互定稿见 `docs/04-设计规范`**(神策风 mint 主题、布局、漏斗图、控件、抗抖滚动模型),已锁定。

## 2. 仓库结构

采用 monorepo：

```text
apps/
  web/        # 前端应用
  api/        # FastAPI 后端服务
docs/         # 产品、技术、数据契约文档
infra/        # 本地开发和部署配置
```

MVP 阶段不拆分多个 Git 仓库。前后端、文档和本地基础设施放在同一个仓库，方便联调、交付和 AI 协作。

## 3. 前端职责

前端负责产品交互和展示(拼团固定漏斗,v3):

- 周期选择:单日(可回溯历史日,上限昨日)/ 近 7 天 / 近 30 天。
- 单日的历史日期不可选今天及未来(T+1)。
- 请求后端漏斗查询接口。
- 使用 **ECharts** 展示漏斗图。
- 使用 **shadcn/ui + Tailwind** 展示表格、控件、空状态和错误提示。
- 按 `data_status`(`ready` / `missing`)显式渲染,缺失不补零。

前端不解析底层存储,只消费接口返回的 UV / 转化率 / 流失率。

## 4. 后端职责

后端负责漏斗查询 API:

- 提供 `POST /api/funnels/query`(契约见 §5)。
- 校验 `period`(枚举)与 `snapshot_dt`(仅单日有效、上限昨日)。
- 从 PostgreSQL 读取**预聚合宽表**(`ads_trd_group_funnel_daily` / `_rolling`,见 `docs/03` §11),按 `period` 选对应列,**不读 bitmap、不做 OR、不跨天聚合**。
- 返回每层 UV、相邻转化率/流失率、`data_status`(`ready` / `missing`)。

后端不存储埋点明细，不负责数仓产出逻辑。

## 5. 查询 API

> **v3(2026-06-24 修订)**:MVP = **拼团漏斗**,数据源拆为两张表(`ads_trd_group_funnel_daily` + `ads_trd_group_funnel_rolling`,见 `docs/03` §11)。
> 固定 5 步:启动 `start` → 曝光 `show` → **拼团详情** `detail` → 下单 `order` → 成功 `paid`。
> 单日支持历史日期(daily 表留全历史);近 7/30 天只有最新 as-of(rolling 表覆盖式 1 行)。数据 T+1,最大可查日始终昨日。
> 原 v1"泛用漏斗"(任意步骤 + bitmap)仍挪后续,详见 §6。

接口：

```text
POST /api/funnels/query
```

请求字段:

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

- `period` ∈ `day`(单日) | `last_7d` | `last_30d`。
- `snapshot_dt`(可选,`yyyy-MM-dd`):**仅对 `day` 有意义**。省略=最新(昨日),给值=该历史日;上限昨日(T+1),今天/未来 → 422。`last_7d`/`last_30d` 忽略该字段。
- MVP 不接受任意 `steps`、不接受自定义日期范围。

响应字段:

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

- `snapshot_dt`:实际取数那行的 `dt`(`yyyyMMdd`)。单日=该天;近 7/30 天=rolling 的 as-of 日(即"数据截至"日)。
- `step_index` 从 1 开始;第 1 步 `conversion_rate`/`dropoff_rate` 为 `null`。
- 相邻转化率 = `uv[i]/uv[i-1]`,流失率 = `1-转化率`;`uv[i-1]==0` 时为 `null`。
- `data_status` ∈ `ready` | `missing`(目标行不存在或对应列为空时 `missing`,不补零)。

## 6. 计算策略

### MVP(拼团漏斗,v3)

数据源两张表(`docs/03` §11),按 `period` 路由:

- `period = day` → 读 `ads_trd_group_funnel_daily`;给 `snapshot_dt` → `WHERE dt=:dt`,否则 `ORDER BY dt DESC LIMIT 1`;取 `uv_start/show/detail/order/paid` 五列。
- `period = last_7d` → 读 `ads_trd_group_funnel_rolling`(唯一行),取 `uv_*_7d`。
- `period = last_30d` → 读 `ads_trd_group_funnel_rolling`(唯一行),取 `uv_*_30d`。

UV 直接取列值;相邻转化率由 UV 计算。**不读 bitmap、不做 OR、不做跨天聚合。** 单日可回溯历史,近 7/30 天仅最新 as-of。

### 后续(泛用漏斗,v1 设计,暂不实现)

- 任意步骤事件 + 自定义范围最大 15 天。
- 标准周期优先读预计算结果;自定义范围读每日 bitmap,逐步骤跨天 OR 后取 cardinality。
- 依赖 `daily_event_bitmap` / `period_event_bitmap`(`docs/03` §4、§5),这两表 MVP 暂不落地。

## 7. 性能策略

系统是内部低并发数据平台，MVP 不引入额外缓存层。

后端性能策略(拼团两表,v3):

- FastAPI 多 worker 部署。
- 查询是**单行宽表读取 + 取列值**(取最新 `dt` 行或指定单日 `dt`),无 bitmap 计算、无跨天聚合,极轻。

MVP 不引入：

- Redis。
- Celery。
- ClickHouse。

## 8. 测试策略

后端测试(对照实现):

- `period` 校验:`day` / `last_7d` / `last_30d` 接受,非法值 422。
- 单日:无 `snapshot_dt` 取最新行;给 `snapshot_dt` 取该日;不存在的日 → `missing`;`snapshot_dt` > 昨日(今天/未来)→ 422。
- 近 7/30 天:从 rolling 唯一行取 `*_7d` / `*_30d`。
- 转化率:第 1 层 `null`;`uv[i]/uv[i-1]`;`uv[i-1]==0` → `null`。
- `data_status`:`ready` / `missing`;`snapshot_dt` 回显正确。

前端测试：

- 周期选择(单日 / 近 7 天 / 近 30 天),默认单日。
- 单日日历:今天/未来不可选;选历史日重查。
- 图表渲染、表格渲染。
- `missing` 数据缺失空态、错误态。

## 9. 前端模块结构与路由

> **导航信息架构(L1/L2/L3)以 `01-产品需求` §2 为准**。本节只讲路由落地。

前端是多模块单页应用,左侧导航按 **5 个 L1 能力域**组织(行为分析 / 指标体系 / 画像体系 / 数据看板 / 营销触达,见 `docs/01` §2.1):

> 导航分组手动展开/折叠、多个同时展开、进入某页自动展开其所在分支(`NavTree.tsx`,交互见 `docs/01` §2.3)。

- 布局壳:统一外框(顶栏 + 左侧 L1 导航 + 内容区),各模块挂在内容区。
- **三级路由**:L1 能力域一级路由;有可用模块的域下挂 L2(分析模块)、L3(报表/实例)。
  - MVP 仅 `行为分析 > 漏斗分析 > 拼团漏斗` 一条 L1→L2→L3 链渲染完整分析页(当前实现路由 `/funnel` 即此 L3,后续可规整为 `/behavior/funnel/group`)。
  - 其余 L1/L2 路由渲染统一的"待开发"占位组件。
- 占位机制:非可用模块复用同一占位组件(`src/modules/placeholder/`),文案统一"待开发",可正常进入、不报错、不空白。
- L2 子菜单(域内多模块)与 L3 报表列表后续按路线图补;当前 MVP 导航可先平铺 7 个 L1 + 漏斗页,不强求展开全部 L2。