# hs-data 内部数据平台

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

> **新接手先读 [docs/07 项目结构与模块](docs/07-项目结构与模块.md)**(目录层级 / 模块职责 / 运行与部署流程)。
> 产品与信息架构见 [docs/01](docs/01-产品需求-MVP.md);技术架构与契约见 [docs/02](docs/02-技术架构.md) / [docs/03](docs/03-数据契约.md);视觉设计见 [docs/04](docs/04-设计规范.md);接口见 [docs/06](docs/06-接口文档.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/              # 部署与本地基础设施(look.sh / serve-hs-api.sh / serve.py / docker-compose)
├── CLAUDE.md           # 给 AI 与人的开发硬约束
└── CHANGELOG.md
```

> 各模块/文件职责、运行与部署数据流详见 [docs/07 项目结构与模块](docs/07-项目结构与模块.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`**(管理员合并,合并后自动删)。

## 部署到服务器

目标服务器 **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/02-技术架构.md) 与 [docs/07](docs/07-项目结构与模块.md) §7–8。