技术架构

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：

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

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

3. 前端职责

前端负责产品交互和展示：

漏斗步骤选择。
时间范围选择。
自定义时间最大 15 天限制。
今天不可选或不可提交。
请求后端漏斗查询接口。
使用 ECharts 展示漏斗图。
使用 Ant Design 展示表格、表单、空状态和错误提示。

前端不负责 bitmap 解析或计算。

4. 后端职责

后端负责数据服务 API 和 bitmap 计算：

提供漏斗查询接口。
校验时间范围和漏斗步骤参数。
从 PostgreSQL 读取 bytea bitmap。
对自定义时间范围内的 daily bitmap 做 OR 计算。
对标准周期优先读取预计算 period bitmap 或结果。
返回每层 UV、转化率和数据状态。

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

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。

接口：

POST /api/funnels/query

请求字段:

{ "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、不接受自定义日期范围。

响应字段:

{
  "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 不引入额外缓存层。

后端性能策略：

FastAPI 使用多 worker 部署。
大 bitmap 的 CPU 计算不直接阻塞 async event loop。
典型查询按 漏斗层数 x 日期天数 读取 bitmap。
自定义范围最大 15 天，用产品规则控制计算上限。

MVP 不引入：

Redis。
Celery。
ClickHouse。
PostgreSQL bitmap 扩展。

8. 测试策略

后端测试：

单日查询。
多日查询。
标准周期查询。
空 bitmap 查询。
缺失数据查询。
重复用户在 bitmap 中只计一次。
多步骤 UV 和转化率计算。

前端测试：

快捷时间选择。
自定义时间最大 15 天限制。
今天不可选或不可提交。
图表渲染。
表格渲染。
空状态和错误状态展示。

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。

02-技术架构.md 7.5 KB 히스토리 Raw