hs-data

hs-data 内部数据平台

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

产品与信息架构见 docs/01;技术架构与契约见 docs/02 / docs/03;视觉设计定稿见 docs/04;协作约定见 docs/05 与根 CLAUDE.md。改动留痕见 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/              # docker-compose(PG)、setup.sh(服务器装环境)
├── CLAUDE.md           # 给 AI 与人的开发硬约束
└── CHANGELOG.md

技术栈

层	选型
前端	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(管理员合并,合并后自动删)。

部署到服务器(对外提供 web 服务)

目标服务器为 CentOS 7(glibc 2.17,自带 Node 16 / Python 3.6 / 无 docker)。Node 20 / Python 3.11 的官方二进制在此跑不起来,两种部署法:

① conda 自建环境(源码留 git,服务器自行构建/运行)

# 服务器一次性:装 Miniconda,再
conda create -n hs python=3.11 nodejs=20 -y && conda activate hs
git clone http://git.hobbystocks.cn/tianyu.chu/hs-data.git ~/hs-data && cd ~/hs-data
bash infra/setup.sh           # 装依赖
corepack pnpm@10 --filter @hs-data/web build      # 出 dist/
# 用 nginx 或 python -m http.server 托管 apps/web/dist

② 本地构建 + 服务器只托管静态(服务器不需要 Node/Python)

# 本地(Windows)
corepack pnpm@10 --filter @hs-data/web build       # 出 apps/web/dist
# 把 dist/ 传到服务器,用 nginx / python3 -m http.server 托管

前端单靠 mock 数据即可独立提供 web 服务;后端(FastAPI)按需用 conda 的 Python 3.11 起 uvicorn,或接真实 ads_trd_group_funnel_* 两表。