# hs-data 内部数据平台

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

> 产品与信息架构见 [docs/01](docs/01-产品需求-MVP.md);技术架构与契约见 [docs/02](docs/02-技术架构.md) / [docs/03](docs/03-数据契约.md);视觉设计定稿见 [docs/04](docs/04-设计规范.md);协作约定见 [docs/05](docs/05-agent协作准则.md) 与根 [CLAUDE.md](CLAUDE.md)。改动留痕见 [CHANGELOG.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(后端,可选)。

```bash
# 前端(默认 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,服务器自行构建/运行)**
```bash
# 服务器一次性:装 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)
```bash
# 本地(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_*` 两表。