hs-data

hs-data 内部数据平台

面向内部的一站式数据平台门户。MVP 已端到端交付一个可用模块:拼团漏斗(行为分析 > 漏斗分析 > 拼团漏斗,含漏斗与趋势两视图),其余能力域进导航、出"待开发"占位。

新接手先读 docs/07 项目结构与模块(目录层级 / 模块职责 / 运行与部署流程)。 产品与信息架构见 docs/01;技术架构与契约见 docs/02 / docs/03;视觉设计见 docs/04;接口见 docs/06;协作约定见 docs/05 与根 CLAUDE.md;迭代与发布流程见 docs/08。改动留痕见 CHANGELOG.md。

能力域(信息架构,5 个 L1)

L1 能力域	内含(L2)	状态
行为分析	漏斗分析(拼团漏斗)、留存/路径/事件/分布/归因	拼团漏斗可用,余待开发
指标体系	指标目录 / 指标大盘 / 指标监控	待开发
画像体系	用户画像 / 商家画像 / 产品画像	待开发
数据看板	业务大盘 / 实时大盘 / 关键报表	待开发
营销触达	触达规则 / 触达记录 / 触达效果	待开发

导航为三级 IA(L1 能力域 → L2 模块 → L3 报表),拼团漏斗即 L3。详见 docs/01 §2。

Monorepo 结构

.
├── apps/
│   ├── web/            # 前端(React 19 + Vite + Tailwind v4 + shadcn/ui + ECharts)
│   └── api/            # 后端(FastAPI · 只读查询服务)
├── packages/
│   └── api-types/      # 由后端 OpenAPI 生成的 TS 类型(勿手改)
├── docs/               # 产品 / 技术 / 数据契约 / 设计 / 协作 / 接口 / 结构
├── infra/              # 部署与本地基础设施(look.sh / serve-hs-api.sh / serve.py / docker-compose)
├── CLAUDE.md           # 给 AI 与人的开发硬约束
└── CHANGELOG.md

各模块/文件职责、运行与部署数据流详见 docs/07 项目结构与模块。

技术栈

层	选型
前端	React 19 + Vite + TypeScript + Tailwind v4 + shadcn/ui(神策风 mint 主题)+ ECharts + TanStack Query
后端	Python 3.11+ + FastAPI + Pydantic v2 + SQLAlchemy(async)
数据	PostgreSQL 16 · 拼团漏斗预聚合两表(ads_trd_group_funnel_daily / _rolling,见 docs/03 §11)
契约	后端 OpenAPI → 前端生成 TS 类型(pnpm gen:api-types)

注:pnpm 用 corepack 调用(corepack pnpm@10 …)即可,无需全局安装。

快速开始(本地开发)

前置:Node ≥ 20、Python ≥ 3.11(后端,可选)。

# 前端(默认 mock 数据,无需后端即可看页面)
corepack pnpm@10 install
corepack pnpm@10 --filter @hs-data/web dev        # http://localhost:5173

# 后端(可选;USE_FAKE_DATA 默认 true,无需 DB 即可起)
cd apps/api
python -m venv .venv && .venv/Scripts/python -m pip install -e ".[dev]"   # Win
.venv/Scripts/uvicorn app.main:app --reload --port 8000                    # http://localhost:8000/docs

# 接真实 Postgres(可选)
docker compose -f infra/docker-compose.yml up -d
cd apps/api && alembic upgrade head && python -m scripts.seed
# 然后 apps/api/.env 设 USE_FAKE_DATA=false 再起后端

# 让前端连真后端:apps/web/.env 设 VITE_USE_MOCK=false

# 测试
corepack pnpm@10 --filter @hs-data/web test       # Vitest
cd apps/api && .venv/Scripts/pytest -q             # pytest

数据为 T+1(最大可查日为昨日):单日支持历史回溯;近 7/30 天为滚动窗口(只有最新 as-of)。详见 docs/02 §5(v3)、docs/03 §11。

分支模型与协作

开发在本地(Windows),通过 git 与远程互通。分支模型:

分支	定位	保护	合并来源
master	稳定版本归档	是	release(打 Tag)
release	线上运行版本	是	feature
feature	公共开发分支	是	feature-xxx(PR + Review)
feature-xxx	个人开发分支(feature-<人>-<模块>-<日期>)	否	——

日常:从 feature 切个人分支 → 改 → push → PR 合入 feature(管理员合并,合并后自动删)。

部署到服务器

目标服务器 CentOS 7(glibc 2.17),内网 http://100.64.0.62:8080/。因 glibc 太老跑不了现代前端构建,采用本地构建 → git 送达 → 服务器托管+跑后端:

• 一键部署:/look(即 bash infra/look.sh)—— web 测试+构建 → 推 feature(源码)+ deploy(产物)到 GitLab → 服务器 git pull → 上线。仅显式触发。
• 单进程同源:服务器用隔离 Miniconda 的 Python 3.11 跑 uvicorn,以 STATIC_DIR 同源托管前端 SPA(~/hs-data 产物,实时读盘)+ /api,端口 8080。前端相对 /api 调用 → 免 CORS、免反代。
• 纯前端改动免重启(实时读盘);仅当 apps/api 变更才重启后端。不动系统 Python(3.6/3.7,其他项目依赖)。

完整部署架构(隔离环境、两份 clone、按需重启、取数)见 docs/02 §10 与 docs/07 §7–8。